happyskills 0.31.0 → 0.32.0

package/CHANGELOG.md

@@ -7,6 +7,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.32.0] - 2026-04-07
+
+### Added
+- Add changelog version validation to `validate` and `publish` — verifies that the top `## [x.y.z]` entry in CHANGELOG.md matches the `skill.json` version before publishing, preventing stale or missing changelog releases
+
+## [0.31.1] - 2026-04-07
+
+### Fixed
+- Fix `check` and `update --all` ignoring kit dependencies and transitive dependencies — previously only root-level skills were checked, hiding available updates for skills installed via kits or as dependencies of other skills
+- Fix pre-existing test failure in lock reader caused by lazy `require` of `print_warn` breaking under Jest environment teardown
+
+### Added
+- Add `via` field to `check` and `update` JSON output showing which parent skill or kit pulled in each dependency (`null` for directly installed skills)
+- Add "Via" column to `check` table output (only shown when dependencies are present)
+
 ## [0.31.0] - 2026-04-06
 
 ### Added

package/package.json

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

package/src/commands/check.js

@@ -1,5 +1,5 @@
 const { error: { catch_errors, wrap_errors: e } } = require('puffy-core')
-const { read_lock, get_all_locked_skills } = require('../lock/reader')
+const { read_lock, get_all_locked_skills, get_via } = require('../lock/reader')
 const repos_api = require('../api/repos')
 const { print_help, print_table, print_json, print_info, print_success, print_warn, print_hint, code } = require('../ui/output')
 const { green, yellow, red } = require('../ui/colors')
@@ -44,15 +44,15 @@ const run = (args) => catch_errors('Check failed', async () => {
 
 	const target_skill = args._[0]
 	const to_check = target_skill
-		? entries.filter(([name]) => name === target_skill)
-		: entries.filter(([, data]) => data.requested_by?.includes('__root__'))
+		? entries.filter(([name, data]) => name === target_skill && data !== null)
+		: entries.filter(([, data]) => data !== null)
 
 	if (to_check.length === 0) {
 		if (args.flags.json) {
 			print_json({ data: { results: [], outdated_count: 0, up_to_date_count: 0 } })
 			return
 		}
-		print_info(target_skill ? `${target_skill} is not installed.` : 'No directly installed skills found.')
+		print_info(target_skill ? `${target_skill} is not installed.` : 'No installed skills found.')
 		return
 	}
 
@@ -62,25 +62,26 @@ const run = (args) => catch_errors('Check failed', async () => {
 	const results = []
 	if (batch_err) {
 		for (const [name, data] of to_check) {
-			results.push({ skill: name, installed: data.version, latest: 'error', status: 'error' })
+			results.push({ skill: name, installed: data.version, latest: 'error', status: 'error', via: get_via(data) })
 		}
 	} else {
 		for (const [name, data] of to_check) {
 			const info = batch_data?.results?.[name]
+			const via = get_via(data)
 			const has_conflicts = (data.conflict_files || []).length > 0
 			if (has_conflicts) {
-				results.push({ skill: name, installed: data.version, latest: info?.latest_version || '-', status: 'conflicts' })
+				results.push({ skill: name, installed: data.version, latest: info?.latest_version || '-', status: 'conflicts', via })
 			} else if (info?.access_denied) {
-				results.push({ skill: name, installed: data.version, latest: '-', status: 'no-access' })
+				results.push({ skill: name, installed: data.version, latest: '-', status: 'no-access', via })
 			} else if (!info || !info.latest_version) {
-				results.push({ skill: name, installed: data.version, latest: '-', status: 'unknown' })
+				results.push({ skill: name, installed: data.version, latest: '-', status: 'unknown', via })
 			} else if (data.base_commit && info.commit && data.base_commit !== info.commit) {
-				results.push({ skill: name, installed: data.version, latest: info.latest_version, status: 'outdated' })
+				results.push({ skill: name, installed: data.version, latest: info.latest_version, status: 'outdated', via })
 			} else if (!data.base_commit && info.latest_version !== data.version) {
 				// Fallback to version comparison for old lock files without base_commit
-				results.push({ skill: name, installed: data.version, latest: info.latest_version, status: 'outdated' })
+				results.push({ skill: name, installed: data.version, latest: info.latest_version, status: 'outdated', via })
 			} else {
-				results.push({ skill: name, installed: data.version, latest: info.latest_version, status: 'up-to-date' })
+				results.push({ skill: name, installed: data.version, latest: info.latest_version, status: 'up-to-date', via })
 			}
 		}
 	}
@@ -102,14 +103,21 @@ const run = (args) => catch_errors('Check failed', async () => {
 		'unknown': (s) => s
 	}
 
-	const rows = results.map(r => [
-		r.skill,
-		r.installed,
-		r.latest,
-		(status_colors[r.status] || ((s) => s))(r.status)
-	])
-
-	print_table(['Skill', 'Installed', 'Latest', 'Status'], rows)
+	const has_via = results.some(r => r.via)
+	const rows = results.map(r => {
+		const row = [
+			r.skill,
+			r.installed,
+			r.latest,
+			(status_colors[r.status] || ((s) => s))(r.status)
+		]
+		if (has_via) row.push(r.via || '-')
+		return row
+	})
+
+	const headers = ['Skill', 'Installed', 'Latest', 'Status']
+	if (has_via) headers.push('Via')
+	print_table(headers, rows)
 
 	const outdated = results.filter(r => r.status === 'outdated')
 	const conflicts = results.filter(r => r.status === 'conflicts')
@@ -121,7 +129,7 @@ const run = (args) => catch_errors('Check failed', async () => {
 	}
 	if (outdated.length > 0) {
 		console.log()
-		print_info(`Run ${code('happyskills update')} to upgrade ${outdated.length} skill(s).`)
+		print_info(`Run ${code('happyskills update --all')} to upgrade ${outdated.length} skill(s).`)
 	} else if (conflicts.length === 0 && results.every(r => r.status === 'up-to-date')) {
 		console.log()
 		print_success('All skills are up to date.')

package/src/commands/update.js

@@ -1,7 +1,6 @@
-const path = require('path')
 const { error: { catch_errors, wrap_errors: e } } = require('puffy-core')
 const { install } = require('../engine/installer')
-const { read_lock, get_all_locked_skills } = require('../lock/reader')
+const { read_lock, get_all_locked_skills, get_via } = require('../lock/reader')
 const { detect_status } = require('../merge/detector')
 const { print_help, print_success, print_info, print_warn, print_json } = require('../ui/output')
 const { exit_with_error, UsageError } = require('../utils/errors')
@@ -48,7 +47,7 @@ const run = (args) => catch_errors('Update failed', async () => {
 
 	const to_update = target_skill
 		? [[target_skill, skills[target_skill]]]
-		: Object.entries(skills).filter(([, data]) => data.requested_by?.includes('__root__'))
+		: Object.entries(skills).filter(([, data]) => data !== null)
 
 	if (to_update.length === 0) {
 		if (args.flags.json) {
@@ -96,9 +95,9 @@ const run = (args) => catch_errors('Update failed', async () => {
 		const [errors, result] = await install(name, options)
 		if (errors) throw e(`Update ${name} failed`, errors)
 		if (!result.no_op) {
-			updated.push({ skill: name, from: before_version, to: result.version })
+			updated.push({ skill: name, from: before_version, to: result.version, via: get_via(data) })
 		} else {
-			already_up_to_date.push({ skill: name, version: result.version })
+			already_up_to_date.push({ skill: name, version: result.version, via: get_via(data) })
 		}
 	}
 

package/src/commands/validate.js

@@ -5,6 +5,7 @@ const { validate_skill_json } = require('../validation/skill_json_rules')
 const { validate_cross } = require('../validation/cross_rules')
 const { validate_no_conflict_markers } = require('../validation/conflict_marker_rules')
 const { validate_file_sizes } = require('../validation/file_size_rules')
+const { validate_changelog_version } = require('../validation/changelog_rules')
 const { file_exists, read_json } = require('../utils/fs')
 const { skills_dir, find_project_root } = require('../config/paths')
 const { print_help, print_json } = require('../ui/output')
@@ -150,8 +151,10 @@ const run = (args) => catch_errors('Validate failed', async () => {
 	if (marker_err) throw marker_err
 	const [size_err, size_results] = await validate_file_sizes(skill_dir)
 	if (size_err) throw size_err
+	const [cl_err, cl_results] = await validate_changelog_version(skill_dir, json_data.manifest)
+	if (cl_err) throw cl_err
 
-	const all_results = [...md_data.results, ...json_data.results, ...cross_results, ...marker_results, ...size_results]
+	const all_results = [...md_data.results, ...json_data.results, ...cross_results, ...marker_results, ...size_results, ...cl_results]
 	const type_label = is_kit ? ' [kit]' : ''
 
 	if (args.flags.json) {

package/src/lock/reader.js

@@ -2,6 +2,7 @@ const { error: { catch_errors } } = require('puffy-core')
 const { read_json } = require('../utils/fs')
 const { lock_file_path } = require('../config/paths')
 const { LOCK_VERSION } = require('../constants')
+const { print_warn } = require('../ui/output')
 
 const read_lock = (project_root) => catch_errors('Failed to read lock file', async () => {
 	const lock_path = lock_file_path(project_root)
@@ -9,7 +10,6 @@ const read_lock = (project_root) => catch_errors('Failed to read lock file', asy
 	if (errors) return null
 
 	if (data.lockVersion !== LOCK_VERSION) {
-		const { print_warn } = require('../ui/output')
 		print_warn(`Lock file version mismatch (found ${data.lockVersion}, expected ${LOCK_VERSION}). Consider running with --fresh.`)
 	}
 
@@ -26,4 +26,10 @@ const get_all_locked_skills = (lock_data) => {
 	return lock_data.skills
 }
 
-module.exports = { read_lock, get_locked_skill, get_all_locked_skills }
+const get_via = (data) => {
+	const requester = data?.requested_by?.[0]
+	if (!requester || requester === '__root__') return null
+	return requester
+}
+
+module.exports = { read_lock, get_locked_skill, get_all_locked_skills, get_via }

package/src/lock/reader.test.js

@@ -5,7 +5,7 @@ const os = require('os')
 const path = require('path')
 const fs = require('fs')
 
-const { read_lock, get_locked_skill, get_all_locked_skills } = require('./reader')
+const { read_lock, get_locked_skill, get_all_locked_skills, get_via } = require('./reader')
 const { LOCK_VERSION } = require('../constants')
 
 // ─── helpers ──────────────────────────────────────────────────────────────────
@@ -126,3 +126,39 @@ describe('get_all_locked_skills', () => {
 		assert.deepEqual(get_all_locked_skills({ skills: {} }), {})
 	})
 })
+
+// ─── get_via ────────────────────────────────────────────────────────────────
+
+describe('get_via', () => {
+	it('returns null for a directly installed skill (__root__)', () => {
+		assert.strictEqual(get_via({ requested_by: ['__root__'] }), null)
+	})
+
+	it('returns the parent skill name for a dependency', () => {
+		assert.strictEqual(get_via({ requested_by: ['acme/deploy-aws'] }), 'acme/deploy-aws')
+	})
+
+	it('returns the kit name for a kit dependency', () => {
+		assert.strictEqual(get_via({ requested_by: ['acme/_kit-react'] }), 'acme/_kit-react')
+	})
+
+	it('returns the first requester when multiple exist', () => {
+		assert.strictEqual(get_via({ requested_by: ['acme/foo', 'acme/bar'] }), 'acme/foo')
+	})
+
+	it('returns null when requested_by is empty', () => {
+		assert.strictEqual(get_via({ requested_by: [] }), null)
+	})
+
+	it('returns null when requested_by is missing', () => {
+		assert.strictEqual(get_via({}), null)
+	})
+
+	it('returns null when data is null', () => {
+		assert.strictEqual(get_via(null), null)
+	})
+
+	it('returns null when data is undefined', () => {
+		assert.strictEqual(get_via(undefined), null)
+	})
+})

package/src/validation/changelog_rules.js

@@ -0,0 +1,64 @@
+const fs = require('fs')
+const path = require('path')
+const { error: { catch_errors } } = require('puffy-core')
+
+const CHANGELOG = 'CHANGELOG.md'
+const VERSION_HEADING_RE = /^##\s+\[(\d+\.\d+\.\d+[^\]]*)\]/
+
+/**
+ * Validates that the CHANGELOG.md top version entry matches skill.json version.
+ * Only runs when both CHANGELOG.md and skill.json exist — skills without a
+ * changelog are not penalised.
+ *
+ * @param {string} skill_dir - Absolute path to the skill directory
+ * @param {object|null} manifest - Parsed skill.json (may be null if missing)
+ * @returns {[errors, results[]]}
+ */
+const validate_changelog_version = (skill_dir, manifest) => catch_errors('Failed to validate changelog', async () => {
+	const changelog_path = path.join(skill_dir, CHANGELOG)
+	let content
+	try { content = await fs.promises.readFile(changelog_path, 'utf-8') } catch { return [] }
+
+	// No manifest means skill.json is missing — other rules already flag that
+	if (!manifest || !manifest.version) return []
+
+	const lines = content.split('\n')
+	let first_version = null
+	for (const line of lines) {
+		const m = line.match(VERSION_HEADING_RE)
+		if (m) {
+			first_version = m[1]
+			break
+		}
+	}
+
+	if (!first_version) {
+		return [{
+			file: CHANGELOG,
+			field: null,
+			rule: 'changelog_has_version',
+			severity: 'warning',
+			message: 'CHANGELOG.md exists but has no version entry (expected ## [x.y.z])'
+		}]
+	}
+
+	if (first_version !== manifest.version) {
+		return [{
+			file: CHANGELOG,
+			field: 'version',
+			rule: 'changelog_version_match',
+			severity: 'error',
+			message: `CHANGELOG.md top version [${first_version}] does not match skill.json version ${manifest.version}`
+		}]
+	}
+
+	return [{
+		file: CHANGELOG,
+		field: null,
+		rule: 'changelog_version_match',
+		severity: 'pass',
+		message: `CHANGELOG.md version matches skill.json (${manifest.version})`
+	}]
+})
+
+module.exports = { validate_changelog_version }

package/src/validation/changelog_rules.test.js

@@ -0,0 +1,90 @@
+const { describe, it, beforeEach, afterEach } = require('node:test')
+const assert = require('node:assert/strict')
+const fs = require('fs')
+const path = require('path')
+const os = require('os')
+const { validate_changelog_version } = require('./changelog_rules')
+
+const make_temp_dir = () => fs.mkdtempSync(path.join(os.tmpdir(), 'changelog-test-'))
+const clean = (dir) => fs.rmSync(dir, { recursive: true, force: true })
+
+describe('validate_changelog_version', () => {
+	let dir
+
+	beforeEach(() => { dir = make_temp_dir() })
+	afterEach(() => { clean(dir) })
+
+	it('returns empty when no CHANGELOG.md exists', async () => {
+		const [err, results] = await validate_changelog_version(dir, { version: '1.0.0' })
+		assert.strictEqual(err, null)
+		assert.strictEqual(results.length, 0)
+	})
+
+	it('returns empty when manifest is null', async () => {
+		fs.writeFileSync(path.join(dir, 'CHANGELOG.md'), '## [1.0.0] - 2026-01-01\n')
+		const [err, results] = await validate_changelog_version(dir, null)
+		assert.strictEqual(err, null)
+		assert.strictEqual(results.length, 0)
+	})
+
+	it('returns empty when manifest has no version', async () => {
+		fs.writeFileSync(path.join(dir, 'CHANGELOG.md'), '## [1.0.0] - 2026-01-01\n')
+		const [err, results] = await validate_changelog_version(dir, {})
+		assert.strictEqual(err, null)
+		assert.strictEqual(results.length, 0)
+	})
+
+	it('returns pass when versions match', async () => {
+		fs.writeFileSync(path.join(dir, 'CHANGELOG.md'), '# Changelog\n\n## [2.1.0] - 2026-04-07\n\n### Added\n- Something\n')
+		const [err, results] = await validate_changelog_version(dir, { version: '2.1.0' })
+		assert.strictEqual(err, null)
+		assert.strictEqual(results.length, 1)
+		assert.strictEqual(results[0].severity, 'pass')
+		assert.strictEqual(results[0].rule, 'changelog_version_match')
+	})
+
+	it('returns error when versions mismatch', async () => {
+		fs.writeFileSync(path.join(dir, 'CHANGELOG.md'), '# Changelog\n\n## [1.0.0] - 2026-01-01\n')
+		const [err, results] = await validate_changelog_version(dir, { version: '1.1.0' })
+		assert.strictEqual(err, null)
+		assert.strictEqual(results.length, 1)
+		assert.strictEqual(results[0].severity, 'error')
+		assert.strictEqual(results[0].rule, 'changelog_version_match')
+		assert.ok(results[0].message.includes('[1.0.0]'))
+		assert.ok(results[0].message.includes('1.1.0'))
+	})
+
+	it('uses the first version heading, not later ones', async () => {
+		const content = '# Changelog\n\n## [2.0.0] - 2026-04-07\n\n## [1.0.0] - 2026-01-01\n'
+		fs.writeFileSync(path.join(dir, 'CHANGELOG.md'), content)
+		const [err, results] = await validate_changelog_version(dir, { version: '2.0.0' })
+		assert.strictEqual(err, null)
+		assert.strictEqual(results[0].severity, 'pass')
+	})
+
+	it('skips [Unreleased] heading and finds the first real version', async () => {
+		const content = '# Changelog\n\n## [Unreleased]\n\n## [1.5.0] - 2026-03-01\n'
+		fs.writeFileSync(path.join(dir, 'CHANGELOG.md'), content)
+		const [err, results] = await validate_changelog_version(dir, { version: '1.5.0' })
+		assert.strictEqual(err, null)
+		assert.strictEqual(results[0].severity, 'pass')
+	})
+
+	it('returns warning when changelog has no version entries', async () => {
+		fs.writeFileSync(path.join(dir, 'CHANGELOG.md'), '# Changelog\n\nNothing here yet.\n')
+		const [err, results] = await validate_changelog_version(dir, { version: '1.0.0' })
+		assert.strictEqual(err, null)
+		assert.strictEqual(results.length, 1)
+		assert.strictEqual(results[0].severity, 'warning')
+		assert.strictEqual(results[0].rule, 'changelog_has_version')
+	})
+
+	it('handles changelog with only [Unreleased] heading', async () => {
+		fs.writeFileSync(path.join(dir, 'CHANGELOG.md'), '# Changelog\n\n## [Unreleased]\n\n- WIP stuff\n')
+		const [err, results] = await validate_changelog_version(dir, { version: '1.0.0' })
+		assert.strictEqual(err, null)
+		assert.strictEqual(results.length, 1)
+		assert.strictEqual(results[0].severity, 'warning')
+		assert.strictEqual(results[0].rule, 'changelog_has_version')
+	})
+})