happyskills 0.31.1 → 0.32.0

package/CHANGELOG.md

@@ -7,6 +7,11 @@ 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

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "happyskills",
-	"version": "0.31.1",
+	"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/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/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')
+	})
+})