happyskills 0.32.0 → 0.33.0

package/CHANGELOG.md

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

package/package.json

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