happyskills 0.16.0 → 0.17.0

package/CHANGELOG.md

@@ -7,6 +7,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.17.0] - 2026-03-29
+
+### Added
+- Add `status` command (`st` alias) for divergence detection — shows whether installed skills have local modifications, remote updates, or both
+- Add `--force` flag to `publish` to bypass divergence check when deliberately overwriting remote changes
+- Add `--force` flag to `update` to overwrite skills with local modifications
+- Add `base_commit` and `base_integrity` fields to lock file entries — tracks the install-time commit SHA and integrity hash for divergence detection
+- Add `cli/src/merge/detector.js` module with `detect_status()` for local modification detection via integrity comparison
+- Add `cli/src/utils/git_hash.js` with Git-format blob hashing (`sha256("blob <size>\0" + content)`)
+
+### Changed
+- Bump lock file version from 1 to 2 (new `base_commit`/`base_integrity` fields)
+- Switch file hashing in `file_collector.js` from raw SHA-256 to Git blob format (`hash_blob`) for compatibility with the registry's Git object format
+- Send `base_commit` and `force` fields with push requests for server-side divergence checking
+- Update `publish` to read `base_commit` from lock file, handle `409 DIVERGED` responses, and update `base_commit`/`base_integrity` in lock on success
+- Update `update` to refuse overwriting skills with local modifications unless `--force` is passed
+
 ## [0.16.0] - 2026-03-28
 
 ### Added

package/package.json

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

package/src/api/push.js

@@ -12,13 +12,13 @@ const estimate_payload_size = (files) => {
 	return size
 }
 
-const smart_push = (owner, repo, { version, message, files, visibility }, on_progress) =>
+const smart_push = (owner, repo, { version, message, files, visibility, base_commit, force }, on_progress) =>
 	catch_errors('Smart push failed', async () => {
 		const payload_size = estimate_payload_size(files)
 
 		if (payload_size < DIRECT_PUSH_THRESHOLD) {
 			// Small payload — use direct push
-			const [err, data] = await repos_api.push(owner, repo, { version, message, files, visibility })
+			const [err, data] = await repos_api.push(owner, repo, { version, message, files, visibility, base_commit, force })
 			if (err) throw e('Direct push failed', err)
 			return data
 		}
@@ -28,7 +28,7 @@ const smart_push = (owner, repo, { version, message, files, visibility }, on_pro
 
 		// Step 1: Initiate
 		const [init_err, init_data] = await initiate_upload(owner, repo, {
-			version, message, files: file_meta, visibility
+			version, message, files: file_meta, visibility, base_commit, force
 		})
 		if (init_err) throw e('Upload initiation failed', init_err)
 
@@ -53,7 +53,7 @@ const smart_push = (owner, repo, { version, message, files, visibility }, on_pro
 
 		// Step 3: Complete
 		const [complete_err, complete_data] = await complete_upload(owner, repo, {
-			upload_id, version, message, files: file_meta
+			upload_id, version, message, files: file_meta, base_commit, force
 		})
 		if (complete_err) throw e('Upload completion failed', complete_err)
 

package/src/commands/publish.js

@@ -32,6 +32,7 @@ Options:
   --bump <type>          Auto-bump version before publishing (patch, minor, major)
   --workspace <slug>     Target workspace (overrides lock file owner)
   --public               Publish as public (default is private)
+  --force                Bypass divergence check (may overwrite remote changes)
 
 Aliases: pub
 
@@ -153,6 +154,26 @@ const run = (args) => catch_errors('Publish failed', async () => {
 		}
 	}
 
+	// Read base_commit from lock file for divergence check
+	const full_name_pre = `${workspace.slug}/${manifest.name}`
+	const project_root = find_project_root()
+	const [lock_err, lock_data] = await read_lock(project_root)
+	let base_commit = null
+	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]) {
+			base_commit = all_skills[lock_key].base_commit || null
+		}
+	}
+
+	const force = !!args.flags.force
+	if (force) {
+		print_warn('Force publishing — this may overwrite remote changes that haven\'t been merged.')
+		print_hint(`Consider ${code('happyskills pull')} first to merge safely.`)
+	}
+
 	spinner.update('Packaging skill...')
 	const [collect_err, skill_files] = await collect_files(dir)
 	if (collect_err) { spinner.fail('Failed to collect files'); throw e('File collection failed', collect_err) }
@@ -166,15 +187,26 @@ const run = (args) => catch_errors('Publish failed', async () => {
 		version: manifest.version,
 		message: `Release ${manifest.version}`,
 		files: skill_files,
-		visibility
+		visibility,
+		base_commit: force ? null : base_commit,
+		force
 	}, on_progress)
-	if (push_err) { spinner.fail('Publish failed'); throw e('Push failed', push_err) }
+	if (push_err) {
+		const last = push_err[push_err.length - 1]
+		if (last?.message?.includes('diverged') || last?.message?.includes('DIVERGED')) {
+			spinner.fail('Remote has diverged')
+			print_error('Remote has newer changes. Run \'happyskills pull\' to merge, then publish again.')
+			print_hint(`Or use ${code('happyskills publish ' + skill_name + ' --force')} to overwrite remote changes.`)
+			return process.exit(EXIT_CODES.ERROR)
+		}
+		spinner.fail('Publish failed')
+		throw e('Push failed', push_err)
+	}
 
 	spinner.succeed(`Published ${workspace.slug}/${manifest.name}@${manifest.version}`)
 
-	const full_name = `${workspace.slug}/${manifest.name}`
-	const project_root = find_project_root()
-	const [lock_err, lock_data] = await read_lock(project_root)
+	// Update lock file: set base_commit and base_integrity to new values
+	const full_name = full_name_pre
 	if (!lock_err && lock_data) {
 		const all_skills = get_all_locked_skills(lock_data)
 		const suffix = `/${skill_name}`
@@ -185,7 +217,9 @@ const run = (args) => catch_errors('Publish failed', async () => {
 				...all_skills[lock_key],
 				version: manifest.version,
 				ref: push_data?.ref || `refs/tags/v${manifest.version}`,
-				commit: push_data?.commit || null
+				commit: push_data?.commit || null,
+				base_commit: push_data?.commit || null,
+				base_integrity: (!hash_err && integrity) ? integrity : null
 			}
 			if (!hash_err && integrity) updated_entry.integrity = integrity
 			const updated_skills = update_lock_skills(lock_data, { [lock_key]: updated_entry })
@@ -196,6 +230,8 @@ const run = (args) => catch_errors('Publish failed', async () => {
 				ref: push_data?.ref || `refs/tags/v${manifest.version}`,
 				commit: push_data?.commit || null,
 				integrity: (!hash_err && integrity) ? integrity : null,
+				base_commit: push_data?.commit || null,
+				base_integrity: (!hash_err && integrity) ? integrity : null,
 				requested_by: ['__root__'],
 				dependencies: manifest.dependencies || {}
 			}

package/src/commands/status.js

@@ -0,0 +1,153 @@
+const { error: { catch_errors, wrap_errors: e } } = require('puffy-core')
+const { read_lock, get_all_locked_skills } = require('../lock/reader')
+const { detect_status } = require('../merge/detector')
+const repos_api = require('../api/repos')
+const { print_help, print_info, print_json } = require('../ui/output')
+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 HELP_TEXT = `Usage: happyskills status [owner/skill] [options]
+
+Show divergence status for installed skills.
+
+Arguments:
+  owner/skill       Check specific skill (optional, defaults to all)
+
+Options:
+  -g, --global      Check globally installed skills
+  --json            Output as JSON
+
+Aliases: st
+
+Examples:
+  happyskills status
+  happyskills st acme/deploy-aws
+  happyskills status --json`
+
+const classify = (local_modified, remote_updated) => {
+	if (local_modified && remote_updated) return 'diverged'
+	if (local_modified) return 'modified'
+	if (remote_updated) return 'outdated'
+	return 'clean'
+}
+
+const run = (args) => catch_errors('Status failed', async () => {
+	if (args.flags._show_help) {
+		print_help(HELP_TEXT)
+		return process.exit(EXIT_CODES.SUCCESS)
+	}
+
+	const project_root = find_project_root()
+	const is_global = args.flags.global || false
+	const target_skill = args._[0]
+
+	const [lock_err, lock_data] = await read_lock(lock_root(is_global, project_root))
+	if (lock_err || !lock_data) {
+		if (args.flags.json) {
+			print_json({ data: { results: [] } })
+			return
+		}
+		print_info('No lock file found. Nothing to check.')
+		return
+	}
+
+	const all_skills = get_all_locked_skills(lock_data)
+	const entries = target_skill
+		? [[target_skill, all_skills[target_skill]]]
+		: Object.entries(all_skills).filter(([, data]) => data?.requested_by?.includes('__root__'))
+
+	if (entries.length === 0) {
+		if (args.flags.json) {
+			print_json({ data: { results: [] } })
+			return
+		}
+		print_info('No root-level skills found.')
+		return
+	}
+
+	const base_dir = skills_dir(is_global, project_root)
+
+	// Detect local modifications for each skill
+	const results = []
+	for (const [name, data] of entries) {
+		if (!data) {
+			results.push({ skill: name, status: 'not_found', local_modified: false, remote_updated: false })
+			continue
+		}
+		const short_name = name.split('/')[1] || name
+		const dir = skill_install_dir(base_dir, short_name)
+		const [, det] = await detect_status(data, dir)
+		results.push({
+			skill: name,
+			base_version: data.version || null,
+			base_commit: data.base_commit || null,
+			local_modified: det?.local_modified || false,
+			// remote_updated is populated below after API call
+			remote_updated: false,
+			remote_version: null,
+			remote_commit: null,
+			status: 'clean'
+		})
+	}
+
+	// Check remote for updates
+	const skill_names = results.filter(r => r.status !== 'not_found').map(r => r.skill)
+	if (skill_names.length > 0) {
+		const [api_err, api_data] = await repos_api.check_updates(skill_names)
+		if (!api_err && api_data?.results) {
+			for (const r of results) {
+				const remote = api_data.results[r.skill]
+				if (!remote || remote.access_denied) continue
+				r.remote_version = remote.latest_version || null
+				r.remote_commit = remote.commit || null
+				// Remote is updated if the commit differs from our base
+				if (r.base_commit && r.remote_commit && r.base_commit !== r.remote_commit) {
+					r.remote_updated = true
+				}
+			}
+		}
+	}
+
+	// Classify each result
+	for (const r of results) {
+		if (r.status !== 'not_found') {
+			r.status = classify(r.local_modified, r.remote_updated)
+		}
+	}
+
+	if (args.flags.json) {
+		print_json({ data: { results } })
+		return
+	}
+
+	// Human-readable table
+	const col_skill = 'Skill'
+	const col_base = 'Base'
+	const col_remote = 'Remote'
+	const col_status = 'Status'
+
+	const rows = results.map(r => ({
+		skill: r.skill,
+		base: r.base_version || '?',
+		remote: r.remote_version || '?',
+		status: r.status === 'diverged' ? 'diverged (local + remote changes)'
+			: r.status === 'modified' ? 'modified (local changes)'
+				: r.status === 'outdated' ? 'outdated (remote changes)'
+					: r.status === 'not_found' ? 'not found'
+						: 'clean'
+	}))
+
+	const w_skill = Math.max(col_skill.length, ...rows.map(r => r.skill.length))
+	const w_base = Math.max(col_base.length, ...rows.map(r => r.base.length))
+	const w_remote = Math.max(col_remote.length, ...rows.map(r => r.remote.length))
+
+	const pad = (s, w) => s + ' '.repeat(Math.max(0, w - s.length))
+
+	console.log(`${pad(col_skill, w_skill)}  ${pad(col_base, w_base)}  ${pad(col_remote, w_remote)}  ${col_status}`)
+	for (const r of rows) {
+		console.log(`${pad(r.skill, w_skill)}  ${pad(r.base, w_base)}  ${pad(r.remote, w_remote)}  ${r.status}`)
+	}
+}).then(([errors]) => { if (errors) { exit_with_error(errors); return } })
+
+module.exports = { run }

package/src/commands/update.js

@@ -1,9 +1,11 @@
+const path = require('path')
 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 { print_help, print_success, print_info, print_json } = require('../ui/output')
+const { detect_status } = require('../merge/detector')
+const { print_help, print_success, print_info, print_warn, print_json } = require('../ui/output')
 const { exit_with_error, UsageError } = 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 update [owner/skill|--all] [options]
@@ -67,7 +69,21 @@ const run = (args) => catch_errors('Update failed', async () => {
 	const updated = []
 	const already_up_to_date = []
 
+	const base_dir = skills_dir(is_global, project_root)
+	const force = args.flags.force || false
+
 	for (const [name, data] of to_update) {
+		// Check for local modifications before overwriting
+		if (!force && data) {
+			const short_name = name.split('/')[1] || name
+			const dir = skill_install_dir(base_dir, short_name)
+			const [, det] = await detect_status(data, dir)
+			if (det?.local_modified) {
+				print_warn(`${name} has local modifications. Use --force to discard, or 'happyskills pull' to merge.`)
+				continue
+			}
+		}
+
 		const before_version = data?.version || null
 		const [errors, result] = await install(name, options)
 		if (errors) throw e(`Update ${name} failed`, errors)

package/src/constants.js

@@ -16,7 +16,7 @@ const SKILL_TYPES = { SKILL: 'skill', KIT: 'kit' }
 const KIT_PREFIX = '_kit-'
 const VALID_SKILL_TYPES = ['skill', 'kit']
 
-const LOCK_VERSION = 1
+const LOCK_VERSION = 2
 
 const SKILL_JSON = 'skill.json'
 const SKILL_MD = 'SKILL.md'
@@ -31,6 +31,7 @@ const COMMAND_ALIASES = {
 	ls: 'list',
 	s: 'search',
 	r: 'refresh',
+	st: 'status',
 	up: 'update',
 	pub: 'publish',
 	v: 'validate',
@@ -48,6 +49,7 @@ const COMMANDS = [
 	'search',
 	'check',
 	'refresh',
+	'status',
 	'update',
 	'bump',
 	'publish',

package/src/engine/installer.js

@@ -168,6 +168,8 @@ const install = (skill, options = {}) => catch_errors('Install failed', async ()
 				ref: pkg.ref,
 				commit: pkg.commit || null,
 				integrity: integrity || null,
+				base_commit: pkg.commit || null,
+				base_integrity: integrity || null,
 				requested_by: pkg.skill === skill ? ['__root__'] : [skill],
 				dependencies: pkg.dependencies || {},
 				...(pkg_type ? { type: pkg_type } : {}),

package/src/merge/detector.js

@@ -0,0 +1,31 @@
+const { error: { catch_errors } } = require('puffy-core')
+const { hash_directory } = require('../lock/integrity')
+
+/**
+ * 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.
+ *
+ * @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 }]}
+ */
+const detect_status = (lock_entry, skill_dir) => 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 }
+
+	const [hash_err, current_integrity] = await hash_directory(skill_dir)
+	if (hash_err) return { local_modified: false, current_integrity: null, base_integrity, base_commit }
+
+	return {
+		local_modified: current_integrity !== base_integrity,
+		current_integrity,
+		base_integrity,
+		base_commit
+	}
+})
+
+module.exports = { detect_status }

package/src/merge/detector.test.js

@@ -0,0 +1,77 @@
+const { describe, it, afterEach } = 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 } = require('../lock/integrity')
+
+const make_tmp = () => {
+	const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'detector-test-'))
+	return dir
+}
+
+const rm = (dir) => { try { fs.rmSync(dir, { recursive: true }) } catch (_) {} }
+
+describe('detect_status', () => {
+	let tmp_dir
+
+	afterEach(() => { if (tmp_dir) rm(tmp_dir) })
+
+	it('returns local_modified: false when integrity matches', async () => {
+		tmp_dir = make_tmp()
+		fs.writeFileSync(path.join(tmp_dir, 'SKILL.md'), 'hello')
+		fs.writeFileSync(path.join(tmp_dir, 'skill.json'), '{}')
+
+		const [, integrity] = await hash_directory(tmp_dir)
+		const lock_entry = { base_integrity: integrity, base_commit: 'abc123' }
+
+		const [err, result] = await detect_status(lock_entry, tmp_dir)
+		assert.equal(err, null)
+		assert.equal(result.local_modified, false)
+		assert.equal(result.current_integrity, integrity)
+		assert.equal(result.base_commit, 'abc123')
+	})
+
+	it('returns local_modified: true when integrity differs', async () => {
+		tmp_dir = make_tmp()
+		fs.writeFileSync(path.join(tmp_dir, 'SKILL.md'), 'hello')
+
+		const [, integrity] = await hash_directory(tmp_dir)
+
+		// Modify the file
+		fs.writeFileSync(path.join(tmp_dir, 'SKILL.md'), 'modified')
+
+		const lock_entry = { base_integrity: integrity, base_commit: 'abc123' }
+		const [err, result] = await detect_status(lock_entry, tmp_dir)
+		assert.equal(err, null)
+		assert.equal(result.local_modified, true)
+		assert.notEqual(result.current_integrity, integrity)
+	})
+
+	it('returns local_modified: false when base_integrity is missing', async () => {
+		tmp_dir = make_tmp()
+		fs.writeFileSync(path.join(tmp_dir, 'SKILL.md'), 'hello')
+
+		const lock_entry = { base_commit: 'abc123' }
+		const [err, result] = await detect_status(lock_entry, tmp_dir)
+		assert.equal(err, null)
+		assert.equal(result.local_modified, false)
+		assert.equal(result.base_integrity, null)
+	})
+
+	it('handles null lock_entry gracefully', async () => {
+		tmp_dir = make_tmp()
+		const [err, result] = await detect_status(null, tmp_dir)
+		assert.equal(err, null)
+		assert.equal(result.local_modified, false)
+		assert.equal(result.base_commit, null)
+	})
+
+	it('handles nonexistent skill dir without crashing', async () => {
+		const lock_entry = { base_integrity: 'sha256-abc', base_commit: 'abc123' }
+		const [err, result] = await detect_status(lock_entry, '/tmp/nonexistent-dir-12345')
+		assert.equal(err, null)
+		assert.equal(result.local_modified, false)
+	})
+})

package/src/utils/file_collector.js

@@ -1,7 +1,7 @@
-const crypto = require('crypto')
 const fs = require('fs')
 const path = require('path')
 const { error: { catch_errors, wrap_errors: e } } = require('puffy-core')
+const { hash_blob } = require('./git_hash')
 
 const EXCLUDE_PATTERNS = [
 	'node_modules',
@@ -38,7 +38,7 @@ const collect_files = (dir, base_dir) => catch_errors('Failed to collect files',
 			files.push(...sub_files)
 		} else if (entry.isFile()) {
 			const content = await fs.promises.readFile(full_path)
-			const sha = crypto.createHash('sha256').update(content).digest('hex')
+			const sha = hash_blob(content)
 			files.push({ path: rel_path, content: content.toString('base64'), size: content.length, sha })
 		}
 	}

package/src/utils/git_hash.js

@@ -0,0 +1,9 @@
+const crypto = require('crypto')
+
+const hash_blob = (buf) => {
+	if (!Buffer.isBuffer(buf)) buf = Buffer.from(buf)
+	const header = Buffer.from(`blob ${buf.length}\0`)
+	return crypto.createHash('sha256').update(header).update(buf).digest('hex')
+}
+
+module.exports = { hash_blob }

package/src/utils/git_hash.test.js

@@ -0,0 +1,49 @@
+const { describe, it } = require('node:test')
+const assert = require('node:assert/strict')
+const crypto = require('crypto')
+const { hash_blob } = require('./git_hash')
+
+describe('hash_blob', () => {
+	it('produces sha256 with git blob header', () => {
+		const content = Buffer.from('hello world')
+		const expected = crypto.createHash('sha256')
+			.update(`blob ${content.length}\0`)
+			.update(content)
+			.digest('hex')
+		assert.equal(hash_blob(content), expected)
+	})
+
+	it('accepts string input', () => {
+		const from_string = hash_blob('hello')
+		const from_buffer = hash_blob(Buffer.from('hello'))
+		assert.equal(from_string, from_buffer)
+	})
+
+	it('handles empty content', () => {
+		const sha = hash_blob(Buffer.alloc(0))
+		assert.equal(typeof sha, 'string')
+		assert.equal(sha.length, 64)
+	})
+
+	it('handles binary content', () => {
+		const buf = Buffer.from([0x00, 0xff, 0x80, 0x01])
+		const sha = hash_blob(buf)
+		assert.equal(typeof sha, 'string')
+		assert.equal(sha.length, 64)
+	})
+
+	it('handles unicode content', () => {
+		const sha = hash_blob(Buffer.from('日本語テスト'))
+		assert.equal(typeof sha, 'string')
+		assert.equal(sha.length, 64)
+	})
+
+	it('matches api/app/utils/git_objects hash_blob', () => {
+		// CLI and API must produce identical SHAs for the same input
+		const api_hash_blob = require('../../../api/app/utils/git_objects').hash_blob
+		const inputs = ['hello', '', 'binary\x00data', '日本語']
+		for (const input of inputs) {
+			assert.equal(hash_blob(input), api_hash_blob(input))
+		}
+	})
+})