happyskills 0.36.0 → 0.38.0

package/CHANGELOG.md

@@ -7,6 +7,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.38.0] - 2026-05-01
+
+### Changed
+- **BREAKING:** Make `--limit` required for the `search` command — there is no default. Running `happyskills search ...` without `--limit` now returns a usage error (exit code 2). The previous hidden default of 10 caused AI-agent callers to miss results without realizing a limit was being applied. Affects both smart-search and `--exact` keyword modes. Update help text and all examples to show `--limit` explicitly.
+
+### Fixed
+- Fix `search --workspace <slug>` (in browse mode with no query, and in `--exact` keyword mode) silently excluding private skills the caller has access to. The CLI was omitting the auth token when only `--workspace` was specified without `--mine` or `--personal`, causing the API to fall back to public-only results. The auth token is now always attached when one is available, regardless of the search mode.
+
+## [0.37.0] - 2026-04-25
+
+### Added
+- Add unified content diffs to `diff` command — fetches base and local/remote file content for changed files, computes line-by-line unified diffs using the Myers O(ND) algorithm, and includes them in both CLI and JSON output
+- Add `--no-content` flag to `diff` command to skip content diffs and show only the file list (previous behavior)
+- Add `text_diff.js` utility module — lightweight Myers diff with unified diff formatting, no external dependencies
+- Add colored CLI diff output (red/green/cyan) matching standard unified diff conventions
+
+### Changed
+- Change `diff` JSON output to include `diff` field on each changed file entry with the unified diff text. For `both_modified` files, `local_diff` and `remote_diff` fields are provided instead
+
 ## [0.36.0] - 2026-04-17
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "happyskills",
-	"version": "0.36.0",
+	"version": "0.38.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

@@ -10,8 +10,7 @@ const search = (query, options = {}) => catch_errors('Search failed', async () =
 	if (options.workspace) params.set('workspace', options.workspace)
 	if (options.tags) params.set('tags', options.tags)
 	if (options.type) params.set('type', options.type)
-	const needs_auth = options.scope && options.scope !== 'public'
-	const [errors, data] = await client.get(`/repos/search?${params}`, { auth: needs_auth || false })
+	const [errors, data] = await client.get(`/repos/search?${params}`)
 	if (errors) throw errors[errors.length - 1]
 	return data
 })

package/src/commands/diff.js

@@ -2,19 +2,20 @@ 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 { unified_diff } = require('../utils/text_diff')
 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 { red, green, cyan, bold } = require('../ui/colors')
 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.
+Show file-level differences for a skill with unified diffs.
 
 Arguments:
   owner/skill       Skill to diff (required)
@@ -22,6 +23,7 @@ Arguments:
 Options:
   --remote          Show base vs remote changes (default: local vs base)
   --full            Show three-way diff (base vs local vs remote)
+  --no-content      Show only file list without content diffs
   -g, --global      Diff globally installed skill
   --json            Output as JSON
 
@@ -30,7 +32,8 @@ Aliases: d
 Examples:
   happyskills diff acme/deploy-aws
   happyskills diff acme/deploy-aws --remote
-  happyskills diff acme/deploy-aws --full`
+  happyskills diff acme/deploy-aws --full
+  happyskills diff acme/deploy-aws --no-content`
 
 // ─── Helpers ──────────────────────────────────────────────────────────────────
 
@@ -64,6 +67,98 @@ const STATUS_LABELS = {
 	local_only_deleted: 'D (local)'
 }
 
+const DIFF_CLASSIFICATIONS = new Set([
+	'local_only_modified', 'local_only_added', 'local_only_deleted',
+	'remote_only_modified', 'remote_only_added', 'remote_only_deleted',
+	'both_modified'
+])
+
+// ─── Content diff enrichment ─────────────────────────────────────────────────
+
+/**
+ * Enrich report file entries with unified diffs for changed files.
+ *
+ * Memory strategy:
+ * - Only decode/read content for files whose SHAs actually differ
+ * - Local file reads run concurrently via Promise.all
+ * - All content maps are cleared after diffs are computed
+ *
+ * @param {object} report - The merge report with file entries
+ * @param {Array} base_clone_files - Raw clone response files (with base64 content)
+ * @param {string|null} skill_dir - Local skill directory (null if local content not needed)
+ * @param {Array|null} remote_clone_files - Raw remote clone files (null if not needed)
+ */
+const enrich_with_diffs = (report, base_clone_files, skill_dir, remote_clone_files) => catch_errors('Failed to compute content diffs', async () => {
+	const changed = report.files.filter(f => DIFF_CLASSIFICATIONS.has(f.classification))
+	if (changed.length === 0) return
+
+	const changed_paths = new Set(changed.map(f => f.path))
+
+	// Build base content map — only decode changed paths from the clone response
+	const base_map = new Map()
+	for (const f of (base_clone_files || [])) {
+		if (changed_paths.has(f.path) && f.content) {
+			base_map.set(f.path, Buffer.from(f.content, 'base64').toString('utf-8'))
+		}
+	}
+
+	// Build remote content map — same selective decode
+	const remote_map = new Map()
+	for (const f of (remote_clone_files || [])) {
+		if (changed_paths.has(f.path) && f.content) {
+			remote_map.set(f.path, Buffer.from(f.content, 'base64').toString('utf-8'))
+		}
+	}
+
+	// Read local content concurrently — only files that exist locally
+	const local_map = new Map()
+	if (skill_dir) {
+		const needs_local = changed.filter(f => f.local_sha)
+		const results = await Promise.all(needs_local.map(async f => {
+			try {
+				const content = await fs.promises.readFile(path.join(skill_dir, f.path), 'utf-8')
+				return { path: f.path, content }
+			} catch {
+				return null
+			}
+		}))
+		for (const r of results) {
+			if (r) local_map.set(r.path, r.content)
+		}
+	}
+
+	// Compute unified diffs — CPU-only, no I/O
+	for (const f of changed) {
+		const base = base_map.get(f.path) ?? ''
+		const local = local_map.get(f.path) ?? ''
+		const remote = remote_map.get(f.path) ?? ''
+
+		switch (f.classification) {
+		case 'local_only_modified':
+		case 'local_only_added':
+		case 'local_only_deleted':
+			f.diff = unified_diff(base, local, `base/${f.path}`, `local/${f.path}`)
+			break
+		case 'remote_only_modified':
+		case 'remote_only_added':
+		case 'remote_only_deleted':
+			f.diff = unified_diff(base, remote, `base/${f.path}`, `remote/${f.path}`)
+			break
+		case 'both_modified':
+			f.local_diff = unified_diff(base, local, `base/${f.path}`, `local/${f.path}`)
+			f.remote_diff = unified_diff(base, remote, `base/${f.path}`, `remote/${f.path}`)
+			break
+		}
+	}
+
+	// Flush content maps to release memory
+	base_map.clear()
+	remote_map.clear()
+	local_map.clear()
+})
+
+// ─── CLI output ──────────────────────────────────────────────────────────────
+
 const print_file_table = (classified) => {
 	const lines = []
 	for (const [category, label] of Object.entries(STATUS_LABELS)) {
@@ -84,6 +179,44 @@ const print_file_table = (classified) => {
 	}
 }
 
+const print_colored_diff = (diff_text) => {
+	if (!diff_text) return
+	for (const line of diff_text.split('\n')) {
+		if (line.startsWith('---') || line.startsWith('+++')) {
+			console.log(bold(line))
+		} else if (line.startsWith('@@')) {
+			console.log(cyan(line))
+		} else if (line.startsWith('+')) {
+			console.log(green(line))
+		} else if (line.startsWith('-')) {
+			console.log(red(line))
+		} else {
+			console.log(line)
+		}
+	}
+}
+
+const print_report_diffs = (report) => {
+	const has_diffs = report.files.some(f => f.diff || f.local_diff || f.remote_diff)
+	if (!has_diffs) return
+
+	console.log('')
+	for (const f of report.files) {
+		if (f.diff) {
+			print_colored_diff(f.diff)
+			console.log('')
+		}
+		if (f.local_diff) {
+			print_colored_diff(f.local_diff)
+			console.log('')
+		}
+		if (f.remote_diff) {
+			print_colored_diff(f.remote_diff)
+			console.log('')
+		}
+	}
+}
+
 // ─── Main ─────────────────────────────────────────────────────────────────────
 
 const run = (args) => catch_errors('Diff failed', async () => {
@@ -99,6 +232,7 @@ const run = (args) => catch_errors('Diff failed', async () => {
 
 	const is_global = args.flags.global || false
 	const mode = args.flags.full ? 'full' : args.flags.remote ? 'remote' : 'local'
+	const skip_content = args.flags['no-content'] || false
 	const project_root = find_project_root()
 
 	// Read lock
@@ -114,29 +248,33 @@ const run = (args) => catch_errors('Diff failed', async () => {
 	const base_dir = skills_dir(is_global, project_root)
 	const skill_dir = skill_install_dir(base_dir, repo)
 
-	// Always need base files
+	// Always need base files — keep full clone response for content diffs
 	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)
+		const report = build_report(skill_name, lock_entry.version, lock_entry.version, classified)
+
+		if (!skip_content) {
+			const [enrich_err] = await enrich_with_diffs(report, base_clone.files, skill_dir, null)
+			if (enrich_err) throw e('Content diff failed', enrich_err)
+		}
 
 		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)
+			print_report_diffs(report)
 		}
 		return
 	}
 
 	if (mode === 'remote') {
-		// Base vs remote — get head commit via compare, clone at that commit
 		const [cmp_err, cmp_data] = await repos_api.compare(owner, repo, lock_entry.base_commit)
 		if (cmp_err) throw e('Compare failed', cmp_err)
 
@@ -145,17 +283,23 @@ const run = (args) => catch_errors('Diff failed', async () => {
 		const remote_files = (remote_clone.files || []).map(f => ({ path: f.path, sha: f.sha }))
 
 		const classified = classify_changes(base_files, base_files, remote_files)
+		const report = build_report(skill_name, lock_entry.version, cmp_data.head_version, classified)
+
+		if (!skip_content) {
+			const [enrich_err] = await enrich_with_diffs(report, base_clone.files, null, remote_clone.files)
+			if (enrich_err) throw e('Content diff failed', enrich_err)
+		}
 
 		if (args.flags.json) {
-			const report = build_report(skill_name, lock_entry.version, cmp_data.head_version, classified)
 			print_json({ data: { mode, report } })
 		} else {
 			print_file_table(classified)
+			print_report_diffs(report)
 		}
 		return
 	}
 
-	// Full three-way diff — get head commit via compare
+	// Full three-way diff
 	const [cmp_err, cmp_data] = await repos_api.compare(owner, repo, lock_entry.base_commit)
 	if (cmp_err) throw e('Compare failed', cmp_err)
 
@@ -169,10 +313,16 @@ const run = (args) => catch_errors('Diff failed', async () => {
 	const classified = classify_changes(base_files, local_files, remote_files)
 	const report = build_report(skill_name, lock_entry.version, cmp_data.head_version, classified)
 
+	if (!skip_content) {
+		const [enrich_err] = await enrich_with_diffs(report, base_clone.files, skill_dir, remote_clone.files)
+		if (enrich_err) throw e('Content diff failed', enrich_err)
+	}
+
 	if (args.flags.json) {
 		print_json({ data: { mode, report } })
 	} else {
 		print_file_table(classified)
+		print_report_diffs(report)
 		if (report.summary.conflicted > 0) {
 			console.error('')
 			print_warn(`${report.summary.conflicted} file(s) modified on both sides`)

package/src/commands/search.js

@@ -23,21 +23,21 @@ Options:
   --tags <tags>           Filter by tags (comma-separated)
   --type <type>           Filter by type (skill, kit)
   --exact                 Use keyword-only matching instead of smart search
-  --limit <n>             Max results (default: 10, max: 50)
+  --limit <n>             Max results (required, 1-50)
   --min-quality <n>       Minimum quality score 0-100
   --json                  Output as JSON
 
 Aliases: s
 
 Examples:
-  happyskills search deploy
-  happyskills search "REST API with Node.js"
-  happyskills search --mine
-  happyskills search deploy --workspace acme
-  happyskills search --type kit
-  happyskills s --personal --json
+  happyskills search deploy --limit 10
+  happyskills search "REST API with Node.js" --limit 10
+  happyskills search --mine --limit 20
+  happyskills search deploy --workspace acme --limit 50
+  happyskills search --type kit --limit 10
+  happyskills s --personal --json --limit 20
   happyskills search "deploy to AWS" --limit 5
-  happyskills search deploy --exact`
+  happyskills search deploy --exact --limit 10`
 
 const QUALITY_TIERS = [
 	{ min: 80, label: 'High quality', color: cyan },
@@ -95,7 +95,7 @@ const format_smart_result = (item, index) => {
 }
 
 const run_smart_search = (args, query, options) => catch_errors('Smart search failed', async () => {
-	const limit = args.flags.limit ? parseInt(args.flags.limit) : 10
+	const limit = parseInt(args.flags.limit)
 	const capped_limit = Math.min(Math.max(limit, 1), 50)
 	const min_quality = args.flags['min-quality'] != null ? parseInt(args.flags['min-quality']) : null
 
@@ -230,6 +230,10 @@ const run = (args) => catch_errors('Search failed', async () => {
 		throw new UsageError('Please provide a search query or use --mine, --personal, or --workspace.')
 	}
 
+	if (!args.flags.limit) {
+		throw new UsageError('--limit is required. Specify the number of results you want (e.g. --limit 10).')
+	}
+
 	if (type && !VALID_SKILL_TYPES.includes(type)) {
 		throw new UsageError(`--type must be one of: ${VALID_SKILL_TYPES.join(', ')}`)
 	}

package/src/integration/cli.test.js

@@ -276,8 +276,9 @@ describe('CLI — --json: stdout is always valid JSON', () => {
 	})
 
 	it('network error produces JSON with code NETWORK_ERROR', () => {
-		// search requires a network call; localhost:0 always fails
-		const { stdout, code } = run(['search', 'anything', '--json'])
+		// search requires a network call; localhost:0 always fails.
+		// --limit is required, so it must be passed to reach the network call.
+		const { stdout, code } = run(['search', 'anything', '--json', '--limit', '10'])
 		assert.strictEqual(code, 4)
 		const out = parse_json_output(stdout, 'search --json network failure')
 		assert.strictEqual(out.error.code, 'NETWORK_ERROR')

package/src/utils/text_diff.js

@@ -0,0 +1,247 @@
+/**
+ * Lightweight unified diff — no external dependencies.
+ *
+ * Uses the Myers diff algorithm for line-level comparison, then formats
+ * the result as a standard unified diff with configurable context lines.
+ *
+ * Designed for memory efficiency:
+ * - No intermediate copies of full file content
+ * - Hunks are built incrementally
+ * - Input strings are split once, not retained
+ */
+
+// ─── Myers diff ──────────────────────────────────────────────────────────────
+
+/**
+ * Compute the shortest edit script between two line arrays using Myers' O(ND) algorithm.
+ * Returns an array of { type: 'equal'|'delete'|'insert', old_idx?, new_idx? } operations.
+ *
+ * For files with small edit distance D, this runs in O((M+N)*D) time and O(D²) space
+ * for the trace. Skill files are typically < 1000 lines with small diffs, so this is
+ * well within acceptable bounds.
+ */
+const myers_edit_script = (old_lines, new_lines) => {
+	const N = old_lines.length
+	const M = new_lines.length
+
+	if (N === 0 && M === 0) return []
+	if (N === 0) return new_lines.map((_, j) => ({ type: 'insert', new_idx: j }))
+	if (M === 0) return old_lines.map((_, i) => ({ type: 'delete', old_idx: i }))
+
+	const MAX = N + M
+	const V = new Map([[1, 0]])
+	const trace = []
+
+	for (let d = 0; d <= MAX; d++) {
+		// Snapshot V for backtracking
+		trace.push(new Map(V))
+
+		for (let k = -d; k <= d; k += 2) {
+			let x
+			if (k === -d || (k !== d && (V.get(k - 1) ?? -1) < (V.get(k + 1) ?? -1))) {
+				x = V.get(k + 1) ?? 0 // move down (insert)
+			} else {
+				x = (V.get(k - 1) ?? 0) + 1 // move right (delete)
+			}
+			let y = x - k
+
+			// Follow diagonal (equal lines)
+			while (x < N && y < M && old_lines[x] === new_lines[y]) {
+				x++
+				y++
+			}
+
+			V.set(k, x)
+
+			if (x >= N && y >= M) {
+				return backtrack(trace, old_lines, new_lines, d)
+			}
+		}
+	}
+
+	// Should never reach here
+	return []
+}
+
+/**
+ * Backtrack through the trace to reconstruct the edit script.
+ */
+const backtrack = (trace, old_lines, new_lines, d) => {
+	const ops = []
+	let x = old_lines.length
+	let y = new_lines.length
+
+	for (let step = d; step > 0; step--) {
+		// trace[step] = V snapshot taken at the START of iteration d=step,
+		// which is V AFTER d=step-1 completed — i.e., the previous step's result
+		const v_prev = trace[step]
+		const k = x - y
+
+		let prev_k
+		if (k === -step || (k !== step && (v_prev.get(k - 1) ?? -1) < (v_prev.get(k + 1) ?? -1))) {
+			prev_k = k + 1 // came from above (insert)
+		} else {
+			prev_k = k - 1 // came from left (delete)
+		}
+
+		const prev_x = v_prev.get(prev_k) ?? 0
+		const prev_y = prev_x - prev_k
+
+		// Diagonal moves (equal lines) — collect in reverse
+		while (x > prev_x + (prev_k < k ? 1 : 0) && y > prev_y + (prev_k > k ? 1 : 0)) {
+			x--
+			y--
+			ops.push({ type: 'equal', old_idx: x, new_idx: y })
+		}
+
+		// The actual edit
+		if (prev_k < k) {
+			// Moved right → delete
+			x--
+			ops.push({ type: 'delete', old_idx: x })
+		} else {
+			// Moved down → insert
+			y--
+			ops.push({ type: 'insert', new_idx: y })
+		}
+	}
+
+	// Remaining diagonal at the start
+	while (x > 0 && y > 0) {
+		x--
+		y--
+		ops.push({ type: 'equal', old_idx: x, new_idx: y })
+	}
+
+	ops.reverse()
+	return ops
+}
+
+// ─── Hunk building ───────────────────────────────────────────────────────────
+
+/**
+ * Group edit operations into unified diff hunks with context lines.
+ */
+const build_hunks = (ops, old_lines, new_lines, context) => {
+	// Find ranges of changes (non-equal ops)
+	const change_indices = []
+	for (let i = 0; i < ops.length; i++) {
+		if (ops[i].type !== 'equal') change_indices.push(i)
+	}
+
+	if (change_indices.length === 0) return []
+
+	// Group changes that are within (2 * context) lines of each other
+	const groups = []
+	let group_start = change_indices[0]
+	let group_end = change_indices[0]
+
+	for (let i = 1; i < change_indices.length; i++) {
+		const gap = change_indices[i] - change_indices[i - 1]
+		if (gap <= context * 2 + 1) {
+			group_end = change_indices[i]
+		} else {
+			groups.push([group_start, group_end])
+			group_start = change_indices[i]
+			group_end = change_indices[i]
+		}
+	}
+	groups.push([group_start, group_end])
+
+	// Build hunks from groups
+	const hunks = []
+	for (const [start, end] of groups) {
+		const hunk_start = Math.max(0, start - context)
+		const hunk_end = Math.min(ops.length - 1, end + context)
+
+		let old_start = null
+		let new_start = null
+		let old_count = 0
+		let new_count = 0
+		const lines = []
+
+		for (let i = hunk_start; i <= hunk_end; i++) {
+			const op = ops[i]
+			if (op.type === 'equal') {
+				if (old_start === null) old_start = op.old_idx
+				if (new_start === null) new_start = op.new_idx
+				lines.push(` ${old_lines[op.old_idx]}`)
+				old_count++
+				new_count++
+			} else if (op.type === 'delete') {
+				if (old_start === null) old_start = op.old_idx
+				if (new_start === null) {
+					// Find the new_idx from the nearest equal op before this
+					new_start = find_new_start(ops, i)
+				}
+				lines.push(`-${old_lines[op.old_idx]}`)
+				old_count++
+			} else if (op.type === 'insert') {
+				if (new_start === null) new_start = op.new_idx
+				if (old_start === null) {
+					old_start = find_old_start(ops, i)
+				}
+				lines.push(`+${new_lines[op.new_idx]}`)
+				new_count++
+			}
+		}
+
+		hunks.push({
+			old_start: (old_start ?? 0) + 1, // 1-based
+			old_count,
+			new_start: (new_start ?? 0) + 1, // 1-based
+			new_count,
+			lines
+		})
+	}
+
+	return hunks
+}
+
+const find_new_start = (ops, from) => {
+	for (let i = from - 1; i >= 0; i--) {
+		if (ops[i].new_idx !== undefined) return ops[i].new_idx + 1
+	}
+	return 0
+}
+
+const find_old_start = (ops, from) => {
+	for (let i = from - 1; i >= 0; i--) {
+		if (ops[i].old_idx !== undefined) return ops[i].old_idx + 1
+	}
+	return 0
+}
+
+// ─── Public API ──────────────────────────────────────────────────────────────
+
+/**
+ * Compute a unified diff between two text strings.
+ *
+ * @param {string} old_text - Original text
+ * @param {string} new_text - Modified text
+ * @param {string} old_label - Label for original (e.g., "base/SKILL.md")
+ * @param {string} new_label - Label for modified (e.g., "local/SKILL.md")
+ * @param {number} [context=3] - Number of context lines around each change
+ * @returns {string} Unified diff string, empty if no differences
+ */
+const unified_diff = (old_text, new_text, old_label, new_label, context = 3) => {
+	if (old_text === new_text) return ''
+
+	const old_lines = old_text.split('\n')
+	const new_lines = new_text.split('\n')
+
+	const ops = myers_edit_script(old_lines, new_lines)
+	const hunks = build_hunks(ops, old_lines, new_lines, context)
+
+	if (hunks.length === 0) return ''
+
+	const header = `--- ${old_label}\n+++ ${new_label}`
+	const hunk_strings = hunks.map(h => {
+		const range = `@@ -${h.old_start},${h.old_count} +${h.new_start},${h.new_count} @@`
+		return `${range}\n${h.lines.join('\n')}`
+	})
+
+	return `${header}\n${hunk_strings.join('\n')}`
+}
+
+module.exports = { unified_diff }