happyskills 0.35.1 → 0.35.3

package/CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.35.3] - 2026-04-11
+
+### Fixed
+- Fix `refresh` and `install` silently leaving stale symlinks for up-to-date skills — symlinks copied from another project (e.g., absolute paths pointing to a different directory) were never validated or repaired unless the skill version changed; now all symlinks are verified and repaired regardless of version status
+
+## [0.35.2] - 2026-04-11
+
+### Added
+- Add match quality labels to smart search output — each result shows its confidence level (Strong match, Good match, Partial match, Weak match) based on cosine similarity
+- Add weak-match notice when no results have strong or good match quality, warning that results may not match the user's intent
+- Add `match_quality` and `match_notice` fields to JSON search output
+
 ## [0.35.1] - 2026-04-10
 
 ### Fixed

package/package.json

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

package/src/agents/index.js

@@ -1,11 +1,11 @@
 const { AGENTS, get_agent, get_all_agent_ids } = require('./registry')
 const { detect_agents, resolve_agents } = require('./detector')
-const { link_to_agents, unlink_from_agents, is_symlink } = require('./linker')
+const { link_to_agents, unlink_from_agents, is_symlink, verify_and_repair_symlinks } = require('./linker')
 const { is_skill_enabled, get_skills_enabled_map } = require('./status')
 
 module.exports = {
 	AGENTS, get_agent, get_all_agent_ids,
 	detect_agents, resolve_agents,
-	link_to_agents, unlink_from_agents, is_symlink,
+	link_to_agents, unlink_from_agents, is_symlink, verify_and_repair_symlinks,
 	is_skill_enabled, get_skills_enabled_map
 }

package/src/agents/linker.js

@@ -105,6 +105,60 @@ const link_to_agents = (source_dir, agents, options = {}) => catch_errors('Agent
 	return results
 })
 
+/**
+ * Verify and repair symlinks for a list of skills across all agents.
+ * For each skill, checks that each agent's symlink points to the correct canonical source.
+ * Repairs symlinks that are missing, broken, absolute, or pointing to the wrong location.
+ *
+ * @param {Array<{ skill_name: string, source_dir: string }>} skills — skill name + canonical dir
+ * @param {Agent[]} agents — array of agent objects to verify
+ * @param {object} options — { global, project_root }
+ * @returns {Promise} [errors, { repaired: Array<{ skill_name, agent_id }>, already_correct: number }]
+ */
+const verify_and_repair_symlinks = (skills, agents, options = {}) => catch_errors('Symlink verification failed', async () => {
+	const { global: is_global = false, project_root } = options
+	const repaired = []
+	let already_correct = 0
+
+	for (const { skill_name, source_dir } of skills) {
+		for (const agent of agents) {
+			const target = agent_skill_install_dir(agent, is_global, project_root, skill_name)
+
+			const [, is_link] = await is_symlink(target)
+			if (is_link) {
+				try {
+					const link_target = await fs.promises.readlink(target)
+					const resolved_link = path.resolve(path.dirname(target), link_target)
+					if (resolved_link === source_dir) {
+						already_correct++
+						continue
+					}
+				} catch {
+					// readlink failed — remove and recreate
+				}
+			} else if (!(await _exists(target))) {
+				// Symlink missing — create it
+			} else {
+				// Target exists but is not a symlink (physical dir) — skip, don't destroy user data
+				already_correct++
+				continue
+			}
+
+			// Remove stale/broken symlink
+			if (await _exists(target)) {
+				await remove_dir(target)
+			}
+
+			// Ensure parent dir exists and create correct symlink
+			await ensure_dir(path.dirname(target))
+			await _link_or_copy(source_dir, target)
+			repaired.push({ skill_name, agent_id: agent.id })
+		}
+	}
+
+	return { repaired, already_correct }
+})
+
 /**
  * Unlink a skill from agents. Removes symlinks or physical copies.
  *
@@ -138,4 +192,4 @@ const unlink_from_agents = (skill_name, agents, options = {}) => catch_errors('A
 	return results
 })
 
-module.exports = { link_to_agents, unlink_from_agents, is_symlink }
+module.exports = { link_to_agents, unlink_from_agents, is_symlink, verify_and_repair_symlinks }

package/src/agents/linker.test.js

@@ -5,7 +5,7 @@ const fs = require('fs')
 const path = require('path')
 const os = require('os')
 
-const { link_to_agents, unlink_from_agents, is_symlink } = require('./linker')
+const { link_to_agents, unlink_from_agents, is_symlink, verify_and_repair_symlinks } = require('./linker')
 
 const make_tmp = () => fs.mkdtempSync(path.join(os.tmpdir(), 'hs-linker-test-'))
 const cleanup = (dir) => fs.rmSync(dir, { recursive: true, force: true })
@@ -204,3 +204,179 @@ describe('unlink_from_agents', () => {
 		assert.ok(fs.existsSync(path.join(source, 'SKILL.md')))
 	})
 })
+
+describe('verify_and_repair_symlinks', () => {
+	let tmp
+	beforeEach(() => { tmp = make_tmp() })
+	afterEach(() => { cleanup(tmp) })
+
+	it('reports already_correct when symlinks point to the right place', async () => {
+		const source = path.join(tmp, '.agents', 'skills', 'deploy-aws')
+		fs.mkdirSync(source, { recursive: true })
+
+		const agent_dir = path.join(tmp, '.claude', 'skills')
+		fs.mkdirSync(agent_dir, { recursive: true })
+		const relative = path.relative(agent_dir, source)
+		fs.symlinkSync(relative, path.join(agent_dir, 'deploy-aws'), 'junction')
+
+		const agents = [make_agent('claude', '.claude/skills')]
+		const [errors, result] = await verify_and_repair_symlinks(
+			[{ skill_name: 'deploy-aws', source_dir: source }],
+			agents,
+			{ global: false, project_root: tmp }
+		)
+
+		assert.equal(errors, null)
+		assert.equal(result.repaired.length, 0)
+		assert.equal(result.already_correct, 1)
+	})
+
+	it('repairs symlink pointing to wrong project (absolute path)', async () => {
+		const source = path.join(tmp, '.agents', 'skills', 'deploy-aws')
+		fs.mkdirSync(source, { recursive: true })
+
+		// Create a symlink pointing to a different project (absolute path)
+		const wrong_source = path.join(tmp, 'other-project', '.agents', 'skills', 'deploy-aws')
+		fs.mkdirSync(wrong_source, { recursive: true })
+		const agent_dir = path.join(tmp, '.claude', 'skills')
+		fs.mkdirSync(agent_dir, { recursive: true })
+		fs.symlinkSync(wrong_source, path.join(agent_dir, 'deploy-aws'), 'junction')
+
+		const agents = [make_agent('claude', '.claude/skills')]
+		const [errors, result] = await verify_and_repair_symlinks(
+			[{ skill_name: 'deploy-aws', source_dir: source }],
+			agents,
+			{ global: false, project_root: tmp }
+		)
+
+		assert.equal(errors, null)
+		assert.equal(result.repaired.length, 1)
+		assert.equal(result.repaired[0].skill_name, 'deploy-aws')
+		assert.equal(result.repaired[0].agent_id, 'claude')
+
+		// Verify the symlink now points to the correct source with a relative path
+		const link_path = path.join(agent_dir, 'deploy-aws')
+		const link_target = fs.readlinkSync(link_path)
+		assert.equal(link_target, path.relative(agent_dir, source))
+	})
+
+	it('creates missing symlinks', async () => {
+		const source = path.join(tmp, '.agents', 'skills', 'deploy-aws')
+		fs.mkdirSync(source, { recursive: true })
+
+		// No symlink exists in agent dir at all
+		const agents = [make_agent('claude', '.claude/skills')]
+		const [errors, result] = await verify_and_repair_symlinks(
+			[{ skill_name: 'deploy-aws', source_dir: source }],
+			agents,
+			{ global: false, project_root: tmp }
+		)
+
+		assert.equal(errors, null)
+		assert.equal(result.repaired.length, 1)
+
+		const link_path = path.join(tmp, '.claude', 'skills', 'deploy-aws')
+		assert.ok(fs.lstatSync(link_path).isSymbolicLink())
+		const link_target = fs.readlinkSync(link_path)
+		assert.equal(link_target, path.relative(path.dirname(link_path), source))
+	})
+
+	it('repairs broken symlinks (dangling)', async () => {
+		const source = path.join(tmp, '.agents', 'skills', 'deploy-aws')
+		fs.mkdirSync(source, { recursive: true })
+
+		// Create a symlink to a non-existent location
+		const agent_dir = path.join(tmp, '.claude', 'skills')
+		fs.mkdirSync(agent_dir, { recursive: true })
+		fs.symlinkSync('/nonexistent/path/deploy-aws', path.join(agent_dir, 'deploy-aws'), 'junction')
+
+		const agents = [make_agent('claude', '.claude/skills')]
+		const [errors, result] = await verify_and_repair_symlinks(
+			[{ skill_name: 'deploy-aws', source_dir: source }],
+			agents,
+			{ global: false, project_root: tmp }
+		)
+
+		assert.equal(errors, null)
+		assert.equal(result.repaired.length, 1)
+
+		const link_path = path.join(agent_dir, 'deploy-aws')
+		const link_target = fs.readlinkSync(link_path)
+		assert.equal(link_target, path.relative(agent_dir, source))
+	})
+
+	it('handles multiple skills and multiple agents', async () => {
+		const skill_a = path.join(tmp, '.agents', 'skills', 'skill-a')
+		const skill_b = path.join(tmp, '.agents', 'skills', 'skill-b')
+		fs.mkdirSync(skill_a, { recursive: true })
+		fs.mkdirSync(skill_b, { recursive: true })
+
+		// skill-a has correct symlink in claude, missing in cursor
+		const claude_dir = path.join(tmp, '.claude', 'skills')
+		fs.mkdirSync(claude_dir, { recursive: true })
+		const relative_a = path.relative(claude_dir, skill_a)
+		fs.symlinkSync(relative_a, path.join(claude_dir, 'skill-a'), 'junction')
+
+		// skill-b has wrong symlink in claude
+		const wrong_b = path.join(tmp, 'other-project', '.agents', 'skills', 'skill-b')
+		fs.mkdirSync(wrong_b, { recursive: true })
+		fs.symlinkSync(wrong_b, path.join(claude_dir, 'skill-b'), 'junction')
+
+		const agents = [
+			make_agent('claude', '.claude/skills'),
+			make_agent('cursor', '.cursor/skills')
+		]
+		const [errors, result] = await verify_and_repair_symlinks(
+			[
+				{ skill_name: 'skill-a', source_dir: skill_a },
+				{ skill_name: 'skill-b', source_dir: skill_b }
+			],
+			agents,
+			{ global: false, project_root: tmp }
+		)
+
+		assert.equal(errors, null)
+		// skill-a correct in claude (1 correct), missing in cursor (1 repair)
+		// skill-b wrong in claude (1 repair), missing in cursor (1 repair)
+		assert.equal(result.already_correct, 1)
+		assert.equal(result.repaired.length, 3)
+
+		// Verify all symlinks are now correct
+		for (const agent of agents) {
+			for (const name of ['skill-a', 'skill-b']) {
+				const link_path = path.join(tmp, agent.skills_dir, name)
+				assert.ok(fs.lstatSync(link_path).isSymbolicLink(), `${agent.id}/${name} should be a symlink`)
+				const source_dir = path.join(tmp, '.agents', 'skills', name)
+				const resolved = path.resolve(path.dirname(link_path), fs.readlinkSync(link_path))
+				assert.equal(resolved, source_dir, `${agent.id}/${name} should resolve to canonical dir`)
+			}
+		}
+	})
+
+	it('does not destroy physical directories (non-symlink)', async () => {
+		const source = path.join(tmp, '.agents', 'skills', 'deploy-aws')
+		fs.mkdirSync(source, { recursive: true })
+
+		// Agent dir has a physical directory (not a symlink) — should be left alone
+		const agent_dir = path.join(tmp, '.claude', 'skills')
+		const physical = path.join(agent_dir, 'deploy-aws')
+		fs.mkdirSync(physical, { recursive: true })
+		fs.writeFileSync(path.join(physical, 'SKILL.md'), 'user content')
+
+		const agents = [make_agent('claude', '.claude/skills')]
+		const [errors, result] = await verify_and_repair_symlinks(
+			[{ skill_name: 'deploy-aws', source_dir: source }],
+			agents,
+			{ global: false, project_root: tmp }
+		)
+
+		assert.equal(errors, null)
+		// Physical dir should be counted as correct (not destroyed)
+		assert.equal(result.repaired.length, 0)
+		assert.equal(result.already_correct, 1)
+
+		// User content should still be there
+		assert.ok(fs.existsSync(path.join(physical, 'SKILL.md')))
+		assert.equal(fs.readFileSync(path.join(physical, 'SKILL.md'), 'utf-8'), 'user content')
+	})
+})

package/src/commands/refresh.js

@@ -10,6 +10,8 @@ const { create_spinner } = require('../ui/spinner')
 const { exit_with_error } = require('../utils/errors')
 const { find_project_root, lock_root, skills_dir, skill_install_dir } = require('../config/paths')
 const { EXIT_CODES } = require('../constants')
+const { resolve_agents, verify_and_repair_symlinks } = require('../agents')
+const { is_skill_enabled } = require('../agents/status')
 
 const HELP_TEXT = `Usage: happyskills refresh [options]
 
@@ -74,6 +76,7 @@ const run = (args) => catch_errors('Refresh failed', async () => {
 	const spinner = !args.flags.json ? create_spinner('Checking for updates…') : null
 	const skill_names = to_check.map(([name]) => name)
 	const [batch_err, batch_data] = await repos_api.check_updates(skill_names)
+	const base_dir = skills_dir(is_global, project_root)
 
 	const results = []
 	if (batch_err) {
@@ -83,7 +86,6 @@ const run = (args) => catch_errors('Refresh failed', async () => {
 		}
 	} else {
 		spinner?.succeed('Checked for updates')
-		const base_dir = skills_dir(is_global, project_root)
 		// Read all installed manifests in parallel to check for dependency drift
 		const manifest_map = {}
 		await Promise.all(to_check.map(async ([name]) => {
@@ -115,21 +117,51 @@ const run = (args) => catch_errors('Refresh failed', async () => {
 	const outdated = results.filter(r => r.status === 'outdated')
 	const up_to_date = results.filter(r => r.status === 'up-to-date')
 
-	// 2. If nothing to update, report and exit
+	// 2. Verify and repair symlinks for all skills (even when nothing is outdated)
+	const [, agents_data] = await resolve_agents(args.flags.agents)
+	const detected_agents = agents_data?.agents || []
+	let symlink_repairs = []
+	if (detected_agents.length > 0) {
+		const skills_to_check = []
+		for (const [name] of to_check) {
+			const short_name = name.split('/')[1] || name
+			const source_dir = skill_install_dir(base_dir, short_name)
+			const [, enabled] = await is_skill_enabled(short_name, detected_agents, is_global, project_root)
+			if (enabled) {
+				skills_to_check.push({ skill_name: short_name, source_dir })
+			}
+		}
+		if (skills_to_check.length > 0) {
+			const link_spinner = !args.flags.json ? create_spinner('Verifying symlinks…') : null
+			const [, repair_result] = await verify_and_repair_symlinks(skills_to_check, detected_agents, { global: is_global, project_root })
+			symlink_repairs = repair_result?.repaired || []
+			if (symlink_repairs.length > 0) {
+				link_spinner?.succeed(`Repaired ${symlink_repairs.length} symlink(s)`)
+			} else {
+				link_spinner?.succeed('All symlinks verified')
+			}
+		}
+	}
+
+	// 3. If nothing to update, report and exit
 	if (outdated.length === 0) {
 		if (args.flags.json) {
-			print_json({ data: { results, outdated_count: 0, up_to_date_count: up_to_date.length, updated: [], already_up_to_date: up_to_date.map(r => ({ skill: r.skill, version: r.installed })), errors: [] } })
+			print_json({ data: { results, outdated_count: 0, up_to_date_count: up_to_date.length, updated: [], already_up_to_date: up_to_date.map(r => ({ skill: r.skill, version: r.installed })), symlink_repairs, errors: [] } })
 			return
 		}
 		print_table(['Skill', 'Installed', 'Latest', 'Status'], results.map(r => [
 			r.skill, r.installed, r.latest, green(r.status)
 		]))
 		console.log()
-		print_success('All skills are up to date.')
+		if (symlink_repairs.length > 0) {
+			print_success(`All skills are up to date. Repaired ${symlink_repairs.length} symlink(s).`)
+		} else {
+			print_success('All skills are up to date.')
+		}
 		return
 	}
 
-	// 3. Show results table (non-json)
+	// 4. Show results table (non-json)
 	if (!args.flags.json) {
 		const status_colors = { 'up-to-date': green, 'outdated': yellow, 'no-access': yellow, 'error': red, 'unknown': (s) => s }
 		print_table(['Skill', 'Installed', 'Latest', 'Status'], results.map(r => [
@@ -139,7 +171,7 @@ const run = (args) => catch_errors('Refresh failed', async () => {
 		print_info(`${outdated.length} skill(s) can be updated.`)
 	}
 
-	// 4. Confirm update
+	// 5. Confirm update
 	const should_update = auto_yes || !process.stdin.isTTY
 	if (!should_update && !args.flags.json) {
 		const answer = await confirm_prompt(`\nUpdate ${outdated.length} skill(s)? [y/N] `)
@@ -149,8 +181,7 @@ const run = (args) => catch_errors('Refresh failed', async () => {
 		}
 	}
 
-	// 5. Detect local modifications for all outdated skills in parallel
-	const base_dir = skills_dir(is_global, project_root)
+	// 6. Detect local modifications for all outdated skills in parallel
 	const detections = await Promise.all(outdated.map(r => {
 		const lock_entry = skills[r.skill]
 		const short_name = r.skill.split('/')[1] || r.skill
@@ -168,7 +199,7 @@ const run = (args) => catch_errors('Refresh failed', async () => {
 		}
 	}
 
-	// 6. Update safe skills
+	// 7. Update safe skills
 	const options = { global: is_global, fresh: true, agents: args.flags.agents || undefined, project_root }
 	const updated = []
 	const update_errors = []
@@ -187,7 +218,7 @@ const run = (args) => catch_errors('Refresh failed', async () => {
 		}
 	}
 
-	// 7. Output results
+	// 8. Output results
 	if (args.flags.json) {
 		print_json({
 			data: {

package/src/commands/search.js

@@ -46,6 +46,13 @@ const QUALITY_TIERS = [
 	{ min: 20, label: 'Low quality', color: yellow },
 ]
 
+const MATCH_QUALITY_LABELS = {
+	strong: { label: 'Strong match', color: cyan },
+	good: { label: 'Good match', color: cyan },
+	partial: { label: 'Partial match', color: yellow },
+	weak: { label: 'Weak match', color: yellow },
+}
+
 const get_quality_label = (score) => {
 	if (score == null) return null
 	for (const tier of QUALITY_TIERS) {
@@ -67,10 +74,12 @@ const format_smart_result = (item, index) => {
 	const name = `${item.workspace_slug}/${item.name}`
 	const stars = item.star_count || 0
 	const tier = get_quality_label(item.quality_score)
+	const match = item.match_quality ? MATCH_QUALITY_LABELS[item.match_quality] : null
 
 	const star_str = `★ ${stars}`
 	const quality_str = tier ? tier.color(tier.label) : ''
-	const meta_parts = [star_str, quality_str].filter(Boolean).join(' · ')
+	const match_str = match ? match.color(match.label) : ''
+	const meta_parts = [match_str, star_str, quality_str].filter(Boolean).join(' · ')
 
 	const num = `  ${String(index + 1).padStart(2)}. `
 	const name_and_meta = `${bold(name)}${meta_parts ? `  ${dim(meta_parts)}` : ''}`
@@ -114,6 +123,13 @@ const run_smart_search = (args, query, options) => catch_errors('Smart search fa
 		return
 	}
 
+	const has_strong_or_good = items.some(item =>
+		item.match_quality === 'strong' || item.match_quality === 'good'
+	)
+	const match_notice = !has_strong_or_good && items.length > 0
+		? 'No strong matches found. The results below are the closest available but may not match your intent.'
+		: null
+
 	if (args.flags.json) {
 		const mapped = items.map(item => ({
 			skill: `${item.workspace_slug}/${item.name}`,
@@ -126,17 +142,23 @@ const run_smart_search = (args, query, options) => catch_errors('Smart search fa
 			quality_score: item.quality_score != null ? item.quality_score : null,
 			quality_tier: get_quality_tier_name(item.quality_score),
 			relevance_score: item.relevance_score != null ? item.relevance_score : null,
+			match_quality: item.match_quality || null,
 			tags: item.tags || [],
 			download_count: item.download_count || 0,
 			created_at: item.created_at,
 			updated_at: item.updated_at,
 		}))
-		print_json({ data: { query, mode: 'smart', results: mapped, count: mapped.length } })
+		const data = { query, mode: 'smart', results: mapped, count: mapped.length }
+		if (match_notice) data.match_notice = match_notice
+		print_json({ data })
 		return
 	}
 
 	// Human-readable smart output
 	console.log(`\n${bold(`Skills for: "${query}"`)}\n`)
+	if (match_notice) {
+		console.log(`  ${yellow(match_notice)}\n`)
+	}
 	items.forEach((item, i) => {
 		console.log(format_smart_result(item, i))
 		if (i < items.length - 1) console.log('')

package/src/engine/installer.js

@@ -11,7 +11,7 @@ const { write_lock, update_lock_skills } = require('../lock/writer')
 const { skills_dir, tmp_dir, skill_install_dir, lock_root } = require('../config/paths')
 const { ensure_dir, remove_dir, file_exists, read_json } = require('../utils/fs')
 const { SKILL_JSON } = require('../constants')
-const { resolve_agents, link_to_agents } = require('../agents')
+const { resolve_agents, link_to_agents, verify_and_repair_symlinks } = require('../agents')
 const { is_skill_enabled } = require('../agents/status')
 const { create_spinner } = require('../ui/spinner')
 const { print_success, print_warn, print_info } = require('../ui/output')
@@ -42,6 +42,18 @@ const install = (skill, options = {}) => catch_errors('Install failed', async ()
 			if (exists) {
 				const [, valid] = locked.integrity ? await verify_integrity(install_dir, locked.integrity) : [null, true]
 				if (valid !== false) {
+					// Verify and repair symlinks even for already-installed skills
+					if (agents.length > 0) {
+						const name = skill.split('/')[1]
+						const [, enabled] = await is_skill_enabled(name, agents, is_global, project_root)
+						if (enabled) {
+							await verify_and_repair_symlinks(
+								[{ skill_name: name, source_dir: install_dir }],
+								agents,
+								{ global: is_global, project_root }
+							)
+						}
+					}
 					print_success(`${skill}@${locked.version} already installed`)
 					return {
 						skill,
@@ -91,6 +103,20 @@ const install = (skill, options = {}) => catch_errors('Install failed', async ()
 	}
 
 	if (packages_to_install.length === 0) {
+		// Verify and repair symlinks for all skipped packages
+		if (agents.length > 0) {
+			const skills_to_verify = []
+			for (const pkg of packages) {
+				const name = pkg.skill.split('/')[1]
+				const [, enabled] = await is_skill_enabled(name, agents, is_global, project_root)
+				if (enabled) {
+					skills_to_verify.push({ skill_name: name, source_dir: skill_install_dir(base_dir, name) })
+				}
+			}
+			if (skills_to_verify.length > 0) {
+				await verify_and_repair_symlinks(skills_to_verify, agents, { global: is_global, project_root })
+			}
+		}
 		spinner.succeed(`${skill}@${packages[0]?.version} already up to date`)
 		const skipped = packages.map(p => ({ skill: p.skill, version: p.version, reason: 'already installed' }))
 		return { skill, version: packages[0]?.version, no_op: true, installed: [], skipped, warnings: [], forced: [] }