happyskills 0.2.0 → 0.3.1

package/CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.3.1] - 2026-03-04
+
+### Fixed
+- Fix global installs writing `skills-lock.json` to the local project directory instead of `~/.claude/`; global lock state is now read/written from `~/.claude/skills-lock.json` across `install`, `uninstall`, `list`, `update`, and `convert` commands
+
+## [0.3.0] - 2026-03-04
+
+### Added
+- Add `setup` command to install the official `happyskillsai/happyskills-cli` Claude Code skill globally (`~/.claude/skills/`); idempotent — reports "already up to date" if already at the latest version
+- Add `self-update` command to upgrade the `happyskills` CLI itself to the latest published npm version via `npm install -g happyskills@latest`
+- Add passive update-check notification — once per day the CLI silently checks npm for a newer version and prints a warning to stderr before the command runs; suppressed in `--json` mode and when running `self-update`
+
 ## [0.2.0] - 2026-03-04
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "happyskills",
-	"version": "0.2.0",
+	"version": "0.3.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/convert.js

@@ -12,7 +12,7 @@ const { write_manifest } = require('../manifest/writer')
 const { read_lock } = require('../lock/reader')
 const { write_lock, update_lock_skills } = require('../lock/writer')
 const { hash_directory } = require('../lock/integrity')
-const { skills_dir, find_project_root } = require('../config/paths')
+const { skills_dir, find_project_root, lock_root } = require('../config/paths')
 const { file_exists } = require('../utils/fs')
 const { create_spinner } = require('../ui/spinner')
 const { print_help, print_success, print_error, print_info, print_label, print_json } = require('../ui/output')
@@ -154,7 +154,8 @@ const run = (args) => catch_errors('Convert failed', async () => {
 	if (push_err) { pub_spinner.fail('Publish failed'); throw e('Push failed', push_err) }
 
 	pub_spinner.update('Updating lock file...')
-	const [, lock_data] = await read_lock(project_root)
+	const lock_dir = lock_root(is_global, project_root)
+	const [, lock_data] = await read_lock(lock_dir)
 	const [, integrity] = await hash_directory(skill_dir)
 
 	const full_name = `${workspace.slug}/${skill_name}`
@@ -170,7 +171,7 @@ const run = (args) => catch_errors('Convert failed', async () => {
 	}
 
 	const new_skills = update_lock_skills(lock_data, updates)
-	const [lock_err] = await write_lock(project_root, new_skills)
+	const [lock_err] = await write_lock(lock_dir, new_skills)
 	if (lock_err) { pub_spinner.fail('Failed to write lock file'); throw e('Lock write failed', lock_err) }
 
 	pub_spinner.succeed(`Converted ${full_name}@${version}`)

package/src/commands/list.js

@@ -1,6 +1,6 @@
 const { error: { catch_errors, wrap_errors: e } } = require('puffy-core')
 const { read_lock, get_all_locked_skills } = require('../lock/reader')
-const { skills_dir, skill_install_dir, find_project_root } = require('../config/paths')
+const { skills_dir, skill_install_dir, find_project_root, lock_root } = require('../config/paths')
 const { file_exists } = require('../utils/fs')
 const { scan_skills_dir } = require('../utils/skill_scanner')
 const { print_help, print_table, print_json, print_info } = require('../ui/output')
@@ -32,7 +32,7 @@ const run = (args) => catch_errors('List failed', async () => {
 	const project_root = find_project_root()
 	const base_dir = skills_dir(is_global, project_root)
 
-	const [, lock_data] = await read_lock(project_root)
+	const [, lock_data] = await read_lock(lock_root(is_global, project_root))
 	const skills = get_all_locked_skills(lock_data)
 	const managed_entries = Object.entries(skills)
 

package/src/commands/self-update.js

@@ -0,0 +1,83 @@
+const { error: { catch_errors, wrap_errors: e } } = require('puffy-core')
+const semver = require('semver')
+const { CLI_VERSION, EXIT_CODES } = require('../constants')
+const { print_success, print_info, print_help, print_hint, print_json, code } = require('../ui/output')
+const { exit_with_error, CliError, NetworkError } = require('../utils/errors')
+const { is_json_mode } = require('../state')
+
+const NPM_REGISTRY_URL = process.env.HAPPYSKILLS_NPM_REGISTRY_URL || 'https://registry.npmjs.org/happyskills/latest'
+
+const HELP_TEXT = `Usage: happyskills self-update
+
+Upgrade the happyskills CLI to the latest version.
+
+Fetches the latest version from npm and runs:
+  npm install -g happyskills@latest
+
+Options:
+  --json        Output as JSON
+
+Examples:
+  happyskills self-update`
+
+const get_latest_version = () => catch_errors('Failed to fetch latest version', async () => {
+	let res
+	try {
+		res = await fetch(NPM_REGISTRY_URL, { signal: AbortSignal.timeout(10000) })
+	} catch {
+		throw new NetworkError('Could not reach npm registry. Check your internet connection.')
+	}
+	if (!res.ok) throw new CliError(`npm registry returned ${res.status}`)
+	const data = await res.json()
+	if (!data || !data.version) throw new CliError('Could not parse version from npm registry')
+	return data.version
+})
+
+const run_npm_install = () => catch_errors('npm install failed', async () => {
+	const { spawn } = require('child_process')
+	const stdio = is_json_mode() ? 'pipe' : 'inherit'
+	return new Promise((resolve, reject) => {
+		const child = spawn('npm', ['install', '-g', 'happyskills@latest'], { stdio })
+		child.on('close', (exit_code) => {
+			if (exit_code !== 0) reject(new CliError(`npm install exited with code ${exit_code}`))
+			else resolve()
+		})
+		child.on('error', (err) => reject(err))
+	})
+})
+
+const run = (args) => catch_errors('Self-update failed', async () => {
+	if (args.flags._show_help) {
+		print_help(HELP_TEXT)
+		return process.exit(EXIT_CODES.SUCCESS)
+	}
+
+	const [ver_err, latest] = await get_latest_version()
+	if (ver_err) throw e('Failed to check for updates', ver_err)
+
+	if (!semver.gt(latest, CLI_VERSION)) {
+		if (args.flags.json) {
+			print_json({ data: { status: 'already_up_to_date', version: CLI_VERSION } })
+			return
+		}
+		print_info(`happyskills is already up to date (v${CLI_VERSION})`)
+		return
+	}
+
+	if (!args.flags.json) {
+		print_info(`Updating happyskills v${CLI_VERSION} → v${latest}...`)
+	}
+
+	const [install_err] = await run_npm_install()
+	if (install_err) throw e('Update failed', install_err)
+
+	if (args.flags.json) {
+		print_json({ data: { status: 'updated', from: CLI_VERSION, to: latest } })
+		return
+	}
+
+	print_success(`happyskills updated to v${latest}`)
+	print_hint(`Run ${code('happyskills --version')} to confirm.`)
+}).then(([errors]) => { if (errors) { exit_with_error(errors); return } })
+
+module.exports = { run }

package/src/commands/setup.js

@@ -0,0 +1,55 @@
+const { error: { catch_errors, wrap_errors: e } } = require('puffy-core')
+const { install } = require('../engine/installer')
+const { find_project_root } = require('../config/paths')
+const { print_success, print_info, print_help, print_hint, print_json, code } = require('../ui/output')
+const { exit_with_error } = require('../utils/errors')
+const { EXIT_CODES } = require('../constants')
+
+const SKILL_NAME = 'happyskillsai/happyskills-cli'
+
+const HELP_TEXT = `Usage: happyskills setup
+
+Install (or update) the official HappySkills CLI skill globally.
+
+Installs happyskillsai/happyskills-cli into ~/.claude/skills/ so AI agents
+(Claude Code, etc.) can interact with HappySkills using natural language.
+
+Options:
+  --json        Output as JSON
+
+Examples:
+  happyskills setup`
+
+const run = (args) => catch_errors('Setup failed', async () => {
+	if (args.flags._show_help) {
+		print_help(HELP_TEXT)
+		return process.exit(EXIT_CODES.SUCCESS)
+	}
+
+	const options = {
+		global: true,
+		yes: true,
+		version: 'latest',
+		project_root: find_project_root()
+	}
+
+	const [errors, result] = await install(SKILL_NAME, options)
+	if (errors) throw e(`Failed to install ${SKILL_NAME}`, errors)
+
+	const version = result.version || ''
+	const status = (result.installed && result.installed.length > 0) ? 'installed' : 'already_up_to_date'
+
+	if (args.flags.json) {
+		print_json({ data: { skill: SKILL_NAME, version, status } })
+		return
+	}
+
+	if (status === 'already_up_to_date') {
+		print_info(`${SKILL_NAME} is already up to date${version ? ` (v${version})` : ''}`)
+	} else {
+		print_success(`${SKILL_NAME} installed${version ? ` (v${version})` : ''}`)
+		print_hint(`Restart Claude Code to activate the skill.`)
+	}
+}).then(([errors]) => { if (errors) { exit_with_error(errors); return } })
+
+module.exports = { run }

package/src/commands/update.js

@@ -3,7 +3,7 @@ const { install } = require('../engine/installer')
 const { read_lock, get_all_locked_skills } = require('../lock/reader')
 const { print_help, print_success, print_info, print_json } = require('../ui/output')
 const { exit_with_error, UsageError } = require('../utils/errors')
-const { find_project_root } = require('../config/paths')
+const { find_project_root, lock_root } = require('../config/paths')
 const { EXIT_CODES } = require('../constants')
 
 const HELP_TEXT = `Usage: happyskills update [owner/skill|--all] [options]
@@ -40,7 +40,8 @@ const run = (args) => catch_errors('Update failed', async () => {
 		throw new UsageError("Specify a skill to update or use --all (e.g., 'happyskills update acme/deploy-aws' or 'happyskills update --all').")
 	}
 
-	const [, lock_data] = await read_lock(project_root)
+	const is_global = args.flags.global || false
+	const [, lock_data] = await read_lock(lock_root(is_global, project_root))
 	const skills = get_all_locked_skills(lock_data)
 
 	const to_update = target_skill
@@ -57,7 +58,7 @@ const run = (args) => catch_errors('Update failed', async () => {
 	}
 
 	const options = {
-		global: args.flags.global || false,
+		global: is_global,
 		fresh: true,
 		project_root
 	}

package/src/config/paths.js

@@ -26,6 +26,10 @@ const tmp_dir = (base_skills_dir) => path.join(base_skills_dir, '.tmp')
 
 const install_lock_path = (base_skills_dir) => path.join(base_skills_dir, '.install.lock')
 
+const lock_root = (is_global, project_root) => {
+	return is_global ? path.join(home_dir, '.claude') : project_root
+}
+
 const lock_file_path = (project_root = process.cwd()) => path.join(project_root, 'skills-lock.json')
 
 const skill_install_dir = (base_skills_dir, name) => path.join(base_skills_dir, name)
@@ -60,6 +64,7 @@ module.exports = {
 	skills_dir,
 	tmp_dir,
 	install_lock_path,
+	lock_root,
 	lock_file_path,
 	skill_install_dir,
 	find_project_root

package/src/constants.js

@@ -44,7 +44,9 @@ const COMMANDS = [
 	'login',
 	'logout',
 	'whoami',
-	'fork'
+	'fork',
+	'setup',
+	'self-update'
 ]
 
 module.exports = {

package/src/engine/installer.js

@@ -8,7 +8,7 @@ const { check_system_dependencies } = require('./system_deps')
 const { hash_directory, verify_integrity } = require('../lock/integrity')
 const { read_lock, get_locked_skill } = require('../lock/reader')
 const { write_lock, update_lock_skills } = require('../lock/writer')
-const { skills_dir, tmp_dir, skill_install_dir } = require('../config/paths')
+const { skills_dir, tmp_dir, skill_install_dir, lock_root } = require('../config/paths')
 const { ensure_dir, remove_dir, file_exists } = require('../utils/fs')
 const { create_spinner } = require('../ui/spinner')
 const { print_success, print_warn } = require('../ui/output')
@@ -22,8 +22,9 @@ const install = (skill, options = {}) => catch_errors('Install failed', async ()
 	const { version, global: is_global = false, force = false, fresh = false, project_root } = options
 	const base_dir = skills_dir(is_global, project_root)
 	const temp_dir = tmp_dir(base_dir)
+	const lock_dir = lock_root(is_global, project_root)
 
-	const [, lock_data] = fresh ? [null, null] : await read_lock(project_root)
+	const [, lock_data] = fresh ? [null, null] : await read_lock(lock_dir)
 
 	if (!fresh && lock_data) {
 		const locked = get_locked_skill(lock_data, skill)
@@ -148,7 +149,7 @@ const install = (skill, options = {}) => catch_errors('Install failed', async ()
 		}
 
 		const new_skills = update_lock_skills(lock_data, updates)
-		const [lock_errors] = await write_lock(project_root, new_skills)
+		const [lock_errors] = await write_lock(lock_dir, new_skills)
 		if (lock_errors) { spinner.fail('Failed to write lock file'); throw e('Lock write failed', lock_errors) }
 
 		spinner.succeed(`Installed ${packages_to_install.length} package(s)`)

package/src/engine/uninstaller.js

@@ -1,7 +1,7 @@
 const { error: { catch_errors, wrap_errors: e } } = require('puffy-core')
 const { read_lock, get_locked_skill, get_all_locked_skills } = require('../lock/reader')
 const { write_lock, update_lock_skills } = require('../lock/writer')
-const { skills_dir, skill_install_dir } = require('../config/paths')
+const { skills_dir, skill_install_dir, lock_root } = require('../config/paths')
 const { remove_dir } = require('../utils/fs')
 const { print_success, print_info } = require('../ui/output')
 
@@ -24,8 +24,9 @@ const find_orphans = (skills, removed_skill) => {
 const uninstall = (skill, options = {}) => catch_errors('Uninstall failed', async () => {
 	const { global: is_global = false, project_root } = options
 	const base_dir = skills_dir(is_global, project_root)
+	const lock_dir = lock_root(is_global, project_root)
 
-	const [lock_errors, lock_data] = await read_lock(project_root)
+	const [lock_errors, lock_data] = await read_lock(lock_dir)
 	if (lock_errors || !lock_data) {
 		throw new Error('No skills-lock.json found. Nothing to uninstall.')
 	}
@@ -58,7 +59,7 @@ const uninstall = (skill, options = {}) => catch_errors('Uninstall failed', asyn
 	}
 
 	const new_skills = update_lock_skills(lock_data, updates)
-	const [write_errors] = await write_lock(project_root, new_skills)
+	const [write_errors] = await write_lock(lock_dir, new_skills)
 	if (write_errors) throw e('Failed to update lock file', write_errors)
 
 	print_success(`Removed ${skill}`)

package/src/index.js

@@ -1,6 +1,6 @@
 const { CLI_VERSION, EXIT_CODES, COMMAND_ALIASES, COMMANDS } = require('./constants')
 const { print_error, print_help } = require('./ui/output')
-const { dim } = require('./ui/colors')
+const { dim, yellow } = require('./ui/colors')
 
 const levenshtein = (a, b) => {
 	const m = a.length, n = b.length
@@ -92,6 +92,8 @@ Commands:
   update [owner/skill]     Upgrade to latest versions (alias: up)
   publish                  Push skill to registry (alias: pub)
   fork <owner/skill>       Fork a skill to your workspace
+  setup                    Install the HappySkills CLI skill globally
+  self-update              Upgrade happyskills CLI to latest version
   login                    Authenticate with the registry
   logout                   Clear stored credentials
   whoami                   Show current user
@@ -147,6 +149,17 @@ const run = (argv) => {
 		args.flags._show_help = true
 	}
 
+	if (!args.flags.json && resolved !== 'self-update') {
+		const { check_for_update } = require('./utils/update_check')
+		const update_info = check_for_update(CLI_VERSION)
+		if (update_info && update_info.update_available) {
+			process.stderr.write('\n')
+			process.stderr.write(yellow(`  Update available: v${update_info.current} → v${update_info.latest}\n`))
+			process.stderr.write(dim(`  Run: npm install -g happyskills@latest\n`))
+			process.stderr.write('\n')
+		}
+	}
+
 	const command_module = require(`./commands/${resolved}`)
 	const result = command_module.run(args)
 

package/src/integration/cli.test.js

@@ -92,7 +92,7 @@ describe('CLI — global flags', () => {
 
 	it('--help lists all expected commands', () => {
 		const { stdout } = run(['--help'])
-		const expected_commands = ['install', 'uninstall', 'list', 'search', 'check', 'update', 'publish', 'fork', 'login', 'logout', 'whoami', 'init']
+		const expected_commands = ['install', 'uninstall', 'list', 'search', 'check', 'update', 'publish', 'fork', 'login', 'logout', 'whoami', 'init', 'setup', 'self-update']
 		for (const cmd of expected_commands) {
 			assert.ok(stdout.includes(cmd), `help output should mention "${cmd}"`)
 		}
@@ -163,8 +163,12 @@ describe('CLI — command --help', () => {
 		['update',    'Aliases:'],
 		['publish',   'Aliases:'],
 		['fork',      'Arguments:'],
-		['init',      'Examples:'],
-		['whoami',    '--json'],
+		['init',          'Examples:'],
+		['setup',         'Options:'],
+		['setup',         'Examples:'],
+		['self-update',   'Options:'],
+		['self-update',   'Examples:'],
+		['whoami',        '--json'],
 		['login',     '--browser'],
 		['login',     '--password'],
 		['logout',    'credentials'],
@@ -381,3 +385,48 @@ describe('CLI — --json: existing json commands now use { data } envelope', ()
 		}
 	})
 })
+
+// ─── setup command ─────────────────────────────────────────────────────────────
+
+describe('CLI — setup command', () => {
+	it('setup --help exits 0 and describes the command', () => {
+		const { stdout, code } = run(['setup', '--help'])
+		assert.strictEqual(code, 0)
+		assert.match(stdout, /happyskillsai\/happyskills-cli/)
+		assert.match(stdout, /Options:/)
+		assert.match(stdout, /Examples:/)
+	})
+
+	it('setup --json produces a network error (JSON) when API is unreachable', () => {
+		const { stdout, code } = run(['setup', '--json'])
+		assert.strictEqual(code, 4)
+		const out = parse_json_output(stdout, 'setup --json network failure')
+		assert.ok('error' in out)
+		assert.strictEqual(out.error.code, 'NETWORK_ERROR')
+		assert.strictEqual(out.error.exit_code, 4)
+	})
+})
+
+// ─── self-update command ───────────────────────────────────────────────────────
+
+describe('CLI — self-update command', () => {
+	it('self-update --help exits 0 and describes the command', () => {
+		const { stdout, code } = run(['self-update', '--help'])
+		assert.strictEqual(code, 0)
+		assert.match(stdout, /npm install -g happyskills@latest/)
+		assert.match(stdout, /Options:/)
+		assert.match(stdout, /Examples:/)
+	})
+
+	it('self-update --json produces a network error (JSON) when npm registry is unreachable', () => {
+		const { stdout, code } = run(
+			['self-update', '--json'],
+			{ HAPPYSKILLS_NPM_REGISTRY_URL: 'http://localhost:0' }
+		)
+		assert.strictEqual(code, 4)
+		const out = parse_json_output(stdout, 'self-update --json network failure')
+		assert.ok('error' in out)
+		assert.strictEqual(out.error.code, 'NETWORK_ERROR')
+		assert.strictEqual(out.error.exit_code, 4)
+	})
+})

package/src/utils/update_check.js

@@ -0,0 +1,56 @@
+const os = require('os')
+const fs = require('fs')
+const path = require('path')
+const semver = require('semver')
+
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000
+const NPM_REGISTRY_URL = process.env.HAPPYSKILLS_NPM_REGISTRY_URL || 'https://registry.npmjs.org/happyskills/latest'
+
+const get_cache_path = () => {
+	const base = process.env.XDG_CONFIG_HOME
+		? path.join(process.env.XDG_CONFIG_HOME, 'happyskills')
+		: path.join(os.homedir(), '.config', 'happyskills')
+	return path.join(base, 'update-check.json')
+}
+
+const read_cache = () => {
+	try {
+		const raw = fs.readFileSync(get_cache_path(), 'utf8')
+		return JSON.parse(raw)
+	} catch {
+		return null
+	}
+}
+
+const write_cache = (data) => {
+	try {
+		const cache_path = get_cache_path()
+		fs.mkdirSync(path.dirname(cache_path), { recursive: true })
+		fs.writeFileSync(cache_path, JSON.stringify(data), 'utf8')
+	} catch {
+		// silently ignore write errors
+	}
+}
+
+// Fire-and-forget — NOT wrapped in catch_errors because it ends with .catch(() => {})
+const refresh_cache = () => {
+	fetch(NPM_REGISTRY_URL, { signal: AbortSignal.timeout(5000) })
+		.then(r => r.json())
+		.then(data => {
+			if (data && data.version) {
+				write_cache({ latest: data.version, checked_at: Date.now() })
+			}
+		})
+		.catch(() => {})
+}
+
+const check_for_update = (current_version) => {
+	const cached = read_cache()
+	const is_stale = !cached || !cached.checked_at || (Date.now() - cached.checked_at > CACHE_TTL_MS)
+	if (is_stale) refresh_cache()
+	if (!cached || !cached.latest) return null
+	const update_available = !!semver.gt(cached.latest, current_version)
+	return { update_available, current: current_version, latest: cached.latest }
+}
+
+module.exports = { check_for_update }

package/src/utils/update_check.test.js

@@ -0,0 +1,110 @@
+'use strict'
+const { describe, it } = require('node:test')
+const assert = require('node:assert/strict')
+const fs = require('fs')
+const os = require('os')
+const path = require('path')
+
+/**
+ * Runs fn inside a temporary XDG config dir, restoring the original env
+ * value (or deleting the key) after. Since get_cache_path() reads
+ * process.env.XDG_CONFIG_HOME on every call, this provides full isolation
+ * without needing to re-require the module.
+ */
+const with_tmp_xdg = (fn) => {
+	const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'hs-update-test-'))
+	const orig = process.env.XDG_CONFIG_HOME
+	process.env.XDG_CONFIG_HOME = tmp
+	try {
+		return fn(tmp)
+	} finally {
+		if (orig === undefined) delete process.env.XDG_CONFIG_HOME
+		else process.env.XDG_CONFIG_HOME = orig
+		fs.rmSync(tmp, { recursive: true, force: true })
+	}
+}
+
+const write_cache = (xdg_dir, data) => {
+	const cache_dir = path.join(xdg_dir, 'happyskills')
+	fs.mkdirSync(cache_dir, { recursive: true })
+	fs.writeFileSync(path.join(cache_dir, 'update-check.json'), JSON.stringify(data), 'utf8')
+}
+
+const { check_for_update } = require('./update_check')
+
+describe('check_for_update', () => {
+	it('returns null when no cache file exists', () => {
+		with_tmp_xdg(() => {
+			const result = check_for_update('1.0.0')
+			assert.strictEqual(result, null)
+		})
+	})
+
+	it('returns update_available: true when cached latest is newer', () => {
+		with_tmp_xdg((tmp) => {
+			write_cache(tmp, { latest: '2.0.0', checked_at: Date.now() })
+			const result = check_for_update('1.0.0')
+			assert.ok(result !== null)
+			assert.strictEqual(result.update_available, true)
+			assert.strictEqual(result.current, '1.0.0')
+			assert.strictEqual(result.latest, '2.0.0')
+		})
+	})
+
+	it('returns update_available: false when cached latest equals current', () => {
+		with_tmp_xdg((tmp) => {
+			write_cache(tmp, { latest: '1.0.0', checked_at: Date.now() })
+			const result = check_for_update('1.0.0')
+			assert.ok(result !== null)
+			assert.strictEqual(result.update_available, false)
+			assert.strictEqual(result.current, '1.0.0')
+			assert.strictEqual(result.latest, '1.0.0')
+		})
+	})
+
+	it('returns update_available: false when cached latest is older than current', () => {
+		with_tmp_xdg((tmp) => {
+			write_cache(tmp, { latest: '0.5.0', checked_at: Date.now() })
+			const result = check_for_update('1.0.0')
+			assert.ok(result !== null)
+			assert.strictEqual(result.update_available, false)
+		})
+	})
+
+	it('returns null when cache is missing the latest field', () => {
+		with_tmp_xdg((tmp) => {
+			write_cache(tmp, { checked_at: Date.now() })
+			const result = check_for_update('1.0.0')
+			assert.strictEqual(result, null)
+		})
+	})
+
+	it('returns null when cache file contains malformed JSON', () => {
+		with_tmp_xdg((tmp) => {
+			const cache_dir = path.join(tmp, 'happyskills')
+			fs.mkdirSync(cache_dir, { recursive: true })
+			fs.writeFileSync(path.join(cache_dir, 'update-check.json'), 'not-valid-json', 'utf8')
+			const result = check_for_update('1.0.0')
+			assert.strictEqual(result, null)
+		})
+	})
+
+	it('respects XDG_CONFIG_HOME for cache path', () => {
+		with_tmp_xdg((tmp) => {
+			// Write cache in the XDG-derived path
+			write_cache(tmp, { latest: '9.9.9', checked_at: Date.now() })
+			const result = check_for_update('1.0.0')
+			assert.ok(result !== null, 'should read cache from XDG_CONFIG_HOME-derived path')
+			assert.strictEqual(result.latest, '9.9.9')
+		})
+	})
+
+	it('handles patch-level updates correctly', () => {
+		with_tmp_xdg((tmp) => {
+			write_cache(tmp, { latest: '1.0.1', checked_at: Date.now() })
+			const result = check_for_update('1.0.0')
+			assert.ok(result !== null)
+			assert.strictEqual(result.update_available, true)
+		})
+	})
+})