happyskills 0.38.0 → 0.39.1

package/CHANGELOG.md

@@ -7,6 +7,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.39.1] - 2026-05-01
+
+### Fixed
+- Fix `status` command falsely reporting `local_modified: true` and `status: diverged` for skills whose on-disk content is byte-for-byte identical to the registry baseline. The previous single-stage aggregate-integrity check could disagree with `diff` whenever the lock's `base_integrity` drifted from what `hash_directory` produces today (e.g. server-side normalization of the file set, or differences between the JSON-clone and archive install paths). `detect_status` now falls through to a per-file content comparison against the registry manifest at `base_commit` when the aggregate hash disagrees: zero real diffs → reports clean and silently auto-heals the lock entry's `integrity` / `base_integrity`; one or more real diffs → reports modified and includes the list of differing paths in the new `modified_files` field of the JSON output. Fixes the false-positive that blocked `update` (and required `--force`) and `pull` for skills with stale lock entries. The fast path is unchanged when the aggregate hash matches.
+
+## [0.39.0] - 2026-05-01
+
+### Removed
+- **BREAKING:** Remove the `refresh` command (and its `r` alias) entirely. Its smart-batch-check behavior is now the default for `update` — see the Changed entry below. The `r` alias is also removed. Anyone scripting `happyskills refresh ...` should switch to `happyskills update --all -y --json` (same outcome, same JSON shape under `.data.results`).
+
+### Changed
+- **BREAKING (behavior):** `update [--all]` is now smart by default. It runs one `POST /repos:check-updates` batch call against the registry and only re-installs skills that are actually outdated. Skills already at the latest version are left alone (no download). Previously `update --all` always re-installed every locked skill regardless of version. Pass `--force` to opt back into the legacy "always re-install" behavior (now also overwrites local modifications, replacing the previous narrow meaning of `--force`).
+- For `--all`, only **root-level** skills are checked (transitive dependencies follow their parents through the install pipeline). For a specific target, any locked skill works.
+- `update --json` output shape now mirrors what `refresh --json` returned: `{ results, outdated_count, up_to_date_count, updated, skipped, already_up_to_date, errors }` plus `symlink_repairs`. With `--force`, the shape is the simpler `{ updated, count, forced: true }`.
+
+### Migration
+- Replace `happyskills refresh` → `happyskills update --all`
+- Replace `happyskills refresh -y --json` → `happyskills update --all -y --json`
+- If you actually wanted the old `update --all` behavior (force re-install regardless of version), now use `happyskills update --all --force`
+
 ## [0.38.0] - 2026-05-01
 
 ### Changed

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "happyskills",
-	"version": "0.38.0",
+	"version": "0.39.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/pull.js

@@ -152,7 +152,7 @@ const run = (args) => catch_errors('Pull failed', async () => {
 	const spinner = create_spinner(`Pulling ${skill_name}...`)
 
 	// 2. Detect local modifications
-	const [det_err, det] = await detect_status(lock_entry, skill_dir)
+	const [det_err, det] = await detect_status(lock_entry, skill_dir, { skill_name, project_root, is_global })
 	if (det_err) { spinner.fail('Failed to detect local status'); throw det_err[0] }
 
 	// 3. Compare with remote

package/src/commands/status.js

@@ -74,7 +74,7 @@ const run = (args) => catch_errors('Status failed', async () => {
 		if (!data) return { name, data, det: null }
 		const short_name = name.split('/')[1] || name
 		const dir = skill_install_dir(base_dir, short_name)
-		return detect_status(data, dir).then(([, det]) => ({ name, data, det }))
+		return detect_status(data, dir, { skill_name: name, project_root, is_global }).then(([, det]) => ({ name, data, det }))
 	}))
 
 	const results = detections.map(({ name, data, det }) => {
@@ -85,6 +85,7 @@ const run = (args) => catch_errors('Status failed', async () => {
 			base_version: data.version || null,
 			base_commit: data.base_commit || null,
 			local_modified: det?.local_modified || false,
+			modified_files: det?.modified_files || null,
 			// remote_updated is populated below after API call
 			remote_updated: false,
 			remote_version: null,

package/src/commands/update.js

@@ -1,31 +1,65 @@
 const { error: { catch_errors, wrap_errors: e } } = require('puffy-core')
 const { install } = require('../engine/installer')
 const { read_lock, get_all_locked_skills, get_via } = require('../lock/reader')
+const { read_manifest } = require('../manifest/reader')
 const { detect_status } = require('../merge/detector')
-const { print_help, print_success, print_info, print_warn, print_json } = require('../ui/output')
+const repos_api = require('../api/repos')
+const { print_help, print_table, print_json, print_info, print_success, print_warn, print_hint, code } = require('../ui/output')
+const { green, yellow, red } = require('../ui/colors')
+const { create_spinner } = require('../ui/spinner')
 const { exit_with_error, UsageError } = require('../utils/errors')
 const { find_project_root, lock_root, skills_dir, skill_install_dir } = require('../config/paths')
-const { EXIT_CODES } = require('../constants')
+const { EXIT_CODES, SKILL_TYPES } = require('../constants')
+const { resolve_agents, verify_and_repair_symlinks } = require('../agents')
+const { is_skill_enabled } = require('../agents/status')
 
 const HELP_TEXT = `Usage: happyskills update [owner/skill|--all] [options]
 
-Upgrade skills to latest compatible versions.
+Bring installed skills up to date. By default, checks each skill against the
+registry (one batch API call) and only re-installs skills that are actually
+outdated. Skills already at the latest version are left alone — no download,
+no work. Use --force to re-install regardless of version.
 
 Arguments:
-  owner/skill       Update specific skill (optional)
+  owner/skill       Update a specific skill (optional)
 
 Options:
-  --all             Update all installed skills
+  --all             Update all installed root-level skills
+  --force           Re-install regardless of version. Also overwrites skills
+                    with local modifications.
   -g, --global      Update globally installed skills
   -y, --yes         Skip confirmation prompts
+  --agents <list>   Target specific agents (comma-separated). Default: auto-detect
   --json            Output as JSON
 
 Aliases: up
 
 Examples:
-  happyskills update acme/deploy-aws
-  happyskills up --all
-  happyskills up -g --all`
+  happyskills update acme/deploy-aws       # update one skill if outdated
+  happyskills up --all                     # check + update all outdated skills
+  happyskills up --all --force             # force re-install everything
+  happyskills up --all -y --json           # batch mode, no prompt`
+
+/**
+ * Returns true if the lock entry's dependencies differ from the installed
+ * skill.json's dependencies — indicates the lock file is stale relative to
+ * the on-disk manifest.
+ */
+const has_dependency_drift = (lock_entry, manifest) => {
+	if (!manifest) return false
+	const lock_deps = JSON.stringify(lock_entry.dependencies || {})
+	const manifest_deps = JSON.stringify(manifest.dependencies || {})
+	return lock_deps !== manifest_deps
+}
+
+const confirm_prompt = (question) => new Promise((resolve) => {
+	const readline = require('readline')
+	const rl = readline.createInterface({ input: process.stdin, output: process.stderr })
+	rl.question(question, (answer) => {
+		rl.close()
+		resolve(answer.trim().toLowerCase())
+	})
+})
 
 const run = (args) => catch_errors('Update failed', async () => {
 	if (args.flags._show_help) {
@@ -36,80 +70,241 @@ const run = (args) => catch_errors('Update failed', async () => {
 	const project_root = find_project_root()
 	const target_skill = args._[0]
 	const update_all = args.flags.all || false
+	const force = args.flags.force || false
+	const auto_yes = args.flags.yes || false
+	const is_global = args.flags.global || false
 
 	if (!target_skill && !update_all) {
 		throw new UsageError("Specify a skill to update or use --all (e.g., 'happyskills update acme/deploy-aws' or 'happyskills update --all').")
 	}
 
-	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 base_dir = skills_dir(is_global, project_root)
 
-	const to_update = target_skill
-		? [[target_skill, skills[target_skill]]]
-		: Object.entries(skills).filter(([, data]) => data !== null)
+	// Determine which skills to consider.
+	// For --all, only root-level skills (transitive deps come along through their parents).
+	// For a specific target, allow any locked skill.
+	const candidates = target_skill
+		? (skills[target_skill] ? [[target_skill, skills[target_skill]]] : [])
+		: Object.entries(skills).filter(([, data]) => data && data.requested_by?.includes('__root__'))
 
-	if (to_update.length === 0) {
+	if (candidates.length === 0) {
+		if (target_skill) {
+			throw new UsageError(`${target_skill} is not installed. Run 'happyskills install ${target_skill}' first.`)
+		}
 		if (args.flags.json) {
-			print_json({ data: { updated: [], already_up_to_date: [], count: 0 } })
+			print_json({ data: { results: [], outdated_count: 0, up_to_date_count: 0, updated: [], already_up_to_date: [], errors: [] } })
 			return
 		}
-		print_info('No skills to update.')
+		print_info('No skills installed.')
 		return
 	}
 
-	const options = {
-		global: is_global,
-		fresh: true,
-		agents: args.flags.agents || undefined,
-		project_root
+	// ─── --force path: skip the version check, re-install everything ─────────
+	if (force) {
+		const options = { global: is_global, fresh: true, force: true, agents: args.flags.agents || undefined, project_root }
+		const updated = []
+		for (const [name, data] of candidates) {
+			const before_version = data?.version || null
+			const spinner = !args.flags.json ? create_spinner(`Re-installing ${name}…`) : null
+			const [errors, result] = await install(name, options)
+			if (errors) {
+				spinner?.fail(`Failed to re-install ${name}`)
+				throw e(`Update ${name} failed`, errors)
+			}
+			spinner?.succeed(`Re-installed ${name}@${result.version}`)
+			updated.push({ skill: name, from: before_version, to: result.version, via: get_via(data) })
+		}
+		if (args.flags.json) {
+			print_json({ data: { updated, count: updated.length, forced: true } })
+			return
+		}
+		if (updated.length > 0) {
+			print_success(`Re-installed ${updated.length} skill(s) (--force).`)
+		}
+		return
 	}
 
-	const updated = []
-	const already_up_to_date = []
+	// ─── Default smart path: batch-check, then install only outdated ─────────
+	const spinner = !args.flags.json ? create_spinner('Checking for updates…') : null
+	const skill_names = candidates.map(([name]) => name)
+	const [batch_err, batch_data] = await repos_api.check_updates(skill_names)
 
-	const base_dir = skills_dir(is_global, project_root)
-	const force = args.flags.force || false
+	const results = []
+	if (batch_err) {
+		spinner?.fail('Failed to check for updates')
+		for (const [name, data] of candidates) {
+			results.push({ skill: name, installed: data.version, latest: 'error', status: 'error' })
+		}
+	} else {
+		spinner?.succeed('Checked for updates')
 
-	// Detect local modifications for all skills in parallel
-	const modified_set = new Set()
-	if (!force) {
-		const detections = await Promise.all(to_update.map(([name, data]) => {
-			if (!data) return { name, modified: false }
+		// Read installed manifests in parallel for dependency-drift detection
+		const manifest_map = {}
+		await Promise.all(candidates.map(async ([name]) => {
 			const short_name = name.split('/')[1] || name
 			const dir = skill_install_dir(base_dir, short_name)
-			return detect_status(data, dir).then(([, det]) => ({ name, modified: det?.local_modified || false }))
+			const [, manifest] = await read_manifest(dir)
+			if (manifest) manifest_map[name] = manifest
 		}))
-		for (const { name, modified } of detections) {
-			if (modified) modified_set.add(name)
+
+		for (const [name, data] of candidates) {
+			const info = batch_data?.results?.[name]
+			if (info?.access_denied) {
+				results.push({ skill: name, installed: data.version, latest: '-', status: 'no-access' })
+			} else if (!info || !info.latest_version) {
+				results.push({ skill: name, installed: data.version, latest: '-', status: 'unknown' })
+			} else if (data.base_commit && info.commit && data.base_commit !== info.commit) {
+				results.push({ skill: name, installed: data.version, latest: info.latest_version, status: 'outdated' })
+			} else if (!data.base_commit && info.latest_version !== data.version) {
+				// Fallback to version comparison for old lock files without base_commit
+				results.push({ skill: name, installed: data.version, latest: info.latest_version, status: 'outdated' })
+			} else if (has_dependency_drift(data, manifest_map[name])) {
+				// Lock dependencies are stale compared to installed skill.json
+				results.push({ skill: name, installed: data.version, latest: info.latest_version, status: 'outdated' })
+			} else {
+				results.push({ skill: name, installed: data.version, latest: info.latest_version, status: 'up-to-date' })
+			}
 		}
 	}
 
-	for (const [name, data] of to_update) {
-		if (modified_set.has(name)) {
-			print_warn(`${name} has local modifications. Use --force to discard, or 'happyskills pull' to merge.`)
-			continue
+	const outdated = results.filter(r => r.status === 'outdated')
+	const up_to_date = results.filter(r => r.status === 'up-to-date')
+
+	// Verify and repair symlinks (even when nothing is outdated)
+	const [, agents_data] = await resolve_agents(args.flags.agents)
+	const detected_agents = agents_data?.agents || []
+	let symlink_repairs = []
+	if (detected_agents.length > 0) {
+		const skills_to_check = []
+		for (const [name, data] of Object.entries(skills)) {
+			if (data?.type === SKILL_TYPES.KIT) continue
+			const short_name = name.split('/')[1] || name
+			const source_dir = skill_install_dir(base_dir, short_name)
+			const [, enabled] = await is_skill_enabled(short_name, detected_agents, is_global, project_root)
+			if (enabled) {
+				skills_to_check.push({ skill_name: short_name, source_dir })
+			}
 		}
+		if (skills_to_check.length > 0) {
+			const link_spinner = !args.flags.json ? create_spinner('Verifying symlinks…') : null
+			const [, repair_result] = await verify_and_repair_symlinks(skills_to_check, detected_agents, { global: is_global, project_root })
+			symlink_repairs = repair_result?.repaired || []
+			if (symlink_repairs.length > 0) {
+				link_spinner?.succeed(`Repaired ${symlink_repairs.length} symlink(s)`)
+			} else {
+				link_spinner?.succeed('All symlinks verified')
+			}
+		}
+	}
 
-		const before_version = data?.version || null
-		const [errors, result] = await install(name, options)
-		if (errors) throw e(`Update ${name} failed`, errors)
-		if (!result.no_op) {
-			updated.push({ skill: name, from: before_version, to: result.version, via: get_via(data) })
+	// If nothing to update, report and exit
+	if (outdated.length === 0) {
+		if (args.flags.json) {
+			print_json({ data: { results, outdated_count: 0, up_to_date_count: up_to_date.length, updated: [], already_up_to_date: up_to_date.map(r => ({ skill: r.skill, version: r.installed })), symlink_repairs, errors: [] } })
+			return
+		}
+		print_table(['Skill', 'Installed', 'Latest', 'Status'], results.map(r => [
+			r.skill, r.installed, r.latest, green(r.status)
+		]))
+		console.log()
+		if (symlink_repairs.length > 0) {
+			print_success(`All skills are up to date. Repaired ${symlink_repairs.length} symlink(s).`)
 		} else {
-			already_up_to_date.push({ skill: name, version: result.version, via: get_via(data) })
+			print_success('All skills are up to date.')
 		}
+		return
 	}
 
+	// Show results table (non-json)
+	if (!args.flags.json) {
+		const status_colors = { 'up-to-date': green, 'outdated': yellow, 'no-access': yellow, 'error': red, 'unknown': (s) => s }
+		print_table(['Skill', 'Installed', 'Latest', 'Status'], results.map(r => [
+			r.skill, r.installed, r.latest, (status_colors[r.status] || ((s) => s))(r.status)
+		]))
+		console.log()
+		print_info(`${outdated.length} skill(s) can be updated.`)
+	}
+
+	// Confirm
+	const should_update = auto_yes || !process.stdin.isTTY
+	if (!should_update && !args.flags.json) {
+		const answer = await confirm_prompt(`\nUpdate ${outdated.length} skill(s)? [y/N] `)
+		if (answer !== 'y' && answer !== 'yes') {
+			print_info('Skipped.')
+			return
+		}
+	}
+
+	// Detect local modifications on the outdated set
+	const detections = await Promise.all(outdated.map(r => {
+		const lock_entry = skills[r.skill]
+		const short_name = r.skill.split('/')[1] || r.skill
+		const dir = skill_install_dir(base_dir, short_name)
+		return detect_status(lock_entry, dir, { skill_name: r.skill, project_root, is_global }).then(([, det]) => ({ r, det }))
+	}))
+
+	const skipped = []
+	const safe_to_update = []
+	for (const { r, det } of detections) {
+		if (det?.local_modified) {
+			skipped.push({ skill: r.skill, reason: 'local_modifications', suggestion: `happyskills pull ${r.skill}` })
+		} else {
+			safe_to_update.push(r)
+		}
+	}
+
+	// Install only the outdated, non-modified skills
+	const options = { global: is_global, fresh: true, agents: args.flags.agents || undefined, project_root }
+	const updated = []
+	const update_errors = []
+
+	for (const r of safe_to_update) {
+		const update_spinner = !args.flags.json ? create_spinner(`Updating ${r.skill}…`) : null
+		const [errors, result] = await install(r.skill, options)
+		if (errors) {
+			update_spinner?.fail(`Failed to update ${r.skill}`)
+			update_errors.push({ skill: r.skill, message: errors[errors.length - 1]?.message || 'Unknown error' })
+		} else if (!result.no_op) {
+			update_spinner?.succeed(`Updated ${r.skill} ${r.installed} → ${result.version}`)
+			updated.push({ skill: r.skill, from: r.installed, to: result.version })
+		} else {
+			update_spinner?.succeed(`${r.skill} already up to date`)
+		}
+	}
+
+	// Output
 	if (args.flags.json) {
-		print_json({ data: { updated, already_up_to_date, count: updated.length } })
+		print_json({
+			data: {
+				results,
+				outdated_count: outdated.length,
+				up_to_date_count: up_to_date.length,
+				updated,
+				skipped,
+				already_up_to_date: up_to_date.map(r => ({ skill: r.skill, version: r.installed })),
+				errors: update_errors
+			}
+		})
 		return
 	}
 
+	if (skipped.length > 0) {
+		console.log()
+		print_warn(`Skipped ${skipped.length} skill(s) with local modifications:`)
+		for (const s of skipped) {
+			print_info(`  ${s.skill}`)
+		}
+		print_hint(`Use ${code('happyskills pull <skill>')} to merge remote changes.`)
+	}
 	if (updated.length > 0) {
-		print_success(`Updated ${updated.length} skill(s)`)
-	} else {
-		print_success('All skills are already up to date.')
+		console.log()
+		print_success(`Updated ${updated.length} skill(s).`)
+	}
+	if (update_errors.length > 0) {
+		console.log()
+		print_info(`${update_errors.length} skill(s) failed to update. Run ${code('happyskills check')} for details.`)
 	}
 }).then(([errors]) => { if (errors) { exit_with_error(errors); return } })
 

package/src/constants.js

@@ -30,7 +30,6 @@ const COMMAND_ALIASES = {
 	remove: 'uninstall',
 	ls: 'list',
 	s: 'search',
-	r: 'refresh',
 	st: 'status',
 	d: 'diff',
 	up: 'update',
@@ -52,7 +51,6 @@ const COMMANDS = [
 	'list',
 	'search',
 	'check',
-	'refresh',
 	'status',
 	'pull',
 	'diff',

package/src/index.js

@@ -92,11 +92,10 @@ Commands:
   list                     List installed skills (alias: ls)
   search <query>           Search the registry (alias: s)
   check [owner/skill]      Check for available updates
-  refresh                  Check + update all outdated skills (alias: r)
   status [owner/skill]     Show divergence status (alias: st)
   pull <owner/skill>       Pull remote changes and merge
   diff <owner/skill>       Show file-level differences (alias: d)
-  update [owner/skill]     Upgrade to latest versions (alias: up)
+  update [owner/skill]     Update outdated skills (alias: up). Smart by default; --force to re-install regardless
   publish                  Push skill to registry (alias: pub)
   validate <skill-name>    Validate skill against all rules (alias: v)
   fork <owner/skill>       Fork a skill to your workspace

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', 'refresh', 'update', 'publish', 'validate', 'fork', 'login', 'logout', 'whoami', 'init', 'setup', 'self-update']
+		const expected_commands = ['install', 'uninstall', 'list', 'search', 'check', 'update', 'publish', 'validate', 'fork', 'login', 'logout', 'whoami', 'init', 'setup', 'self-update']
 		for (const cmd of expected_commands) {
 			assert.ok(stdout.includes(cmd), `help output should mention "${cmd}"`)
 		}
@@ -160,10 +160,8 @@ describe('CLI — command --help', () => {
 		['search',    'Arguments:'],
 		['search',    'Aliases:'],
 		['check',     'Examples:'],
-		['refresh',   'Options:'],
-		['refresh',   'Examples:'],
-		['refresh',   'Aliases:'],
 		['update',    'Aliases:'],
+		['update',    '--force'],
 		['publish',   'Aliases:'],
 		['validate',  'Arguments:'],
 		['validate',  'Aliases:'],
@@ -199,7 +197,6 @@ describe('CLI — command aliases', () => {
 		['remove', 'uninstall'],
 		['ls',     'list'],
 		['s',      'search'],
-		['r',      'refresh'],
 		['up',     'update'],
 		['pub',    'publish'],
 		['v',      'validate'],
@@ -423,15 +420,15 @@ describe('CLI — --json: existing json commands now use { data } envelope', ()
 	})
 })
 
-// ─── refresh command ──────────────────────────────────────────────────────────
+// ─── update --all (smart batch-check) ─────────────────────────────────────────
 
-describe('CLI — --json: refresh command', () => {
-	it('refresh --json with no skills returns { data: { results, outdated_count, ... } }', () => {
+describe('CLI — --json: update --all command', () => {
+	it('update --all --json with no installed skills returns { data: { results, outdated_count, ... } }', () => {
 		const tmp = make_tmp()
 		try {
-			const { stdout, code } = run(['refresh', '--json'], {}, { cwd: tmp })
+			const { stdout, code } = run(['update', '--all', '--json'], {}, { cwd: tmp })
 			assert.strictEqual(code, 0)
-			const out = parse_json_output(stdout, 'refresh --json empty')
+			const out = parse_json_output(stdout, 'update --all --json empty')
 			assert.ok('data' in out)
 			assert.ok(Array.isArray(out.data.results))
 			assert.strictEqual(out.data.outdated_count, 0)

package/src/merge/detector.js

@@ -1,31 +1,91 @@
 const { error: { catch_errors } } = require('puffy-core')
 const { hash_directory } = require('../lock/integrity')
+const { find_modified_files } = require('./file_diff')
+const { read_lock, get_all_locked_skills } = require('../lock/reader')
+const { write_lock, update_lock_skills } = require('../lock/writer')
+const { lock_root } = require('../config/paths')
+
+// Serialize lock heals across concurrent detect_status calls so parallel
+// read-modify-write sequences don't clobber each other's updates.
+let heal_chain = Promise.resolve()
+
+const queue_heal = (skill_name, current_integrity, project_root, is_global) => {
+	const next = heal_chain.then(async () => {
+		const root = lock_root(is_global, project_root)
+		const [, lock_data] = await read_lock(root)
+		if (!lock_data) return
+		const skills = get_all_locked_skills(lock_data)
+		const entry = skills[skill_name]
+		if (!entry) return
+		if (entry.base_integrity === current_integrity && entry.integrity === current_integrity) return
+		const updated = { ...entry, base_integrity: current_integrity, integrity: current_integrity }
+		const merged = update_lock_skills(lock_data, { [skill_name]: updated })
+		await write_lock(root, merged)
+		if (process.env.HAPPYSKILLS_DEBUG) {
+			process.stderr.write(`integrity drift auto-healed for ${skill_name}\n`)
+		}
+	}).catch(() => {})
+	heal_chain = next
+	return next
+}
 
 /**
  * Detects whether a skill has been locally modified since install/pull.
  *
- * Compares the current directory hash against the base_integrity recorded
- * in the lock file. If they differ, the user has local modifications.
+ * Two-stage check:
+ *   1. Fast path — compare hash_directory(disk) against lock.base_integrity.
+ *      If they match, the skill is unmodified.
+ *   2. Fallback — when the aggregate hash disagrees, fetch the registry
+ *      manifest at base_commit and compare per-file (git blob SHAs). The
+ *      aggregate hash is only an optimization; the per-file comparison is
+ *      the source of truth.
+ *
+ *      - Zero files differ → the lock's integrity has drifted (e.g. server
+ *        normalized which files are returned). Auto-heal the lock entry's
+ *        integrity / base_integrity to the current value and report clean.
+ *      - One or more files differ → real local modifications. Return them
+ *        in `modified_files` for better diagnostics.
  *
- * @param {object} lock_entry - Lock file entry for the skill
- * @param {string} skill_dir  - Absolute path to the skill directory
- * @returns {[errors, { local_modified, current_integrity, base_integrity, base_commit }]}
+ * The fallback requires `options.skill_name` and a base_commit on the lock;
+ * without them, the function falls back to the legacy pessimistic answer
+ * (local_modified: true on aggregate mismatch).
+ *
+ * @param {object} lock_entry
+ * @param {string} skill_dir
+ * @param {object} [options]
+ * @param {string} [options.skill_name]   - "owner/repo" (enables fallback)
+ * @param {string} [options.project_root] - Project root for lock heal
+ * @param {boolean} [options.is_global]   - Whether to heal the global lock
  */
-const detect_status = (lock_entry, skill_dir) => catch_errors('Failed to detect status', async () => {
+const detect_status = (lock_entry, skill_dir, options = {}) => catch_errors('Failed to detect status', async () => {
 	const base_commit = lock_entry?.base_commit || null
 	const base_integrity = lock_entry?.base_integrity || null
 
-	if (!base_integrity) return { local_modified: false, current_integrity: null, base_integrity: null, base_commit }
+	if (!base_integrity) return { local_modified: false, current_integrity: null, base_integrity: null, base_commit, modified_files: null }
 
 	const [hash_err, current_integrity] = await hash_directory(skill_dir)
-	if (hash_err) return { local_modified: false, current_integrity: null, base_integrity, base_commit }
+	if (hash_err) return { local_modified: false, current_integrity: null, base_integrity, base_commit, modified_files: null }
+
+	if (current_integrity === base_integrity) {
+		return { local_modified: false, current_integrity, base_integrity, base_commit, modified_files: [] }
+	}
 
-	return {
-		local_modified: current_integrity !== base_integrity,
-		current_integrity,
-		base_integrity,
-		base_commit
+	const { skill_name = null, project_root = null, is_global = false } = options
+	if (!skill_name || !base_commit) {
+		return { local_modified: true, current_integrity, base_integrity, base_commit, modified_files: null }
 	}
+
+	const [, modified_files] = await find_modified_files(skill_name, base_commit, skill_dir)
+	if (modified_files === null) {
+		return { local_modified: true, current_integrity, base_integrity, base_commit, modified_files: null }
+	}
+
+	if (modified_files.length === 0) {
+		if (project_root) await queue_heal(skill_name, current_integrity, project_root, is_global)
+		return { local_modified: false, current_integrity, base_integrity: current_integrity, base_commit, modified_files: [], healed: true }
+	}
+
+	return { local_modified: true, current_integrity, base_integrity, base_commit, modified_files }
 })
 
 module.exports = { detect_status }

package/src/merge/detector.test.js

@@ -1,22 +1,40 @@
-const { describe, it, afterEach } = require('node:test')
+const { describe, it, afterEach, before, after } = require('node:test')
 const assert = require('node:assert/strict')
 const fs = require('fs')
 const path = require('path')
 const os = require('os')
-const { detect_status } = require('./detector')
 const { hash_directory, clear_integrity_cache } = require('../lock/integrity')
+const { hash_blob } = require('../utils/git_hash')
 
-const make_tmp = () => {
-	const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'detector-test-'))
-	return dir
+// Stub repos_api before file_diff/detector load it. find_modified_files
+// uses repos_api.clone, so we control its return value via the stub state.
+const repos_api_path = require.resolve('../api/repos')
+const stub_state = { files: [], err: null }
+require.cache[repos_api_path] = {
+	id: repos_api_path,
+	filename: repos_api_path,
+	loaded: true,
+	exports: {
+		clone: async () => stub_state.err
+			? [[stub_state.err], null]
+			: [null, { files: stub_state.files }]
+	}
 }
 
+const { detect_status } = require('./detector')
+
+const make_tmp = () => fs.mkdtempSync(path.join(os.tmpdir(), 'detector-test-'))
 const rm = (dir) => { try { fs.rmSync(dir, { recursive: true }) } catch (_) {} }
 
 describe('detect_status', () => {
 	let tmp_dir
 
-	afterEach(() => { if (tmp_dir) rm(tmp_dir) })
+	afterEach(() => {
+		if (tmp_dir) { rm(tmp_dir); tmp_dir = null }
+		stub_state.files = []
+		stub_state.err = null
+		clear_integrity_cache()
+	})
 
 	it('returns local_modified: false when integrity matches', async () => {
 		tmp_dir = make_tmp()
@@ -33,13 +51,12 @@ describe('detect_status', () => {
 		assert.equal(result.base_commit, 'abc123')
 	})
 
-	it('returns local_modified: true when integrity differs', async () => {
+	it('returns local_modified: true when integrity differs and no fallback context is given', async () => {
 		tmp_dir = make_tmp()
 		fs.writeFileSync(path.join(tmp_dir, 'SKILL.md'), 'hello')
 
 		const [, integrity] = await hash_directory(tmp_dir)
 
-		// Modify the file and clear hash cache (cache is per-command-invocation optimization)
 		fs.writeFileSync(path.join(tmp_dir, 'SKILL.md'), 'modified')
 		clear_integrity_cache()
 
@@ -48,6 +65,7 @@ describe('detect_status', () => {
 		assert.equal(err, null)
 		assert.equal(result.local_modified, true)
 		assert.notEqual(result.current_integrity, integrity)
+		assert.equal(result.modified_files, null)
 	})
 
 	it('returns local_modified: false when base_integrity is missing', async () => {
@@ -75,4 +93,100 @@ describe('detect_status', () => {
 		assert.equal(err, null)
 		assert.equal(result.local_modified, false)
 	})
+
+	it('auto-heals the lock when aggregate integrity drifts but per-file content matches the registry', async () => {
+		tmp_dir = make_tmp()
+		const project_root = make_tmp()
+
+		const skill_content = 'hello'
+		fs.writeFileSync(path.join(tmp_dir, 'SKILL.md'), skill_content)
+
+		// Stub registry to return the same content the disk has (same git blob sha).
+		stub_state.files = [{ path: 'SKILL.md', sha: hash_blob(Buffer.from(skill_content)) }]
+
+		// Lock has a stale base_integrity that does NOT match the current hash_directory.
+		const stale_integrity = 'sha256-stale0000000000000000000000000000000000000000000000000000000000'
+		const lock_path = path.join(project_root, 'skills-lock.json')
+		fs.writeFileSync(lock_path, JSON.stringify({
+			lockVersion: 2,
+			generatedAt: new Date().toISOString(),
+			skills: {
+				'acme/test-skill': {
+					version: '1.0.0',
+					base_commit: 'abc123',
+					base_integrity: stale_integrity,
+					integrity: stale_integrity
+				}
+			}
+		}))
+
+		const lock_entry = { base_integrity: stale_integrity, base_commit: 'abc123' }
+		const [err, result] = await detect_status(lock_entry, tmp_dir, {
+			skill_name: 'acme/test-skill',
+			project_root,
+			is_global: false
+		})
+
+		assert.equal(err, null)
+		assert.equal(result.local_modified, false)
+		assert.equal(result.healed, true)
+		assert.deepEqual(result.modified_files, [])
+
+		// Wait for the heal write to complete (queued via promise chain).
+		await new Promise(r => setTimeout(r, 50))
+		const lock_after = JSON.parse(fs.readFileSync(lock_path, 'utf-8'))
+		assert.equal(lock_after.skills['acme/test-skill'].base_integrity, result.current_integrity)
+		assert.equal(lock_after.skills['acme/test-skill'].integrity, result.current_integrity)
+
+		rm(project_root)
+	})
+
+	it('reports real local modifications with a list of differing files when fallback runs', async () => {
+		tmp_dir = make_tmp()
+		const project_root = make_tmp()
+
+		fs.writeFileSync(path.join(tmp_dir, 'SKILL.md'), 'edited locally')
+		fs.writeFileSync(path.join(tmp_dir, 'skill.json'), '{}')
+
+		// Registry says SKILL.md should have different content; skill.json matches.
+		stub_state.files = [
+			{ path: 'SKILL.md', sha: hash_blob(Buffer.from('original')) },
+			{ path: 'skill.json', sha: hash_blob(Buffer.from('{}')) }
+		]
+
+		fs.writeFileSync(path.join(project_root, 'skills-lock.json'), JSON.stringify({
+			lockVersion: 2,
+			generatedAt: new Date().toISOString(),
+			skills: {}
+		}))
+
+		const lock_entry = { base_integrity: 'sha256-stale', base_commit: 'abc123' }
+		const [err, result] = await detect_status(lock_entry, tmp_dir, {
+			skill_name: 'acme/test-skill',
+			project_root,
+			is_global: false
+		})
+
+		assert.equal(err, null)
+		assert.equal(result.local_modified, true)
+		assert.deepEqual(result.modified_files, ['SKILL.md'])
+
+		rm(project_root)
+	})
+
+	it('falls back to pessimistic local_modified: true when registry fetch fails', async () => {
+		tmp_dir = make_tmp()
+		fs.writeFileSync(path.join(tmp_dir, 'SKILL.md'), 'hello')
+
+		stub_state.err = new Error('network down')
+
+		const lock_entry = { base_integrity: 'sha256-stale', base_commit: 'abc123' }
+		const [err, result] = await detect_status(lock_entry, tmp_dir, {
+			skill_name: 'acme/test-skill'
+		})
+
+		assert.equal(err, null)
+		assert.equal(result.local_modified, true)
+		assert.equal(result.modified_files, null)
+	})
 })

package/src/merge/file_diff.js

@@ -0,0 +1,68 @@
+const fs = require('fs')
+const path = require('path')
+const { error: { catch_errors } } = require('puffy-core')
+const repos_api = require('../api/repos')
+const { hash_blob } = require('../utils/git_hash')
+
+const build_local_file_shas = (skill_dir) => catch_errors('Failed to build local file shas', async () => {
+	const entries = []
+	const walk = async (dir, prefix) => {
+		let items
+		try {
+			items = await fs.promises.readdir(dir, { withFileTypes: true })
+		} catch {
+			return
+		}
+		for (const item of items) {
+			if (item.name.startsWith('.')) continue
+			const rel = prefix ? `${prefix}/${item.name}` : item.name
+			const full = path.join(dir, item.name)
+			if (item.isDirectory()) {
+				await walk(full, rel)
+			} else if (item.isFile()) {
+				const content = await fs.promises.readFile(full)
+				entries.push({ path: rel, sha: hash_blob(content) })
+			}
+		}
+	}
+	await walk(skill_dir, '')
+	return entries
+})
+
+/**
+ * Compares disk content against the registry baseline at base_commit and
+ * returns the list of paths whose content actually differs. An empty array
+ * means the disk is byte-identical to the registry (per Git blob hashing).
+ *
+ * Returns null when the comparison cannot be performed (network failure,
+ * missing inputs) so callers can fall back to a pessimistic answer.
+ *
+ * @param {string} skill_name - "owner/repo"
+ * @param {string} base_commit
+ * @param {string} skill_dir - Absolute path to the on-disk skill
+ * @returns {[errors, string[]|null]}
+ */
+const find_modified_files = (skill_name, base_commit, skill_dir) => catch_errors('Failed to compare disk to registry', async () => {
+	if (!skill_name || !skill_name.includes('/') || !base_commit) return null
+
+	const [owner, repo] = skill_name.split('/')
+	const [clone_err, clone_data] = await repos_api.clone(owner, repo, null, { commit: base_commit })
+	if (clone_err) return null
+
+	const base_files = clone_data.files || []
+	const base_map = new Map(base_files.map(f => [f.path, f.sha]))
+
+	const [local_err, local_entries] = await build_local_file_shas(skill_dir)
+	if (local_err) return null
+	const local_map = new Map(local_entries.map(e => [e.path, e.sha]))
+
+	const all_paths = new Set([...base_map.keys(), ...local_map.keys()])
+	const modified = []
+	for (const p of all_paths) {
+		if (base_map.get(p) !== local_map.get(p)) modified.push(p)
+	}
+	modified.sort()
+	return modified
+})
+
+module.exports = { find_modified_files, build_local_file_shas }

package/src/commands/refresh.js

@@ -1,256 +0,0 @@
-const { error: { catch_errors, wrap_errors: e } } = require('puffy-core')
-const { install } = require('../engine/installer')
-const { read_lock, get_all_locked_skills } = require('../lock/reader')
-const { read_manifest } = require('../manifest/reader')
-const { detect_status } = require('../merge/detector')
-const repos_api = require('../api/repos')
-const { print_help, print_table, print_json, print_info, print_success, print_warn, print_hint, code } = require('../ui/output')
-const { green, yellow, red } = require('../ui/colors')
-const { create_spinner } = require('../ui/spinner')
-const { exit_with_error } = require('../utils/errors')
-const { find_project_root, lock_root, skills_dir, skill_install_dir } = require('../config/paths')
-const { EXIT_CODES, SKILL_TYPES } = require('../constants')
-const { resolve_agents, verify_and_repair_symlinks } = require('../agents')
-const { is_skill_enabled } = require('../agents/status')
-
-const HELP_TEXT = `Usage: happyskills refresh [options]
-
-Check all installed skills for updates and upgrade outdated ones.
-
-Options:
-  -g, --global      Refresh globally installed skills
-  -y, --yes         Skip confirmation prompts
-  --json            Output as JSON
-
-Aliases: r
-
-Examples:
-  happyskills refresh
-  happyskills refresh -y
-  happyskills refresh -g -y --json`
-
-/**
- * Returns true if the lock entry's dependencies differ from the installed skill.json's dependencies.
- */
-const has_dependency_drift = (lock_entry, manifest) => {
-	if (!manifest) return false
-	const lock_deps = JSON.stringify(lock_entry.dependencies || {})
-	const manifest_deps = JSON.stringify(manifest.dependencies || {})
-	return lock_deps !== manifest_deps
-}
-
-const confirm_prompt = (question) => new Promise((resolve) => {
-	const readline = require('readline')
-	const rl = readline.createInterface({ input: process.stdin, output: process.stderr })
-	rl.question(question, (answer) => {
-		rl.close()
-		resolve(answer.trim().toLowerCase())
-	})
-})
-
-const run = (args) => catch_errors('Refresh failed', async () => {
-	if (args.flags._show_help) {
-		print_help(HELP_TEXT)
-		return process.exit(EXIT_CODES.SUCCESS)
-	}
-
-	const is_global = args.flags.global || false
-	const auto_yes = args.flags.yes || false
-	const project_root = find_project_root()
-	const [, lock_data] = await read_lock(lock_root(is_global, project_root))
-	const skills = get_all_locked_skills(lock_data)
-	const entries = Object.entries(skills)
-
-	const to_check = entries.filter(([, data]) => data.requested_by?.includes('__root__'))
-
-	if (to_check.length === 0) {
-		if (args.flags.json) {
-			print_json({ data: { results: [], outdated_count: 0, up_to_date_count: 0, updated: [], already_up_to_date: [], errors: [] } })
-			return
-		}
-		print_info('No skills installed.')
-		return
-	}
-
-	// 1. Check for updates
-	const spinner = !args.flags.json ? create_spinner('Checking for updates…') : null
-	const skill_names = to_check.map(([name]) => name)
-	const [batch_err, batch_data] = await repos_api.check_updates(skill_names)
-	const base_dir = skills_dir(is_global, project_root)
-
-	const results = []
-	if (batch_err) {
-		spinner?.fail('Failed to check for updates')
-		for (const [name, data] of to_check) {
-			results.push({ skill: name, installed: data.version, latest: 'error', status: 'error' })
-		}
-	} else {
-		spinner?.succeed('Checked for updates')
-		// Read all installed manifests in parallel to check for dependency drift
-		const manifest_map = {}
-		await Promise.all(to_check.map(async ([name]) => {
-			const short_name = name.split('/')[1] || name
-			const dir = skill_install_dir(base_dir, short_name)
-			const [, manifest] = await read_manifest(dir)
-			if (manifest) manifest_map[name] = manifest
-		}))
-		for (const [name, data] of to_check) {
-			const info = batch_data?.results?.[name]
-			if (info?.access_denied) {
-				results.push({ skill: name, installed: data.version, latest: '-', status: 'no-access' })
-			} else if (!info || !info.latest_version) {
-				results.push({ skill: name, installed: data.version, latest: '-', status: 'unknown' })
-			} else if (data.base_commit && info.commit && data.base_commit !== info.commit) {
-				results.push({ skill: name, installed: data.version, latest: info.latest_version, status: 'outdated' })
-			} else if (!data.base_commit && info.latest_version !== data.version) {
-				// Fallback to version comparison for old lock files without base_commit
-				results.push({ skill: name, installed: data.version, latest: info.latest_version, status: 'outdated' })
-			} else if (has_dependency_drift(data, manifest_map[name])) {
-				// Lock dependencies are stale compared to installed skill.json
-				results.push({ skill: name, installed: data.version, latest: info.latest_version, status: 'outdated' })
-			} else {
-				results.push({ skill: name, installed: data.version, latest: info.latest_version, status: 'up-to-date' })
-			}
-		}
-	}
-
-	const outdated = results.filter(r => r.status === 'outdated')
-	const up_to_date = results.filter(r => r.status === 'up-to-date')
-
-	// 2. Verify and repair symlinks for all skills (even when nothing is outdated)
-	const [, agents_data] = await resolve_agents(args.flags.agents)
-	const detected_agents = agents_data?.agents || []
-	let symlink_repairs = []
-	if (detected_agents.length > 0) {
-		const skills_to_check = []
-		for (const [name, data] of entries) {
-			if (data.type === SKILL_TYPES.KIT) continue
-			const short_name = name.split('/')[1] || name
-			const source_dir = skill_install_dir(base_dir, short_name)
-			const [, enabled] = await is_skill_enabled(short_name, detected_agents, is_global, project_root)
-			if (enabled) {
-				skills_to_check.push({ skill_name: short_name, source_dir })
-			}
-		}
-		if (skills_to_check.length > 0) {
-			const link_spinner = !args.flags.json ? create_spinner('Verifying symlinks…') : null
-			const [, repair_result] = await verify_and_repair_symlinks(skills_to_check, detected_agents, { global: is_global, project_root })
-			symlink_repairs = repair_result?.repaired || []
-			if (symlink_repairs.length > 0) {
-				link_spinner?.succeed(`Repaired ${symlink_repairs.length} symlink(s)`)
-			} else {
-				link_spinner?.succeed('All symlinks verified')
-			}
-		}
-	}
-
-	// 3. If nothing to update, report and exit
-	if (outdated.length === 0) {
-		if (args.flags.json) {
-			print_json({ data: { results, outdated_count: 0, up_to_date_count: up_to_date.length, updated: [], already_up_to_date: up_to_date.map(r => ({ skill: r.skill, version: r.installed })), symlink_repairs, errors: [] } })
-			return
-		}
-		print_table(['Skill', 'Installed', 'Latest', 'Status'], results.map(r => [
-			r.skill, r.installed, r.latest, green(r.status)
-		]))
-		console.log()
-		if (symlink_repairs.length > 0) {
-			print_success(`All skills are up to date. Repaired ${symlink_repairs.length} symlink(s).`)
-		} else {
-			print_success('All skills are up to date.')
-		}
-		return
-	}
-
-	// 4. Show results table (non-json)
-	if (!args.flags.json) {
-		const status_colors = { 'up-to-date': green, 'outdated': yellow, 'no-access': yellow, 'error': red, 'unknown': (s) => s }
-		print_table(['Skill', 'Installed', 'Latest', 'Status'], results.map(r => [
-			r.skill, r.installed, r.latest, (status_colors[r.status] || ((s) => s))(r.status)
-		]))
-		console.log()
-		print_info(`${outdated.length} skill(s) can be updated.`)
-	}
-
-	// 5. Confirm update
-	const should_update = auto_yes || !process.stdin.isTTY
-	if (!should_update && !args.flags.json) {
-		const answer = await confirm_prompt(`\nUpdate ${outdated.length} skill(s)? [y/N] `)
-		if (answer !== 'y' && answer !== 'yes') {
-			print_info('Skipped.')
-			return
-		}
-	}
-
-	// 6. Detect local modifications for all outdated skills in parallel
-	const detections = await Promise.all(outdated.map(r => {
-		const lock_entry = skills[r.skill]
-		const short_name = r.skill.split('/')[1] || r.skill
-		const dir = skill_install_dir(base_dir, short_name)
-		return detect_status(lock_entry, dir).then(([, det]) => ({ r, det }))
-	}))
-
-	const skipped = []
-	const safe_to_update = []
-	for (const { r, det } of detections) {
-		if (det?.local_modified) {
-			skipped.push({ skill: r.skill, reason: 'local_modifications', suggestion: `happyskills pull ${r.skill}` })
-		} else {
-			safe_to_update.push(r)
-		}
-	}
-
-	// 7. Update safe skills
-	const options = { global: is_global, fresh: true, agents: args.flags.agents || undefined, project_root }
-	const updated = []
-	const update_errors = []
-
-	for (const r of safe_to_update) {
-		const update_spinner = !args.flags.json ? create_spinner(`Updating ${r.skill}…`) : null
-		const [errors, result] = await install(r.skill, options)
-		if (errors) {
-			update_spinner?.fail(`Failed to update ${r.skill}`)
-			update_errors.push({ skill: r.skill, message: errors[errors.length - 1]?.message || 'Unknown error' })
-		} else if (!result.no_op) {
-			update_spinner?.succeed(`Updated ${r.skill} ${r.installed} → ${result.version}`)
-			updated.push({ skill: r.skill, from: r.installed, to: result.version })
-		} else {
-			update_spinner?.succeed(`${r.skill} already up to date`)
-		}
-	}
-
-	// 8. Output results
-	if (args.flags.json) {
-		print_json({
-			data: {
-				results,
-				outdated_count: outdated.length,
-				up_to_date_count: up_to_date.length,
-				updated,
-				skipped,
-				already_up_to_date: up_to_date.map(r => ({ skill: r.skill, version: r.installed })),
-				errors: update_errors
-			}
-		})
-		return
-	}
-
-	if (skipped.length > 0) {
-		console.log()
-		print_warn(`Skipped ${skipped.length} skill(s) with local modifications:`)
-		for (const s of skipped) {
-			print_info(`  ${s.skill}`)
-		}
-		print_hint(`Use ${code('happyskills pull <skill>')} to merge remote changes.`)
-	}
-	if (updated.length > 0) {
-		console.log()
-		print_success(`Updated ${updated.length} skill(s).`)
-	}
-	if (update_errors.length > 0) {
-		console.log()
-		print_info(`${update_errors.length} skill(s) failed to update. Run ${code('happyskills check')} for details.`)
-	}
-}).then(([errors]) => { if (errors) { exit_with_error(errors); return } })
-
-module.exports = { run }