happyskills 1.3.0 → 1.4.0

package/CHANGELOG.md

@@ -7,6 +7,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [1.4.0] - 2026-06-03
+
+### Added
+
+- Add `star <owner/name>` and `unstar <owner/name>` commands to curate your favorites. Both require auth and are idempotent (starring an already-starred skill, or unstarring one you haven't starred, succeeds without error).
+- Add `--favorites` flag to `search` — query only the skills you've starred (`scope=favorites`). Routes through the smart dispatcher; a bare `search --favorites` (no query) browses all your starred skills. Requires auth; cannot be combined with `--exact`.
+
 ## [1.3.0] - 2026-06-03
 
 ### Added

package/package.json

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

@@ -105,6 +105,21 @@ const patch_repo = (owner, name, fields) => catch_errors(`Failed to update ${own
 	return data
 })
 
+// Star / unstar a repo. Both endpoints are idempotent server-side (starring an
+// already-starred repo, or unstarring an unstarred one, succeeds). The user's
+// own stars power the `favorites` search scope.
+const star = (owner, name) => catch_errors(`Failed to star ${owner}/${name}`, async () => {
+	const [errors, data] = await client.post(`/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/star`)
+	if (errors) throw errors[errors.length - 1]
+	return data
+})
+
+const unstar = (owner, name) => catch_errors(`Failed to unstar ${owner}/${name}`, async () => {
+	const [errors, data] = await client.del(`/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/star`)
+	if (errors) throw errors[errors.length - 1]
+	return data
+})
+
 const compare = (owner, repo, base_commit) => catch_errors(`Compare ${owner}/${repo} failed`, async () => {
 	const [errors, data] = await client.post(`/repos/${owner}/${repo}/compare`, { base_commit })
 	if (errors) throw errors[errors.length - 1]
@@ -195,4 +210,4 @@ const semantic_search = (query, options = {}) => catch_errors('Semantic search f
 	return data
 })
 
-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 }
+module.exports = { search, dispatch_search, semantic_search, resolve_dependencies, clone, push, get_refs, get_repo, check_updates, del_repo, patch_repo, star, unstar, compare, get_blob, get_tree }

package/src/api/repos.test.js

@@ -169,3 +169,51 @@ describe('repos.get_blob — content integrity verification', () => {
 		assert.strictEqual(data.size, content.length)
 	})
 })
+
+// Capturing client stub: records (method, path) for each call so star/unstar
+// path construction can be asserted. Mirrors stub_client above.
+const stub_client_capture = () => {
+	const calls = []
+	const record = (method) => async (path) => { calls.push([method, path]); return [null, { message: 'ok' }] }
+	const client_path = require.resolve('./client')
+	require.cache[client_path] = {
+		id: client_path,
+		filename: client_path,
+		loaded: true,
+		exports: {
+			get: record('get'),
+			post: record('post'),
+			put: record('put'),
+			patch: record('patch'),
+			del: record('del'),
+			request: record('request'),
+			get_base_url: () => 'http://test'
+		}
+	}
+	delete require.cache[require.resolve('./repos')]
+	return { repos: require('./repos'), calls }
+}
+
+describe('repos.star / repos.unstar — endpoint + path', () => {
+	afterEach(restore)
+
+	it('star() POSTs to /repos/<owner>/<name>/star', async () => {
+		const { repos, calls } = stub_client_capture()
+		const [err] = await repos.star('acme', 'deploy-aws')
+		assert.strictEqual(err, null)
+		assert.deepStrictEqual(calls[0], ['post', '/repos/acme/deploy-aws/star'])
+	})
+
+	it('unstar() DELETEs /repos/<owner>/<name>/star', async () => {
+		const { repos, calls } = stub_client_capture()
+		const [err] = await repos.unstar('acme', 'deploy-aws')
+		assert.strictEqual(err, null)
+		assert.deepStrictEqual(calls[0], ['del', '/repos/acme/deploy-aws/star'])
+	})
+
+	it('URL-encodes owner and name in the star path', async () => {
+		const { repos, calls } = stub_client_capture()
+		await repos.star('acme corp', 'deploy/aws')
+		assert.strictEqual(calls[0][1], `/repos/${encodeURIComponent('acme corp')}/${encodeURIComponent('deploy/aws')}/star`)
+	})
+})

package/src/commands/search.js

@@ -16,12 +16,13 @@ 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)
+  query               Search term (optional with --mine, --personal, --workspace, or --favorites)
 
 Options:
   -w, --workspace <slug>  Search within specific workspace(s) (comma-separated)
   --mine                  Search across all your workspaces
   --personal              Search only your personal workspace
+  --favorites             Search only skills you've starred (requires auth)
   --tags <tags>           Filter by tags (comma-separated)
   --type <type>           Filter by type (skill, kit)
   --exact                 Force keyword-only FTS matching (skip smart routing)
@@ -42,6 +43,8 @@ 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 --favorites --limit 20                # → your starred skills
+  happyskills search deploy --favorites --limit 10         # → favorites matching "deploy"
   happyskills search deploy --workspace acme --limit 50
   happyskills search --type kit --limit 10
   happyskills search deploy --exact --limit 10            # → keyword FTS only`
@@ -380,15 +383,19 @@ const run = (args) => catch_errors('Search failed', async () => {
 	}
 
 	const query = args._.join(' ') || null
-	const { mine, personal, workspace, tags, type } = args.flags
+	const { mine, personal, workspace, tags, type, favorites } = args.flags
 	const is_exact = !!args.flags.exact
 	const with_rerank = !!args.flags['with-rerank']
-	// --smart / -S accepted for backward compat (now the default when a query is provided)
-	const use_smart = query && !is_exact
-	const has_scope_flag = mine || personal || workspace
+	// --smart / -S accepted for backward compat (now the default when a query is provided).
+	// --favorites also forces the smart (POST /repos:search) path even with no query:
+	// favorites is a dispatcher-only scope, so it must never fall through to the
+	// legacy keyword GET, which doesn't understand it. A bare `--favorites` browses
+	// the user's starred skills (list mode).
+	const use_smart = (query || favorites) && !is_exact
+	const has_scope_flag = mine || personal || workspace || favorites
 
 	if (!query && !has_scope_flag && !tags && !type) {
-		throw new UsageError('Please provide a search query or use --mine, --personal, or --workspace.')
+		throw new UsageError('Please provide a search query or use --mine, --personal, --workspace, or --favorites.')
 	}
 
 	if (!args.flags.limit) {
@@ -405,9 +412,15 @@ const run = (args) => catch_errors('Search failed', async () => {
 		throw new UsageError('--with-rerank cannot be combined with --exact. The rerank protocol applies only to semantic-mode dispatches.')
 	}
 
-	const scope = mine ? 'mine' : personal ? 'personal' : undefined
+	// Favorites is a dispatcher-only scope (POST /repos:search); --exact forces the
+	// legacy keyword endpoint, which doesn't support it. Refuse the combination.
+	if (favorites && is_exact) {
+		throw new UsageError('--favorites cannot be combined with --exact. Favorites search uses the smart dispatcher, not keyword-only FTS.')
+	}
+
+	const scope = favorites ? 'favorites' : mine ? 'mine' : personal ? 'personal' : undefined
 
-	if (mine || personal) {
+	if (mine || personal || favorites) {
 		const [, token_data] = await load_token()
 		if (!token_data) {
 			throw new AuthError('Authentication required. Run `happyskills login` first.')

package/src/commands/search.test.js

@@ -9,7 +9,7 @@
 // short names (`clarify`, `present_to_user` alone) no longer apply where the
 // new enum supersedes them.
 
-const { describe, it } = require('node:test')
+const { describe, it, afterEach } = require('node:test')
 const assert = require('node:assert/strict')
 const { build_search_next_step } = require('./search')
 const {
@@ -146,3 +146,62 @@ describe('build_search_next_step — envelope shape', () => {
 		assert.strictEqual(opts[3].refined_query_hint, null)
 	})
 })
+
+// --- search --favorites wiring (spec 260601-02 § 4.3) ---------------------
+// Stub the API client + token store so run() exercises the flag-routing logic
+// without a network call. favorites is a dispatcher-only scope, so the key
+// assertions are: it sets scope='favorites' on dispatch_search (POST) and never
+// falls through to the keyword GET, and a bare --favorites (no query) is allowed.
+
+const stub_search_deps = (capture) => {
+	const repos_path = require.resolve('../api/repos')
+	require.cache[repos_path] = {
+		id: repos_path, filename: repos_path, loaded: true,
+		exports: {
+			dispatch_search: async (query, opts) => {
+				capture.dispatch = { query, opts }
+				return [null, { data: [], mode: 'list', match_notice: null }]
+			},
+			search: async (query, opts) => { capture.keyword = { query, opts }; return [null, []] },
+		},
+	}
+	const token_path = require.resolve('../auth/token_store')
+	require.cache[token_path] = {
+		id: token_path, filename: token_path, loaded: true,
+		exports: {
+			load_token: async () => [null, { token: 'test-token' }],
+			require_token: async () => ({ token: 'test-token' }),
+			save_token: async () => {}, clear_token: async () => {},
+		},
+	}
+	delete require.cache[require.resolve('./search')]
+	return require('./search')
+}
+
+const restore_search_deps = () => {
+	delete require.cache[require.resolve('../api/repos')]
+	delete require.cache[require.resolve('../auth/token_store')]
+	delete require.cache[require.resolve('./search')]
+}
+
+describe('search --favorites — scope wiring', () => {
+	afterEach(restore_search_deps)
+
+	it('bare --favorites (no query) is allowed and dispatches scope=favorites via POST, not keyword GET', async () => {
+		const capture = {}
+		const search = stub_search_deps(capture)
+		await search.run({ _: [], flags: { favorites: true, limit: '20', json: true } })
+		assert.ok(capture.dispatch, 'dispatch_search (POST) must be called for favorites')
+		assert.strictEqual(capture.keyword, undefined, 'keyword GET must NOT be used for favorites')
+		assert.strictEqual(capture.dispatch.opts.scope, 'favorites')
+		assert.strictEqual(capture.dispatch.query, null, 'bare --favorites sends a null query (list mode)')
+	})
+
+	it('--favorites with a query keeps scope=favorites and forwards the query', async () => {
+		const capture = {}
+		const search = stub_search_deps(capture)
+		await search.run({ _: ['deploy'], flags: { favorites: true, limit: '10', json: true } })
+		assert.strictEqual(capture.dispatch.opts.scope, 'favorites')
+		assert.strictEqual(capture.dispatch.query, 'deploy')
+	})
+})

package/src/commands/star.js

@@ -0,0 +1,82 @@
+const { error: { catch_errors } } = require('puffy-core')
+const { star } = require('../api/repos')
+const { require_token } = require('../auth/token_store')
+const { print_help, print_json, print_success } = require('../ui/output')
+const { exit_with_error, UsageError } = require('../utils/errors')
+const { EXIT_CODES } = require('../constants')
+
+const HELP_TEXT = `Usage: happyskills star <owner/name> [options]
+
+Star a skill. Your starred skills are your favorites — search them with
+\`happyskills search --favorites\`. Idempotent: starring an already-starred
+skill succeeds without error.
+
+Arguments:
+  owner/name        Skill to star (e.g., acme/deploy-aws)
+
+Options:
+  --json            Output as JSON
+
+Examples:
+  happyskills star acme/deploy-aws
+  happyskills star acme/deploy-aws --json`
+
+const run = (args) => catch_errors('Star failed', async () => {
+	if (args.flags._show_help) {
+		print_help(HELP_TEXT)
+		return process.exit(EXIT_CODES.SUCCESS)
+	}
+
+	const skill = args._[0]
+	if (!skill) {
+		throw new UsageError('Please specify a skill to star (e.g., happyskills star acme/deploy-aws).')
+	}
+	if (!skill.includes('/')) {
+		throw new UsageError('Skill must be in owner/name format (e.g., acme/deploy-aws).')
+	}
+
+	await require_token()
+
+	const [owner, name] = skill.split('/')
+	const [errors, result] = await star(owner, name)
+	if (errors) throw errors[errors.length - 1]
+
+	if (args.flags.json) {
+		print_json({ data: { starred: true, skill, ...(result || {}) } })
+		return
+	}
+
+	print_success(`Starred "${skill}". Browse your favorites with: happyskills search --favorites`)
+}).then(([errors]) => { if (errors) { exit_with_error(errors); return } })
+
+const schema = {
+	name:     'star',
+	audience: 'consumer',
+	purpose:  'Star a skill. Starred skills power the favorites search scope. Idempotent.',
+	mutation: true,
+	interactive_in_text_mode: false,
+	input: {
+		positional: [
+			{ name: 'skill', required: true, type: 'string', pattern: '<owner>/<name>' },
+		],
+		flags: [
+			{ name: 'json', type: 'boolean', default: false },
+		],
+	},
+	output: {
+		data_shape: {
+			starred: 'boolean',
+			skill:   'string',
+		},
+	},
+	errors: [
+		{ code: 'USAGE_ERROR',   next_step: { kind: 'routing',  action: 'discover_schema' } },
+		{ code: 'AUTH_REQUIRED', next_step: { kind: 'recovery', action: 'login'           } },
+	],
+	examples: [
+		'happyskills star acme/deploy-aws',
+		'happyskills star acme/deploy-aws --json',
+	],
+}
+
+module.exports = { run, schema }

package/src/commands/unstar.js

@@ -0,0 +1,81 @@
+const { error: { catch_errors } } = require('puffy-core')
+const { unstar } = require('../api/repos')
+const { require_token } = require('../auth/token_store')
+const { print_help, print_json, print_success } = require('../ui/output')
+const { exit_with_error, UsageError } = require('../utils/errors')
+const { EXIT_CODES } = require('../constants')
+
+const HELP_TEXT = `Usage: happyskills unstar <owner/name> [options]
+
+Remove a skill from your favorites. Idempotent: unstarring a skill you have
+not starred succeeds without error.
+
+Arguments:
+  owner/name        Skill to unstar (e.g., acme/deploy-aws)
+
+Options:
+  --json            Output as JSON
+
+Examples:
+  happyskills unstar acme/deploy-aws
+  happyskills unstar acme/deploy-aws --json`
+
+const run = (args) => catch_errors('Unstar failed', async () => {
+	if (args.flags._show_help) {
+		print_help(HELP_TEXT)
+		return process.exit(EXIT_CODES.SUCCESS)
+	}
+
+	const skill = args._[0]
+	if (!skill) {
+		throw new UsageError('Please specify a skill to unstar (e.g., happyskills unstar acme/deploy-aws).')
+	}
+	if (!skill.includes('/')) {
+		throw new UsageError('Skill must be in owner/name format (e.g., acme/deploy-aws).')
+	}
+
+	await require_token()
+
+	const [owner, name] = skill.split('/')
+	const [errors, result] = await unstar(owner, name)
+	if (errors) throw errors[errors.length - 1]
+
+	if (args.flags.json) {
+		print_json({ data: { starred: false, skill, ...(result || {}) } })
+		return
+	}
+
+	print_success(`Unstarred "${skill}".`)
+}).then(([errors]) => { if (errors) { exit_with_error(errors); return } })
+
+const schema = {
+	name:     'unstar',
+	audience: 'consumer',
+	purpose:  'Remove a skill from your favorites (unstar). Idempotent.',
+	mutation: true,
+	interactive_in_text_mode: false,
+	input: {
+		positional: [
+			{ name: 'skill', required: true, type: 'string', pattern: '<owner>/<name>' },
+		],
+		flags: [
+			{ name: 'json', type: 'boolean', default: false },
+		],
+	},
+	output: {
+		data_shape: {
+			starred: 'boolean',
+			skill:   'string',
+		},
+	},
+	errors: [
+		{ code: 'USAGE_ERROR',   next_step: { kind: 'routing',  action: 'discover_schema' } },
+		{ code: 'AUTH_REQUIRED', next_step: { kind: 'recovery', action: 'login'           } },
+	],
+	examples: [
+		'happyskills unstar acme/deploy-aws',
+		'happyskills unstar acme/deploy-aws --json',
+	],
+}
+
+module.exports = { run, schema }

package/src/constants.js

@@ -51,6 +51,8 @@ const COMMANDS = [
 	'visibility',
 	'list',
 	'search',
+	'star',
+	'unstar',
 	'check',
 	'status',
 	'pull',

package/src/index.js

@@ -103,6 +103,8 @@ Commands:
   visibility <owner/skill> Check or set visibility (alias: vis)
   list                     List installed skills (alias: ls)
   search <query>           Search the registry (alias: s)
+  star <owner/skill>       Star a skill (add to your favorites)
+  unstar <owner/skill>     Remove a skill from your favorites
   postlex                  Apply deterministic rerank finalization (agent-only; see happyskills-help skill)
   versions <owner/skill>   List all published versions of a skill
   changelog <owner/skill>  Print a skill's CHANGELOG.md