happyskills 0.48.0 → 0.49.0

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 }

package/src/commands/release.js

@@ -0,0 +1,451 @@
+const path = require('path')
+const fs = require('fs')
+const { error: { catch_errors, wrap_errors: e } } = require('puffy-core')
+const { read_manifest } = require('../manifest/reader')
+const { write_manifest } = require('../manifest/writer')
+const { read_file } = require('../utils/fs')
+const { inc, valid, gt } = require('../utils/semver')
+const { resolve_skill_dir } = require('../utils/resolve_skill')
+const { find_project_root, skills_dir, skill_install_dir, lock_root } = require('../config/paths')
+const { read_lock, get_all_locked_skills } = require('../lock/reader')
+const { verify_lock_disk_consistency, detect_ahead_state, parse_changelog_top_version } = require('../lock/verify')
+const { validate_skill_md } = require('../validation/skill_md_rules')
+const { validate_skill_json } = require('../validation/skill_json_rules')
+const { validate_cross } = require('../validation/cross_rules')
+const { validate_no_conflict_markers } = require('../validation/conflict_marker_rules')
+const { validate_file_sizes } = require('../validation/file_size_rules')
+const snapshot_storage = require('../snapshot/storage')
+const { print_help, print_json, print_success, print_info, print_warn, print_hint, code } = require('../ui/output')
+const { exit_with_error, UsageError, CliError } = require('../utils/errors')
+const { EXIT_CODES } = require('../constants')
+
+const HELP_TEXT = `Usage: happyskills release <skill-name> [options]
+
+Atomic release pipeline. Snapshots, validates, applies a bump (when needed),
+verifies the CHANGELOG, resolves the workspace, and publishes — all as a
+single deterministic command. On any failure, the snapshot is restored.
+
+Recognizes the ahead state directly: if skill.json is already ahead of the
+lock (\`bump\` or hand-edit already done), the disk version IS the version
+to publish — no revert, no re-bump.
+
+Options:
+  --bump <type|version>           patch | minor | major | explicit semver
+  --no-bump                       Refuse to bump; require disk to be already ahead
+  --changelog-from <auto|file>    Source for the new CHANGELOG entry (default: read from CHANGELOG.md)
+  --workspace <slug>              Target workspace
+  --public | --private            Visibility on first publish only
+  --dry-run                       Validate + check status, do not mutate
+  --json                          Output as JSON
+
+Examples:
+  happyskills release my-skill --workspace acme --json
+  happyskills release my-skill --bump patch --workspace acme --json
+  happyskills release my-skill --no-bump --json  # disk is already ahead`
+
+const envelope_error = (code_str, message, extra = {}) => ({ error: { code: code_str, message, ...extra } })
+
+const determine_target_version = async ({ manifest, lock_entry, skill_dir, bump_flag, no_bump }) => {
+	// § 4.5 + § 8.2 step 3 — handle ahead/clean/modified directly without
+	// reverting the disk version that's already been chosen.
+	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) {
+		return {
+			status: 'drift',
+			drift: { reason: verify.reason, lock_version: verify.expected, disk_version: verify.actual }
+		}
+	}
+
+	const [, ahead] = await detect_ahead_state(lock_entry, skill_dir)
+	if (ahead && ahead.ahead) {
+		// Disk already declares the next version.
+		const disk_version = manifest.version
+		if (bump_flag) {
+			// Sanity-check: if --bump would produce the same value the user
+			// already declared, that's fine; otherwise emit a disagreement
+			// next_step so the operator decides.
+			const computed = compute_bump(disk_version, bump_flag)
+			const lock_based = compute_bump(lock_entry?.version, bump_flag)
+			if (computed && computed === disk_version) return { status: 'ahead', target: disk_version }
+			if (lock_based && lock_based === disk_version) return { status: 'ahead', target: disk_version }
+			return {
+				status: 'bump_disagreement',
+				disk_version,
+				requested_bump: bump_flag,
+				lock_version: lock_entry?.version
+			}
+		}
+		return { status: 'ahead', target: disk_version }
+	}
+
+	// First-publish (no lock entry yet) → the disk version IS the version
+	// to publish. Treat as ahead-equivalent: no bump applied, disk wins.
+	// --bump can still override (with the same disagreement check).
+	if (!lock_entry || !lock_entry.version) {
+		if (bump_flag) {
+			const target = compute_bump(manifest.version, bump_flag)
+			if (!target) return { status: 'invalid_bump', bump: bump_flag }
+			if (target === manifest.version) return { status: 'ahead', target: manifest.version }
+			return { status: 'clean_with_bump', target, bump_flag }
+		}
+		return { status: 'ahead', target: manifest.version }
+	}
+
+	// Clean or modified — disk version equals lock version.
+	if (no_bump) {
+		return { status: 'missing_version' }
+	}
+	if (bump_flag) {
+		const target = compute_bump(manifest.version, bump_flag)
+		if (!target) return { status: 'invalid_bump', bump: bump_flag }
+		return { status: 'clean_with_bump', target, bump_flag }
+	}
+
+	// No --bump and no ahead. Try to infer from CHANGELOG top entry.
+	const changelog_path = path.join(skill_dir, 'CHANGELOG.md')
+	const [, cl_content] = await read_file(changelog_path)
+	const cl_version = parse_changelog_top_version(cl_content)
+	if (cl_version && gt(cl_version, manifest.version)) {
+		return { status: 'inferred_from_changelog', target: cl_version }
+	}
+	return { status: 'specify_bump' }
+}
+
+const compute_bump = (base_version, bump) => {
+	if (!base_version || !bump) return null
+	if (bump === 'patch' || bump === 'minor' || bump === 'major') {
+		return inc(base_version, bump) || null
+	}
+	if (valid(bump)) return bump
+	return null
+}
+
+const run_validation = (dir, skill_name) => catch_errors('Validation failed', async () => {
+	const [md_err, md_data] = await validate_skill_md(dir, path.basename(dir), null)
+	if (md_err) throw md_err
+	const [json_err, json_data] = await validate_skill_json(dir)
+	if (json_err) throw json_err
+	const [cross_err, cross_results] = await validate_cross(dir, md_data.frontmatter, json_data.manifest, md_data.content, json_data.manifest?.type)
+	if (cross_err) throw cross_err
+	const [marker_err, marker_results] = await validate_no_conflict_markers(dir)
+	if (marker_err) throw marker_err
+	const [size_err, size_results] = await validate_file_sizes(dir)
+	if (size_err) throw size_err
+	const all = [...md_data.results, ...json_data.results, ...cross_results, ...marker_results, ...size_results]
+	const errors = all.filter(r => r.severity === 'error').map(({ severity, ...rest }) => rest)
+	const warnings = all.filter(r => r.severity === 'warning').map(({ severity, ...rest }) => rest)
+	return { errors, warnings }
+})
+
+const orchestrate = (args) => catch_errors('Release failed', async () => {
+	const skill_name = args._[0]
+	if (!skill_name) throw new UsageError('Usage: happyskills release <skill-name> [options]')
+
+	const project_root = find_project_root()
+	const [dir_err, dir] = await resolve_skill_dir(skill_name)
+	if (dir_err) throw e(`Skill "${skill_name}" not found`, dir_err)
+
+	const [manifest_err, manifest] = await read_manifest(dir)
+	if (manifest_err) throw e('No skill.json found', manifest_err)
+
+	// Resolve lock entry (if any) for ahead detection + version inference.
+	const [, lock_data] = await read_lock(project_root)
+	const all_locked = lock_data ? get_all_locked_skills(lock_data) : {}
+	const lock_key = Object.keys(all_locked).find(k => k.endsWith(`/${skill_name}`)) || skill_name
+	const lock_entry = all_locked[lock_key] || null
+
+	const workspace_flag = typeof args.flags.workspace === 'string' ? args.flags.workspace : null
+	const resolved_workspace = workspace_flag || (lock_key.includes('/') ? lock_key.split('/')[0] : null)
+
+	const bump_flag = typeof args.flags.bump === 'string' ? args.flags.bump : null
+	const no_bump = !!args.flags['no-bump']
+	const changelog_from = typeof args.flags['changelog-from'] === 'string' ? args.flags['changelog-from'] : null
+	const dry_run = !!args.flags['dry-run']
+
+	// (Step 1) Snapshot.
+	let snapshot_id = null
+	let snapshot_workspace = resolved_workspace || 'local'
+	if (!dry_run) {
+		const [snap_err, snap] = await snapshot_storage.create({
+			skill_dir: dir,
+			workspace: snapshot_workspace,
+			skill: skill_name,
+			lock_entry,
+			note: `pre-release: ${skill_name}`,
+			project_root
+		})
+		if (snap_err) throw e('Failed to capture pre-release snapshot', snap_err)
+		snapshot_id = snap.snapshot_id
+	}
+
+	const restore_and = async (env) => {
+		if (snapshot_id) {
+			await snapshot_storage.restore(snapshot_id, { skill_dir: dir, project_root })
+		}
+		return env
+	}
+
+	// (Step 2) Validate.
+	const [val_err, validation] = await run_validation(dir, skill_name)
+	if (val_err) {
+		const restored = await restore_and({
+			...envelope_error('VALIDATION_FAILED', `Validation failed: ${val_err[val_err.length - 1]?.message}`),
+			next_step: { action: 'fix_validation_errors', context: { skill: skill_name } }
+		})
+		return { code: EXIT_CODES.ERROR, envelope: restored }
+	}
+	if (validation.errors.length > 0) {
+		const restored = await restore_and({
+			...envelope_error('VALIDATION_FAILED', `Skill failed validation with ${validation.errors.length} error(s).`, {
+				validation_errors: validation.errors
+			}),
+			next_step: { action: 'fix_validation_errors', context: { skill: skill_name } }
+		})
+		return { code: EXIT_CODES.ERROR, envelope: restored }
+	}
+
+	// (Step 3) Determine target version.
+	const target_info = await determine_target_version({ manifest, lock_entry, skill_dir: dir, bump_flag, no_bump })
+
+	if (target_info.status === 'drift') {
+		const restored = await restore_and({
+			...envelope_error('DRIFT_DETECTED', `Genuine drift detected (${target_info.drift.reason}). Reconcile first.`, {
+				drift: target_info.drift
+			}),
+			next_step: {
+				action: 'reconcile_first',
+				context: {
+					reconcile_command: `npx happyskills reconcile ${lock_key} --json`,
+					skill: lock_key
+				}
+			}
+		})
+		return { code: EXIT_CODES.ERROR, envelope: restored }
+	}
+	if (target_info.status === 'missing_version') {
+		const restored = await restore_and({
+			...envelope_error('MISSING_VERSION', '--no-bump was passed but disk is not ahead of lock; nothing to publish.'),
+			next_step: { action: 'specify_bump_type', context: { current_version: manifest.version } }
+		})
+		return { code: EXIT_CODES.USAGE, envelope: restored }
+	}
+	if (target_info.status === 'invalid_bump') {
+		const restored = await restore_and({
+			...envelope_error('INVALID_BUMP', `--bump "${target_info.bump}" is not patch/minor/major or a valid semver.`),
+			next_step: { action: 'specify_bump_type', context: { current_version: manifest.version } }
+		})
+		return { code: EXIT_CODES.USAGE, envelope: restored }
+	}
+	if (target_info.status === 'specify_bump') {
+		const restored = await restore_and({
+			...envelope_error('MISSING_VERSION', 'No --bump provided and no CHANGELOG entry indicates an intended next version.'),
+			next_step: {
+				action: 'specify_bump_type',
+				context: { current_version: manifest.version, options: ['patch', 'minor', 'major', 'explicit-version'] }
+			}
+		})
+		return { code: EXIT_CODES.USAGE, envelope: restored }
+	}
+	if (target_info.status === 'bump_disagreement') {
+		const restored = await restore_and({
+			...envelope_error('BUMP_DISAGREEMENT', `--bump ${target_info.requested_bump} disagrees with the disk version ${target_info.disk_version}.`),
+			next_step: {
+				action: 'resolve_bump_disagreement',
+				context: {
+					disk_version: target_info.disk_version,
+					requested_bump: target_info.requested_bump,
+					lock_version: target_info.lock_version
+				}
+			}
+		})
+		return { code: EXIT_CODES.USAGE, envelope: restored }
+	}
+
+	// Determine the version to publish.
+	const target_version = target_info.target
+
+	// Apply the bump to skill.json if we computed one. For the ahead path,
+	// skill.json is already correct.
+	if (target_info.status === 'clean_with_bump' || target_info.status === 'inferred_from_changelog') {
+		if (!dry_run) {
+			manifest.version = target_version
+			const [w_err] = await write_manifest(dir, manifest)
+			if (w_err) {
+				const restored = await restore_and({
+					...envelope_error('WRITE_FAILED', 'Failed to write bumped skill.json'),
+					next_step: { action: 'retry' }
+				})
+				return { code: EXIT_CODES.ERROR, envelope: restored }
+			}
+		}
+	}
+
+	// (Step 4) Changelog handling.
+	const changelog_path = path.join(dir, 'CHANGELOG.md')
+	const [, cl_content_raw] = await read_file(changelog_path)
+	const cl_top = parse_changelog_top_version(cl_content_raw)
+	const changelog_ok = cl_top === target_version
+	let changelog_warning = null
+	if (!changelog_ok) {
+		if (changelog_from === 'auto') {
+			changelog_warning = `auto-draft mode was requested but is not implemented in this build — operator must edit CHANGELOG.md manually.`
+		} else if (changelog_from) {
+			// Read from file and prepend.
+			const [cf_err, cf_content] = await read_file(changelog_from)
+			if (cf_err || !cf_content) {
+				const restored = await restore_and({
+					...envelope_error('CHANGELOG_SOURCE_UNREADABLE', `Could not read --changelog-from "${changelog_from}".`),
+					next_step: { action: 'provide_changelog' }
+				})
+				return { code: EXIT_CODES.USAGE, envelope: restored }
+			}
+			if (!dry_run) {
+				const new_content = `${cf_content.trim()}\n\n${(cl_content_raw || '').trim()}\n`
+				await fs.promises.writeFile(changelog_path, new_content, 'utf-8')
+			}
+		} else {
+			const restored = await restore_and({
+				...envelope_error('MISSING_CHANGELOG_ENTRY', `CHANGELOG.md does not contain a ## [${target_version}] entry.`),
+				next_step: {
+					action: 'provide_changelog',
+					context: { target_version, current_top_entry: cl_top }
+				}
+			})
+			return { code: EXIT_CODES.USAGE, envelope: restored }
+		}
+	}
+
+	// (Step 5–7) Status / workspace / visibility.
+	// For Phase 1 we accept --workspace flag verbatim. Pre-publish registry
+	// status check is delegated to publish.js (which already does it) — we
+	// surface its DIVERGED as REGISTRY_DIVERGED in the envelope.
+	if (!resolved_workspace) {
+		const restored = await restore_and({
+			...envelope_error('WORKSPACE_UNRESOLVED', 'Could not resolve target workspace.'),
+			next_step: { action: 'specify_workspace' }
+		})
+		return { code: EXIT_CODES.USAGE, envelope: restored }
+	}
+
+	// (Step 8–9) Publish — delegate to publish.js by spawning it. Easier to
+	// keep release as a thin orchestrator over the existing publish pipeline
+	// than to copy its push logic.
+	if (dry_run) {
+		await restore_and(null) // for dry-run, restore the snapshot if any
+		return {
+			code: EXIT_CODES.SUCCESS,
+			envelope: {
+				data: {
+					dry_run: true,
+					skill: skill_name,
+					workspace: resolved_workspace,
+					target_version,
+					ahead_recognized: target_info.status === 'ahead',
+					bump_applied: target_info.status === 'clean_with_bump' || target_info.status === 'inferred_from_changelog',
+					changelog_ok: changelog_ok || changelog_from !== null
+				}
+			}
+		}
+	}
+
+	const { spawn } = require('child_process')
+	const publish_args = [path.resolve(__dirname, '../../bin/happyskills.js'), 'publish', skill_name, '--workspace', resolved_workspace, '--json']
+	if (args.flags.public) publish_args.push('--public')
+	if (args.flags.force) publish_args.push('--force')
+
+	const publish_result = await new Promise((res) => {
+		const child = spawn(process.execPath, publish_args, {
+			env: process.env,
+			stdio: ['inherit', 'pipe', 'inherit']
+		})
+		let stdout = ''
+		child.stdout.on('data', d => { stdout += d.toString() })
+		child.on('close', (code_) => res({ code: code_, stdout }))
+	})
+
+	let publish_envelope = null
+	try { publish_envelope = JSON.parse(publish_result.stdout) } catch { /* non-JSON */ }
+
+	if (publish_result.code !== 0) {
+		// Map publish error codes to the structured envelope.
+		const err_code = publish_envelope?.error?.code || 'PUBLISH_FAILED'
+		const message = publish_envelope?.error?.message || `publish exit ${publish_result.code}`
+		// REGISTRY_DIVERGED → REGISTRY_DIVERGED next_step
+		const next_step_action = /DIVERG|diverge/i.test(message) ? 'pull_rebase_first' : 'review_publish_error'
+		const restored = await restore_and({
+			...envelope_error(err_code, message, publish_envelope?.error?.validation_errors ? { validation_errors: publish_envelope.error.validation_errors } : {}),
+			next_step: { action: next_step_action, context: { publish_envelope } }
+		})
+		return { code: publish_result.code || EXIT_CODES.ERROR, envelope: restored }
+	}
+
+	// On success, delete the snapshot — the operation succeeded so no
+	// rollback is needed. (We keep snapshot_storage.remove best-effort; if
+	// it fails the snapshot just lingers, which is fine.)
+	if (snapshot_id) {
+		await snapshot_storage.remove(snapshot_id, { project_root })
+	}
+
+	return {
+		code: EXIT_CODES.SUCCESS,
+		envelope: {
+			data: {
+				published: true,
+				skill: publish_envelope?.data?.skill || `${resolved_workspace}/${skill_name}`,
+				version: publish_envelope?.data?.version || target_version,
+				workspace: resolved_workspace,
+				commit: publish_envelope?.data?.commit || null,
+				ref: publish_envelope?.data?.ref || `refs/tags/v${target_version}`,
+				ahead_recognized: target_info.status === 'ahead',
+				bump_applied: target_info.status === 'clean_with_bump' || target_info.status === 'inferred_from_changelog',
+				warnings: publish_envelope?.data?.warnings || [],
+				snapshot_id_preserved: false
+			}
+		}
+	}
+})
+
+const run = (args) => catch_errors('Release wrapper failed', async () => {
+	if (args.flags._show_help) {
+		print_help(HELP_TEXT)
+		return process.exit(EXIT_CODES.SUCCESS)
+	}
+
+	const [err, result] = await orchestrate(args)
+	if (err) {
+		// Catastrophic failure — bubble up through the standard error path.
+		exit_with_error(err)
+		return
+	}
+
+	if (args.flags.json) {
+		print_json(result.envelope)
+		process.exit(result.code || 0)
+		return
+	}
+
+	if (result.envelope?.data?.published) {
+		print_success(`Published ${result.envelope.data.skill}@${result.envelope.data.version}`)
+		if (result.envelope.data.ahead_recognized) {
+			print_info('Recognized ahead state — published the disk version directly.')
+		}
+		process.exit(0)
+		return
+	}
+	if (result.envelope?.data?.dry_run) {
+		print_info(`Dry run: would publish ${result.envelope.data.skill} @ ${result.envelope.data.target_version} to ${result.envelope.data.workspace}.`)
+		process.exit(0)
+		return
+	}
+	if (result.envelope?.error) {
+		print_warn(`Release blocked: ${result.envelope.error.message}`)
+		if (result.envelope.next_step) {
+			print_hint(`Next step: ${result.envelope.next_step.action}`)
+		}
+		process.exit(result.code || EXIT_CODES.ERROR)
+		return
+	}
+}).then(([errors]) => { if (errors) { exit_with_error(errors); return } })
+
+module.exports = { run, orchestrate, determine_target_version, compute_bump }