happyskills 0.16.0 → 0.18.0

package/CHANGELOG.md

@@ -7,6 +7,33 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.18.0] - 2026-03-29
+
+### Added
+- Add `pull` command for pulling remote changes and merging with local files — supports `--theirs`, `--ours`, and `--force` strategies with three-way file classification and dependency reconciliation
+- Add `diff` command (`d` alias) for file-level difference display — supports `--remote` (base vs remote), `--full` (three-way), and default local vs base modes
+- Add `cli/src/merge/comparator.js` module with `classify_changes()` for three-way file classification into 8 categories
+- Add `cli/src/merge/report.js` module with `build_report()` for structured JSON merge reports (v1 contract)
+- Add `compare()` and `get_blob()` to CLI API client for server-side tree comparison and individual blob downloads
+- Extend `clone()` API client to accept `options.commit` for cloning at a specific commit SHA
+
+## [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.18.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/api/repos.js

@@ -22,9 +22,12 @@ const resolve_dependencies = (skill, version, installed = {}) => catch_errors('D
 	return data
 })
 
-const clone = (owner, repo, ref) => catch_errors(`Clone ${owner}/${repo} failed`, async () => {
-	const params = ref ? `?ref=${encodeURIComponent(ref)}` : ''
-	const [errors, data] = await client.get(`/repos/${owner}/${repo}/clone${params}`)
+const clone = (owner, repo, ref, options = {}) => catch_errors(`Clone ${owner}/${repo} failed`, async () => {
+	const params = new URLSearchParams()
+	if (options.commit) params.set('commit', options.commit)
+	else if (ref) params.set('ref', ref)
+	const qs = params.toString() ? `?${params}` : ''
+	const [errors, data] = await client.get(`/repos/${owner}/${repo}/clone${qs}`)
 	if (errors) throw errors[errors.length - 1]
 	return data
 })
@@ -65,4 +68,16 @@ const patch_repo = (owner, name, fields) => catch_errors(`Failed to update ${own
 	return data
 })
 
-module.exports = { search, resolve_dependencies, clone, push, get_refs, get_repo, check_updates, del_repo, patch_repo }
+const compare = (owner, repo, base_commit) => catch_errors(`Compare ${owner}/${repo} failed`, async () => {
+	const [errors, data] = await client.post(`/repos/${owner}/${repo}/compare`, { base_commit })
+	if (errors) throw errors[errors.length - 1]
+	return data
+})
+
+const get_blob = (owner, repo, sha) => catch_errors(`Get blob ${owner}/${repo}/${sha} failed`, async () => {
+	const [errors, data] = await client.get(`/repos/${owner}/${repo}/blob/${sha}`)
+	if (errors) throw errors[errors.length - 1]
+	return data
+})
+
+module.exports = { search, resolve_dependencies, clone, push, get_refs, get_repo, check_updates, del_repo, patch_repo, compare, get_blob }

package/src/commands/diff.js

@@ -0,0 +1,178 @@
+const fs = require('fs')
+const path = require('path')
+const { error: { catch_errors, wrap_errors: e } } = require('puffy-core')
+const repos_api = require('../api/repos')
+const { detect_status } = require('../merge/detector')
+const { classify_changes } = require('../merge/comparator')
+const { build_report } = require('../merge/report')
+const { hash_blob } = require('../utils/git_hash')
+const { read_lock, get_all_locked_skills } = require('../lock/reader')
+const { find_project_root, lock_root, skills_dir, skill_install_dir } = require('../config/paths')
+const { print_help, print_info, print_json, print_warn, code } = require('../ui/output')
+const { exit_with_error, UsageError } = require('../utils/errors')
+const { EXIT_CODES } = require('../constants')
+
+const HELP_TEXT = `Usage: happyskills diff <owner/skill> [options]
+
+Show file-level differences for a skill.
+
+Arguments:
+  owner/skill       Skill to diff (required)
+
+Options:
+  --remote          Show base vs remote changes (default: local vs base)
+  --full            Show three-way diff (base vs local vs remote)
+  -g, --global      Diff globally installed skill
+  --json            Output as JSON
+
+Aliases: d
+
+Examples:
+  happyskills diff acme/deploy-aws
+  happyskills diff acme/deploy-aws --remote
+  happyskills diff acme/deploy-aws --full`
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+const build_local_entries = (skill_dir) => catch_errors('Failed to build local entries', async () => {
+	const entries = []
+	const walk = async (dir, prefix) => {
+		const items = await fs.promises.readdir(dir, { withFileTypes: true })
+		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 {
+				const content = await fs.promises.readFile(full)
+				entries.push({ path: rel, sha: hash_blob(content) })
+			}
+		}
+	}
+	await walk(skill_dir, '')
+	return entries
+})
+
+const STATUS_LABELS = {
+	remote_only_modified: 'M (remote)',
+	local_only_modified: 'M (local)',
+	both_modified: 'M (both)',
+	remote_only_added: 'A (remote)',
+	local_only_added: 'A (local)',
+	remote_only_deleted: 'D (remote)',
+	local_only_deleted: 'D (local)'
+}
+
+const print_file_table = (classified) => {
+	const lines = []
+	for (const [category, label] of Object.entries(STATUS_LABELS)) {
+		for (const entry of (classified[category] || [])) {
+			lines.push({ status: label, path: entry.path })
+		}
+	}
+
+	if (lines.length === 0) {
+		print_info('No differences found.')
+		return
+	}
+
+	const max_status = Math.max(...lines.map(l => l.status.length))
+	for (const line of lines) {
+		const padded = line.status + ' '.repeat(max_status - line.status.length)
+		console.log(`  ${padded}  ${line.path}`)
+	}
+}
+
+// ─── Main ─────────────────────────────────────────────────────────────────────
+
+const run = (args) => catch_errors('Diff failed', async () => {
+	if (args.flags._show_help) {
+		print_help(HELP_TEXT)
+		return process.exit(EXIT_CODES.SUCCESS)
+	}
+
+	const skill_name = args._[0]
+	if (!skill_name || !skill_name.includes('/')) {
+		throw new UsageError('Skill name required in owner/name format. Example: happyskills diff acme/deploy-aws')
+	}
+
+	const is_global = args.flags.global || false
+	const mode = args.flags.full ? 'full' : args.flags.remote ? 'remote' : 'local'
+	const project_root = find_project_root()
+
+	// Read lock
+	const [lock_err, lock_data] = await read_lock(lock_root(is_global, project_root))
+	if (lock_err || !lock_data) throw new UsageError('No lock file found.')
+
+	const all_skills = get_all_locked_skills(lock_data)
+	const lock_entry = all_skills[skill_name]
+	if (!lock_entry) throw new UsageError(`${skill_name} is not installed.`)
+	if (!lock_entry.base_commit) throw new UsageError(`${skill_name} has no base_commit. Run ${code('happyskills install --fresh')} to upgrade the lock file.`)
+
+	const [owner, repo] = skill_name.split('/')
+	const base_dir = skills_dir(is_global, project_root)
+	const skill_dir = skill_install_dir(base_dir, repo)
+
+	// Always need base files
+	const [base_err, base_clone] = await repos_api.clone(owner, repo, null, { commit: lock_entry.base_commit })
+	if (base_err) throw e('Failed to fetch base files', base_err)
+	const base_files = (base_clone.files || []).map(f => ({ path: f.path, sha: f.sha }))
+
+	if (mode === 'local') {
+		// Local vs base — use classify_changes with base as the "remote" side
+		const [local_err, local_files] = await build_local_entries(skill_dir)
+		if (local_err) throw e('Failed to read local files', local_err)
+
+		const classified = classify_changes(base_files, local_files, base_files)
+
+		if (args.flags.json) {
+			const report = build_report(skill_name, lock_entry.version, lock_entry.version, classified)
+			print_json({ data: { mode, report } })
+		} else {
+			print_file_table(classified)
+		}
+		return
+	}
+
+	if (mode === 'remote') {
+		// Base vs remote — use classify_changes with base as the "local" side
+		const [remote_err, remote_clone] = await repos_api.clone(owner, repo, null)
+		if (remote_err) throw e('Failed to fetch remote files', remote_err)
+		const remote_files = (remote_clone.files || []).map(f => ({ path: f.path, sha: f.sha }))
+
+		const classified = classify_changes(base_files, base_files, remote_files)
+
+		if (args.flags.json) {
+			const report = build_report(skill_name, lock_entry.version, null, classified)
+			print_json({ data: { mode, report } })
+		} else {
+			print_file_table(classified)
+		}
+		return
+	}
+
+	// Full three-way diff
+	const [local_err, local_files] = await build_local_entries(skill_dir)
+	if (local_err) throw e('Failed to read local files', local_err)
+
+	const [remote_err, remote_clone] = await repos_api.clone(owner, repo, null)
+	if (remote_err) throw e('Failed to fetch remote files', remote_err)
+	const remote_files = (remote_clone.files || []).map(f => ({ path: f.path, sha: f.sha }))
+
+	const classified = classify_changes(base_files, local_files, remote_files)
+	const report = build_report(skill_name, lock_entry.version, null, classified)
+
+	if (args.flags.json) {
+		print_json({ data: { mode, report } })
+	} else {
+		print_file_table(classified)
+		if (report.summary.conflicted > 0) {
+			console.error('')
+			print_warn(`${report.summary.conflicted} file(s) modified on both sides`)
+		}
+	}
+
+}).then(([errors]) => { if (errors) { exit_with_error(errors); return } })
+
+module.exports = { run }

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 || {}
 			}