happyskills 0.48.0 → 0.49.0

package/src/merge/rebase.js

@@ -0,0 +1,322 @@
+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 snapshot_storage = require('../snapshot/storage')
+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 { skills_dir, skill_install_dir, lock_root, find_project_root } = require('../config/paths')
+const { ensure_dir, read_file } = require('../utils/fs')
+const { unified_diff } = require('../utils/text_diff')
+
+// ──────────────────────────────────────────────────────────────────────────────
+// Rebase-style pull (§ 8.3)
+//
+// Differs from the existing 3-way merge: instead of writing conflict markers
+// into files, we capture local edits as patches, fast-forward to the registry
+// HEAD, and reapply the patches. On rejection (the rebased file's expected
+// context no longer matches), emit a structured envelope that gives the
+// operator (LLM or human) enough information to produce a corrected patch
+// without re-reading entire files.
+//
+// Snapshot-first invariant: every rebase begins with a snapshot. On any
+// failure path the operator can restore — the snapshot_id is in every
+// rejection envelope.
+// ──────────────────────────────────────────────────────────────────────────────
+
+const decode_b64 = (file) => file ? Buffer.from(file.content, 'base64').toString('utf-8') : null
+
+// Read every file in skill_dir relative to skill_dir, returning a map of
+// path → utf-8 content. Skips dotfiles/dotdirs, matching the rest of the
+// codebase's collect_files semantics.
+const read_dir_files = (dir) => catch_errors('Failed to read dir files', async () => {
+	const out = new Map()
+	const walk = async (cur, prefix) => {
+		const items = await fs.promises.readdir(cur, { withFileTypes: true })
+		for (const item of items) {
+			if (item.name.startsWith('.')) continue
+			const rel = prefix ? `${prefix}/${item.name}` : item.name
+			const full = path.join(cur, item.name)
+			if (item.isDirectory()) {
+				await walk(full, rel)
+			} else if (item.isFile()) {
+				const content = await fs.promises.readFile(full, 'utf-8')
+				out.set(rel, content)
+			}
+		}
+	}
+	await walk(dir, '')
+	return out
+})
+
+// Compare base content vs current disk content → patches for files that
+// differ. The result is a list of { path, base_content, local_content,
+// patch } — we keep the raw contents around because the reapply step needs
+// them to detect three-way conflicts cleanly.
+const capture_local_patches = ({ base_files_map, local_files_map }) => {
+	const patches = []
+	const all_paths = new Set([...base_files_map.keys(), ...local_files_map.keys()])
+	for (const p of all_paths) {
+		const base = base_files_map.get(p)
+		const local = local_files_map.get(p)
+		if (base === local) continue
+		if (base === undefined && local !== undefined) {
+			patches.push({ path: p, type: 'added', base_content: null, local_content: local, patch: unified_diff('', local, `base/${p}`, `local/${p}`) })
+			continue
+		}
+		if (local === undefined && base !== undefined) {
+			patches.push({ path: p, type: 'deleted', base_content: base, local_content: null, patch: unified_diff(base, '', `base/${p}`, `local/${p}`) })
+			continue
+		}
+		patches.push({ path: p, type: 'modified', base_content: base, local_content: local, patch: unified_diff(base, local, `base/${p}`, `local/${p}`) })
+	}
+	return patches
+}
+
+// Reapply a captured patch onto a new base file (post-fast-forward content).
+// Strategy:
+//   - If the new base content equals the captured base_content → patch
+//     trivially applies (we just write local_content back).
+//   - If the new base content equals the captured local_content → patch
+//     is already a no-op (remote already had our change). Skip.
+//   - Otherwise → rejection. Emit a structured rejection entry with both
+//     contexts so the operator can re-aim the patch.
+const reapply_patch = (patch, remote_file_content) => {
+	if (patch.type === 'added') {
+		// File was added locally. If remote also added it, prefer local
+		// (this is rebase — local wins on add/add); if remote didn't,
+		// just write our addition.
+		return { kind: 'apply_local', content: patch.local_content }
+	}
+	if (patch.type === 'deleted') {
+		// File was deleted locally. If remote also deleted it, no-op.
+		// If remote modified it, that's a conflict.
+		if (remote_file_content === undefined || remote_file_content === null) {
+			return { kind: 'apply_delete' }
+		}
+		return {
+			kind: 'reject',
+			reason: 'delete_vs_modify',
+			expected_context_before: patch.base_content,
+			actual_context_before: remote_file_content,
+			intended_change_summary: 'Local deleted; remote modified the same file.'
+		}
+	}
+	// Modified locally.
+	if (remote_file_content === patch.base_content) {
+		return { kind: 'apply_local', content: patch.local_content }
+	}
+	if (remote_file_content === patch.local_content) {
+		// Remote already has the same change we made — patch is a no-op.
+		return { kind: 'noop' }
+	}
+	return {
+		kind: 'reject',
+		reason: 'context_changed',
+		expected_context_before: patch.base_content,
+		actual_context_before: remote_file_content,
+		intended_change_summary: 'Local modified a file whose remote content has also changed.'
+	}
+}
+
+const rebase_pull = (skill_name, options = {}) => catch_errors('Pull --rebase failed', async () => {
+	if (!skill_name || !skill_name.includes('/')) {
+		throw new Error('skill_name must be in owner/name format')
+	}
+	const project_root = options.project_root || find_project_root()
+	const is_global = !!options.is_global
+
+	const [lock_err, lock_data] = await read_lock(lock_root(is_global, project_root))
+	if (lock_err || !lock_data) throw new Error('No lock file found')
+	const all = get_all_locked_skills(lock_data)
+	const lock_entry = all[skill_name]
+	if (!lock_entry) throw new Error(`${skill_name} is not installed`)
+	if (!lock_entry.base_commit) throw new Error(`${skill_name} has no base_commit`)
+
+	const [owner, repo] = skill_name.split('/')
+	const base_dir = skills_dir(is_global, project_root)
+	const skill_dir = skill_install_dir(base_dir, repo)
+
+	// Snapshot first — always.
+	const [snap_err, snap] = await snapshot_storage.create({
+		skill_dir,
+		workspace: owner,
+		skill: repo,
+		lock_entry,
+		note: `pre-rebase-pull`,
+		is_global,
+		project_root
+	})
+	if (snap_err) throw e('Snapshot failed', snap_err)
+
+	const restore_and = async (envelope) => {
+		await snapshot_storage.restore(snap.snapshot_id, { skill_dir, is_global, project_root })
+		return { ...envelope, snapshot_id: snap.snapshot_id }
+	}
+
+	// Compare with remote.
+	const [cmp_err, cmp_data] = await repos_api.compare(owner, repo, lock_entry.base_commit)
+	if (cmp_err) {
+		return await restore_and({
+			error: { code: 'COMPARE_FAILED', message: 'Failed to compare with remote' },
+			next_step: { action: 'retry_or_abandon' }
+		})
+	}
+
+	if (cmp_data.added.length === 0 && cmp_data.removed.length === 0 && cmp_data.modified.length === 0) {
+		// Up to date — drop the snapshot (nothing happened).
+		await snapshot_storage.remove(snap.snapshot_id, { is_global, project_root })
+		return {
+			data: { status: 'up_to_date', skill: skill_name },
+			next_step: null
+		}
+	}
+
+	// Pull base and remote content.
+	const [base_clone_err, base_clone] = await repos_api.clone(owner, repo, null, { commit: lock_entry.base_commit })
+	if (base_clone_err) {
+		return await restore_and({
+			error: { code: 'CLONE_BASE_FAILED', message: 'Failed to clone base commit' },
+			next_step: { action: 'retry_or_abandon' }
+		})
+	}
+	const [remote_clone_err, remote_clone] = await repos_api.clone(owner, repo, null, { commit: cmp_data.head_commit })
+	if (remote_clone_err) {
+		return await restore_and({
+			error: { code: 'CLONE_REMOTE_FAILED', message: 'Failed to clone remote head' },
+			next_step: { action: 'retry_or_abandon' }
+		})
+	}
+
+	const base_files_map = new Map((base_clone.files || []).map(f => [f.path, decode_b64(f)]))
+	const remote_files_map = new Map((remote_clone.files || []).map(f => [f.path, decode_b64(f)]))
+
+	// Capture local patches relative to the base commit.
+	const [local_err, local_files_map] = await read_dir_files(skill_dir)
+	if (local_err) {
+		return await restore_and({
+			error: { code: 'READ_LOCAL_FAILED', message: 'Failed to read local files' },
+			next_step: { action: 'retry_or_abandon' }
+		})
+	}
+	const patches = capture_local_patches({ base_files_map, local_files_map })
+
+	// Fast-forward: write remote files into skill_dir, deleting anything not in remote.
+	// We do this in a staging directory and atomically swap.
+	const staging = `${skill_dir}.rebase-staging-${process.pid}-${Date.now()}`
+	await fs.promises.mkdir(staging, { recursive: true })
+	for (const [p, content] of remote_files_map) {
+		const dest = path.join(staging, p)
+		await ensure_dir(path.dirname(dest))
+		await fs.promises.writeFile(dest, content, 'utf-8')
+	}
+
+	// Reapply each patch.
+	const applied = []
+	const rejected = []
+	for (const patch of patches) {
+		const remote_content = remote_files_map.get(patch.path)
+		const decision = reapply_patch(patch, remote_content)
+		if (decision.kind === 'apply_local') {
+			const dest = path.join(staging, patch.path)
+			await ensure_dir(path.dirname(dest))
+			await fs.promises.writeFile(dest, decision.content, 'utf-8')
+			applied.push({ path: patch.path, type: patch.type })
+		} else if (decision.kind === 'apply_delete') {
+			const dest = path.join(staging, patch.path)
+			try { await fs.promises.unlink(dest) } catch { /* not present, fine */ }
+			applied.push({ path: patch.path, type: 'deleted' })
+		} else if (decision.kind === 'noop') {
+			applied.push({ path: patch.path, type: patch.type, noop: true })
+		} else if (decision.kind === 'reject') {
+			rejected.push({
+				file: patch.path,
+				patch_type: patch.type,
+				reason: decision.reason,
+				expected_context_before: decision.expected_context_before,
+				actual_context_before: decision.actual_context_before,
+				patch: patch.patch,
+				intended_change_summary: decision.intended_change_summary
+			})
+		}
+	}
+
+	if (rejected.length > 0) {
+		// Discard staging directory; the snapshot is the canonical safety net
+		// and the operator decides what to do next.
+		await fs.promises.rm(staging, { recursive: true, force: true })
+		// Note: we do NOT restore the snapshot here — the operator may want
+		// to inspect the captured patches and rejection context before
+		// deciding. Restoration is one explicit `snapshot restore` away.
+		return {
+			data: {
+				operation: 'pull_rebase',
+				skill: skill_name,
+				fast_forward_to: cmp_data.head_commit,
+				patches_applied: applied,
+				patches_rejected: rejected,
+				snapshot_id: snap.snapshot_id
+			},
+			next_step: {
+				action: 'resolve_patch_rejections',
+				context: {
+					rejection_count: rejected.length,
+					options: ['resolve_and_continue', 'abandon_and_restore'],
+					instructions: 'Either resolve each rejection by re-applying the corrected patches yourself, or restore the pre-rebase state with `npx happyskills snapshot restore <snapshot_id>`.'
+				}
+			},
+			error: null
+		}
+	}
+
+	// All patches applied cleanly — swap staging into place.
+	const trash = `${skill_dir}.rebase-trash-${process.pid}-${Date.now()}`
+	await fs.promises.rename(skill_dir, trash)
+	try {
+		await fs.promises.rename(staging, skill_dir)
+	} catch (err) {
+		// Roll back.
+		await fs.promises.rename(trash, skill_dir).catch(() => {})
+		await fs.promises.rm(staging, { recursive: true, force: true })
+		return await restore_and({
+			error: { code: 'SWAP_FAILED', message: 'Failed to swap rebased content into place' },
+			next_step: { action: 'retry_or_abandon' }
+		})
+	}
+	await fs.promises.rm(trash, { recursive: true, force: true }).catch(() => {})
+
+	// Update lock.
+	const [, new_integrity] = await hash_directory(skill_dir)
+	const updated_entry = {
+		...lock_entry,
+		commit: cmp_data.head_commit,
+		base_commit: cmp_data.head_commit,
+		integrity: new_integrity || lock_entry.integrity,
+		base_integrity: new_integrity || lock_entry.base_integrity,
+		version: cmp_data.head_version || lock_entry.version
+	}
+	delete updated_entry.merge_parents
+	delete updated_entry.conflict_files
+	const merged = update_lock_skills(lock_data, { [skill_name]: updated_entry })
+	await write_lock(lock_root(is_global, project_root), merged)
+
+	// Success — drop the snapshot.
+	await snapshot_storage.remove(snap.snapshot_id, { is_global, project_root })
+
+	return {
+		data: {
+			operation: 'pull_rebase',
+			status: applied.length > 0 ? 'rebased' : 'fast_forward',
+			skill: skill_name,
+			fast_forward_to: cmp_data.head_commit,
+			patches_applied: applied,
+			patches_rejected: [],
+			version: cmp_data.head_version || lock_entry.version
+		},
+		next_step: null,
+		error: null
+	}
+})
+
+module.exports = { rebase_pull, capture_local_patches, reapply_patch, read_dir_files }

package/src/merge/rebase.test.js

@@ -0,0 +1,110 @@
+'use strict'
+const { describe, it } = require('node:test')
+const assert = require('node:assert/strict')
+const fs = require('fs')
+const os = require('os')
+const path = require('path')
+
+const { capture_local_patches, reapply_patch, read_dir_files } = require('./rebase')
+
+describe('rebase.capture_local_patches', () => {
+	it('identifies modified files and produces a patch', () => {
+		const base = new Map([['SKILL.md', 'one\ntwo\n'], ['skill.json', '{"v":1}']])
+		const local = new Map([['SKILL.md', 'one\ntwo\nthree\n'], ['skill.json', '{"v":1}']])
+		const patches = capture_local_patches({ base_files_map: base, local_files_map: local })
+		assert.strictEqual(patches.length, 1)
+		assert.strictEqual(patches[0].path, 'SKILL.md')
+		assert.strictEqual(patches[0].type, 'modified')
+		assert.ok(patches[0].patch.includes('+three'), 'unified diff should show the added line')
+	})
+
+	it('identifies added files', () => {
+		const base = new Map([['SKILL.md', 'body']])
+		const local = new Map([['SKILL.md', 'body'], ['references/new.md', 'new']])
+		const patches = capture_local_patches({ base_files_map: base, local_files_map: local })
+		assert.strictEqual(patches.length, 1)
+		assert.strictEqual(patches[0].path, 'references/new.md')
+		assert.strictEqual(patches[0].type, 'added')
+		assert.strictEqual(patches[0].local_content, 'new')
+		assert.strictEqual(patches[0].base_content, null)
+	})
+
+	it('identifies deleted files', () => {
+		const base = new Map([['SKILL.md', 'body'], ['gone.md', 'goodbye']])
+		const local = new Map([['SKILL.md', 'body']])
+		const patches = capture_local_patches({ base_files_map: base, local_files_map: local })
+		assert.strictEqual(patches.length, 1)
+		assert.strictEqual(patches[0].path, 'gone.md')
+		assert.strictEqual(patches[0].type, 'deleted')
+	})
+
+	it('returns no patches when base and local are identical', () => {
+		const same = new Map([['SKILL.md', 'body'], ['skill.json', '{}']])
+		const patches = capture_local_patches({ base_files_map: same, local_files_map: same })
+		assert.deepEqual(patches, [])
+	})
+})
+
+describe('rebase.reapply_patch', () => {
+	it('applies a modified patch when remote content equals base (clean apply)', () => {
+		const patch = { path: 'SKILL.md', type: 'modified', base_content: 'a\nb\nc\n', local_content: 'a\nb\nc\nd\n' }
+		const remote = 'a\nb\nc\n'
+		const decision = reapply_patch(patch, remote)
+		assert.strictEqual(decision.kind, 'apply_local')
+		assert.strictEqual(decision.content, 'a\nb\nc\nd\n')
+	})
+
+	it('returns noop when remote already has the same change', () => {
+		const patch = { path: 'SKILL.md', type: 'modified', base_content: 'a\n', local_content: 'a\nb\n' }
+		const remote = 'a\nb\n'
+		const decision = reapply_patch(patch, remote)
+		assert.strictEqual(decision.kind, 'noop')
+	})
+
+	it('rejects when remote content differs from both base and local (context change)', () => {
+		const patch = { path: 'SKILL.md', type: 'modified', base_content: 'a\n', local_content: 'a\nb\n' }
+		const remote = 'a\nx\ny\n'
+		const decision = reapply_patch(patch, remote)
+		assert.strictEqual(decision.kind, 'reject')
+		assert.strictEqual(decision.reason, 'context_changed')
+		assert.strictEqual(decision.expected_context_before, 'a\n')
+		assert.strictEqual(decision.actual_context_before, 'a\nx\ny\n')
+	})
+
+	it('writes added file unconditionally for add patches', () => {
+		const patch = { path: 'new.md', type: 'added', base_content: null, local_content: 'fresh\n' }
+		const decision = reapply_patch(patch, undefined)
+		assert.strictEqual(decision.kind, 'apply_local')
+		assert.strictEqual(decision.content, 'fresh\n')
+	})
+
+	it('deletes the file when both sides deleted it', () => {
+		const patch = { path: 'gone.md', type: 'deleted', base_content: 'x', local_content: null }
+		const decision = reapply_patch(patch, undefined)
+		assert.strictEqual(decision.kind, 'apply_delete')
+	})
+
+	it('rejects delete-vs-modify (local deleted; remote modified)', () => {
+		const patch = { path: 'gone.md', type: 'deleted', base_content: 'x', local_content: null }
+		const decision = reapply_patch(patch, 'modified-on-remote')
+		assert.strictEqual(decision.kind, 'reject')
+		assert.strictEqual(decision.reason, 'delete_vs_modify')
+	})
+})
+
+describe('rebase.read_dir_files', () => {
+	it('reads all non-dot files recursively', async () => {
+		const root = fs.mkdtempSync(path.join(os.tmpdir(), 'hs-rebase-readdir-'))
+		try {
+			fs.mkdirSync(path.join(root, 'references'), { recursive: true })
+			fs.writeFileSync(path.join(root, 'SKILL.md'), 'top')
+			fs.writeFileSync(path.join(root, 'references', 'foo.md'), 'nested')
+			fs.mkdirSync(path.join(root, '.tmp'), { recursive: true })
+			fs.writeFileSync(path.join(root, '.tmp', 'ignore.txt'), 'should be skipped')
+			const [, files] = await read_dir_files(root)
+			assert.strictEqual(files.size, 2)
+			assert.strictEqual(files.get('SKILL.md'), 'top')
+			assert.strictEqual(files.get('references/foo.md'), 'nested')
+		} finally { fs.rmSync(root, { recursive: true, force: true }) }
+	})
+})

package/src/snapshot/paths.js

@@ -0,0 +1,31 @@
+const path = require('path')
+const { home_dir } = require('../config/paths')
+
+// Snapshots are local-only artifacts. Project snapshots live under the project
+// root; global snapshots live under the user's home so global-installed skills
+// have a parallel safety net. Workspace is encoded into the path so a skill
+// short-name collision across workspaces is impossible.
+const snapshots_root = (is_global, project_root) => {
+	if (is_global) return path.join(home_dir, '.happyskills', 'snapshots')
+	return path.join(project_root || process.cwd(), '.happyskills', 'snapshots')
+}
+
+const skill_snapshots_dir = (is_global, project_root, workspace, skill) => {
+	return path.join(snapshots_root(is_global, project_root), workspace, skill)
+}
+
+const snapshot_dir = (is_global, project_root, workspace, skill, snapshot_id) => {
+	return path.join(skill_snapshots_dir(is_global, project_root, workspace, skill), snapshot_id)
+}
+
+const snapshot_manifest_path = (snap_dir) => path.join(snap_dir, 'manifest.json')
+
+const snapshot_content_dir = (snap_dir) => path.join(snap_dir, 'content')
+
+module.exports = {
+	snapshots_root,
+	skill_snapshots_dir,
+	snapshot_dir,
+	snapshot_manifest_path,
+	snapshot_content_dir
+}