happyskills 0.47.1 → 0.49.0

package/src/commands/postlex.test.js

@@ -16,6 +16,9 @@ const {
 	determine_next_step,
 	build_retry_envelope,
 	parse_input,
+	resolve_row_name,
+	normalize_data_rows,
+	extract_data_array_from_search_output,
 } = require('./postlex')
 
 // ─── Test fixtures ────────────────────────────────────────────────────────
@@ -283,6 +286,144 @@ describe('parse_input', () => {
 
 // ─── build_final_ordering ─────────────────────────────────────────────────
 
+// ─── resolve_row_name + normalize_data_rows (v0.48.0) ─────────────────────
+
+describe('resolve_row_name', () => {
+	it('returns row.name when present', () => {
+		assert.equal(resolve_row_name({ name: 'foo', skill: 'acme/foo' }), 'foo')
+	})
+
+	it('falls back to last segment of skill when name is missing', () => {
+		assert.equal(resolve_row_name({ skill: 'acme/deploy-aws' }), 'deploy-aws')
+	})
+
+	it('returns null when neither name nor skill is present', () => {
+		assert.equal(resolve_row_name({ description: 'whatever' }), null)
+		assert.equal(resolve_row_name({}), null)
+		assert.equal(resolve_row_name(null), null)
+	})
+
+	it('returns null when skill is malformed (no slash, just a bare value, returns the value itself)', () => {
+		// "deploy-aws" with no slash is a one-segment slug — last segment IS deploy-aws.
+		assert.equal(resolve_row_name({ skill: 'deploy-aws' }), 'deploy-aws')
+	})
+
+	it('handles empty-string name by falling back to skill', () => {
+		assert.equal(resolve_row_name({ name: '', skill: 'acme/foo' }), 'foo')
+	})
+})
+
+describe('normalize_data_rows', () => {
+	it('adds name to rows that only have skill', () => {
+		const data = [{ skill: 'acme/deploy-aws', workspace_slug: 'acme' }]
+		normalize_data_rows(data)
+		assert.equal(data[0].name, 'deploy-aws')
+	})
+
+	it('leaves rows with existing name untouched', () => {
+		const data = [{ name: 'pre-existing', skill: 'acme/different' }]
+		normalize_data_rows(data)
+		assert.equal(data[0].name, 'pre-existing')
+	})
+
+	it('is idempotent', () => {
+		const data = [{ skill: 'acme/deploy-aws' }]
+		normalize_data_rows(data)
+		normalize_data_rows(data)
+		assert.equal(data[0].name, 'deploy-aws')
+	})
+
+	it('handles non-array input without crashing', () => {
+		normalize_data_rows(null)
+		normalize_data_rows('not an array')
+		normalize_data_rows({})
+		// no assertion — just confirming no throw
+	})
+})
+
+// ─── extract_data_array_from_search_output (v0.48.0) ──────────────────────
+
+describe('extract_data_array_from_search_output', () => {
+	it('extracts data.results from the canonical envelope shape', () => {
+		const env = { data: { query: 'q', mode: 'semantic', results: [{ name: 'foo' }] }, error: null, next_step: null }
+		const r = extract_data_array_from_search_output(env)
+		assert.equal(r.length, 1)
+		assert.equal(r[0].name, 'foo')
+	})
+
+	it('handles legacy {data: [...]} (data is bare array)', () => {
+		const env = { data: [{ name: 'foo' }] }
+		assert.deepEqual(extract_data_array_from_search_output(env), [{ name: 'foo' }])
+	})
+
+	it('handles bare array', () => {
+		const env = [{ name: 'foo' }]
+		assert.deepEqual(extract_data_array_from_search_output(env), env)
+	})
+
+	it('handles double-wrapped {data: {data: [...]}} (defensive)', () => {
+		const env = { data: { data: [{ name: 'foo' }] } }
+		assert.deepEqual(extract_data_array_from_search_output(env), [{ name: 'foo' }])
+	})
+
+	it('returns null when no data array can be found', () => {
+		assert.equal(extract_data_array_from_search_output({}), null)
+		assert.equal(extract_data_array_from_search_output({ data: null }), null)
+		assert.equal(extract_data_array_from_search_output('string'), null)
+		assert.equal(extract_data_array_from_search_output(null), null)
+	})
+})
+
+// ─── parse_input with --search-output path (v0.48.0) ──────────────────────
+
+describe('parse_input with --search-output', () => {
+	it('extracts data.results from a full search envelope passed as the third argument', () => {
+		const ranking = JSON.stringify({ ranking: [{ rank: 1, candidate_id: 1, rationale: 'top' }] })
+		const search_out = JSON.stringify({
+			data: { query: 'q', mode: 'semantic', results: [{ name: 'deploy-aws', workspace_slug: 'acme' }] },
+			error: null,
+			next_step: null,
+		})
+		const r = parse_input(ranking, null, search_out)
+		assert.equal(r.parse_error, null)
+		assert.equal(r.ranking[0].candidate_id, 1)
+		assert.equal(r.data[0].name, 'deploy-aws')
+	})
+
+	it('search-output overrides inline data when both are provided', () => {
+		const combined = JSON.stringify({
+			ranking: [{ rank: 1, candidate_id: 1, rationale: 'x' }],
+			data: [{ name: 'stale-inline-name' }],
+		})
+		const search_out = JSON.stringify({ data: { results: [{ name: 'fresh-from-search-output' }] } })
+		const r = parse_input(combined, null, search_out)
+		assert.equal(r.parse_error, null)
+		assert.equal(r.data[0].name, 'fresh-from-search-output')
+	})
+
+	it('normalizes rows that only have skill (no name) when sourced from search-output', () => {
+		const ranking = JSON.stringify({ ranking: [{ rank: 1, candidate_id: 1, rationale: 'x' }] })
+		// to_smart_json before v0.48.0 emitted `skill` without `name`. Simulate that.
+		const search_out = JSON.stringify({ data: { results: [{ skill: 'acme/legacy-row', workspace_slug: 'acme' }] } })
+		const r = parse_input(ranking, null, search_out)
+		assert.equal(r.parse_error, null)
+		assert.equal(r.data[0].name, 'legacy-row')
+	})
+
+	it('errors when search-output does not contain a data array', () => {
+		const ranking = JSON.stringify({ ranking: [{ rank: 1, candidate_id: 1, rationale: 'x' }] })
+		const search_out = JSON.stringify({ data: { query: 'q' } })
+		const r = parse_input(ranking, null, search_out)
+		assert.match(r.parse_error, /does not contain a data\.results array/)
+	})
+
+	it('errors with an actionable message when data is missing from all sources', () => {
+		const ranking = JSON.stringify({ ranking: [{ rank: 1, candidate_id: 1, rationale: 'x' }] })
+		const r = parse_input(ranking, null, null)
+		assert.match(r.parse_error, /--search-output/)
+	})
+})
+
 describe('build_final_ordering', () => {
 	it('joins ranking with data rows, producing slug + rationale', () => {
 		const data = make_data(['deploy-aws', 'serverless'])

package/src/commands/publish.js

@@ -260,45 +260,52 @@ const run = (args) => catch_errors('Publish failed', async () => {
 
 	spinner.succeed(`Published ${workspace.slug}/${manifest.name}@${manifest.version}`)
 
-	// Update lock file: set base_commit and base_integrity to new values
+	// Update lock file: set base_commit and base_integrity to new values.
+	// When no lock file exists yet (first publish in a fresh project), we
+	// still create one — otherwise downstream `list`/`status`/`check` would
+	// treat the just-published skill as external. This was a latent bug
+	// pre-260523-02; the spec's lock-as-registry-view principle (§ 4.5) makes
+	// it especially important to keep the lock authoritative.
 	const full_name = full_name_pre
 	let post_publish_entry = 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))
-		const [hash_err, integrity] = await hash_directory(dir)
-		if (lock_key && all_skills[lock_key]) {
-			const updated_entry = {
-				...all_skills[lock_key],
-				version: manifest.version,
-				ref: push_data?.ref || `refs/tags/v${manifest.version}`,
-				commit: push_data?.commit || null,
-				base_commit: push_data?.commit || null,
-				base_integrity: (!hash_err && integrity) ? integrity : null,
-				dependencies: manifest.dependencies || {}
-			}
-			if (!hash_err && integrity) updated_entry.integrity = integrity
-			delete updated_entry.merge_parents
-			delete updated_entry.conflict_files
-			const updated_skills = update_lock_skills(lock_data, { [lock_key]: updated_entry })
-			await write_lock(project_root, updated_skills)
-			post_publish_entry = updated_entry
-		} else {
-			const new_entry = {
-				version: manifest.version,
-				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 || {}
-			}
-			const updated_skills = update_lock_skills(lock_data, { [full_name]: new_entry })
-			await write_lock(project_root, updated_skills)
-			post_publish_entry = new_entry
+	const [hash_err, integrity] = await hash_directory(dir)
+
+	const new_entry = {
+		version: manifest.version,
+		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 || {}
+	}
+
+	const lock_data_to_use = (!lock_err && lock_data) ? lock_data : { lockVersion: 2, generatedAt: new Date().toISOString(), skills: {} }
+	const all_skills = get_all_locked_skills(lock_data_to_use)
+	const suffix = `/${skill_name}`
+	const existing_lock_key = Object.keys(all_skills).find(k => k.endsWith(suffix))
+
+	if (existing_lock_key && all_skills[existing_lock_key]) {
+		const updated_entry = {
+			...all_skills[existing_lock_key],
+			version: manifest.version,
+			ref: push_data?.ref || `refs/tags/v${manifest.version}`,
+			commit: push_data?.commit || null,
+			base_commit: push_data?.commit || null,
+			base_integrity: (!hash_err && integrity) ? integrity : null,
+			dependencies: manifest.dependencies || {}
 		}
+		if (!hash_err && integrity) updated_entry.integrity = integrity
+		delete updated_entry.merge_parents
+		delete updated_entry.conflict_files
+		const updated_skills = update_lock_skills(lock_data_to_use, { [existing_lock_key]: updated_entry })
+		await write_lock(project_root, updated_skills)
+		post_publish_entry = updated_entry
+	} else {
+		const updated_skills = update_lock_skills(lock_data_to_use, { [full_name]: new_entry })
+		await write_lock(project_root, updated_skills)
+		post_publish_entry = new_entry
 	}
 
 	// Post-write verification — confirm the lock entry now agrees with the

package/src/commands/pull.js

@@ -33,6 +33,7 @@ Options:
   --theirs [files]  Take remote version on conflicts (all, or comma-separated file list)
   --ours [files]    Keep local version on conflicts (all, or comma-separated file list)
   --force           Discard all local changes, take remote entirely
+  --rebase          Rebase local edits onto the remote head (snapshot-backed, structured rejection envelope on failure)
   -g, --global      Pull globally installed skill
   --strict          Fail on incompatible dependency ranges instead of warning
   --json            Output as JSON
@@ -40,6 +41,7 @@ Options:
 
 Examples:
   happyskills pull acme/deploy-aws
+  happyskills pull acme/deploy-aws --rebase --json
   happyskills pull acme/deploy-aws --theirs
   happyskills pull acme/deploy-aws --theirs SKILL.md,skill.json --ours references/foo.md
   happyskills pull acme/deploy-aws --json --full-report`
@@ -111,6 +113,44 @@ const run = (args) => catch_errors('Pull failed', async () => {
 	const is_global = args.flags.global || false
 	const full_report = !!(args.flags.json && args.flags['full-report'])
 
+	// § 8.3 — rebase-style pull. Delegates to merge/rebase.js for the snapshot-
+	// first capture/fast-forward/reapply flow with structured rejection envelopes.
+	if (args.flags.rebase) {
+		const { rebase_pull } = require('../merge/rebase')
+		const [err, result] = await rebase_pull(skill_name, { project_root: find_project_root(), is_global })
+		if (err) throw err
+		if (args.flags.json) {
+			print_json({
+				data: result.data || null,
+				next_step: result.next_step || null,
+				error: result.error || null
+			})
+			if (result.next_step) process.exit(EXIT_CODES.ERROR)
+			return
+		}
+		if (result.error) {
+			print_warn(result.error.message || 'Pull --rebase failed')
+			if (result.next_step) print_hint(`Next: ${result.next_step.action}`)
+			process.exit(EXIT_CODES.ERROR)
+			return
+		}
+		if (result.next_step?.action === 'resolve_patch_rejections') {
+			print_warn(`Pull --rebase: ${result.data.patches_rejected.length} patch(es) need resolution.`)
+			for (const r of result.data.patches_rejected) {
+				print_info(`  - ${r.file}: ${r.reason}`)
+			}
+			print_hint(`Restore the pre-rebase state with ${code(`happyskills snapshot restore ${result.data.snapshot_id}`)} if needed.`)
+			process.exit(EXIT_CODES.ERROR)
+			return
+		}
+		if (result.data?.status === 'up_to_date') {
+			print_info(`${skill_name} is already up to date.`)
+			return
+		}
+		print_success(`Rebased ${skill_name} → ${result.data.version || 'latest'}`)
+		return
+	}
+
 	// Parse per-file strategies: --theirs SKILL.md,skill.json --ours references/foo.md
 	const theirs_files = typeof args.flags.theirs === 'string'
 		? new Set(args.flags.theirs.split(',').map(s => s.trim()))

package/src/commands/reconcile.js

@@ -0,0 +1,229 @@
+const path = require('path')
+const fs = require('fs')
+const { error: { catch_errors, wrap_errors: e } } = require('puffy-core')
+const { read_lock, get_all_locked_skills } = require('../lock/reader')
+const { write_lock, update_lock_skills } = require('../lock/writer')
+const { verify_lock_disk_consistency, detect_ahead_state } = require('../lock/verify')
+const { write_manifest } = require('../manifest/writer')
+const { read_manifest } = require('../manifest/reader')
+const { find_project_root, skills_dir, skill_install_dir, lock_root } = require('../config/paths')
+const { print_help, print_info, print_json, print_warn, print_success, print_hint, code } = require('../ui/output')
+const { exit_with_error, UsageError } = require('../utils/errors')
+const { EXIT_CODES } = require('../constants')
+
+const HELP_TEXT = `Usage: happyskills reconcile <owner/skill> [--apply <action>] [options]
+
+Diagnose drift and apply a deterministic repair, or emit structured options
+for the operator to choose from. Reserved for GENUINE drift only —
+regression, missing files, or unparseable skill.json. The "ahead" state
+(disk version > lock version) is NOT drift; reconcile reports it as a
+non-event and points back to publish.
+
+Arguments:
+  owner/skill                    Skill to inspect
+
+Options:
+  --apply <action>               Execute one of the recommended options directly
+                                 (skips the next_step round-trip).
+  -g, --global                   Operate on globally-installed skills
+  --json                         Output as JSON
+
+Examples:
+  happyskills reconcile acme/deploy-aws --json
+  happyskills reconcile acme/deploy-aws --apply restore_from_lock_version --json`
+
+const SUBTYPE_OPTIONS = {
+	regression: ['restore_from_lock_version', 'accept_disk_as_explicit_downgrade', 'investigate_with_diff'],
+	missing_skill_json: ['restore_from_registry_at_lock_version', 'restore_from_git', 'abandon'],
+	missing_dir: ['reinstall_at_lock_version', 'abandon']
+}
+
+const ACTION_NEXT_STEPS = {
+	regression: 'resolve_regression',
+	missing_skill_json: 'resolve_missing_skill_json',
+	missing_dir: 'resolve_missing_dir'
+}
+
+const resolve_lock_entry = (raw, project_root, is_global) => catch_errors('Failed to resolve lock entry', async () => {
+	const [, lock_data] = await read_lock(lock_root(is_global, project_root))
+	if (!lock_data) return { full: null, lock_entry: null, lock_data: null }
+	const all = get_all_locked_skills(lock_data)
+	let full = raw
+	let lock_entry = all[full] || null
+	if (!lock_entry && !raw.includes('/')) {
+		const suffix = `/${raw}`
+		full = Object.keys(all).find(k => k.endsWith(suffix)) || raw
+		lock_entry = all[full] || null
+	}
+	return { full, lock_entry, lock_data }
+})
+
+const apply_restore_from_lock_version = ({ skill_dir, lock_entry }) => catch_errors('Failed to restore from lock', async () => {
+	const [read_err, manifest] = await read_manifest(skill_dir)
+	if (read_err) throw e('Failed to read skill.json', read_err)
+	manifest.version = lock_entry.version
+	const [write_err] = await write_manifest(skill_dir, manifest)
+	if (write_err) throw e('Failed to write skill.json', write_err)
+	return { applied: 'restore_from_lock_version', new_disk_version: lock_entry.version }
+})
+
+const reconcile_one = (full, lock_entry, skill_dir, options) => catch_errors('Failed to reconcile', async () => {
+	if (!lock_entry) {
+		return {
+			data: { skill: full, no_drift: true, status: 'not_found' },
+			next_step: { action: 'install_first', context: { skill: full, hint: `Skill is not in the lock file. Install it first.` } }
+		}
+	}
+
+	const [verify_err, verify] = await verify_lock_disk_consistency(lock_entry, skill_dir)
+	if (verify_err) throw verify_err[0] || verify_err
+
+	if (verify.ok) {
+		// No genuine drift. Could be clean, modified, or ahead. Reconcile only
+		// reports — it doesn't touch any of these.
+		const [, ahead] = await detect_ahead_state(lock_entry, skill_dir)
+		if (ahead && ahead.ahead) {
+			return {
+				data: {
+					skill: full,
+					no_drift: true,
+					status: 'ahead',
+					ahead: {
+						lock_version: ahead.lock_version,
+						disk_version: ahead.disk_version,
+						has_changelog_entry: ahead.has_changelog_entry || false,
+						changelog_version: ahead.changelog_version || null
+					}
+				},
+				next_step: null,
+				hint: `ahead is a valid precondition for publish, not drift — use \`release\` or \`publish\` to advance the lock, or \`pull\` if the registry has advanced past lock_version`
+			}
+		}
+		return {
+			data: { skill: full, no_drift: true, status: 'clean' },
+			next_step: null
+		}
+	}
+
+	// Genuine drift — handle by subtype.
+	const drift = { reason: verify.reason, lock_version: verify.expected, disk_version: verify.actual }
+	const apply = options.apply || null
+
+	if (verify.reason === 'regression') {
+		if (apply === 'restore_from_lock_version') {
+			const [apply_err, applied] = await apply_restore_from_lock_version({ skill_dir, lock_entry })
+			if (apply_err) throw e('Apply failed', apply_err)
+			return {
+				data: { skill: full, drift_state: 'regression', applied, lock_version: lock_entry.version, disk_version: applied.new_disk_version },
+				next_step: null
+			}
+		}
+		return {
+			data: { skill: full, drift_state: 'regression', lock_version: lock_entry.version, disk_version: drift.disk_version },
+			next_step: {
+				action: 'resolve_regression',
+				context: {
+					skill: full,
+					drift,
+					options: SUBTYPE_OPTIONS.regression,
+					hint: 'Choose: restore_from_lock_version (Edit skill.json back to lock), accept_disk_as_explicit_downgrade (publish disk version as a downgrade), or investigate_with_diff (run happyskills diff first).'
+				}
+			}
+		}
+	}
+
+	if (verify.reason === 'missing_skill_json') {
+		return {
+			data: { skill: full, drift_state: 'missing_skill_json', lock_version: lock_entry.version },
+			next_step: {
+				action: 'resolve_missing_skill_json',
+				context: {
+					skill: full,
+					drift,
+					options: SUBTYPE_OPTIONS.missing_skill_json,
+					hint: 'Choose: restore_from_git (if tracked), restore_from_registry_at_lock_version (verify lock_version is published first), or abandon.'
+				}
+			}
+		}
+	}
+
+	if (verify.reason === 'missing_dir') {
+		return {
+			data: { skill: full, drift_state: 'missing_dir', lock_version: lock_entry.version },
+			next_step: {
+				action: 'resolve_missing_dir',
+				context: {
+					skill: full,
+					drift,
+					options: SUBTYPE_OPTIONS.missing_dir,
+					hint: 'Choose: reinstall_at_lock_version (no --fresh needed; the directory is missing), or abandon (uninstall to clear the stale lock entry).'
+				}
+			}
+		}
+	}
+
+	return {
+		data: { skill: full, drift_state: verify.reason || 'unknown', drift },
+		next_step: {
+			action: 'resolve_unknown_drift',
+			context: { skill: full, drift, hint: 'Unrecognized drift subtype. Surface to the user for manual decision.' }
+		}
+	}
+})
+
+const run = (args) => catch_errors('Reconcile failed', async () => {
+	if (args.flags._show_help) {
+		print_help(HELP_TEXT)
+		return process.exit(EXIT_CODES.SUCCESS)
+	}
+
+	const raw = args._[0]
+	if (!raw) throw new UsageError('Usage: happyskills reconcile <owner/skill> [--apply <action>]')
+
+	const project_root = find_project_root()
+	const is_global = !!args.flags.global
+	const base_dir = skills_dir(is_global, project_root)
+	const apply = typeof args.flags.apply === 'string' ? args.flags.apply : null
+
+	const [resolve_err, resolved] = await resolve_lock_entry(raw, project_root, is_global)
+	if (resolve_err) throw e('Failed to resolve skill', resolve_err)
+
+	const full = resolved.full
+	const lock_entry = resolved.lock_entry
+	const short = full && full.includes('/') ? full.split('/')[1] : (raw.includes('/') ? raw.split('/')[1] : raw)
+	const skill_dir = skill_install_dir(base_dir, short)
+
+	const [recon_err, result] = await reconcile_one(full, lock_entry, skill_dir, { apply })
+	if (recon_err) throw e('Reconcile failed', recon_err)
+
+	if (args.flags.json) {
+		const envelope = { data: result.data }
+		if (result.next_step !== undefined) envelope.next_step = result.next_step
+		if (result.hint !== undefined) envelope.hint = result.hint
+		print_json(envelope)
+		return
+	}
+
+	// Human output — terse, lead with plain meaning.
+	if (result.data?.no_drift) {
+		if (result.data.status === 'ahead') {
+			print_info(`${full} is ahead (lock ${result.data.ahead.lock_version}, disk ${result.data.ahead.disk_version}).`)
+			print_hint(`Publish with ${code(`happyskills publish ${full}`)}.`)
+			return
+		}
+		print_success(`${full} is ${result.data.status} — nothing to reconcile.`)
+		return
+	}
+	if (result.data?.applied) {
+		print_success(`Applied ${result.data.applied.applied} — skill.json now at ${result.data.applied.new_disk_version}.`)
+		return
+	}
+	if (result.next_step) {
+		print_warn(`${full} has drift (${result.data.drift_state || 'unknown'}).`)
+		const opts = result.next_step.context?.options || []
+		for (const o of opts) print_info(`  - ${o}`)
+		print_hint(`Pick one and re-run: ${code(`happyskills reconcile ${full} --apply <option>`)}`)
+	}
+}).then(([errors]) => { if (errors) { exit_with_error(errors); return } })
+
+module.exports = { run, reconcile_one, SUBTYPE_OPTIONS, ACTION_NEXT_STEPS }