happyskills 0.44.0 → 0.45.0

package/CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.45.0] - 2026-05-13
+
+### Fixed
+- `diff`, `pull`, `install`, and every other command that calls `repos_api.clone(owner, repo, ref, { commit })` now refuses any response whose top-level `commit` field does not match the requested commit. The pre-fix CLI silently trusted whatever the registry returned, which produced false-positive `local_only_modified` diffs (and would have produced silent base-content corruption on `pull` and `install`) whenever a CDN cache key collision served one commit's response for a different commit's request. The check lives at the single `clone()` chokepoint in `cli/src/api/repos.js` so all 8 call sites are covered automatically — no per-command opt-in. The error message names the requested vs returned commit, attributes the most likely cause (stale CDN cache or upstream cache-key misconfig), and tells the user to retry. Companion API fix shipped in `happyskills-api@2.11.5` closes the root cause by adding `commit` and `format` to the CloudFront cache-key whitelist for `/repos/*/clone`; this CLI check stays as defense in depth so the next cache/MITM/origin bug surfaces as a hard error instead of a quiet false positive. Reproduction: with the broken cache, `happyskills diff happyskillsai/happyskills-design` against linwong's `e65040…` returned a tree pinned to `6533f944…` — a different commit than the lock asked for; the new check stops on that exact mismatch.
+- `repos_api.clone()` and `repos_api.get_blob()` additionally verify per-file content integrity: every file's bytes must hash to the SHA the server advertises (git-blob SHA-256 via `hash_blob` in `cli/src/utils/git_hash.js`). Catches the second failure mode where SHA and content are mismatched within a single response (MITM corruption, partial transfers, origin bugs that produce inconsistent pairs). Skipped cleanly for `format=archive` responses (no inline content) and for metadata-only entries that omit `content`. Test coverage in `cli/src/api/repos.test.js` (9 tests across commit-pin, content-pin, archive passthrough, and ref-based clone).
+- `status <bare-skill-name>` now resolves the bare name to its locked `owner/skill` key by suffix match — same disambiguation that `validate`, `bump`, and `resolve_skill_owner` already use. Previously, running `happyskills status happyskills-design` (without the `happyskillsai/` prefix) returned `status: not_found` because `all_skills[target_skill]` is a direct lookup and the lock keys are fully qualified. `diff` still requires owner/name explicitly because its API path depends on the workspace; `status` reads only the lock and can always resolve unambiguously.
+
+## [0.44.1] - 2026-05-13
+
+### Changed
+- `diff` no longer hard-blocks when the target skill has lock-vs-disk drift. Previously, running `happyskills diff <skill>` against a drifted skill threw a `UsageError` telling the user to run `happyskills install <skill> --fresh` before diffing — but `--fresh` overwrites the on-disk content, destroying the very local state the user was trying to inspect. Drift is exactly the case where diff is most useful as a diagnostic tool. The command now prints a one-line warning (`<skill> has drift: lock <X>, disk <Y>. Diff is shown against the lock-recorded base (<X>).`) and proceeds with the diff. JSON output gains a top-level `drift` field (same `{ reason, lock_version, disk_version }` shape used elsewhere) in `local` and `full` modes, or `null` when clean. `--remote` mode skips the drift probe entirely since it reads nothing from disk. Other drift-aware commands are unchanged — `status`/`check`/`list` still surface drift in their reports, `update` still skips drifted skills to avoid clobbering local work, and the post-write self-checks in `install`/`pull`/`bump`/`publish`/`convert` still throw on inconsistency.
+
 ## [0.44.0] - 2026-05-12
 
 ### Added

package/package.json

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

@@ -1,5 +1,40 @@
 const { error: { catch_errors } } = require('puffy-core')
 const client = require('./client')
+const { hash_blob } = require('../utils/git_hash')
+
+// Verify a clone response against the request that produced it. Two checks:
+//
+//   1. Commit pin (the structural one): when the caller passed `options.commit`,
+//      the response's top-level `commit` field MUST equal that value. If the CDN
+//      cache key drops the `commit` query param (or any future proxy/cache does
+//      the same), one commit's response can be returned for a different commit's
+//      request — internally self-consistent, but pinned to the wrong tree.
+//      This is exactly how the May 2026 `clone_cache_policy` whitelist bug
+//      surfaced as false-positive `local_only_modified` diffs.
+//
+//   2. Per-file content address (defense in depth): every file's bytes must
+//      hash to the SHA the server advertises. Catches MITM corruption, partial
+//      responses, and origin bugs that produce mismatched (sha, content) pairs.
+//
+// Returns an error message string on failure, or null when the response is
+// trustworthy. Caller throws.
+const verify_clone_integrity = (data, owner, repo, requested_commit) => {
+	if (!data) return null
+	if (requested_commit && typeof data.commit === 'string' && data.commit !== requested_commit) {
+		return `Clone commit mismatch for ${owner}/${repo}: requested commit ${requested_commit} but the response is pinned to ${data.commit}. This indicates a stale CDN cache entry serving a different commit's response. Retry the command; if it persists, the registry's clone-cache policy is misconfigured (the commit query param is missing from the CloudFront cache key).`
+	}
+	if (Array.isArray(data.files)) {
+		for (const f of data.files) {
+			if (!f || typeof f.sha !== 'string' || typeof f.content !== 'string') continue
+			const buf = Buffer.from(f.content, 'base64')
+			const computed = hash_blob(buf)
+			if (computed !== f.sha) {
+				return `Clone integrity check failed for ${owner}/${repo} file "${f.path}": server reported sha ${f.sha} but content hashes to ${computed}. This usually means a stale CDN cache entry is serving wrong content for the requested commit. Retry the command; if it persists, report to the registry maintainers.`
+			}
+		}
+	}
+	return null
+}
 
 const search = (query, options = {}) => catch_errors('Search failed', async () => {
 	const params = new URLSearchParams()
@@ -29,6 +64,8 @@ const clone = (owner, repo, ref, options = {}) => catch_errors(`Clone ${owner}/$
 	const qs = params.toString() ? `?${params}` : ''
 	const [errors, data] = await client.get(`/repos/${owner}/${repo}/clone${qs}`)
 	if (errors) throw errors[errors.length - 1]
+	const integrity_msg = verify_clone_integrity(data, owner, repo, options.commit || null)
+	if (integrity_msg) throw new Error(integrity_msg)
 	return data
 })
 
@@ -77,6 +114,12 @@ const compare = (owner, repo, base_commit) => catch_errors(`Compare ${owner}/${r
 const get_blob = (owner, repo, sha) => catch_errors(`Get blob ${owner}/${repo}/${sha} failed`, async () => {
 	const [errors, data] = await client.get(`/repos/${owner}/${repo}/blob/${sha}`)
 	if (errors) throw errors[errors.length - 1]
+	if (data && typeof data.content === 'string') {
+		const computed = hash_blob(Buffer.from(data.content, 'base64'))
+		if (computed !== sha) {
+			throw new Error(`Blob integrity check failed for ${owner}/${repo}@${sha}: content hashes to ${computed}. Possible stale CDN cache or registry corruption.`)
+		}
+	}
 	return data
 })
 

package/src/api/repos.test.js

@@ -0,0 +1,171 @@
+const { describe, it, beforeEach, afterEach } = require('node:test')
+const assert = require('node:assert')
+const crypto = require('node:crypto')
+
+// Compute the same git-blob SHA the registry advertises and the CLI verifies
+// against. Mirrors cli/src/utils/git_hash.js so the test is self-contained.
+const git_blob_sha = (buf) => {
+	const header = Buffer.from(`blob ${buf.length}\0`)
+	return crypto.createHash('sha256').update(header).update(buf).digest('hex')
+}
+
+// Stub the API client before requiring the module under test. We swap in a
+// per-test fake `get` so we control exactly what `clone()` and `get_blob()` see.
+const stub_client = (response) => {
+	const client_path = require.resolve('./client')
+	require.cache[client_path] = {
+		id: client_path,
+		filename: client_path,
+		loaded: true,
+		exports: {
+			get: async () => [null, response],
+			post: async () => [null, null],
+			put: async () => [null, null],
+			patch: async () => [null, null],
+			del: async () => [null, null],
+			request: async () => [null, null],
+			get_base_url: () => 'http://test'
+		}
+	}
+	delete require.cache[require.resolve('./repos')]
+	return require('./repos')
+}
+
+const restore = () => {
+	delete require.cache[require.resolve('./client')]
+	delete require.cache[require.resolve('./repos')]
+}
+
+describe('repos.clone — content integrity verification', () => {
+	afterEach(restore)
+
+	it('accepts a response whose file SHAs match the content', async () => {
+		const content = Buffer.from('hello world\n')
+		const sha = git_blob_sha(content)
+		const repos = stub_client({
+			ref: null,
+			commit: 'a'.repeat(64),
+			files: [{ path: 'README.md', content: content.toString('base64'), sha }]
+		})
+		const [err, data] = await repos.clone('acme', 'demo', null, { commit: 'a'.repeat(64) })
+		assert.strictEqual(err, null, 'clone should not error on a clean response')
+		assert.strictEqual(data.files.length, 1)
+	})
+
+	it('rejects a response whose file SHA does not match the bytes (cache pollution)', async () => {
+		// The exact failure mode of the CloudFront cache-key bug: server claims
+		// SHA X for a file whose bytes hash to Y. Pre-fix CLI silently trusted X
+		// and produced false-positive diffs. Post-fix CLI must throw here.
+		const content = Buffer.from('this is the REAL content of the file at commit B')
+		const wrong_sha = git_blob_sha(Buffer.from('STALE content cached under a colliding key'))
+		const repos = stub_client({
+			ref: null,
+			commit: 'b'.repeat(64),
+			files: [{ path: 'SKILL.md', content: content.toString('base64'), sha: wrong_sha }]
+		})
+		const [err] = await repos.clone('acme', 'demo', null, { commit: 'b'.repeat(64) })
+		assert.ok(err, 'clone must error when content does not hash to the advertised SHA')
+		const msg = err.map(e => e.message).join(' | ')
+		assert.match(msg, /integrity check failed/i, `error should mention integrity: ${msg}`)
+		assert.match(msg, /SKILL\.md/, `error should name the offending file: ${msg}`)
+	})
+
+	it('accepts an archive-format response with no per-file content', async () => {
+		// format=archive returns { format, ref, commit, url } — no `files` array
+		// to verify. The check must pass through cleanly so archive installs are
+		// not blocked.
+		const repos = stub_client({
+			format: 'archive',
+			ref: 'refs/tags/v1.0.0',
+			commit: 'c'.repeat(64),
+			url: 'https://s3.example.com/presigned'
+		})
+		const [err, data] = await repos.clone('acme', 'demo', 'refs/tags/v1.0.0', { format: 'archive' })
+		assert.strictEqual(err, null)
+		assert.strictEqual(data.format, 'archive')
+	})
+
+	it('rejects a response whose `commit` field does not match the requested commit (cache key collision)', async () => {
+		// The exact failure mode of the May 2026 CDN cache-key bug: CloudFront
+		// dropped `?commit=` from the cache key, so a clone response generated
+		// for commit X got served back for a request asking for commit Y. The
+		// response is internally consistent (SHAs match content), but pinned to
+		// the wrong tree. Pre-fix CLI silently used it as `base_commit`
+		// content and produced false-positive local_only_modified diffs.
+		const content = Buffer.from('// content of commit X\n')
+		const sha = git_blob_sha(content)
+		const repos = stub_client({
+			ref: null,
+			commit: 'x'.repeat(64),  // server-pinned to X
+			files: [{ path: 'SKILL.md', content: content.toString('base64'), sha }]
+		})
+		const requested = 'y'.repeat(64)
+		const [err] = await repos.clone('acme', 'demo', null, { commit: requested })
+		assert.ok(err, 'clone must error when response.commit !== options.commit')
+		const msg = err.map(e => e.message).join(' | ')
+		assert.match(msg, /commit mismatch/i, `error should mention commit mismatch: ${msg}`)
+		assert.match(msg, new RegExp(requested.slice(0, 12)), 'error should include requested commit')
+	})
+
+	it('accepts a response when `commit` matches the requested commit', async () => {
+		const content = Buffer.from('matching content\n')
+		const sha = git_blob_sha(content)
+		const commit = 'a'.repeat(64)
+		const repos = stub_client({
+			ref: null,
+			commit,
+			files: [{ path: 'SKILL.md', content: content.toString('base64'), sha }]
+		})
+		const [err] = await repos.clone('acme', 'demo', null, { commit })
+		assert.strictEqual(err, null)
+	})
+
+	it('does not enforce commit pin when caller did not pass options.commit (ref-based clone)', async () => {
+		// When asking by `ref`, the caller does not know which commit will be
+		// resolved — that's the whole point. We can't pin in that direction;
+		// per-file SHA verification still applies.
+		const content = Buffer.from('content\n')
+		const sha = git_blob_sha(content)
+		const repos = stub_client({
+			ref: 'refs/tags/v1.0.0',
+			commit: 'z'.repeat(64),
+			files: [{ path: 'SKILL.md', content: content.toString('base64'), sha }]
+		})
+		const [err] = await repos.clone('acme', 'demo', 'refs/tags/v1.0.0')
+		assert.strictEqual(err, null)
+	})
+
+	it('skips entries that have no content (e.g. metadata-only responses)', async () => {
+		// Some endpoints return file metadata without inlined content; the check
+		// should not synthesize a false negative.
+		const repos = stub_client({
+			ref: null,
+			commit: 'd'.repeat(64),
+			files: [{ path: 'README.md', sha: 'whatever' }]
+		})
+		const [err] = await repos.clone('acme', 'demo', null, { commit: 'd'.repeat(64) })
+		assert.strictEqual(err, null)
+	})
+})
+
+describe('repos.get_blob — content integrity verification', () => {
+	afterEach(restore)
+
+	it('rejects a blob whose bytes do not hash to the requested SHA', async () => {
+		const content = Buffer.from('wrong bytes')
+		const requested_sha = git_blob_sha(Buffer.from('right bytes'))
+		const repos = stub_client({ content: content.toString('base64'), size: content.length })
+		const [err] = await repos.get_blob('acme', 'demo', requested_sha)
+		assert.ok(err, 'get_blob must error on hash mismatch')
+		assert.match(err.map(e => e.message).join(' | '), /integrity check failed/i)
+	})
+
+	it('accepts a blob whose bytes hash to the requested SHA', async () => {
+		const content = Buffer.from('hello')
+		const sha = git_blob_sha(content)
+		const repos = stub_client({ content: content.toString('base64'), size: content.length })
+		const [err, data] = await repos.get_blob('acme', 'demo', sha)
+		assert.strictEqual(err, null)
+		assert.strictEqual(data.size, content.length)
+	})
+})

package/src/commands/diff.js

@@ -249,16 +249,20 @@ const run = (args) => catch_errors('Diff failed', async () => {
 	const base_dir = skills_dir(is_global, project_root)
 	const skill_dir = skill_install_dir(base_dir, repo)
 
-	// A drifted skill makes diff incoherent: the lock claims one version is
-	// installed, the disk has a different version, and `base_commit` points at
-	// the lock-claimed version. Diffing local-vs-base would show the entire
-	// disk content as "modified" — noise, not signal. Refuse with a clear
-	// remediation rather than show a misleading report.
-	const [, drift] = await verify_lock_disk_consistency(lock_entry, skill_dir)
-	if (drift && !drift.ok) {
-		throw new UsageError(
+	// Drift (lock-vs-disk version mismatch) does NOT block diff — diff is the
+	// diagnostic tool a user reaches for precisely when things have diverged,
+	// and the obvious "remediation" (install --fresh) would destroy the local
+	// content they're trying to inspect. We probe drift only to warn the user
+	// that the "base" shown is the lock-recorded base (not the disk version's
+	// base). Skipped in --remote mode, which reads nothing from disk.
+	const drift = mode === 'remote'
+		? null
+		: (await verify_lock_disk_consistency(lock_entry, skill_dir))[1]
+	const has_drift = drift && !drift.ok
+	if (has_drift && !args.flags.json) {
+		print_warn(
 			`${skill_name} has drift: lock ${drift.expected}, disk ${drift.actual || 'none'}. ` +
-			`Run ${code(`happyskills install ${skill_name} --fresh`)} to restore the install record before diffing.`
+			`Diff is shown against the lock-recorded base (${lock_entry.version}).`
 		)
 	}
 
@@ -280,7 +284,7 @@ const run = (args) => catch_errors('Diff failed', async () => {
 		}
 
 		if (args.flags.json) {
-			print_json({ data: { mode, report } })
+			print_json({ data: { mode, report, drift: has_drift ? { reason: drift.reason, lock_version: drift.expected, disk_version: drift.actual } : null } })
 		} else {
 			print_file_table(classified)
 			print_report_diffs(report)
@@ -333,7 +337,7 @@ const run = (args) => catch_errors('Diff failed', async () => {
 	}
 
 	if (args.flags.json) {
-		print_json({ data: { mode, report } })
+		print_json({ data: { mode, report, drift: has_drift ? { reason: drift.reason, lock_version: drift.expected, disk_version: drift.actual } : null } })
 	} else {
 		print_file_table(classified)
 		print_report_diffs(report)

package/src/commands/status.js

@@ -59,9 +59,27 @@ const run = (args) => catch_errors('Status failed', async () => {
 	}
 
 	const all_skills = get_all_locked_skills(lock_data)
-	const entries = target_skill
-		? [[target_skill, all_skills[target_skill]]]
-		: Object.entries(all_skills).filter(([, data]) => data !== null)
+	// Accept either fully-qualified "owner/skill" or bare "skill" — find by
+	// suffix when bare, matching how `validate`, `bump`, and other commands
+	// disambiguate from the lock. `diff` requires owner/name explicitly because
+	// its API calls need the workspace; status reads only the lock and can
+	// always resolve a bare name to its single locked owner.
+	let entries
+	if (target_skill) {
+		let key = target_skill
+		let data = all_skills[key] || null
+		if (!data && !target_skill.includes('/')) {
+			const suffix = `/${target_skill}`
+			const found = Object.keys(all_skills).find(k => k.endsWith(suffix))
+			if (found) {
+				key = found
+				data = all_skills[key] || null
+			}
+		}
+		entries = [[key, data]]
+	} else {
+		entries = Object.entries(all_skills).filter(([, data]) => data !== null)
+	}
 
 	if (entries.length === 0) {
 		if (args.flags.json) {

package/src/integration/drift.test.js

@@ -11,6 +11,11 @@
  *   - `list` reported the lock's version as the installed version (lying)
  *   - `diff` used the lock's `base_commit` as a comparison baseline that no
  *     longer matched what was on disk (incoherent diff)
+ *
+ * Note on `diff`: an earlier fix hard-blocked `diff` on drift. That was wrong
+ * — diff is the diagnostic tool a user reaches for *because* of drift, and
+ * the suggested "install --fresh" remediation would destroy the local
+ * content. The current behavior is to warn and proceed.
  *   - `update` could decide a drifted skill was up-to-date and skip it
  *
  * These tests reconstruct the exact linwong scenario that surfaced the bug
@@ -258,19 +263,38 @@ describe('list — drift surfacing', () => {
 
 // ─── diff ─────────────────────────────────────────────────────────────────────
 
-describe('diff — drift refusal', () => {
-	it('diff refuses with a clear UsageError when the skill is drifted', () => {
-		// diff against an inconsistent baseline produces noise, not signal —
-		// refusing is the principal-friendly choice.
+describe('diff — drift does not block', () => {
+	it('diff proceeds past the drift check (no UsageError) and warns the user', () => {
+		// Drift must not block diff: diff is the diagnostic tool for this case,
+		// and "install --fresh" would destroy the local content. We assert that
+		// the command moves past the drift gate — it will then fail trying to
+		// reach the fake API URL, but exit code 2 (UsageError) means the old
+		// pre-block is back.
 		const { root, cleanup } = scaffold_drifted([
 			{ full: 'acme/cant-diff', short: 'cant-diff', lock_version: '0.4.0', disk_version: '0.3.0' }
 		])
 		try {
 			const { code, stderr } = run(['diff', 'acme/cant-diff'], { cwd: root })
-			assert.strictEqual(code, 2, 'should exit with usage error code')
-			assert.ok(stderr.toLowerCase().includes('drift'), 'error must mention drift')
-			assert.ok(stderr.includes('0.4.0'), 'should mention lock version')
-			assert.ok(stderr.includes('0.3.0'), 'should mention disk version')
+			assert.notStrictEqual(code, 2, 'must not exit with the old drift UsageError')
+			assert.ok(
+				stderr.toLowerCase().includes('drift') && stderr.includes('0.4.0') && stderr.includes('0.3.0'),
+				'should warn about drift with both versions'
+			)
+			assert.ok(
+				!/before diffing/i.test(stderr),
+				'must not tell the user to fix drift before diffing'
+			)
+		} finally { cleanup() }
+	})
+
+	it('diff --remote skips the drift probe entirely (drift is irrelevant when no disk is read)', () => {
+		const { root, cleanup } = scaffold_drifted([
+			{ full: 'acme/cant-diff', short: 'cant-diff', lock_version: '0.4.0', disk_version: '0.3.0' }
+		])
+		try {
+			const { code, stderr } = run(['diff', 'acme/cant-diff', '--remote'], { cwd: root })
+			assert.notStrictEqual(code, 2, 'must not exit with the old drift UsageError')
+			assert.ok(!/drift/i.test(stderr), '--remote mode should not surface drift at all')
 		} finally { cleanup() }
 	})
 })