happyskills 1.14.0 → 1.15.0

package/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [1.15.0] - 2026-06-30
+
+### Changed
+
+- Make `happyskills match` **version-precise**: it now matches each local skill against **all** published versions of a skill, not just the latest. A local copy that is byte-identical to an *older* release is reported as `certified` at that exact version (the result carries `match.version`, `match.latest_version`, and `match.is_latest`) — instead of being diffed against head and misreported as `likely`/drift just because you're a few versions behind. The text output gains an "identical to an older published version (you are behind)" line listing each such skill as `name → owner/skill @ <version> (latest <latest>)`. Mechanically, the match funnel now also sends the whole-skill `tree_sha`s in the same batched `POST /repos:match` call and certifies on a cross-version tree match (with a fallback to the previous head-only behavior for older API servers). Requires API ≥ 5.18.0 (the `tree_shas` axis on `POST /repos:match`). (Spec 260629-03 §4.8.)
+
 ## [1.14.0] - 2026-06-30
 
 ### Added

package/package.json

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

@@ -214,11 +214,14 @@ const semantic_search = (query, options = {}) => catch_errors('Semantic search f
 })
 
 // POST /repos:match — catalog matching for `happyskills match` (spec 260629-03).
-// ONE batch call for the whole folder's hashes + names. Returns
-// { results: [{ skill_md_sha, candidates }], name_results: [{ name, candidates }] }
-// (two keys, so the client's single-key unwrap leaves it intact).
-const match = (hashes, names) => catch_errors('Catalog match lookup failed', async () => {
-	const [errors, data] = await client.post('/repos:match', { hashes, names: names || [] })
+// ONE batch call for the whole folder's hashes + names + tree shas. Returns
+// { results: [{ skill_md_sha, candidates }], name_results: [{ name, candidates }],
+//   tree_results: [{ tree_sha, candidates }] } — multi-key, so the client's
+// single-key unwrap leaves it intact. `tree_results` (spec §4.8) matches the
+// whole-skill content address across ALL versions, so a local copy identical to
+// an older release is pinned to that exact version instead of drifting vs head.
+const match = (hashes, names, tree_shas) => catch_errors('Catalog match lookup failed', async () => {
+	const [errors, data] = await client.post('/repos:match', { hashes, names: names || [], tree_shas: tree_shas || [] })
 	if (errors) throw errors[errors.length - 1]
 	return data
 })

package/src/commands/match.js

@@ -131,6 +131,17 @@ const render_text = (data, warnings) => {
 	print_info(`Scanned ${s.total} skill${s.total === 1 ? '' : 's'}.`)
 	print_success(`✓ ${s.certified} already in HappySkills, unchanged · ≈ ${s.near} with small differences · ~ ${s.likely + s.possible} loosely matched · ✗ ${s.unmatched} not found`)
 
+	// A certified match to an OLDER version is still an exact match — surface the
+	// version gap so the principal knows it is the real skill, just behind.
+	const behind = data.certified.filter(en => en.match && en.match.latest_version && en.match.is_latest === false)
+	if (behind.length) {
+		print_info('\nIdentical to an older published version (you are behind):')
+		for (const en of behind) {
+			const where = en.match ? `${en.match.workspace}/${en.match.name}` : '(catalog)'
+			print_info(`  ${en.local.name} → ${where} @ ${en.match.version} (latest ${en.match.latest_version})`)
+		}
+	}
+
 	if (data.near.length) {
 		print_info('\nSkills with small differences:')
 		for (const en of data.near) {

package/src/integration/api_envelope.test.js

@@ -90,7 +90,13 @@ const run_cli = (args, env_override = {}) => new Promise((resolve) => {
 	const has_mode_flag = args.includes('--json') || args.includes('--text')
 	const final_args = has_mode_flag ? args : [...args, '--text']
 	const child = spawn(NODE, [CLI, ...final_args], {
-		env: { ...process.env, NO_COLOR: '1', CI: '', ...env_override },
+		// Isolate the CLI config dir so the spawned binary never reads the
+		// developer's real ~/.config/happyskills credentials. A stored (expired)
+		// token would otherwise make an authed command (e.g. a search POST)
+		// attempt a token refresh against the stub's missing /auth/refresh route
+		// and fail with NETWORK_ERROR — a machine-state-dependent flake. A test
+		// that needs a specific config dir overrides this via env_override (last).
+		env: { ...process.env, NO_COLOR: '1', CI: '', XDG_CONFIG_HOME: make_tmp(), ...env_override },
 	})
 	let stdout = ''
 	let stderr = ''

package/src/match/funnel.js

@@ -42,6 +42,11 @@ const match_view = (c) => ({
 	version: c.version,
 	tree_sha: c.tree_sha,
 	is_source_of_truth: !!c.is_source_of_truth,
+	// Cross-version probe carries the repo head so a certified-but-older match
+	// can be surfaced as "certified @ 0.3.0 (latest 0.3.2)". Null when the
+	// candidate came from the legacy head-only path (older server).
+	latest_version: c.latest_version || null,
+	is_latest: c.latest_version ? c.version === c.latest_version : null,
 })
 
 // deps: { match(hashes,names), manifests(repo_versions), semantic_search?(query) }
@@ -56,13 +61,18 @@ const run_funnel = (skills, deps, opts = {}) =>
 		if (!skills.length) return { buckets, warnings }
 
 		// ── Stage 1: one batched match for the whole folder ──────────────────
+		// Hashes, names AND whole-skill tree shas ride the same call. The tree
+		// probe (spec §4.8) is what lets an OLDER local copy match its exact
+		// published version instead of drifting against head.
 		const hashes = [...new Set(skills.map(s => s.skill_md_sha).filter(Boolean))]
 		const names = [...new Set(skills.map(s => s.name).filter(Boolean))]
-		const [m_err, match_data] = await deps.match(hashes, names)
+		const tree_shas = [...new Set(skills.map(s => s.tree_sha).filter(Boolean))]
+		const [m_err, match_data] = await deps.match(hashes, names, tree_shas)
 		if (m_err) throw e('Stage 1 /repos:match failed', m_err)
 
 		const by_hash = new Map((match_data.results || []).map(r => [r.skill_md_sha, r.candidates || []]))
 		const by_name = new Map((match_data.name_results || []).map(r => [String(r.name).toLowerCase(), r.candidates || []]))
+		const by_tree = new Map((match_data.tree_results || []).map(r => [r.tree_sha, r.candidates || []]))
 
 		// ── Stage 2: classify; collect the narrowed manifest set ─────────────
 		const pending = []          // needs a manifest diff
@@ -70,14 +80,16 @@ const run_funnel = (skills, deps, opts = {}) =>
 		const manifest_needs = new Map()
 
 		for (const skill of skills) {
+			const tree_cands = (skill.tree_sha && by_tree.get(skill.tree_sha)) || []
 			const hash_cands = (skill.skill_md_sha && by_hash.get(skill.skill_md_sha)) || []
 			const name_cands = by_name.get(String(skill.name || '').toLowerCase()) || []
 
-			// Certified = tree SHA equal, by the spec's definition — regardless of
-			// whether the candidate was found by hash or name. (A SKILL.md-less
-			// skill has a null hash but can still be byte-identical to a name
-			// match; hash candidates are preferred since they are checked first.)
-			const certified = [...hash_cands, ...name_cands].find(c => c.tree_sha === skill.tree_sha)
+			// Certified = byte-identical to SOME published version. The cross-version
+			// tree probe is authoritative and pins the EXACT version (even an older
+			// one — candidates are source-of-truth + newest-matching first). Fall
+			// back to head tree-SHA equality from a hash/name candidate so an older
+			// server with no tree_results still certifies a head-identical skill.
+			const certified = tree_cands[0] || [...hash_cands, ...name_cands].find(c => c.tree_sha === skill.tree_sha)
 			if (certified) {
 				buckets.certified.push({ local: local_view(skill), match: match_view(certified) })
 				continue

package/src/match/funnel.test.js

@@ -21,11 +21,11 @@ const skill = (over) => ({
 const cand = (over) => ({ workspace: 'anthropics', name: 'webapp-testing', version: '1.0.0', tree_sha: 't_remote', skill_md_sha: 'h_skillmd', is_source_of_truth: true, ...over })
 
 // A deps double that records calls.
-const make_deps = ({ results = [], name_results = [], manifests = [], semantic = null } = {}) => {
+const make_deps = ({ results = [], name_results = [], tree_results = [], manifests = [], semantic = null } = {}) => {
 	const calls = { match: 0, manifests: 0, semantic: 0, blob: 0 }
 	return {
 		calls,
-		match: async () => { calls.match++; return [null, { results, name_results }] },
+		match: async () => { calls.match++; return [null, { results, name_results, tree_results }] },
 		manifests: async () => { calls.manifests++; return [null, { manifests, warnings: [] }] },
 		...(semantic ? { semantic_search: async (q) => { calls.semantic++; return semantic(q) } } : {}),
 	}
@@ -107,6 +107,52 @@ test('Stage 1 is ONE batched call regardless of skill count (no N+1)', async ()
 	assert.equal(deps.calls.match, 1, 'the whole folder resolves in one /repos:match call')
 })
 
+// ── Tier 1: cross-version tree probe (spec 260629-03 §4.8) ───────────────────
+
+test('local tree byte-identical to an OLDER published version → certified at that exact version', async () => {
+	// HEAD is 0.3.2 (a DIFFERENT tree — this is the drift the bug surfaced); the
+	// local copy is byte-identical to 0.3.0. The cross-version tree probe must
+	// pin it to 0.3.0 and certify it — NOT diff it against head and call it likely.
+	const local = skill({ name: 'tiny-gemini-image', skill_md_sha: 'h_old', tree_sha: 't_v030' })
+	const deps = make_deps({
+		// hash/name discovery still points at HEAD (head's tree differs from local)
+		name_results: [{ name: 'tiny-gemini-image', candidates: [cand({ name: 'tiny-gemini-image', version: '0.3.2', tree_sha: 't_v032', skill_md_sha: 'h_head' })] }],
+		tree_results: [{ tree_sha: 't_v030', candidates: [
+			{ workspace: 'nicolasdao', name: 'tiny-gemini-image', version: '0.3.0', tree_sha: 't_v030', skill_md_sha: 'h_old', is_source_of_truth: true, latest_version: '0.3.2' },
+		] }],
+	})
+	const [err, out] = await run_funnel([local], deps)
+	assert.equal(err, null)
+	assert.equal(out.buckets.certified.length, 1, 'an older byte-identical version is certified, not likely')
+	assert.equal(out.buckets.likely.length, 0)
+	assert.equal(out.buckets.near.length, 0)
+	assert.equal(out.buckets.certified[0].match.version, '0.3.0', 'pinned to the EXACT matching version, not head')
+	assert.equal(out.buckets.certified[0].match.latest_version, '0.3.2', 'carries the latest version so the caller can show "behind by"')
+	assert.equal(out.buckets.certified[0].match.is_latest, false)
+	assert.equal(deps.calls.manifests, 0, 'an exact tree match needs no manifest diff')
+})
+
+test('the local tree probe is sent in the SAME batched match call (no extra round-trip)', async () => {
+	const deps = make_deps({ tree_results: [{ tree_sha: 't_local', candidates: [
+		{ workspace: 'anthropics', name: 'webapp-testing', version: '1.0.0', tree_sha: 't_local', is_source_of_truth: true, latest_version: '1.0.0' },
+	] }] })
+	const [err, out] = await run_funnel([skill(), skill({ dir: '/b' })], deps)
+	assert.equal(err, null)
+	assert.equal(deps.calls.match, 1, 'hashes + names + tree_shas all ride one /repos:match call')
+	assert.equal(out.buckets.certified.length, 2)
+	assert.equal(out.buckets.certified[0].match.is_latest, true, 'matching head is is_latest:true')
+})
+
+test('backward-compat: a server with no tree_results still certifies a head-identical skill', async () => {
+	// Older server returns no tree_results; the funnel falls back to head tree
+	// equality from the hash/name candidate so existing behavior is preserved.
+	const deps = make_deps({ results: [{ skill_md_sha: 'h_skillmd', candidates: [cand({ tree_sha: 't_local' })] }] })
+	const [err, out] = await run_funnel([skill()], deps)
+	assert.equal(err, null)
+	assert.equal(out.buckets.certified.length, 1)
+	assert.equal(out.buckets.certified[0].match.version, '1.0.0')
+})
+
 test('a failed manifest batch becomes a warning, not a thrown error', async () => {
 	const deps = {
 		calls: {},