happyskills 0.20.0 → 0.22.0

package/CHANGELOG.md

@@ -7,6 +7,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.22.0] - 2026-03-30
+
+### Added
+- Add remote version check to `bump` — warns if the target version already exists on the registry before proceeding
+- Add per-file merge strategy to `pull` — use `--theirs SKILL.md,skill.json --ours references/foo.md` to resolve conflicts file-by-file instead of all-or-nothing
+- Add `--strict` flag to `pull` — fails on incompatible dependency ranges instead of warning
+- Add dependency range validation to `pull` — warns when an installed dependency version falls outside the constraint declared in the merged `skill.json`
+
+### Changed
+- Move auth verification earlier in `publish` — `list_workspaces()` now runs immediately after `require_token()`, failing fast on invalid/expired tokens before validation or upload
+- Cache `hash_directory` results in memory within a single command invocation — prevents redundant disk reads when `status` or `refresh` checks multiple skills
+
+## [0.21.0] - 2026-03-30
+
+### Changed
+- Upgrade `check` and `refresh` from semver-only to commit-level comparison (`base_commit` vs remote head) for accurate divergence detection — catches divergence even when version strings match (e.g., after force-publish). Falls back to version comparison for old lock files without `base_commit`.
+
+### Added
+- Add `conflicts` status to `check` command — detects unresolved merge conflicts from the lock file's `conflict_files` field without disk I/O. JSON output now includes `conflicts_count`.
+- Add local modification protection to `refresh` — skills with local edits are skipped with a warning and `happyskills pull` suggestion instead of being silently overwritten. JSON output includes `skipped` array with `{ skill, reason, suggestion }` per entry.
+
 ## [0.20.0] - 2026-03-30
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "happyskills",
-	"version": "0.20.0",
+	"version": "0.22.0",
 	"description": "Package manager for AI agent skills",
 	"license": "SEE LICENSE IN LICENSE",
 	"author": "Nicolas Dao <nic@cloudlesslabs.com> (https://cloudlesslabs.com)",

package/src/commands/bump.js

@@ -8,7 +8,8 @@ const { find_project_root } = require('../config/paths')
 const { read_lock, get_all_locked_skills } = require('../lock/reader')
 const { write_lock, update_lock_skills } = require('../lock/writer')
 const { hash_directory } = require('../lock/integrity')
-const { print_help, print_success, print_json } = require('../ui/output')
+const repos_api = require('../api/repos')
+const { print_help, print_success, print_warn, print_json } = require('../ui/output')
 const { exit_with_error, UsageError } = require('../utils/errors')
 const { EXIT_CODES } = require('../constants')
 
@@ -50,6 +51,17 @@ const run = (args) => catch_errors('Bump failed', async () => {
 
 	const old_version = manifest.version
 
+	// Read lock file early to resolve full skill name for remote check + lock update
+	const project_root = find_project_root()
+	const [lock_err, lock_data] = await read_lock(project_root)
+	let lock_key = null
+	let all_skills = null
+	if (!lock_err && lock_data) {
+		all_skills = get_all_locked_skills(lock_data)
+		const suffix = `/${skill_name}`
+		lock_key = Object.keys(all_skills).find(k => k.endsWith(suffix)) || null
+	}
+
 	if (BUMP_TYPES.includes(input)) {
 		const new_version = inc(old_version, input)
 		if (!new_version) throw new Error(`Failed to bump version from ${old_version}`)
@@ -60,6 +72,15 @@ const run = (args) => catch_errors('Bump failed', async () => {
 		manifest.version = cleaned
 	}
 
+	// Warn if target version already exists remotely
+	if (lock_key) {
+		const [, batch_data] = await repos_api.check_updates([lock_key])
+		const info = batch_data?.results?.[lock_key]
+		if (info?.latest_version === manifest.version) {
+			print_warn(`Version ${manifest.version} already exists remotely for ${lock_key}. Publishing will fail with VERSION_EXISTS.`)
+		}
+	}
+
 	const validation = validate_manifest(manifest)
 	if (!validation.valid) {
 		throw new Error(`Invalid manifest after bump: ${validation.errors.join(', ')}`)
@@ -68,23 +89,16 @@ const run = (args) => catch_errors('Bump failed', async () => {
 	const [write_err] = await write_manifest(dir, manifest)
 	if (write_err) throw e('Failed to update skill.json', write_err)
 
-	const project_root = find_project_root()
-	const [lock_err, lock_data] = await read_lock(project_root)
-	if (!lock_err && lock_data) {
-		const all_skills = get_all_locked_skills(lock_data)
-		const suffix = `/${skill_name}`
-		const lock_key = Object.keys(all_skills).find(k => k.endsWith(suffix))
-		if (lock_key && all_skills[lock_key]) {
-			const [hash_err, integrity] = await hash_directory(dir)
-			const updated_entry = {
-				...all_skills[lock_key],
-				version: manifest.version,
-				ref: `refs/tags/v${manifest.version}`
-			}
-			if (!hash_err && integrity) updated_entry.integrity = integrity
-			const updated_skills = update_lock_skills(lock_data, { [lock_key]: updated_entry })
-			await write_lock(project_root, updated_skills)
+	if (lock_key && all_skills?.[lock_key]) {
+		const [hash_err, integrity] = await hash_directory(dir)
+		const updated_entry = {
+			...all_skills[lock_key],
+			version: manifest.version,
+			ref: `refs/tags/v${manifest.version}`
 		}
+		if (!hash_err && integrity) updated_entry.integrity = integrity
+		const updated_skills = update_lock_skills(lock_data, { [lock_key]: updated_entry })
+		await write_lock(project_root, updated_skills)
 	}
 
 	if (args.flags.json) {

package/src/commands/check.js

@@ -1,7 +1,6 @@
 const { error: { catch_errors, wrap_errors: e } } = require('puffy-core')
 const { read_lock, get_all_locked_skills } = require('../lock/reader')
 const repos_api = require('../api/repos')
-const { gt } = require('../utils/semver')
 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 { exit_with_error } = require('../utils/errors')
@@ -68,13 +67,17 @@ const run = (args) => catch_errors('Check failed', async () => {
 	} else {
 		for (const [name, data] of to_check) {
 			const info = batch_data?.results?.[name]
-			if (info?.access_denied) {
+			const has_conflicts = (data.conflict_files || []).length > 0
+			if (has_conflicts) {
+				results.push({ skill: name, installed: data.version, latest: info?.latest_version || '-', status: 'conflicts' })
+			} else 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 (info.latest_version === data.version) {
-				results.push({ skill: name, installed: data.version, latest: info.latest_version, status: 'up-to-date' })
-			} else if (gt(info.latest_version, data.version)) {
+			} 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 {
 				results.push({ skill: name, installed: data.version, latest: info.latest_version, status: 'up-to-date' })
@@ -85,13 +88,15 @@ const run = (args) => catch_errors('Check failed', async () => {
 	if (args.flags.json) {
 		const outdated_count = results.filter(r => r.status === 'outdated').length
 		const up_to_date_count = results.filter(r => r.status === 'up-to-date').length
-		print_json({ data: { results, outdated_count, up_to_date_count } })
+		const conflicts_count = results.filter(r => r.status === 'conflicts').length
+		print_json({ data: { results, outdated_count, up_to_date_count, conflicts_count } })
 		return
 	}
 
 	const status_colors = {
 		'up-to-date': green,
 		'outdated': yellow,
+		'conflicts': red,
 		'no-access': yellow,
 		'error': red,
 		'unknown': (s) => s
@@ -107,11 +112,17 @@ const run = (args) => catch_errors('Check failed', async () => {
 	print_table(['Skill', 'Installed', 'Latest', 'Status'], rows)
 
 	const outdated = results.filter(r => r.status === 'outdated')
+	const conflicts = results.filter(r => r.status === 'conflicts')
 	const no_access = results.filter(r => r.status === 'no-access')
+	if (conflicts.length > 0) {
+		console.log()
+		print_warn(`${conflicts.length} skill(s) have unresolved merge conflicts.`)
+		print_hint(`Run ${code('happyskills status')} for details.`)
+	}
 	if (outdated.length > 0) {
 		console.log()
 		print_info(`Run ${code('happyskills update')} to upgrade ${outdated.length} skill(s).`)
-	} else if (results.every(r => r.status === 'up-to-date')) {
+	} else if (conflicts.length === 0 && results.every(r => r.status === 'up-to-date')) {
 		console.log()
 		print_success('All skills are up to date.')
 	}

package/src/commands/publish.js

@@ -67,6 +67,10 @@ const run = (args) => catch_errors('Publish failed', async () => {
 
 	await require_token()
 
+	// Verify auth early — fail fast before validation and upload
+	const [ws_err, workspaces] = await workspaces_api.list_workspaces()
+	if (ws_err) throw e('Authentication failed — run \'happyskills login\' to re-authenticate.', ws_err)
+
 	const [dir_err, dir] = await resolve_skill_dir(skill_name)
 	if (dir_err) throw e(`Skill "${skill_name}" not found`, dir_err)
 
@@ -133,9 +137,6 @@ const run = (args) => catch_errors('Publish failed', async () => {
 		if (resolved_owner) owner = resolved_owner
 	}
 
-	const [ws_err, workspaces] = await workspaces_api.list_workspaces()
-	if (ws_err) { spinner.fail('Failed to list workspaces'); throw e('Failed to list workspaces', ws_err) }
-
 	const workspace = choose_workspace(workspaces, owner)
 
 	if (manifest.dependencies && Object.keys(manifest.dependencies).length > 0) {

package/src/commands/pull.js

@@ -10,6 +10,7 @@ const { three_way_merge } = require('../merge/text_merge')
 const { merge_skill_json } = require('../merge/json_merge')
 const { merge_changelog } = require('../merge/changelog_merge')
 const { hash_blob } = require('../utils/git_hash')
+const { satisfies } = require('../utils/semver')
 const { read_lock, get_all_locked_skills } = require('../lock/reader')
 const { write_lock, update_lock_skills } = require('../lock/writer')
 const { hash_directory } = require('../lock/integrity')
@@ -28,16 +29,18 @@ Arguments:
   owner/skill       Skill to pull (required)
 
 Options:
-  --theirs          Take remote version on conflicts
-  --ours            Keep local version on conflicts
+  --theirs [files]  Take remote version on conflicts (all, or comma-separated file list)
+  --ours [files]    Keep local version on conflicts (all, or comma-separated file list)
   --force           Discard all local changes, take remote entirely
   -g, --global      Pull globally installed skill
+  --strict          Fail on incompatible dependency ranges instead of warning
   --json            Output as JSON
   --full-report     Include inline file content and resolution steps in JSON output (for AI agent review)
 
 Examples:
   happyskills pull acme/deploy-aws
   happyskills pull acme/deploy-aws --theirs
+  happyskills pull acme/deploy-aws --theirs SKILL.md,skill.json --ours references/foo.md
   happyskills pull acme/deploy-aws --json --full-report`
 
 // ─── Helpers ──────────────────────────────────────────────────────────────────
@@ -105,8 +108,32 @@ const run = (args) => catch_errors('Pull failed', async () => {
 	}
 
 	const is_global = args.flags.global || false
-	const strategy = args.flags.theirs ? 'theirs' : args.flags.ours ? 'ours' : args.flags.force ? 'force' : null
 	const full_report = !!(args.flags.json && args.flags['full-report'])
+
+	// Parse per-file strategies: --theirs SKILL.md,skill.json --ours references/foo.md
+	const theirs_files = typeof args.flags.theirs === 'string'
+		? new Set(args.flags.theirs.split(',').map(s => s.trim()))
+		: null
+	const ours_files = typeof args.flags.ours === 'string'
+		? new Set(args.flags.ours.split(',').map(s => s.trim()))
+		: null
+
+	// Validate no path appears in both --theirs and --ours
+	if (theirs_files && ours_files) {
+		for (const p of theirs_files) {
+			if (ours_files.has(p)) throw new UsageError(`"${p}" cannot be in both --theirs and --ours.`)
+		}
+	}
+
+	// Global strategy (boolean flags only, backward compatible)
+	const strategy = args.flags.theirs === true ? 'theirs' : args.flags.ours === true ? 'ours' : args.flags.force ? 'force' : null
+
+	// Per-file strategy resolver: per-file overrides take precedence over global
+	const file_strategy = (file_path) => {
+		if (theirs_files?.has(file_path)) return 'theirs'
+		if (ours_files?.has(file_path)) return 'ours'
+		return strategy
+	}
 	const project_root = find_project_root()
 
 	// 1. Read lock file
@@ -212,17 +239,33 @@ const run = (args) => catch_errors('Pull failed', async () => {
 	const classified = classify_changes(base_files, local_files, remote_files)
 	const report = build_report(skill_name, lock_entry.version, cmp_data.head_version, classified)
 
+	// Validate per-file strategy paths against actual conflicts
+	if (theirs_files || ours_files) {
+		const both_paths = new Set(classified.both_modified.map(e => e.path))
+		for (const p of (theirs_files || [])) {
+			if (!both_paths.has(p)) print_warn(`--theirs path "${p}" not found in conflicted files — ignored.`)
+		}
+		for (const p of (ours_files || [])) {
+			if (!both_paths.has(p)) print_warn(`--ours path "${p}" not found in conflicted files — ignored.`)
+		}
+	}
+
+	// Split both_modified by resolved strategy
+	const auto_merge_entries = classified.both_modified.filter(e => !file_strategy(e.path))
+	const theirs_entries = classified.both_modified.filter(e => file_strategy(e.path) === 'theirs')
+	const ours_entries = classified.both_modified.filter(e => file_strategy(e.path) === 'ours')
+
 	// Apply changes
 	spinner.update('Applying changes...')
 	const base_file_map = new Map((base_clone.files || []).map(f => [f.path, f]))
 	const remote_file_map = new Map((remote_clone.files || []).map(f => [f.path, f]))
 
-	// Auto-merge both_modified files when no strategy is set
+	// Auto-merge both_modified files that have no explicit strategy
 	const conflict_files = []
 	const json_conflicts = []
-	if (classified.both_modified.length > 0 && !strategy) {
+	if (auto_merge_entries.length > 0) {
 		spinner.update('Auto-merging...')
-		for (const entry of classified.both_modified) {
+		for (const entry of auto_merge_entries) {
 			const report_file = report.files.find(f => f.path === entry.path)
 
 			// Delete-vs-modify — cannot auto-merge, keep what exists
@@ -333,9 +376,9 @@ const run = (args) => catch_errors('Pull failed', async () => {
 		}
 	}
 
-	// Both-modified → apply strategy
-	if (strategy === 'theirs') {
-		for (const entry of classified.both_modified) {
+	// Both-modified → apply explicit strategy (global or per-file)
+	if (theirs_entries.length > 0) {
+		for (const entry of theirs_entries) {
 			if (full_report) {
 				const report_file = report.files.find(f => f.path === entry.path)
 				if (report_file) {
@@ -362,8 +405,8 @@ const run = (args) => catch_errors('Pull failed', async () => {
 			}
 		}
 	}
-	if (strategy === 'ours' && full_report) {
-		for (const entry of classified.both_modified) {
+	if (ours_entries.length > 0 && full_report) {
+		for (const entry of ours_entries) {
 			const report_file = report.files.find(f => f.path === entry.path)
 			if (report_file) {
 				const content = { base: decode_b64(base_file_map.get(entry.path)), remote: decode_b64(remote_file_map.get(entry.path)) }
@@ -407,8 +450,10 @@ const run = (args) => catch_errors('Pull failed', async () => {
 		if (report.summary.auto_merged > 0) {
 			print_info(`${report.summary.auto_merged} file(s) auto-applied (non-conflicting changes)`)
 		}
-		if (classified.both_modified.length > 0 && strategy) {
-			print_info(`${classified.both_modified.length} conflict(s) resolved with --${strategy}`)
+		const resolved_count = theirs_entries.length + ours_entries.length
+		if (resolved_count > 0) {
+			const label = strategy ? `--${strategy}` : 'per-file strategy'
+			print_info(`${resolved_count} conflict(s) resolved with ${label}`)
 		}
 		const auto_merged_count = classified.both_modified.length - conflict_files.length
 		if (auto_merged_count > 0 && !strategy) {
@@ -457,7 +502,12 @@ const reconcile_dependencies = (skill_dir, skill_name, lock_data, is_global, pro
 				to_install.push(dep)
 				continue
 			}
-			// Installed version exists — skip (higher-version-wins is handled by the resolver)
+			// Check if installed version satisfies the new constraint
+			if (constraint && installed.version && !satisfies(installed.version, constraint)) {
+				const msg = `${dep}@${installed.version} is installed but ${skill_name} requires ${constraint}. Installed version is outside the declared range — verify compatibility.`
+				if (args.flags.strict) throw new Error(msg)
+				print_warn(msg)
+			}
 		}
 
 		if (to_install.length === 0) return

package/src/commands/refresh.js

@@ -1,13 +1,13 @@
 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 { detect_status } = require('../merge/detector')
 const repos_api = require('../api/repos')
-const { gt } = require('../utils/semver')
 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 } = require('../config/paths')
+const { find_project_root, lock_root, skills_dir, skill_install_dir } = require('../config/paths')
 const { EXIT_CODES } = require('../constants')
 
 const HELP_TEXT = `Usage: happyskills refresh [options]
@@ -78,9 +78,10 @@ const run = (args) => catch_errors('Refresh failed', async () => {
 				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 (info.latest_version === data.version) {
-				results.push({ skill: name, installed: data.version, latest: info.latest_version, status: 'up-to-date' })
-			} else if (gt(info.latest_version, data.version)) {
+			} 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 {
 				results.push({ skill: name, installed: data.version, latest: info.latest_version, status: 'up-to-date' })
@@ -125,12 +126,29 @@ const run = (args) => catch_errors('Refresh failed', async () => {
 		}
 	}
 
-	// 5. Update outdated skills
+	// 5. Detect local modifications before updating
+	const base_dir = skills_dir(is_global, project_root)
+	const skipped = []
+	const safe_to_update = []
+
+	for (const r of outdated) {
+		const lock_entry = skills[r.skill]
+		const short_name = r.skill.split('/')[1] || r.skill
+		const dir = skill_install_dir(base_dir, short_name)
+		const [, det] = await detect_status(lock_entry, dir)
+		if (det?.local_modified) {
+			skipped.push({ skill: r.skill, reason: 'local_modifications', suggestion: `happyskills pull ${r.skill}` })
+		} else {
+			safe_to_update.push(r)
+		}
+	}
+
+	// 6. 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 outdated) {
+	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) {
@@ -144,7 +162,7 @@ const run = (args) => catch_errors('Refresh failed', async () => {
 		}
 	}
 
-	// 6. Output results
+	// 7. Output results
 	if (args.flags.json) {
 		print_json({
 			data: {
@@ -152,6 +170,7 @@ const run = (args) => catch_errors('Refresh failed', async () => {
 				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
 			}
@@ -159,6 +178,14 @@ const run = (args) => catch_errors('Refresh failed', async () => {
 		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).`)

package/src/lock/integrity.js

@@ -8,7 +8,13 @@ const hash_file = (file_path) => catch_errors(`Failed to hash file ${file_path}`
 	return crypto.createHash('sha256').update(content).digest('hex')
 })
 
+const _hash_cache = new Map()
+
+const clear_integrity_cache = () => _hash_cache.clear()
+
 const hash_directory = (dir_path) => catch_errors(`Failed to hash directory ${dir_path}`, async () => {
+	if (_hash_cache.has(dir_path)) return _hash_cache.get(dir_path)
+
 	const hash = crypto.createHash('sha256')
 	const entries = await collect_files(dir_path)
 
@@ -20,7 +26,9 @@ const hash_directory = (dir_path) => catch_errors(`Failed to hash directory ${di
 		hash.update(content)
 	}
 
-	return `sha256-${hash.digest('hex')}`
+	const result = `sha256-${hash.digest('hex')}`
+	_hash_cache.set(dir_path, result)
+	return result
 })
 
 const collect_files = async (dir_path, base_path = dir_path) => {
@@ -51,4 +59,4 @@ const verify_integrity = (dir_path, expected_hash) => catch_errors('Integrity ve
 	return actual_hash === expected_hash
 })
 
-module.exports = { hash_file, hash_directory, verify_integrity }
+module.exports = { hash_file, hash_directory, verify_integrity, clear_integrity_cache }

package/src/merge/detector.test.js

@@ -4,7 +4,7 @@ const fs = require('fs')
 const path = require('path')
 const os = require('os')
 const { detect_status } = require('./detector')
-const { hash_directory } = require('../lock/integrity')
+const { hash_directory, clear_integrity_cache } = require('../lock/integrity')
 
 const make_tmp = () => {
 	const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'detector-test-'))
@@ -39,8 +39,9 @@ describe('detect_status', () => {
 
 		const [, integrity] = await hash_directory(tmp_dir)
 
-		// Modify the file
+		// 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()
 
 		const lock_entry = { base_integrity: integrity, base_commit: 'abc123' }
 		const [err, result] = await detect_status(lock_entry, tmp_dir)