happyskills 0.48.0 → 0.49.0

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 }) }
+	})
+})

package/src/commands/snapshot.js

@@ -0,0 +1,252 @@
+const path = require('path')
+const { error: { catch_errors, wrap_errors: e } } = require('puffy-core')
+const storage = require('../snapshot/storage')
+const { find_project_root, skills_dir, skill_install_dir } = require('../config/paths')
+const { read_lock, get_all_locked_skills } = require('../lock/reader')
+const { print_help, print_success, print_info, print_table, print_json, print_warn } = require('../ui/output')
+const { exit_with_error, UsageError } = require('../utils/errors')
+const { EXIT_CODES } = require('../constants')
+
+const HELP_TEXT = `Usage: happyskills snapshot <subcommand> [args] [options]
+
+Capture and restore skill state — the safety net for every mutation.
+
+Subcommands:
+  create <owner/skill>           Capture skill directory + lock entry
+  list <owner/skill>             List existing snapshots for a skill
+  restore <snapshot-id>          Restore a skill from a snapshot
+  delete <snapshot-id>           Delete a snapshot
+  prune <owner/skill>            Keep only the N most recent snapshots
+
+Options:
+  --note <text>                  Attach a note to a new snapshot (create only)
+  --keep <n>                     Retention count for prune (default: 10)
+  -g, --global                   Operate on the global snapshot store
+  --json                         Output as JSON
+
+Examples:
+  happyskills snapshot create acme/deploy-aws --note "pre-release" --json
+  happyskills snapshot list acme/deploy-aws --json
+  happyskills snapshot restore snap_20260523T103045Z_abc123 --json
+  happyskills snapshot delete snap_20260523T103045Z_abc123 --json
+  happyskills snapshot prune acme/deploy-aws --keep 5 --json`
+
+const parse_skill_arg = (raw) => {
+	if (!raw) return null
+	if (raw.includes('/')) {
+		const [workspace, ...rest] = raw.split('/')
+		return { workspace, skill: rest.join('/'), short: rest.join('/') }
+	}
+	return { workspace: null, skill: raw, short: raw }
+}
+
+const resolve_from_lock = (short_name, project_root) => catch_errors('Failed to resolve skill from lock', async () => {
+	const [, lock_data] = await read_lock(project_root)
+	if (!lock_data) return null
+	const all = get_all_locked_skills(lock_data)
+	const suffix = `/${short_name}`
+	const key = Object.keys(all).find(k => k === short_name || k.endsWith(suffix))
+	if (!key) return null
+	const [workspace, name] = key.includes('/') ? key.split('/') : [null, key]
+	return { workspace, skill: name, lock_entry: all[key] }
+})
+
+const do_create = (args) => catch_errors('Snapshot create failed', async () => {
+	const raw = args._[1]
+	if (!raw) throw new UsageError('Usage: happyskills snapshot create <owner/skill> [--note <text>]')
+
+	const project_root = find_project_root()
+	const is_global = !!args.flags.global
+	const parsed = parse_skill_arg(raw)
+	let workspace = parsed.workspace
+	let skill = parsed.skill
+	let lock_entry = null
+
+	const [, resolved] = await resolve_from_lock(parsed.short, project_root)
+	if (resolved) {
+		if (!workspace) workspace = resolved.workspace
+		skill = resolved.skill
+		lock_entry = resolved.lock_entry
+	}
+
+	if (!workspace) {
+		throw new UsageError(`Cannot determine workspace for "${raw}" — pass it as owner/skill or install via the registry first.`)
+	}
+
+	const base_dir = skills_dir(is_global, project_root)
+	const skill_dir = skill_install_dir(base_dir, skill)
+
+	const [err, result] = await storage.create({
+		skill_dir, workspace, skill, lock_entry,
+		note: typeof args.flags.note === 'string' ? args.flags.note : null,
+		is_global, project_root
+	})
+	if (err) throw e('Failed to create snapshot', err)
+
+	if (args.flags.json) {
+		print_json({ data: result })
+		return
+	}
+	print_success(`Snapshot ${result.snapshot_id}`)
+	print_info(`  Path: ${result.path}`)
+	if (result.note) print_info(`  Note: ${result.note}`)
+	if (result.pruned?.length > 0) print_info(`  Pruned ${result.pruned.length} older snapshot(s)`)
+})
+
+const do_list = (args) => catch_errors('Snapshot list failed', async () => {
+	const raw = args._[1]
+	if (!raw) throw new UsageError('Usage: happyskills snapshot list <owner/skill>')
+
+	const project_root = find_project_root()
+	const is_global = !!args.flags.global
+	const parsed = parse_skill_arg(raw)
+	let workspace = parsed.workspace
+	let skill = parsed.skill
+
+	if (!workspace) {
+		const [, resolved] = await resolve_from_lock(parsed.short, project_root)
+		if (resolved) {
+			workspace = resolved.workspace
+			skill = resolved.skill
+		}
+	}
+
+	if (!workspace) {
+		if (args.flags.json) {
+			print_json({ data: { snapshots: [] } })
+			return
+		}
+		print_info('No workspace resolved — no snapshots to list.')
+		return
+	}
+
+	const [err, result] = await storage.list({ workspace, skill, is_global, project_root })
+	if (err) throw e('Failed to list snapshots', err)
+
+	if (args.flags.json) {
+		print_json({ data: { workspace, skill, snapshots: result.snapshots } })
+		return
+	}
+
+	if (result.snapshots.length === 0) {
+		print_info(`No snapshots for ${workspace}/${skill}.`)
+		return
+	}
+	const rows = result.snapshots.map(s => [
+		s.snapshot_id,
+		s.timestamp,
+		(s.note || '').slice(0, 60)
+	])
+	print_table(['Snapshot ID', 'Timestamp', 'Note'], rows)
+})
+
+const do_restore = (args) => catch_errors('Snapshot restore failed', async () => {
+	const snapshot_id = args._[1]
+	if (!snapshot_id) throw new UsageError('Usage: happyskills snapshot restore <snapshot-id>')
+
+	const project_root = find_project_root()
+	const is_global = !!args.flags.global
+
+	const [find_err, found] = await storage.find_snapshot(snapshot_id, { is_global, project_root })
+	if (find_err) throw e('Failed to look up snapshot', find_err)
+	if (!found) {
+		throw new Error(`Snapshot not found: ${snapshot_id}`)
+	}
+
+	const base_dir = skills_dir(is_global, project_root)
+	const skill_dir = skill_install_dir(base_dir, found.skill)
+
+	const [err, result] = await storage.restore(snapshot_id, { skill_dir, is_global, project_root })
+	if (err) throw e('Failed to restore snapshot', err)
+
+	if (args.flags.json) {
+		print_json({ data: result })
+		return
+	}
+	print_success(`Restored ${result.workspace}/${result.skill} from ${snapshot_id}`)
+})
+
+const do_delete = (args) => catch_errors('Snapshot delete failed', async () => {
+	const snapshot_id = args._[1]
+	if (!snapshot_id) throw new UsageError('Usage: happyskills snapshot delete <snapshot-id>')
+	const project_root = find_project_root()
+	const is_global = !!args.flags.global
+
+	const [err, result] = await storage.remove(snapshot_id, { is_global, project_root })
+	if (err) throw e('Failed to delete snapshot', err)
+
+	if (args.flags.json) {
+		print_json({ data: result })
+		return
+	}
+	if (result.deleted) print_success(`Deleted ${snapshot_id}`)
+	else print_warn(`No snapshot deleted (${result.reason || 'unknown'}).`)
+})
+
+const do_prune = (args) => catch_errors('Snapshot prune failed', async () => {
+	const raw = args._[1]
+	if (!raw) throw new UsageError('Usage: happyskills snapshot prune <owner/skill> [--keep <n>]')
+
+	const project_root = find_project_root()
+	const is_global = !!args.flags.global
+	const parsed = parse_skill_arg(raw)
+	let workspace = parsed.workspace
+	let skill = parsed.skill
+
+	if (!workspace) {
+		const [, resolved] = await resolve_from_lock(parsed.short, project_root)
+		if (resolved) {
+			workspace = resolved.workspace
+			skill = resolved.skill
+		}
+	}
+
+	if (!workspace) {
+		throw new UsageError(`Cannot determine workspace for "${raw}" — pass it as owner/skill.`)
+	}
+
+	const keep_raw = args.flags.keep
+	const keep = keep_raw === undefined || keep_raw === true ? storage.DEFAULT_RETENTION : parseInt(keep_raw, 10)
+	if (!Number.isFinite(keep) || keep < 0) {
+		throw new UsageError(`--keep must be a non-negative integer (got "${keep_raw}")`)
+	}
+
+	const [err, result] = await storage.prune({ workspace, skill, is_global, project_root, keep })
+	if (err) throw e('Failed to prune snapshots', err)
+
+	if (args.flags.json) {
+		print_json({ data: result })
+		return
+	}
+	print_success(`Kept ${result.kept}, deleted ${result.deleted}`)
+})
+
+const SUBCOMMANDS = {
+	create: do_create,
+	list: do_list,
+	restore: do_restore,
+	delete: do_delete,
+	rm: do_delete,
+	prune: do_prune
+}
+
+const run = (args) => catch_errors('Snapshot failed', async () => {
+	if (args.flags._show_help) {
+		print_help(HELP_TEXT)
+		return process.exit(EXIT_CODES.SUCCESS)
+	}
+
+	const sub = args._[0]
+	if (!sub) {
+		throw new UsageError('Usage: happyskills snapshot <create|list|restore|delete|prune> ...')
+	}
+	const handler = SUBCOMMANDS[sub]
+	if (!handler) {
+		throw new UsageError(`Unknown snapshot subcommand: "${sub}". Run \`happyskills snapshot --help\`.`)
+	}
+
+	const [err] = await handler(args)
+	if (err) throw err
+}).then(([errors]) => { if (errors) { exit_with_error(errors); return } })
+
+module.exports = { run }

package/src/commands/status.js

@@ -1,7 +1,7 @@
 const { error: { catch_errors, wrap_errors: e } } = require('puffy-core')
 const { read_lock, get_all_locked_skills } = require('../lock/reader')
 const { detect_status } = require('../merge/detector')
-const { verify_lock_disk_consistency, describe_drift } = require('../lock/verify')
+const { verify_lock_disk_consistency, detect_ahead_state, describe_drift } = require('../lock/verify')
 const repos_api = require('../api/repos')
 const { print_help, print_info, print_json, print_warn, print_hint, code } = require('../ui/output')
 const { exit_with_error, UsageError } = require('../utils/errors')
@@ -26,12 +26,13 @@ Examples:
   happyskills st acme/deploy-aws
   happyskills status --json`
 
-// Drift outranks every other status: when the lock and the on-disk skill.json
-// disagree about what's installed, every other comparison (modified/outdated/
-// diverged/conflicts) is computed against an untrustworthy baseline.
-const classify = (drift, local_modified, remote_updated, has_conflicts) => {
+// §10.5 — seven canonical states. Drift outranks every other status because
+// the install-record baseline is broken; ahead is reported above local/remote
+// composites because it represents authoring intent the system should preserve.
+const classify = (drift, ahead, local_modified, remote_updated, has_conflicts) => {
 	if (drift && !drift.ok) return 'drift'
 	if (has_conflicts) return 'conflicts'
+	if (ahead) return 'ahead'
 	if (local_modified && remote_updated) return 'diverged'
 	if (local_modified) return 'modified'
 	if (remote_updated) return 'outdated'
@@ -92,20 +93,27 @@ const run = (args) => catch_errors('Status failed', async () => {
 
 	const base_dir = skills_dir(is_global, project_root)
 
-	// Detect drift (lock-vs-disk version mismatch) and local modifications in parallel.
-	// The drift probe is cheap (one skill.json read + version compare); detect_status
-	// is the heavier integrity check. Running both lets us distinguish "user edited
-	// content" from "structural baseline broken".
+	// Detect drift, ahead, and local modifications in parallel. The drift probe
+	// is cheap (one skill.json read + version compare); detect_status is the
+	// heavier integrity check. Running them all lets us distinguish "user edited
+	// content" from "structural baseline broken" from "author bumped locally".
 	const detections = await Promise.all(entries.map(async ([name, data]) => {
-		if (!data) return { name, data, det: null, drift: null }
+		if (!data) return { name, data, det: null, drift: null, ahead: null }
 		const short_name = name.split('/')[1] || name
 		const dir = skill_install_dir(base_dir, short_name)
 		const [, drift] = await verify_lock_disk_consistency(data, dir)
 		const [, det] = await detect_status(data, dir, { skill_name: name, project_root, is_global })
-		return { name, data, det, drift }
+		// Only check ahead when drift is clean — drift represents a broken
+		// baseline that should be reported first.
+		let ahead = null
+		if (drift && drift.ok) {
+			const [, ahead_state] = await detect_ahead_state(data, dir)
+			if (ahead_state && ahead_state.ahead) ahead = ahead_state
+		}
+		return { name, data, det, drift, ahead }
 	}))
 
-	const results = detections.map(({ name, data, det, drift }) => {
+	const results = detections.map(({ name, data, det, drift, ahead }) => {
 		if (!data) return { skill: name, status: 'not_found', local_modified: false, remote_updated: false }
 		const has_conflicts = (data.conflict_files || []).length > 0
 		return {
@@ -122,7 +130,13 @@ const run = (args) => catch_errors('Status failed', async () => {
 			drift: drift && !drift.ok
 				? { reason: drift.reason, lock_version: drift.expected, disk_version: drift.actual }
 				: null,
-			status: drift && !drift.ok ? 'drift' : (has_conflicts ? 'conflicts' : 'clean')
+			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
+			} : null,
+			status: drift && !drift.ok ? 'drift' : (has_conflicts ? 'conflicts' : (ahead ? 'ahead' : 'clean'))
 		}
 	})
 
@@ -145,11 +159,13 @@ const run = (args) => catch_errors('Status failed', async () => {
 	}
 
 	// Classify each result. The drift field is the canonical structural-baseline
-	// signal; pass it to classify so it can outrank everything else.
+	// signal; pass it to classify so it can outrank everything else. The ahead
+	// field is the canonical author-intent signal — it preserves the local bump
+	// during the publish flow.
 	for (const r of results) {
 		if (r.status !== 'not_found') {
 			const drift_check = r.drift ? { ok: false } : { ok: true }
-			r.status = classify(drift_check, r.local_modified, r.remote_updated, r.conflict_files.length > 0)
+			r.status = classify(drift_check, !!r.ahead, r.local_modified, r.remote_updated, r.conflict_files.length > 0)
 		}
 	}
 
@@ -174,12 +190,13 @@ const run = (args) => catch_errors('Status failed', async () => {
 			expected: r.drift?.lock_version,
 			actual: r.drift?.disk_version
 		})
-			: r.status === 'conflicts' ? 'conflicts (unresolved merge conflicts)'
-				: r.status === 'diverged' ? 'diverged (local + remote changes)'
-					: r.status === 'modified' ? 'modified (local changes)'
-						: r.status === 'outdated' ? 'outdated (remote changes)'
-							: r.status === 'not_found' ? 'not found'
-								: 'clean'
+			: r.status === 'ahead' ? `ahead (disk ${r.ahead?.disk_version}, lock ${r.ahead?.lock_version})`
+				: r.status === 'conflicts' ? 'conflicts (unresolved merge conflicts)'
+					: r.status === 'diverged' ? 'diverged (local + remote changes)'
+						: r.status === 'modified' ? 'modified (local changes)'
+							: r.status === 'outdated' ? 'outdated (remote changes)'
+								: r.status === 'not_found' ? 'not found'
+									: 'clean'
 	}))
 
 	const w_skill = Math.max(col_skill.length, ...rows.map(r => r.skill.length))
@@ -194,11 +211,16 @@ const run = (args) => catch_errors('Status failed', async () => {
 	}
 
 	const drifted = results.filter(r => r.status === 'drift')
+	const ahead_skills = results.filter(r => r.status === 'ahead')
 	if (drifted.length > 0) {
 		console.log()
 		print_warn(`${drifted.length} skill(s) drifted: lock and on-disk skill.json disagree.`)
-		print_hint(`Restore install record: ${code('happyskills install <skill> --fresh')}`)
-		print_hint(`Or accept the on-disk version: bump the lock by reinstalling at the disk version.`)
+		print_hint(`Repair: ${code('happyskills reconcile <skill>')}`)
+	}
+	if (ahead_skills.length > 0) {
+		console.log()
+		print_info(`${ahead_skills.length} skill(s) ahead of lock — bumped locally, not yet published.`)
+		print_hint(`Publish: ${code('happyskills publish <skill>')} (lock catches up atomically)`)
 	}
 }).then(([errors]) => { if (errors) { exit_with_error(errors); return } })
 

package/src/config/limits.js

@@ -0,0 +1,11 @@
+// Size limits enforced before publish. Must stay in sync with
+// api/app/config/limits.js — a drift means a publish that passes CLI
+// validation will be rejected by the API.
+
+const MAX_FILE_SIZE = 1 * 1024 * 1024   // 1 MB per file
+const MAX_TOTAL_SIZE = 1 * 1024 * 1024  // 1 MB per skill bundle
+
+module.exports = {
+	MAX_FILE_SIZE,
+	MAX_TOTAL_SIZE
+}

package/src/constants.js

@@ -74,7 +74,10 @@ const COMMANDS = [
 	'versions',
 	'changelog',
 	'agents',
-	'postlex'
+	'postlex',
+	'snapshot',
+	'reconcile',
+	'release'
 ]
 
 module.exports = {

package/src/index.js

@@ -113,6 +113,9 @@ Commands:
   login                    Authenticate with the registry
   logout                   Clear stored credentials
   whoami                   Show current user
+  snapshot <sub>           Capture and restore skill state (create, list, restore, delete, prune)
+  reconcile <owner/skill>  Diagnose and repair lock-vs-disk drift
+  release <skill-name>     Atomic release: snapshot + validate + bump + publish
 
 Global flags:
   --help                   Show help for a command