happyskills 0.44.0 → 0.44.1

package/CHANGELOG.md

@@ -7,6 +7,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [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.44.1",
 	"description": "Package manager for AI agent skills",
 	"license": "SEE LICENSE IN LICENSE",
 	"author": "Nicolas Dao <nic@cloudlesslabs.com> (https://cloudlesslabs.com)",

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/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() }
 	})
 })