happyskills 0.41.0 → 0.43.0

package/CHANGELOG.md

@@ -7,6 +7,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.43.0] - 2026-05-07
+
+### Added
+- Route the default `search` path to the new `POST /repos:search` dispatcher (API v2.9.0+). The same `happyskills search foo` command now picks the right strategy automatically based on the query shape — natural-language queries go to semantic hybrid search (existing behavior, unchanged), single dashed/word tokens like `deploy-aws` go to typo-tolerant fuzzy slug search, and `workspace/skill` form like `letta-ai/remotion-best-practices` goes to fuzzy scoped search (typo-tolerant on both halves). The CLI doesn't pre-decide the mode — it sends the raw query and the server picks. Implementation: new `dispatch_search` in `cli/src/api/repos.js`; default branch in `cli/src/commands/search.js` now calls it.
+- Surface the chosen mode in human output. The result header now shows a `[mode]` chip (e.g. `Skills for: "deploy-aws"  [fuzzy_slug]`) so users can see how the dispatcher routed without inspecting JSON. JSON output gains a top-level `mode` field, plus `workspace_match` when the request was `fuzzy_scoped`.
+- Add an honest-failure path for `workspace/skill` lookups when the workspace doesn't match. Typing `happyskills search helo/do-something` (where `helo` doesn't fuzzy-match any workspace) now prints `No workspace matched "helo".` with a hint to remove the prefix to search globally. Previously a workspace-fuzzy miss would have silently returned nothing useful — the new path explains *why*.
+
+### Changed
+- Rewrite the `search` command's help text to describe the three+list modes explicitly, with one example query per mode. The `--exact` flag is preserved as the explicit "skip the smart routing, just do keyword FTS" escape hatch.
+- Trust the server's `match_notice` field instead of recomputing it client-side. The "No strong matches found..." notice was previously recomputed by the CLI based on `match_quality` — which produced a misleading warning for fuzzy-mode results (a tier-1 partial match is exactly what the user typed, not "may not match your intent"). The server now decides whether to emit a notice (only for `semantic` and `fuzzy_scoped` workspace-not-found cases); the CLI displays whatever it sends, verbatim.
+- The legacy `semantic_search` API client function is now a deprecated alias of `dispatch_search` that forces `mode='semantic'` — kept for any internal callers that still reference it. New code should use `dispatch_search`.
+
+## [0.42.0] - 2026-05-05
+
+### Added
+- Surface the new server-side cluster info from API v2.6.0 in `search` output. Human output gains a `+N similar` chip in the result meta line (alongside match quality, stars, and quality tier) when the row represents a duplicate cluster. JSON output gains two additive fields per result: `similar_count` (integer) and `similar_repos` (array of cluster members, each with a per-member `similarity` score). Internal refactor: extracted `to_smart_json()` so cluster members serialise with the same shape as top-level results.
+
 ## [0.41.0] - 2026-05-04
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "happyskills",
-	"version": "0.41.0",
+	"version": "0.43.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/repos.js

@@ -87,9 +87,32 @@ const get_tree = (owner, repo, ref) => catch_errors(`Get tree for ${owner}/${rep
 	return data
 })
 
+// POST /repos:search — intelligent dispatcher.
+// The server inspects `q` and routes to semantic / fuzzy_slug / fuzzy_scoped
+// automatically. We pass the raw query through; trim + lowercase happens
+// server-side. Always sends auth — when logged in, accessible private skills
+// are included; when not, the client silently skips the auth header.
+const dispatch_search = (query, options = {}) => catch_errors('Search failed', async () => {
+	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:search', body, { auth: true })
+	if (errors) throw errors[errors.length - 1]
+	return data
+})
+
+// Deprecated alias — kept for backwards compatibility with older code paths.
+// Prefer `dispatch_search`. Forces mode='semantic' on the server.
 const semantic_search = (query, options = {}) => catch_errors('Semantic search failed', async () => {
 	const body = {
 		q: query,
+		mode: 'semantic',
 		tags: options.tags ? options.tags.split(',').map(t => t.trim()).filter(Boolean) : null,
 		type: options.type || null,
 		limit: options.limit || 10,
@@ -97,12 +120,9 @@ const semantic_search = (query, options = {}) => catch_errors('Semantic search f
 		workspace_slugs: options.workspace_slug ? options.workspace_slug.split(',').map(s => s.trim()).filter(Boolean) : null,
 		scope: options.workspace_slug ? null : (options.scope || null),
 	}
-	// Always attempt auth for smart search — if the user is logged in, the API
-	// returns public + accessible private skills. If not logged in, the client
-	// silently skips the auth header and the API defaults to public-only.
-	const [errors, data] = await client.post('/repos:semantic-search', body, { auth: true })
+	const [errors, data] = await client.post('/repos:search', body, { auth: true })
 	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, get_tree }
+module.exports = { search, dispatch_search, semantic_search, resolve_dependencies, clone, push, get_refs, get_repo, check_updates, del_repo, patch_repo, compare, get_blob, get_tree }

package/src/commands/search.js

@@ -8,10 +8,10 @@ const { load_token } = require('../auth/token_store')
 
 const HELP_TEXT = `Usage: happyskills search [query] [options]
 
-Search the skill registry.
-
-When a query is provided, smart search (semantic + quality ranking) is used by
-default. Use --exact to fall back to keyword-only matching.
+Search the skill registry. The server picks the right strategy based on the
+query shape — natural-language goes to semantic, a single dashed word goes to
+fuzzy slug, and "workspace/skill" form goes to fuzzy scoped (both parts are
+typo-tolerant). Use --exact to force keyword-only FTS instead.
 
 Arguments:
   query               Search term (optional with --mine, --personal, or --workspace)
@@ -22,7 +22,7 @@ Options:
   --personal              Search only your personal workspace
   --tags <tags>           Filter by tags (comma-separated)
   --type <type>           Filter by type (skill, kit)
-  --exact                 Use keyword-only matching instead of smart search
+  --exact                 Force keyword-only FTS matching (skip smart routing)
   --limit <n>             Max results (required, 1-50)
   --min-quality <n>       Minimum quality score 0-100
   --json                  Output as JSON
@@ -30,14 +30,13 @@ Options:
 Aliases: s
 
 Examples:
-  happyskills search deploy --limit 10
-  happyskills search "REST API with Node.js" --limit 10
+  happyskills search "deploy infra to AWS" --limit 10     # → semantic
+  happyskills search deploy-aws --limit 10                # → fuzzy slug (typo-tolerant)
+  happyskills search letta-ai/remotion --limit 5          # → fuzzy scoped
   happyskills search --mine --limit 20
   happyskills search deploy --workspace acme --limit 50
   happyskills search --type kit --limit 10
-  happyskills s --personal --json --limit 20
-  happyskills search "deploy to AWS" --limit 5
-  happyskills search deploy --exact --limit 10`
+  happyskills search deploy --exact --limit 10            # → keyword FTS only`
 
 const QUALITY_TIERS = [
 	{ min: 80, label: 'High quality', color: cyan },
@@ -79,7 +78,8 @@ const format_smart_result = (item, index) => {
 	const star_str = `★ ${stars}`
 	const quality_str = tier ? tier.color(tier.label) : ''
 	const match_str = match ? match.color(match.label) : ''
-	const meta_parts = [match_str, star_str, quality_str].filter(Boolean).join(' · ')
+	const similar_str = item.similar_count ? `+${item.similar_count} similar` : ''
+	const meta_parts = [match_str, star_str, quality_str, similar_str].filter(Boolean).join(' · ')
 
 	const num = `  ${String(index + 1).padStart(2)}. `
 	const name_and_meta = `${bold(name)}${meta_parts ? `  ${dim(meta_parts)}` : ''}`
@@ -94,16 +94,39 @@ const format_smart_result = (item, index) => {
 	return lines.join('\n')
 }
 
+const to_smart_json = (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,
+	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,
+})
+
 const run_smart_search = (args, query, options) => catch_errors('Smart search failed', async () => {
 	const limit = parseInt(args.flags.limit)
 	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)
+	const [errors, response] = await repos_api.dispatch_search(query, search_opts)
+	if (errors) throw e('Search failed', errors)
 
-	let items = Array.isArray(results) ? results : (results?.repos || results?.items || [])
+	// Response shape: { data: [...], mode, workspace_match, match_notice }
+	const items_raw = Array.isArray(response) ? response : (response?.data || response?.repos || response?.items || [])
+	let items = items_raw
+	const mode = response?.mode || null
+	const workspace_match = response?.workspace_match
+	const server_match_notice = response?.match_notice || null
 
 	// Client-side quality filter (only when explicitly requested)
 	if (min_quality != null) {
@@ -114,48 +137,45 @@ const run_smart_search = (args, query, options) => catch_errors('Smart search fa
 
 	if (items.length === 0) {
 		if (args.flags.json) {
-			print_json({ data: { query, mode: 'smart', results: [], count: 0 } })
+			const data = { query, mode, results: [], count: 0 }
+			if (workspace_match !== undefined) data.workspace_match = workspace_match
+			if (server_match_notice) data.match_notice = server_match_notice
+			print_json({ data })
 			return
 		}
-		const msg = `No skills found for "${query}".`
-		print_info(msg)
-		print_hint('Try broader terms or remove filters.')
+		if (mode === 'fuzzy_scoped' && workspace_match === null) {
+			const ws_part = query.includes('/') ? query.split('/')[0] : query
+			print_info(`No workspace matched "${ws_part}".`)
+			print_hint('Check spelling, or remove the workspace prefix to search globally.')
+		} else {
+			print_info(`No skills found for "${query}".`)
+			print_hint('Try broader terms or remove filters.')
+		}
 		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
+	// Trust the server's notice — only emitted for semantic mode where
+	// intent-matching is the relevant concept. Fuzzy modes return null.
+	const match_notice = server_match_notice
 
 	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,
-			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,
+			...to_smart_json(item),
+			similar_count: item.similar_count || 0,
+			similar_repos: (item.similar_repos || []).map(member => ({
+				...to_smart_json(member),
+				similarity: member.similarity != null ? member.similarity : null,
+			})),
 		}))
-		const data = { query, mode: 'smart', results: mapped, count: mapped.length }
+		const data = { query, mode, results: mapped, count: mapped.length }
+		if (workspace_match !== undefined) data.workspace_match = workspace_match
 		if (match_notice) data.match_notice = match_notice
 		print_json({ data })
 		return
 	}
 
-	// Human-readable smart output
-	console.log(`\n${bold(`Skills for: "${query}"`)}\n`)
+	// Human-readable output
+	console.log(`\n${bold(`Skills for: "${query}"`)}${mode ? dim(`  [${mode}]`) : ''}\n`)
 	if (match_notice) {
 		console.log(`  ${yellow(match_notice)}\n`)
 	}