happyskills 1.5.0 → 1.7.0

package/CHANGELOG.md

@@ -7,6 +7,18 @@ 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
+
+- Extend `stats` (all additive): `--group-by skill` on `--scope my_activity` (rank which skills *you* installed); a new `installs` metric on `--scope my_skills_reach` that counts total installs of your authored skills (you + others; bot excluded), with `--exclude-self` to drop your own. Availability warnings are now softer — suppressed for `--period` presets, terser for explicit `--from`. Requires API v5.4.0+.
+
 ## [1.5.0] - 2026-06-04
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "happyskills",
-	"version": "1.5.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) => {

package/src/commands/stats.js

@@ -15,10 +15,10 @@ const token_store = require('../auth/token_store')
 
 const METRICS_BY_SCOPE = {
 	my_activity:     ['installs', 'updates', 'searches', 'uninstalls'],
-	my_skills_reach: ['installs_by_others', 'distinct_installers'],
+	my_skills_reach: ['installs', 'installs_by_others', 'distinct_installers'],
 }
 const GROUP_BY_BY_SCOPE = {
-	my_activity:     ['none', 'day', 'week', 'month', 'surface'],
+	my_activity:     ['none', 'day', 'week', 'month', 'surface', 'skill'],
 	my_skills_reach: ['none', 'day', 'week', 'month', 'skill'],
 }
 const VALID_PRESETS = ['7d', '30d', '90d', '6mo', '12mo']
@@ -35,21 +35,25 @@ Two scopes:
 Options:
   --scope <scope>         my_activity | my_skills_reach (required)
   --metric <metric>       my_activity:     installs, updates, searches, uninstalls
-                          my_skills_reach: installs_by_others, distinct_installers
+                          my_skills_reach: installs (everyone), installs_by_others,
+                                           distinct_installers
   --period <preset>       ${VALID_PRESETS.join(' | ')}
   --from <ISO date>       Explicit window start (use instead of --period)
   --to <ISO date>         Explicit window end (default: now)
-  --group-by <bucket>     my_activity:     none, day, week, month, surface
+  --group-by <bucket>     my_activity:     none, day, week, month, surface, skill
                           my_skills_reach: none, day, week, month, skill
                           (default: none)
   --skill <owner/skill>   Limit my_skills_reach to one skill you authored
+  --exclude-self          my_skills_reach 'installs' only: exclude your own installs
+                          (installs counts you by default)
   --json                  Output as JSON envelope
 
 Examples:
   happyskills stats --scope my_activity --metric installs --period 30d
+  happyskills stats --scope my_activity --metric installs --period 30d --group-by skill
   happyskills stats --scope my_activity --metric searches --period 90d --group-by week --json
-  happyskills stats --scope my_skills_reach --metric distinct_installers --period 12mo
-  happyskills stats --scope my_skills_reach --metric installs_by_others --period 12mo --group-by skill
+  happyskills stats --scope my_skills_reach --metric installs --period 12mo --group-by skill
+  happyskills stats --scope my_skills_reach --metric installs --period 12mo --exclude-self
   happyskills stats --scope my_skills_reach --metric distinct_installers --period 12mo --skill acme/deploy-aws
   happyskills stats --scope my_activity --metric installs --from 2026-05-01 --to 2026-06-01`
 
@@ -98,6 +102,14 @@ const build_request = (flags) => {
 		body.repo_slug = flags.skill
 	}
 
+	// --exclude-self refines my_skills_reach `installs` (which counts you by
+	// default). Meaningless elsewhere — the server enforces this too.
+	if (flags['exclude-self']) {
+		if (scope !== 'my_skills_reach')
+			throw new UsageError('--exclude-self is only valid for --scope my_skills_reach.')
+		body.exclude_self = true
+	}
+
 	return body
 }
 
@@ -161,14 +173,15 @@ const schema = {
 	input: {
 		positional: [],
 		flags: [
-			{ name: 'scope',    type: 'string', required: true,  description: 'my_activity | my_skills_reach' },
-			{ name: 'metric',   type: 'string', required: true,  description: 'my_activity: installs|updates|searches|uninstalls; my_skills_reach: installs_by_others|distinct_installers' },
-			{ name: 'period',   type: 'string', default: undefined, description: 'Window preset: 7d|30d|90d|6mo|12mo (use instead of --from/--to)' },
-			{ name: 'from',     type: 'string', default: undefined, description: 'Explicit window start (ISO date)' },
-			{ name: 'to',       type: 'string', default: undefined, description: 'Explicit window end (ISO date, default now)' },
-			{ name: 'group-by', type: 'string', default: 'none', description: 'my_activity: none|day|week|month|surface; my_skills_reach: none|day|week|month|skill' },
-			{ name: 'skill',    type: 'string', default: undefined, description: 'my_skills_reach only: limit to one authored skill (owner/skill)' },
-			{ name: 'json',     type: 'boolean', default: false, description: 'Output as JSON' },
+			{ name: 'scope',        type: 'string', required: true,  description: 'my_activity | my_skills_reach' },
+			{ name: 'metric',       type: 'string', required: true,  description: 'my_activity: installs|updates|searches|uninstalls; my_skills_reach: installs|installs_by_others|distinct_installers' },
+			{ name: 'period',       type: 'string', default: undefined, description: 'Window preset: 7d|30d|90d|6mo|12mo (use instead of --from/--to)' },
+			{ name: 'from',         type: 'string', default: undefined, description: 'Explicit window start (ISO date)' },
+			{ name: 'to',           type: 'string', default: undefined, description: 'Explicit window end (ISO date, default now)' },
+			{ name: 'group-by',     type: 'string', default: 'none', description: 'my_activity: none|day|week|month|surface|skill; my_skills_reach: none|day|week|month|skill' },
+			{ name: 'skill',        type: 'string', default: undefined, description: 'my_skills_reach only: limit to one authored skill (owner/skill)' },
+			{ name: 'exclude-self', type: 'boolean', default: false, description: "my_skills_reach 'installs' only: exclude your own installs (counted by default)" },
+			{ name: 'json',         type: 'boolean', default: false, description: 'Output as JSON' },
 		],
 	},
 	output: {
@@ -190,9 +203,10 @@ const schema = {
 		{ code: 'NETWORK_ERROR', next_step: { kind: 'recovery', action: 'retry' } },
 	],
 	examples: [
-		'happyskills stats --scope my_activity --metric installs --period 30d',
-		'happyskills stats --scope my_skills_reach --metric distinct_installers --period 12mo --group-by skill',
-		'happyskills stats --scope my_skills_reach --metric installs_by_others --period 12mo --skill acme/deploy-aws',
+		'happyskills stats --scope my_activity --metric installs --period 30d --group-by skill',
+		'happyskills stats --scope my_skills_reach --metric installs --period 12mo --group-by skill',
+		'happyskills stats --scope my_skills_reach --metric installs --period 12mo --exclude-self',
+		'happyskills stats --scope my_skills_reach --metric distinct_installers --period 12mo --skill acme/deploy-aws',
 	],
 }
 

package/src/commands/stats.test.js

@@ -59,6 +59,26 @@ describe('build_request — closed grammar', () => {
 	it('rejects a --skill without owner/skill form', () => {
 		assert.throws(() => build_request({ scope: 'my_skills_reach', metric: 'installs_by_others', period: '12mo', skill: 'deploy' }), /owner\/skill/)
 	})
+
+	it('accepts group-by skill on my_activity (rank your own installs by skill)', () => {
+		const body = build_request({ scope: 'my_activity', metric: 'installs', period: '30d', 'group-by': 'skill' })
+		assert.equal(body.group_by, 'skill')
+	})
+
+	it('accepts the my_skills_reach `installs` metric', () => {
+		const body = build_request({ scope: 'my_skills_reach', metric: 'installs', period: '12mo' })
+		assert.equal(body.metric, 'installs')
+		assert.equal(body.exclude_self, undefined) // self included by default
+	})
+
+	it('maps --exclude-self to exclude_self for my_skills_reach', () => {
+		const body = build_request({ scope: 'my_skills_reach', metric: 'installs', period: '12mo', 'exclude-self': true })
+		assert.equal(body.exclude_self, true)
+	})
+
+	it('rejects --exclude-self on my_activity', () => {
+		assert.throws(() => build_request({ scope: 'my_activity', metric: 'installs', period: '30d', 'exclude-self': true }), /--exclude-self is only valid/)
+	})
 })
 
 describe('schema export', () => {