happyskills 0.31.1 → 0.33.0

package/CHANGELOG.md

@@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.33.0] - 2026-04-08
+
+### Added
+- Add `--smart` / `-S` flag to `search` command — semantic search using hybrid vector + full-text + quality ranking via `POST /repos:semantic-search`
+- Add `--limit` and `--min-quality` options to `search` (used with `--smart`)
+- Add quality tier labels (High quality / Good / Fair / Low quality), star counts, and tags to smart search output
+- Add `semantic_search()` API client function in `api/repos.js`
+- Add 429 rate limit handling to API client with `Retry-After` header parsing
+
+## [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.33.0",
 	"description": "Package manager for AI agent skills",
 	"license": "SEE LICENSE IN LICENSE",
 	"author": "Nicolas Dao <nic@cloudlesslabs.com> (https://cloudlesslabs.com)",

package/src/api/client.js

@@ -51,6 +51,16 @@ const request = (method, path, options = {}) => catch_errors(`API ${method} ${pa
 			throw new AuthError(err_msg)
 		}
 
+		if (res.status === 429) {
+			const retry_after = res.headers.get('retry-after')
+			const retry_msg = retry_after
+				? `API rate limit reached. Please wait ${retry_after} seconds and try again.`
+				: 'API rate limit reached. Please wait and try again.'
+			const err = new ApiError(retry_msg, 429, 'RATE_LIMITED')
+			err.retry_after = retry_after ? parseInt(retry_after) : null
+			throw err
+		}
+
 		throw new ApiError(err_msg, res.status, err_code)
 	}
 

package/src/api/repos.js

@@ -81,4 +81,20 @@ const get_blob = (owner, repo, sha) => catch_errors(`Get blob ${owner}/${repo}/$
 	return data
 })
 
-module.exports = { search, resolve_dependencies, clone, push, get_refs, get_repo, check_updates, del_repo, patch_repo, compare, get_blob }
+const semantic_search = (query, options = {}) => catch_errors('Semantic search failed', async () => {
+	const needs_auth = !!(options.workspace_slug || options.scope === 'mine' || options.scope === 'personal')
+	const body = {
+		q: query,
+		tags: options.tags ? options.tags.split(',').map(t => t.trim()).filter(Boolean) : null,
+		type: options.type || null,
+		limit: options.limit || 10,
+		min_stars: null,
+		workspace_slugs: options.workspace_slug ? options.workspace_slug.split(',').map(s => s.trim()).filter(Boolean) : null,
+		scope: options.workspace_slug ? null : (options.scope || null),
+	}
+	const [errors, data] = await client.post('/repos:semantic-search', body, { auth: needs_auth || false })
+	if (errors) throw errors[errors.length - 1]
+	return data
+})
+
+module.exports = { search, semantic_search, resolve_dependencies, clone, push, get_refs, get_repo, check_updates, del_repo, patch_repo, compare, get_blob }

package/src/commands/search.js

@@ -1,6 +1,7 @@
 const { error: { catch_errors, wrap_errors: e } } = require('puffy-core')
 const repos_api = require('../api/repos')
-const { print_help, print_table, print_json, print_info } = require('../ui/output')
+const { print_help, print_table, print_json, print_info, print_hint } = require('../ui/output')
+const { bold, dim, yellow, cyan, gray } = require('../ui/colors')
 const { exit_with_error, UsageError, AuthError } = require('../utils/errors')
 const { EXIT_CODES, VALID_SKILL_TYPES } = require('../constants')
 const { load_token } = require('../auth/token_store')
@@ -18,6 +19,9 @@ Options:
   --personal              Search only your personal workspace
   --tags <tags>           Filter by tags (comma-separated)
   --type <type>           Filter by type (skill, kit)
+  --smart, -S             Use semantic search (vector + text + quality ranking)
+  --limit <n>             Max results (default: 10, max: 50) — used with --smart
+  --min-quality <n>       Minimum quality score 0-100 — used with --smart
   --json                  Output as JSON
 
 Aliases: s
@@ -25,52 +29,127 @@ Aliases: s
 Examples:
   happyskills search deploy
   happyskills search --mine
+  happyskills search "REST API with Node.js" --smart
   happyskills search deploy --workspace acme
   happyskills search --type kit
-  happyskills s --personal --json`
-
-const run = (args) => catch_errors('Search failed', async () => {
-	if (args.flags._show_help) {
-		print_help(HELP_TEXT)
-		return process.exit(EXIT_CODES.SUCCESS)
+  happyskills s --personal --json
+  happyskills search "deploy to AWS" -S --limit 5`
+
+const QUALITY_TIERS = [
+	{ min: 80, label: 'High quality', color: cyan },
+	{ min: 60, label: 'Good', color: cyan },
+	{ min: 40, label: 'Fair', color: yellow },
+	{ min: 20, label: 'Low quality', color: yellow },
+]
+
+const get_quality_label = (score) => {
+	if (score == null) return null
+	for (const tier of QUALITY_TIERS) {
+		if (score >= tier.min) return tier
 	}
-
-	const query = args._.join(' ') || null
-	const { mine, personal, workspace, tags, type } = args.flags
-	const has_scope_flag = mine || personal || workspace
-
-	if (!query && !has_scope_flag && !tags && !type) {
-		throw new UsageError('Please provide a search query or use --mine, --personal, or --workspace.')
+	return null
+}
+
+const get_quality_tier_name = (score) => {
+	if (score == null) return null
+	if (score >= 80) return 'high'
+	if (score >= 60) return 'good'
+	if (score >= 40) return 'fair'
+	if (score >= 20) return 'low'
+	return null
+}
+
+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 star_str = `★ ${stars}`
+	const quality_str = tier ? tier.color(tier.label) : ''
+	const meta_parts = [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)}` : ''}`
+	const desc = item.description ? `      ${item.description}` : ''
+	const tags_line = item.tags && item.tags.length > 0
+		? `      ${dim('Tags: ' + item.tags.join(', '))}`
+		: ''
+
+	const lines = [`${num}${name_and_meta}`]
+	if (desc) lines.push(desc)
+	if (tags_line) lines.push(tags_line)
+	return lines.join('\n')
+}
+
+const run_smart_search = (args, query, options) => catch_errors('Smart search failed', async () => {
+	const limit = args.flags.limit ? parseInt(args.flags.limit) : 10
+	const capped_limit = Math.min(Math.max(limit, 1), 50)
+	const min_quality = args.flags['min-quality'] != null ? parseInt(args.flags['min-quality']) : null
+
+	const search_opts = { ...options, limit: capped_limit }
+	const [errors, results] = await repos_api.semantic_search(query, search_opts)
+	if (errors) throw e('Semantic search failed', errors)
+
+	let items = Array.isArray(results) ? results : (results?.repos || results?.items || [])
+
+	// Client-side quality filter (only when explicitly requested)
+	if (min_quality != null) {
+		items = items.filter(item =>
+			item.quality_score != null && item.quality_score >= min_quality
+		)
 	}
 
-	if (type && !VALID_SKILL_TYPES.includes(type)) {
-		throw new UsageError(`--type must be one of: ${VALID_SKILL_TYPES.join(', ')}`)
+	if (items.length === 0) {
+		if (args.flags.json) {
+			print_json({ data: { query, mode: 'smart', results: [], count: 0 } })
+			return
+		}
+		const msg = `No skills found for "${query}".`
+		print_info(msg)
+		print_hint('Try broader terms or remove filters.')
+		return
 	}
 
-	const scope = mine ? 'mine' : personal ? 'personal' : undefined
-
-	if (has_scope_flag) {
-		const [, token_data] = await load_token()
-		if (!token_data) {
-			throw new AuthError('Authentication required. Run `happyskills login` first.')
-		}
+	if (args.flags.json) {
+		const mapped = items.map(item => ({
+			skill: `${item.workspace_slug}/${item.name}`,
+			type: item.type || 'skill',
+			description: item.description || '',
+			version: item.latest_version || item.version || '-',
+			visibility: item.visibility || 'public',
+			workspace_slug: item.workspace_slug,
+			stars: item.star_count || 0,
+			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,
+			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 } })
+		return
 	}
 
-	const options = {}
-	if (scope) options.scope = scope
-	if (workspace) options.workspace = workspace
-	if (tags) options.tags = tags
-	if (type) options.type = type
+	// Human-readable smart output
+	console.log(`\n${bold(`Skills for: "${query}"`)}\n`)
+	items.forEach((item, i) => {
+		console.log(format_smart_result(item, i))
+		if (i < items.length - 1) console.log('')
+	})
+	console.log(`\n${gray(`Showing ${items.length} result${items.length === 1 ? '' : 's'}. Install with: happyskills install <owner>/<name>`)}\n`)
+})
 
+const run_keyword_search = (args, query, options) => catch_errors('Keyword search failed', async () => {
 	const [errors, results] = await repos_api.search(query, options)
 	if (errors) throw e('Search failed', errors)
 
 	const items = Array.isArray(results) ? results : (results?.repos || results?.items || [])
-	const effective_scope = scope || (has_scope_flag ? undefined : undefined)
+	const effective_scope = options.scope || 'all'
 
 	if (items.length === 0) {
 		if (args.flags.json) {
-			print_json({ data: { query, scope: effective_scope || 'all', results: [], count: 0 } })
+			print_json({ data: { query, scope: effective_scope, results: [], count: 0 } })
 			return
 		}
 		const context = query ? ` for "${query}"` : ''
@@ -86,7 +165,7 @@ const run = (args) => catch_errors('Search failed', async () => {
 			version: item.latest_version || item.version || '-',
 			visibility: item.visibility || 'public'
 		}))
-		print_json({ data: { query, scope: effective_scope || 'all', results: mapped, count: mapped.length } })
+		print_json({ data: { query, scope: effective_scope, results: mapped, count: mapped.length } })
 		return
 	}
 
@@ -102,6 +181,59 @@ const run = (args) => catch_errors('Search failed', async () => {
 	})
 
 	print_table(['Skill', 'Description', 'Version'], rows)
+})
+
+const run = (args) => catch_errors('Search failed', async () => {
+	if (args.flags._show_help) {
+		print_help(HELP_TEXT)
+		return process.exit(EXIT_CODES.SUCCESS)
+	}
+
+	const query = args._.join(' ') || null
+	const { mine, personal, workspace, tags, type } = args.flags
+	const is_smart = !!(args.flags.smart || args.flags.S)
+	const has_scope_flag = mine || personal || workspace
+
+	if (is_smart && !query) {
+		throw new UsageError('--smart requires a search query.')
+	}
+
+	if (!query && !has_scope_flag && !tags && !type) {
+		throw new UsageError('Please provide a search query or use --mine, --personal, or --workspace.')
+	}
+
+	if (type && !VALID_SKILL_TYPES.includes(type)) {
+		throw new UsageError(`--type must be one of: ${VALID_SKILL_TYPES.join(', ')}`)
+	}
+
+	const scope = mine ? 'mine' : personal ? 'personal' : undefined
+
+	if (has_scope_flag) {
+		const [, token_data] = await load_token()
+		if (!token_data) {
+			throw new AuthError('Authentication required. Run `happyskills login` first.')
+		}
+	}
+
+	const options = {}
+	if (scope) options.scope = scope
+	if (workspace) options.workspace_slug = workspace
+	if (tags) options.tags = tags
+	if (type) options.type = type
+
+	if (is_smart) {
+		const [errors] = await run_smart_search(args, query, options)
+		if (errors) throw e('Smart search failed', errors)
+	} else {
+		// Keyword search uses 'workspace' not 'workspace_slug'
+		const kw_options = { ...options }
+		if (options.workspace_slug) {
+			kw_options.workspace = options.workspace_slug
+			delete kw_options.workspace_slug
+		}
+		const [errors] = await run_keyword_search(args, query, kw_options)
+		if (errors) throw e('Search failed', errors)
+	}
 }).then(([errors]) => { if (errors) { exit_with_error(errors); return } })
 
 module.exports = { run }

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')
+	})
+})