happyskills 0.17.0 → 0.18.0

package/CHANGELOG.md

@@ -7,6 +7,16 @@ 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

package/package.json

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

@@ -0,0 +1,339 @@
+const fs = require('fs')
+const path = require('path')
+const os = require('os')
+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 { write_lock, update_lock_skills } = require('../lock/writer')
+const { hash_directory } = require('../lock/integrity')
+const { find_project_root, lock_root, skills_dir, skill_install_dir } = require('../config/paths')
+const { ensure_dir } = require('../utils/fs')
+const { create_spinner } = require('../ui/spinner')
+const { print_help, print_success, print_error, print_warn, print_info, print_json, print_hint, code } = require('../ui/output')
+const { exit_with_error, UsageError } = require('../utils/errors')
+const { EXIT_CODES } = require('../constants')
+
+const HELP_TEXT = `Usage: happyskills pull <owner/skill> [options]
+
+Pull remote changes and merge with local files.
+
+Arguments:
+  owner/skill       Skill to pull (required)
+
+Options:
+  --theirs          Take remote version on conflicts
+  --ours            Keep local version on conflicts
+  --force           Discard all local changes, take remote entirely
+  -g, --global      Pull globally installed skill
+  --json            Output as JSON
+
+Examples:
+  happyskills pull acme/deploy-aws
+  happyskills pull acme/deploy-aws --theirs
+  happyskills pull acme/deploy-aws --force`
+
+// ─── 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 write_files_from_clone = (clone_data, skill_dir) => catch_errors('Failed to write files', async () => {
+	for (const file of clone_data.files || []) {
+		const full = path.join(skill_dir, file.path)
+		const [dir_err] = await ensure_dir(path.dirname(full))
+		if (dir_err) throw e(`Failed to create directory for ${file.path}`, dir_err)
+		await fs.promises.writeFile(full, Buffer.from(file.content, 'base64'))
+	}
+})
+
+const remove_files = (skill_dir, paths) => catch_errors('Failed to remove files', async () => {
+	for (const rel_path of paths) {
+		const full = path.join(skill_dir, rel_path)
+		try { await fs.promises.unlink(full) } catch { /* already gone */ }
+	}
+})
+
+const apply_remote_file = (skill_dir, owner, repo, file_entry) => catch_errors('Failed to apply remote file', async () => {
+	const sha = file_entry.remote_sha || file_entry.sha
+	if (!sha) return
+	const [err, blob] = await repos_api.get_blob(owner, repo, sha)
+	if (err) throw e(`Failed to download ${file_entry.path}`, err)
+	const full = path.join(skill_dir, file_entry.path)
+	const [dir_err] = await ensure_dir(path.dirname(full))
+	if (dir_err) throw e(`Failed to create directory for ${file_entry.path}`, dir_err)
+	await fs.promises.writeFile(full, Buffer.from(blob.content, 'base64'))
+})
+
+// ─── Main ─────────────────────────────────────────────────────────────────────
+
+const run = (args) => catch_errors('Pull 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 pull acme/deploy-aws')
+	}
+
+	const is_global = args.flags.global || false
+	const strategy = args.flags.theirs ? 'theirs' : args.flags.ours ? 'ours' : args.flags.force ? 'force' : null
+	const project_root = find_project_root()
+
+	// 1. Read lock file
+	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. Install the skill first.')
+
+	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. Run ${code(`happyskills install ${skill_name}`)} first.`)
+	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)
+
+	const spinner = create_spinner(`Pulling ${skill_name}...`)
+
+	// 2. Detect local modifications
+	const [det_err, det] = await detect_status(lock_entry, skill_dir)
+	if (det_err) { spinner.fail('Failed to detect local status'); throw det_err[0] }
+
+	// 3. Compare with remote
+	spinner.update('Comparing with remote...')
+	const [cmp_err, cmp_data] = await repos_api.compare(owner, repo, lock_entry.base_commit)
+	if (cmp_err) { spinner.fail('Compare failed'); throw cmp_data || cmp_err[0] }
+
+	const no_remote_changes = cmp_data.added.length === 0 && cmp_data.removed.length === 0 && cmp_data.modified.length === 0
+
+	// 4. Already up to date?
+	if (no_remote_changes) {
+		spinner.stop()
+		if (args.flags.json) {
+			print_json({ data: { status: 'up_to_date', skill: skill_name } })
+		} else {
+			print_info(`${skill_name} is already up to date.`)
+		}
+		return
+	}
+
+	// 5. No local mods → fast-forward
+	if (!det.local_modified || strategy === 'force') {
+		spinner.update('Fast-forwarding...')
+		const [clone_err, clone_data] = await repos_api.clone(owner, repo, null)
+		if (clone_err) { spinner.fail('Clone failed'); throw clone_err[0] }
+
+		// Remove existing files and write fresh
+		const [rm_err] = await catch_errors('Cleanup failed', async () => {
+			const items = await fs.promises.readdir(skill_dir, { withFileTypes: true })
+			for (const item of items) {
+				if (item.name.startsWith('.')) continue
+				const full = path.join(skill_dir, item.name)
+				await fs.promises.rm(full, { recursive: true, force: true })
+			}
+		})
+		if (rm_err) { spinner.fail('Failed to clean skill directory'); throw rm_err[0] }
+
+		const [wf_err] = await write_files_from_clone(clone_data, skill_dir)
+		if (wf_err) { spinner.fail('Failed to write files'); throw wf_err[0] }
+
+		// Update lock
+		const [hash_err, new_integrity] = await hash_directory(skill_dir)
+		const updated_entry = {
+			...lock_entry,
+			commit: clone_data.commit,
+			base_commit: clone_data.commit,
+			integrity: new_integrity || lock_entry.integrity,
+			base_integrity: new_integrity || lock_entry.base_integrity,
+			version: cmp_data.head_version || lock_entry.version,
+			ref: clone_data.ref || lock_entry.ref
+		}
+		const merged_skills = update_lock_skills(lock_data, { [skill_name]: updated_entry })
+		const [wl_err] = await write_lock(lock_root(is_global, project_root), merged_skills)
+		if (wl_err) { spinner.fail('Failed to write lock file'); throw wl_err[0] }
+
+		spinner.stop()
+		if (args.flags.json) {
+			print_json({ data: { status: 'fast_forward', skill: skill_name, version: cmp_data.head_version } })
+		} else {
+			const label = strategy === 'force' ? 'Force-pulled' : 'Fast-forwarded'
+			print_success(`${label} ${skill_name} → ${cmp_data.head_version || 'latest'}`)
+		}
+		return
+	}
+
+	// 6. Both changed — three-way classification
+	spinner.update('Classifying changes...')
+
+	// Get base files (clone at base_commit)
+	const [base_err, base_clone] = await repos_api.clone(owner, repo, null, { commit: lock_entry.base_commit })
+	if (base_err) { spinner.fail('Failed to fetch base files'); throw base_err[0] }
+	const base_files = (base_clone.files || []).map(f => ({ path: f.path, sha: f.sha }))
+
+	// Get local files (from disk)
+	const [local_err, local_files] = await build_local_entries(skill_dir)
+	if (local_err) { spinner.fail('Failed to read local files'); throw local_err[0] }
+
+	// Get remote files (clone latest)
+	const [remote_err, remote_clone] = await repos_api.clone(owner, repo, null)
+	if (remote_err) { spinner.fail('Failed to fetch remote files'); throw remote_err[0] }
+	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, cmp_data.head_version, classified)
+
+	// If both_modified exists and no strategy → exit with report
+	if (classified.both_modified.length > 0 && !strategy) {
+		spinner.stop()
+		if (args.flags.json) {
+			print_json({ data: { status: 'conflicts', report } })
+		} else {
+			print_warn(`${report.summary.conflicted} file(s) modified on both sides:`)
+			for (const f of classified.both_modified) {
+				console.error(`  - ${f.path}`)
+			}
+			console.error('')
+			print_hint('Auto-merge not yet available. Use --theirs (take remote) or --ours (keep local) for all conflicting files, or manually merge and publish with --force.')
+		}
+		return process.exit(EXIT_CODES.ERROR)
+	}
+
+	// Apply changes
+	spinner.update('Applying changes...')
+	const remote_file_map = new Map((remote_clone.files || []).map(f => [f.path, f]))
+
+	// Remote-only modified/added → write remote version
+	for (const entry of [...classified.remote_only_modified, ...classified.remote_only_added]) {
+		const remote_file = remote_file_map.get(entry.path)
+		if (remote_file) {
+			const full = path.join(skill_dir, entry.path)
+			const [dir_err] = await ensure_dir(path.dirname(full))
+			if (dir_err) { spinner.fail(`Failed to create dir for ${entry.path}`); throw dir_err[0] }
+			await fs.promises.writeFile(full, Buffer.from(remote_file.content, 'base64'))
+		}
+	}
+
+	// Remote-only deleted → remove local
+	const [del_err] = await remove_files(skill_dir, classified.remote_only_deleted.map(f => f.path))
+	if (del_err) { spinner.fail('Failed to remove deleted files'); throw del_err[0] }
+
+	// Local-only modified/added → keep (no action needed)
+	// Local-only deleted → keep deleted (no action needed)
+
+	// Both-modified → apply strategy
+	if (strategy === 'theirs') {
+		for (const entry of classified.both_modified) {
+			if (entry.remote_sha === null) {
+				// Remote deleted — remove local
+				const full = path.join(skill_dir, entry.path)
+				try { await fs.promises.unlink(full) } catch { /* ok */ }
+			} else {
+				const remote_file = remote_file_map.get(entry.path)
+				if (remote_file) {
+					const full = path.join(skill_dir, entry.path)
+					const [dir_err] = await ensure_dir(path.dirname(full))
+					if (dir_err) { spinner.fail(`Failed to create dir for ${entry.path}`); throw dir_err[0] }
+					await fs.promises.writeFile(full, Buffer.from(remote_file.content, 'base64'))
+				}
+			}
+		}
+	}
+	// strategy === 'ours' → keep local files as-is (no action needed)
+
+	// Update lock
+	const [hash_err, new_integrity] = await hash_directory(skill_dir)
+	const updated_entry = {
+		...lock_entry,
+		commit: remote_clone.commit,
+		base_commit: remote_clone.commit,
+		integrity: new_integrity || lock_entry.integrity,
+		base_integrity: new_integrity || lock_entry.base_integrity,
+		version: cmp_data.head_version || lock_entry.version,
+		ref: remote_clone.ref || lock_entry.ref
+	}
+	const merged_skills = update_lock_skills(lock_data, { [skill_name]: updated_entry })
+	const [wl_err] = await write_lock(lock_root(is_global, project_root), merged_skills)
+	if (wl_err) { spinner.fail('Failed to write lock file'); throw wl_err[0] }
+
+	spinner.stop()
+
+	if (args.flags.json) {
+		print_json({ data: { status: 'merged', report } })
+	} else {
+		print_success(`Pulled ${skill_name} → ${cmp_data.head_version || 'latest'}`)
+		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) {
+			print_info(`${classified.both_modified.length} conflict(s) resolved with --${strategy}`)
+		}
+	}
+
+	// 7. Dependency reconciliation
+	await reconcile_dependencies(skill_dir, skill_name, lock_data, is_global, project_root, spinner, args)
+
+}).then(([errors]) => { if (errors) { exit_with_error(errors); return } })
+
+// ─── Dependency reconciliation ────────────────────────────────────────────────
+
+const reconcile_dependencies = (skill_dir, skill_name, lock_data, is_global, project_root, spinner, args) =>
+	catch_errors('Dependency reconciliation failed', async () => {
+		const manifest_path = path.join(skill_dir, 'skill.json')
+		let manifest
+		try {
+			manifest = JSON.parse(await fs.promises.readFile(manifest_path, 'utf-8'))
+		} catch {
+			return // No manifest or invalid JSON — nothing to reconcile
+		}
+
+		const new_deps = manifest.dependencies || {}
+		if (Object.keys(new_deps).length === 0) return
+
+		const all_skills = get_all_locked_skills(lock_data)
+		const to_install = []
+
+		for (const [dep, constraint] of Object.entries(new_deps)) {
+			const installed = all_skills[dep]
+			if (!installed) {
+				to_install.push(dep)
+				continue
+			}
+			// Installed version exists — skip (higher-version-wins is handled by the resolver)
+		}
+
+		if (to_install.length === 0) return
+
+		if (!args.flags.json) {
+			print_info(`Installing ${to_install.length} new dependenc${to_install.length === 1 ? 'y' : 'ies'}...`)
+		}
+
+		// Delegate to the installer for new deps
+		const { run: run_install } = require('./install')
+		for (const dep of to_install) {
+			await run_install({ _: [dep], flags: { global: is_global, json: args.flags.json || false, yes: true } })
+		}
+	})
+
+module.exports = { run }

package/src/constants.js

@@ -32,6 +32,7 @@ const COMMAND_ALIASES = {
 	s: 'search',
 	r: 'refresh',
 	st: 'status',
+	d: 'diff',
 	up: 'update',
 	pub: 'publish',
 	v: 'validate',
@@ -50,6 +51,8 @@ const COMMANDS = [
 	'check',
 	'refresh',
 	'status',
+	'pull',
+	'diff',
 	'update',
 	'bump',
 	'publish',

package/src/index.js

@@ -93,6 +93,9 @@ Commands:
   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)
   publish                  Push skill to registry (alias: pub)
   validate <skill-name>    Validate skill against all rules (alias: v)

package/src/merge/comparator.js

@@ -0,0 +1,98 @@
+/**
+ * Three-way file classification for merge operations.
+ *
+ * Compares base, local, and remote file sets to classify each file
+ * into one of 8 categories based on which sides changed it.
+ *
+ * All inputs are arrays of { path, sha } entries.
+ */
+
+const classify_changes = (base_files, local_files, remote_files) => {
+	const base_map = new Map(base_files.map(e => [e.path, e.sha]))
+	const local_map = new Map(local_files.map(e => [e.path, e.sha]))
+	const remote_map = new Map(remote_files.map(e => [e.path, e.sha]))
+
+	const all_paths = new Set([...base_map.keys(), ...local_map.keys(), ...remote_map.keys()])
+
+	const remote_only_modified = []
+	const local_only_modified = []
+	const both_modified = []
+	const remote_only_added = []
+	const local_only_added = []
+	const remote_only_deleted = []
+	const local_only_deleted = []
+	const unchanged = []
+
+	for (const path of all_paths) {
+		const base_sha = base_map.get(path) || null
+		const local_sha = local_map.get(path) || null
+		const remote_sha = remote_map.get(path) || null
+
+		const in_base = base_sha !== null
+		const in_local = local_sha !== null
+		const in_remote = remote_sha !== null
+
+		if (in_base) {
+			const local_changed = local_sha !== base_sha
+			const remote_changed = remote_sha !== base_sha
+
+			if (!in_local && !in_remote) {
+				// Both deleted — treat as unchanged (both agree)
+				unchanged.push({ path })
+			} else if (!in_local && in_remote) {
+				if (remote_changed) {
+					// Local deleted, remote modified — classify as both_modified (conflict)
+					both_modified.push({ path, base_sha, local_sha: null, remote_sha })
+				} else {
+					local_only_deleted.push({ path })
+				}
+			} else if (in_local && !in_remote) {
+				if (local_changed) {
+					// Local modified, remote deleted — classify as both_modified (conflict)
+					both_modified.push({ path, base_sha, local_sha, remote_sha: null })
+				} else {
+					remote_only_deleted.push({ path })
+				}
+			} else if (local_changed && remote_changed) {
+				// Both changed — if same SHA, they agree (unchanged from merge perspective)
+				if (local_sha === remote_sha) {
+					unchanged.push({ path, sha: local_sha })
+				} else {
+					both_modified.push({ path, base_sha, local_sha, remote_sha })
+				}
+			} else if (local_changed) {
+				local_only_modified.push({ path, base_sha, local_sha })
+			} else if (remote_changed) {
+				remote_only_modified.push({ path, base_sha, remote_sha })
+			} else {
+				unchanged.push({ path, sha: base_sha })
+			}
+		} else {
+			// Not in base — added by one or both sides
+			if (in_local && in_remote) {
+				if (local_sha === remote_sha) {
+					unchanged.push({ path, sha: local_sha })
+				} else {
+					both_modified.push({ path, base_sha: null, local_sha, remote_sha })
+				}
+			} else if (in_local) {
+				local_only_added.push({ path, local_sha })
+			} else {
+				remote_only_added.push({ path, remote_sha })
+			}
+		}
+	}
+
+	return {
+		remote_only_modified,
+		local_only_modified,
+		both_modified,
+		remote_only_added,
+		local_only_added,
+		remote_only_deleted,
+		local_only_deleted,
+		unchanged
+	}
+}
+
+module.exports = { classify_changes }

package/src/merge/comparator.test.js

@@ -0,0 +1,161 @@
+const { describe, it } = require('node:test')
+const assert = require('node:assert/strict')
+const { classify_changes } = require('./comparator')
+
+describe('classify_changes', () => {
+	it('classifies remote_only_modified', () => {
+		const base = [{ path: 'a.md', sha: '111' }]
+		const local = [{ path: 'a.md', sha: '111' }]
+		const remote = [{ path: 'a.md', sha: '222' }]
+		const r = classify_changes(base, local, remote)
+		assert.strictEqual(r.remote_only_modified.length, 1)
+		assert.deepStrictEqual(r.remote_only_modified[0], { path: 'a.md', base_sha: '111', remote_sha: '222' })
+	})
+
+	it('classifies local_only_modified', () => {
+		const base = [{ path: 'a.md', sha: '111' }]
+		const local = [{ path: 'a.md', sha: '222' }]
+		const remote = [{ path: 'a.md', sha: '111' }]
+		const r = classify_changes(base, local, remote)
+		assert.strictEqual(r.local_only_modified.length, 1)
+		assert.deepStrictEqual(r.local_only_modified[0], { path: 'a.md', base_sha: '111', local_sha: '222' })
+	})
+
+	it('classifies both_modified (different changes)', () => {
+		const base = [{ path: 'a.md', sha: '111' }]
+		const local = [{ path: 'a.md', sha: '222' }]
+		const remote = [{ path: 'a.md', sha: '333' }]
+		const r = classify_changes(base, local, remote)
+		assert.strictEqual(r.both_modified.length, 1)
+		assert.deepStrictEqual(r.both_modified[0], { path: 'a.md', base_sha: '111', local_sha: '222', remote_sha: '333' })
+	})
+
+	it('classifies identical changes on both sides as unchanged', () => {
+		const base = [{ path: 'a.md', sha: '111' }]
+		const local = [{ path: 'a.md', sha: '222' }]
+		const remote = [{ path: 'a.md', sha: '222' }]
+		const r = classify_changes(base, local, remote)
+		assert.strictEqual(r.both_modified.length, 0)
+		assert.strictEqual(r.unchanged.length, 1)
+		assert.deepStrictEqual(r.unchanged[0], { path: 'a.md', sha: '222' })
+	})
+
+	it('classifies remote_only_added', () => {
+		const base = []
+		const local = []
+		const remote = [{ path: 'new.md', sha: 'aaa' }]
+		const r = classify_changes(base, local, remote)
+		assert.strictEqual(r.remote_only_added.length, 1)
+		assert.deepStrictEqual(r.remote_only_added[0], { path: 'new.md', remote_sha: 'aaa' })
+	})
+
+	it('classifies local_only_added', () => {
+		const base = []
+		const local = [{ path: 'new.md', sha: 'aaa' }]
+		const remote = []
+		const r = classify_changes(base, local, remote)
+		assert.strictEqual(r.local_only_added.length, 1)
+		assert.deepStrictEqual(r.local_only_added[0], { path: 'new.md', local_sha: 'aaa' })
+	})
+
+	it('classifies remote_only_deleted', () => {
+		const base = [{ path: 'gone.md', sha: '111' }]
+		const local = [{ path: 'gone.md', sha: '111' }]
+		const remote = []
+		const r = classify_changes(base, local, remote)
+		assert.strictEqual(r.remote_only_deleted.length, 1)
+		assert.deepStrictEqual(r.remote_only_deleted[0], { path: 'gone.md' })
+	})
+
+	it('classifies local_only_deleted', () => {
+		const base = [{ path: 'gone.md', sha: '111' }]
+		const local = []
+		const remote = [{ path: 'gone.md', sha: '111' }]
+		const r = classify_changes(base, local, remote)
+		assert.strictEqual(r.local_only_deleted.length, 1)
+		assert.deepStrictEqual(r.local_only_deleted[0], { path: 'gone.md' })
+	})
+
+	it('unchanged when nothing changed', () => {
+		const base = [{ path: 'a.md', sha: '111' }]
+		const local = [{ path: 'a.md', sha: '111' }]
+		const remote = [{ path: 'a.md', sha: '111' }]
+		const r = classify_changes(base, local, remote)
+		assert.strictEqual(r.unchanged.length, 1)
+		assert.deepStrictEqual(r.unchanged[0], { path: 'a.md', sha: '111' })
+	})
+
+	it('handles mixed scenario with all 8 types', () => {
+		const base = [
+			{ path: 'unchanged.md', sha: '000' },
+			{ path: 'remote_mod.md', sha: '111' },
+			{ path: 'local_mod.md', sha: '222' },
+			{ path: 'both_mod.md', sha: '333' },
+			{ path: 'remote_del.md', sha: '444' },
+			{ path: 'local_del.md', sha: '555' },
+		]
+		const local = [
+			{ path: 'unchanged.md', sha: '000' },
+			{ path: 'remote_mod.md', sha: '111' },
+			{ path: 'local_mod.md', sha: 'L22' },
+			{ path: 'both_mod.md', sha: 'L33' },
+			{ path: 'remote_del.md', sha: '444' },
+			// local_del.md removed
+			{ path: 'local_add.md', sha: 'LA1' },
+		]
+		const remote = [
+			{ path: 'unchanged.md', sha: '000' },
+			{ path: 'remote_mod.md', sha: 'R11' },
+			{ path: 'local_mod.md', sha: '222' },
+			{ path: 'both_mod.md', sha: 'R33' },
+			// remote_del.md removed
+			{ path: 'local_del.md', sha: '555' },
+			{ path: 'remote_add.md', sha: 'RA1' },
+		]
+		const r = classify_changes(base, local, remote)
+		assert.strictEqual(r.unchanged.length, 1)
+		assert.strictEqual(r.remote_only_modified.length, 1)
+		assert.strictEqual(r.local_only_modified.length, 1)
+		assert.strictEqual(r.both_modified.length, 1)
+		assert.strictEqual(r.remote_only_deleted.length, 1)
+		assert.strictEqual(r.local_only_deleted.length, 1)
+		assert.strictEqual(r.local_only_added.length, 1)
+		assert.strictEqual(r.remote_only_added.length, 1)
+	})
+
+	it('handles empty base with both sides adding same file differently', () => {
+		const base = []
+		const local = [{ path: 'new.md', sha: 'L11' }]
+		const remote = [{ path: 'new.md', sha: 'R11' }]
+		const r = classify_changes(base, local, remote)
+		assert.strictEqual(r.both_modified.length, 1)
+		assert.deepStrictEqual(r.both_modified[0], { path: 'new.md', base_sha: null, local_sha: 'L11', remote_sha: 'R11' })
+	})
+
+	it('handles empty base with both sides adding same file identically', () => {
+		const base = []
+		const local = [{ path: 'new.md', sha: 'same' }]
+		const remote = [{ path: 'new.md', sha: 'same' }]
+		const r = classify_changes(base, local, remote)
+		assert.strictEqual(r.unchanged.length, 1)
+		assert.strictEqual(r.both_modified.length, 0)
+	})
+
+	it('handles delete-vs-modify as both_modified (local deleted, remote modified)', () => {
+		const base = [{ path: 'a.md', sha: '111' }]
+		const local = []
+		const remote = [{ path: 'a.md', sha: '222' }]
+		const r = classify_changes(base, local, remote)
+		assert.strictEqual(r.both_modified.length, 1)
+		assert.deepStrictEqual(r.both_modified[0], { path: 'a.md', base_sha: '111', local_sha: null, remote_sha: '222' })
+	})
+
+	it('handles delete-vs-modify as both_modified (local modified, remote deleted)', () => {
+		const base = [{ path: 'a.md', sha: '111' }]
+		const local = [{ path: 'a.md', sha: '222' }]
+		const remote = []
+		const r = classify_changes(base, local, remote)
+		assert.strictEqual(r.both_modified.length, 1)
+		assert.deepStrictEqual(r.both_modified[0], { path: 'a.md', base_sha: '111', local_sha: '222', remote_sha: null })
+	})
+})

package/src/merge/report.js

@@ -0,0 +1,59 @@
+/**
+ * Generates a structured JSON merge report (v1 contract).
+ *
+ * The report is consumed by both human-readable CLI output and the AI agent
+ * semantic review layer (Layer 2). It must include enough data for the agent
+ * to reason about conflicts without additional API calls.
+ */
+
+const CLASSIFICATIONS = [
+	'remote_only_modified', 'local_only_modified', 'both_modified',
+	'remote_only_added', 'local_only_added',
+	'remote_only_deleted', 'local_only_deleted',
+	'unchanged'
+]
+
+const build_report = (skill, base_version, remote_version, classified) => {
+	const files = []
+	let clean = 0
+	let conflicted = 0
+	let auto_merged = 0
+
+	for (const classification of CLASSIFICATIONS) {
+		const entries = classified[classification] || []
+		for (const entry of entries) {
+			if (classification === 'unchanged') {
+				clean++
+				continue
+			}
+
+			const is_conflict = classification === 'both_modified'
+			if (is_conflict) conflicted++
+			else auto_merged++
+
+			files.push({
+				path: entry.path,
+				classification,
+				conflict_written: false,
+				base_sha: entry.base_sha || null,
+				local_sha: entry.local_sha || null,
+				remote_sha: entry.remote_sha || null
+			})
+		}
+	}
+
+	return {
+		skill,
+		base_version: base_version || null,
+		remote_version: remote_version || null,
+		files,
+		summary: {
+			total: clean + auto_merged + conflicted,
+			clean,
+			auto_merged,
+			conflicted
+		}
+	}
+}
+
+module.exports = { build_report, CLASSIFICATIONS }

package/src/merge/report.test.js

@@ -0,0 +1,85 @@
+const { describe, it } = require('node:test')
+const assert = require('node:assert/strict')
+const { build_report, CLASSIFICATIONS } = require('./report')
+
+describe('build_report', () => {
+	it('produces v1 contract fields', () => {
+		const classified = {
+			remote_only_modified: [{ path: 'a.md', base_sha: '111', remote_sha: '222' }],
+			local_only_modified: [],
+			both_modified: [{ path: 'b.md', base_sha: '333', local_sha: '444', remote_sha: '555' }],
+			remote_only_added: [],
+			local_only_added: [],
+			remote_only_deleted: [],
+			local_only_deleted: [],
+			unchanged: [{ path: 'c.md', sha: '666' }]
+		}
+		const report = build_report('acme/deploy-aws', '1.15.0', '1.17.0', classified)
+
+		assert.strictEqual(report.skill, 'acme/deploy-aws')
+		assert.strictEqual(report.base_version, '1.15.0')
+		assert.strictEqual(report.remote_version, '1.17.0')
+		assert.strictEqual(report.files.length, 2)
+		assert.deepStrictEqual(report.summary, { total: 3, clean: 1, auto_merged: 1, conflicted: 1 })
+	})
+
+	it('summary counts match file array', () => {
+		const classified = {
+			remote_only_modified: [{ path: 'a.md', base_sha: '1', remote_sha: '2' }],
+			local_only_modified: [{ path: 'b.md', base_sha: '3', local_sha: '4' }],
+			both_modified: [],
+			remote_only_added: [{ path: 'c.md', remote_sha: '5' }],
+			local_only_added: [],
+			remote_only_deleted: [{ path: 'd.md' }],
+			local_only_deleted: [],
+			unchanged: [{ path: 'e.md', sha: '6' }, { path: 'f.md', sha: '7' }]
+		}
+		const report = build_report('test/skill', '1.0.0', '2.0.0', classified)
+
+		assert.strictEqual(report.files.length, report.summary.auto_merged + report.summary.conflicted)
+		assert.strictEqual(report.summary.total, report.summary.clean + report.summary.auto_merged + report.summary.conflicted)
+	})
+
+	it('classifications are from the defined vocabulary', () => {
+		const classified = {
+			remote_only_modified: [{ path: 'a.md', base_sha: '1', remote_sha: '2' }],
+			local_only_modified: [],
+			both_modified: [{ path: 'b.md', base_sha: '3', local_sha: '4', remote_sha: '5' }],
+			remote_only_added: [],
+			local_only_added: [],
+			remote_only_deleted: [],
+			local_only_deleted: [],
+			unchanged: []
+		}
+		const report = build_report('test/skill', '1.0.0', '2.0.0', classified)
+
+		for (const file of report.files) {
+			assert.ok(CLASSIFICATIONS.includes(file.classification), `Unknown classification: ${file.classification}`)
+		}
+	})
+
+	it('handles null versions gracefully', () => {
+		const classified = {
+			remote_only_modified: [], local_only_modified: [], both_modified: [],
+			remote_only_added: [], local_only_added: [],
+			remote_only_deleted: [], local_only_deleted: [],
+			unchanged: [{ path: 'a.md', sha: '111' }]
+		}
+		const report = build_report('test/skill', null, null, classified)
+		assert.strictEqual(report.base_version, null)
+		assert.strictEqual(report.remote_version, null)
+		assert.strictEqual(report.summary.total, 1)
+	})
+
+	it('unchanged files are not included in files array', () => {
+		const classified = {
+			remote_only_modified: [], local_only_modified: [], both_modified: [],
+			remote_only_added: [], local_only_added: [],
+			remote_only_deleted: [], local_only_deleted: [],
+			unchanged: [{ path: 'a.md', sha: '111' }, { path: 'b.md', sha: '222' }]
+		}
+		const report = build_report('test/skill', '1.0.0', '1.0.0', classified)
+		assert.strictEqual(report.files.length, 0)
+		assert.strictEqual(report.summary.clean, 2)
+	})
+})