happyskills 0.48.0 → 0.50.0

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 }

package/src/commands/release.test.js

@@ -0,0 +1,209 @@
+'use strict'
+const { describe, it } = require('node:test')
+const assert = require('node:assert/strict')
+
+const { determine_target_version, compute_bump } = require('./release')
+
+describe('release.compute_bump', () => {
+	it('handles patch/minor/major shortcuts', () => {
+		assert.strictEqual(compute_bump('1.2.3', 'patch'), '1.2.4')
+		assert.strictEqual(compute_bump('1.2.3', 'minor'), '1.3.0')
+		assert.strictEqual(compute_bump('1.2.3', 'major'), '2.0.0')
+	})
+
+	it('passes through explicit semver', () => {
+		assert.strictEqual(compute_bump('1.2.3', '5.0.0'), '5.0.0')
+	})
+
+	it('returns null for invalid bump and missing base', () => {
+		assert.strictEqual(compute_bump('1.2.3', 'gibberish'), null)
+		assert.strictEqual(compute_bump(null, 'patch'), null)
+	})
+})
+
+const fs = require('fs')
+const os = require('os')
+const path = require('path')
+
+const make_tmp = () => fs.mkdtempSync(path.join(os.tmpdir(), 'hs-release-test-'))
+
+const write_skill = (dir, manifest, opts = {}) => {
+	fs.mkdirSync(dir, { recursive: true })
+	fs.writeFileSync(path.join(dir, 'skill.json'), JSON.stringify(manifest, null, '\t'))
+	fs.writeFileSync(path.join(dir, 'SKILL.md'), opts.skill_md || `---\nname: ${manifest.name}\ndescription: release-test skill\n---\nbody\n`)
+	if (opts.changelog) {
+		fs.writeFileSync(path.join(dir, 'CHANGELOG.md'), opts.changelog)
+	}
+}
+
+describe('release.determine_target_version', () => {
+	it('identifies ahead and uses the disk version', async () => {
+		const root = make_tmp()
+		try {
+			const dir = path.join(root, 'ahead')
+			write_skill(dir, { name: 'ahead', version: '0.3.3' })
+			const lock_entry = { version: '0.3.2' }
+			const r = await determine_target_version({
+				manifest: { name: 'ahead', version: '0.3.3' },
+				lock_entry,
+				skill_dir: dir,
+				bump_flag: null,
+				no_bump: false
+			})
+			assert.strictEqual(r.status, 'ahead')
+			assert.strictEqual(r.target, '0.3.3')
+		} finally { fs.rmSync(root, { recursive: true, force: true }) }
+	})
+
+	it('refuses ahead when --bump disagrees with disk', async () => {
+		const root = make_tmp()
+		try {
+			const dir = path.join(root, 'ahead-bump-disagree')
+			write_skill(dir, { name: 'ahead-bump-disagree', version: '0.5.0' })
+			const r = await determine_target_version({
+				manifest: { name: 'ahead-bump-disagree', version: '0.5.0' },
+				lock_entry: { version: '0.3.2' },
+				skill_dir: dir,
+				bump_flag: 'patch', // would compute 0.3.3, disk is 0.5.0
+				no_bump: false
+			})
+			assert.strictEqual(r.status, 'bump_disagreement')
+			assert.strictEqual(r.disk_version, '0.5.0')
+			assert.strictEqual(r.requested_bump, 'patch')
+		} finally { fs.rmSync(root, { recursive: true, force: true }) }
+	})
+
+	it('flags drift on regression (disk < lock)', async () => {
+		const root = make_tmp()
+		try {
+			const dir = path.join(root, 'reg')
+			write_skill(dir, { name: 'reg', version: '0.3.0' })
+			const r = await determine_target_version({
+				manifest: { name: 'reg', version: '0.3.0' },
+				lock_entry: { version: '0.4.0' },
+				skill_dir: dir,
+				bump_flag: null,
+				no_bump: false
+			})
+			assert.strictEqual(r.status, 'drift')
+			assert.strictEqual(r.drift.reason, 'regression')
+		} finally { fs.rmSync(root, { recursive: true, force: true }) }
+	})
+
+	it('clean + --bump patch produces the new version', async () => {
+		const root = make_tmp()
+		try {
+			const dir = path.join(root, 'clean-bump')
+			write_skill(dir, { name: 'clean-bump', version: '1.0.0' })
+			const r = await determine_target_version({
+				manifest: { name: 'clean-bump', version: '1.0.0' },
+				lock_entry: { version: '1.0.0' },
+				skill_dir: dir,
+				bump_flag: 'patch',
+				no_bump: false
+			})
+			assert.strictEqual(r.status, 'clean_with_bump')
+			assert.strictEqual(r.target, '1.0.1')
+		} finally { fs.rmSync(root, { recursive: true, force: true }) }
+	})
+
+	it('clean + no bump + no CHANGELOG-hint → specify_bump', async () => {
+		const root = make_tmp()
+		try {
+			const dir = path.join(root, 'clean-no-bump')
+			write_skill(dir, { name: 'clean-no-bump', version: '1.0.0' })
+			const r = await determine_target_version({
+				manifest: { name: 'clean-no-bump', version: '1.0.0' },
+				lock_entry: { version: '1.0.0' },
+				skill_dir: dir,
+				bump_flag: null,
+				no_bump: false
+			})
+			assert.strictEqual(r.status, 'specify_bump')
+		} finally { fs.rmSync(root, { recursive: true, force: true }) }
+	})
+
+	it('clean + CHANGELOG-hint > current → inferred_from_changelog', async () => {
+		const root = make_tmp()
+		try {
+			const dir = path.join(root, 'cl-hint')
+			write_skill(dir, { name: 'cl-hint', version: '1.0.0' }, { changelog: '# Changelog\n\n## [1.1.0]\n- new\n' })
+			const r = await determine_target_version({
+				manifest: { name: 'cl-hint', version: '1.0.0' },
+				lock_entry: { version: '1.0.0' },
+				skill_dir: dir,
+				bump_flag: null,
+				no_bump: false
+			})
+			assert.strictEqual(r.status, 'inferred_from_changelog')
+			assert.strictEqual(r.target, '1.1.0')
+		} finally { fs.rmSync(root, { recursive: true, force: true }) }
+	})
+
+	it('--no-bump on clean returns missing_version', async () => {
+		const root = make_tmp()
+		try {
+			const dir = path.join(root, 'no-bump-clean')
+			write_skill(dir, { name: 'no-bump-clean', version: '1.0.0' })
+			const r = await determine_target_version({
+				manifest: { name: 'no-bump-clean', version: '1.0.0' },
+				lock_entry: { version: '1.0.0' },
+				skill_dir: dir,
+				bump_flag: null,
+				no_bump: true
+			})
+			assert.strictEqual(r.status, 'missing_version')
+		} finally { fs.rmSync(root, { recursive: true, force: true }) }
+	})
+
+	it('first-publish (no lock entry) treats the disk version as ahead — no --bump required', async () => {
+		const root = make_tmp()
+		try {
+			const dir = path.join(root, 'first-publish')
+			write_skill(dir, { name: 'first-publish', version: '0.1.0' })
+			const r = await determine_target_version({
+				manifest: { name: 'first-publish', version: '0.1.0' },
+				lock_entry: null, // no lock entry yet
+				skill_dir: dir,
+				bump_flag: null,
+				no_bump: false
+			})
+			assert.strictEqual(r.status, 'ahead')
+			assert.strictEqual(r.target, '0.1.0')
+		} finally { fs.rmSync(root, { recursive: true, force: true }) }
+	})
+
+	it('first-publish with --no-bump works (E2E gap from real-registry test)', async () => {
+		const root = make_tmp()
+		try {
+			const dir = path.join(root, 'first-publish-no-bump')
+			write_skill(dir, { name: 'first-publish-no-bump', version: '0.1.0' })
+			const r = await determine_target_version({
+				manifest: { name: 'first-publish-no-bump', version: '0.1.0' },
+				lock_entry: null,
+				skill_dir: dir,
+				bump_flag: null,
+				no_bump: true // explicitly no bump — should NOT error now
+			})
+			assert.strictEqual(r.status, 'ahead', 'first-publish with --no-bump must NOT emit MISSING_VERSION')
+			assert.strictEqual(r.target, '0.1.0')
+		} finally { fs.rmSync(root, { recursive: true, force: true }) }
+	})
+
+	it('--bump with garbage value returns invalid_bump', async () => {
+		const root = make_tmp()
+		try {
+			const dir = path.join(root, 'bad-bump')
+			write_skill(dir, { name: 'bad-bump', version: '1.0.0' })
+			const r = await determine_target_version({
+				manifest: { name: 'bad-bump', version: '1.0.0' },
+				lock_entry: { version: '1.0.0' },
+				skill_dir: dir,
+				bump_flag: 'gibberish',
+				no_bump: false
+			})
+			assert.strictEqual(r.status, 'invalid_bump')
+			assert.strictEqual(r.bump, 'gibberish')
+		} finally { fs.rmSync(root, { recursive: true, force: true }) }
+	})
+})