happyskills 1.6.0 → 1.7.0

package/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [1.7.0] - 2026-06-04
+
+### Added
+
+- `search` now exposes `created_at` / `updated_at` on every result and accepts `--sort <relevance|recent>`. `--sort recent` orders results newest-created first — pair it with `--mine` to list your latest-created skills (`happyskills search --mine --sort recent --limit 100`); human output shows a `Created` column. Sorts the fetched page, so pass a sufficient `--limit`. No API change required.
+
 ## [1.6.0] - 2026-06-04
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "happyskills",
-	"version": "1.6.0",
+	"version": "1.7.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/search.js

@@ -34,6 +34,8 @@ Options:
                           Carried across re-searches in the clarification flow.
   --limit <n>             Max results (required, 1-50)
   --min-quality <n>       Minimum quality score 0-100
+  --sort <order>          relevance (default) | recent (newest-created first).
+                          Sorts the fetched page — pass a sufficient --limit.
   --json                  Output as JSON
 
 Aliases: s
@@ -43,6 +45,7 @@ Examples:
   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 --mine --sort recent --limit 100     # → your latest-created skills
   happyskills search --favorites --limit 20                # → your starred skills
   happyskills search deploy --favorites --limit 10         # → favorites matching "deploy"
   happyskills search deploy --workspace acme --limit 50
@@ -226,6 +229,10 @@ const run_smart_search = (args, query, options) => catch_errors('Smart search fa
 		)
 	}
 
+	// --sort recent: re-order newest-created first (the smart `data` shape
+	// already carries created_at). Sorts the fetched page.
+	if (args.flags.sort === 'recent') items = sort_by_created_desc(items)
+
 	const next_step = build_search_next_step(response, query, { with_rerank, clarification_turns_used })
 
 	// Telemetry beacons (fire-and-forget). Spec § 5.1 + § 5.3.
@@ -329,12 +336,24 @@ const run_smart_search = (args, query, options) => catch_errors('Smart search fa
 	console.log(`\n${gray(`Showing ${items.length} result${items.length === 1 ? '' : 's'}. Install with: happyskills install <owner>/<name>`)}\n`)
 })
 
+// Sort a result set newest-created first. Items without a created_at sink to the
+// bottom. Pure — returns a new array. Used by --sort recent.
+const sort_by_created_desc = (items) => items.slice().sort((a, b) => {
+	const da = a.created_at ? new Date(a.created_at).getTime() : 0
+	const db = b.created_at ? new Date(b.created_at).getTime() : 0
+	return db - da
+})
+
 const run_keyword_search = (args, query, options, { is_exact } = {}) => 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 || [])
+	let items = Array.isArray(results) ? results : (results?.repos || results?.items || [])
 	const effective_scope = options.scope || 'all'
+	// --sort recent: order by creation date (newest first). Sorts the fetched
+	// page, so pass a --limit large enough to cover the set you care about.
+	const sort_recent = args.flags.sort === 'recent'
+	if (sort_recent) items = sort_by_created_desc(items)
 
 	if (items.length === 0) {
 		if (args.flags.json) {
@@ -354,26 +373,31 @@ const run_keyword_search = (args, query, options, { is_exact } = {}) => catch_er
 			type: item.type || 'skill',
 			description: item.description || '',
 			version: item.latest_version || item.version || '-',
-			visibility: item.visibility || 'public'
+			visibility: item.visibility || 'public',
+			created_at: item.created_at || null,
+			updated_at: item.updated_at || null
 		}))
 		const data = { query, scope: effective_scope, results: mapped, count: mapped.length }
+		if (sort_recent) data.sort = 'recent'
 		if (is_exact) data.hint = 'Smart search (default) uses semantic matching for better results. Remove --exact to use it.'
 		print_json({ data })
 		return
 	}
 
+	// When sorting by creation date, swap the Description column for a Created
+	// column — that's the field the user is sorting on and wants to see.
+	const headers = sort_recent ? ['Skill', 'Created', 'Version'] : ['Skill', 'Description', 'Version']
 	const rows = items.map(item => {
 		const item_type = item.type || 'skill'
 		const name = `${item.owner || item.workspace_slug}/${item.name}`
 		const display_name = item_type === 'kit' ? `${name} [kit]` : name
-		return [
-			display_name,
-			item.description || '',
-			item.latest_version || item.version || '-'
-		]
+		const version = item.latest_version || item.version || '-'
+		return sort_recent
+			? [display_name, item.created_at ? String(item.created_at).slice(0, 10) : '-', version]
+			: [display_name, item.description || '', version]
 	})
 
-	print_table(['Skill', 'Description', 'Version'], rows)
+	print_table(headers, rows)
 })
 
 const run = (args) => catch_errors('Search failed', async () => {
@@ -402,6 +426,10 @@ const run = (args) => catch_errors('Search failed', async () => {
 		throw new UsageError('--limit is required. Specify the number of results you want (e.g. --limit 10).')
 	}
 
+	if (args.flags.sort != null && !['relevance', 'recent'].includes(args.flags.sort)) {
+		throw new UsageError('--sort must be one of: relevance, recent.')
+	}
+
 	if (type && !VALID_SKILL_TYPES.includes(type)) {
 		throw new UsageError(`--type must be one of: ${VALID_SKILL_TYPES.join(', ')}`)
 	}
@@ -467,6 +495,7 @@ const schema = {
 			{ name: 'clarification-turns-used',                 type: 'number',  default: 0,         description: 'Clarification budget already spent (0-2)' },
 			{ name: 'limit',                                    type: 'number',  required: true,     description: 'Max results (1-50)' },
 			{ name: 'min-quality',                              type: 'number',  default: undefined, description: 'Minimum quality score 0-100' },
+			{ name: 'sort',                                     type: 'string',  default: 'relevance', description: 'relevance (default) | recent (newest-created first; sorts the fetched page)' },
 			{ name: 'json',                                     type: 'boolean', default: false,     description: 'Output as JSON' },
 		],
 	},
@@ -490,7 +519,8 @@ const schema = {
 	examples: [
 		'happyskills search "deploy infra to AWS" --limit 10',
 		'happyskills search "deploy infra to AWS" --with-rerank --json --limit 50',
+		'happyskills search --mine --sort recent --limit 100',
 	],
 }
 
-module.exports = { run, build_search_next_step, schema }
+module.exports = { run, build_search_next_step, sort_by_created_desc, schema }

package/src/commands/search.test.js

@@ -11,13 +11,33 @@
 
 const { describe, it, afterEach } = require('node:test')
 const assert = require('node:assert/strict')
-const { build_search_next_step } = require('./search')
+const { build_search_next_step, sort_by_created_desc } = require('./search')
 const {
 	NEXT_STEP_KINDS,
 	NEXT_STEP_ACTIONS,
 	kind_for_action,
 } = require('../constants/next_step_actions')
 
+// --sort recent ordering (Phase B): newest created_at first, nulls last, pure.
+describe('sort_by_created_desc — --sort recent', () => {
+	it('orders newest-created first and sinks items with no created_at', () => {
+		const out = sort_by_created_desc([
+			{ name: 'a', created_at: '2026-05-01T00:00:00Z' },
+			{ name: 'b', created_at: '2026-06-01T00:00:00Z' },
+			{ name: 'c', created_at: null },
+			{ name: 'd', created_at: '2026-05-20T00:00:00Z' },
+		])
+		assert.deepEqual(out.map(x => x.name), ['b', 'd', 'a', 'c'])
+	})
+
+	it('is pure — does not mutate the input array', () => {
+		const input = [{ name: 'a', created_at: '2026-01-01T00:00:00Z' }, { name: 'b', created_at: '2026-02-01T00:00:00Z' }]
+		const before = input.map(x => x.name).join(',')
+		sort_by_created_desc(input)
+		assert.equal(input.map(x => x.name).join(','), before)
+	})
+})
+
 const is_empty = (o) => o && typeof o === 'object' && !Array.isArray(o) && Object.keys(o).length === 0
 
 const assert_envelope_next_step = (ns, expected_action, label) => {