happyskills 0.1.0

package/src/engine/uninstaller.js

@@ -0,0 +1,73 @@
+const { error: { catch_errors, wrap_errors: e } } = require('puffy-core')
+const { read_lock, get_locked_skill, get_all_locked_skills } = require('../lock/reader')
+const { write_lock, update_lock_skills } = require('../lock/writer')
+const { skills_dir, skill_install_dir } = require('../config/paths')
+const { remove_dir } = require('../utils/fs')
+const { print_success, print_info } = require('../ui/output')
+
+const find_orphans = (skills, removed_skill) => {
+	const orphans = []
+	for (const [name, data] of Object.entries(skills)) {
+		if (name === removed_skill) continue
+		if (!data.requested_by || data.requested_by.length === 0) {
+			orphans.push(name)
+			continue
+		}
+		const remaining = data.requested_by.filter(r => r !== removed_skill && skills[r])
+		if (remaining.length === 0) {
+			orphans.push(name)
+		}
+	}
+	return orphans
+}
+
+const uninstall = (skill, options = {}) => catch_errors('Uninstall failed', async () => {
+	const { global: is_global = false, project_root } = options
+	const base_dir = skills_dir(is_global, project_root)
+
+	const [lock_errors, lock_data] = await read_lock(project_root)
+	if (lock_errors || !lock_data) {
+		throw new Error('No skills-lock.json found. Nothing to uninstall.')
+	}
+
+	const locked = get_locked_skill(lock_data, skill)
+	if (!locked) {
+		throw new Error(`${skill} is not installed.`)
+	}
+
+	const all_skills = { ...get_all_locked_skills(lock_data) }
+
+	for (const [name, data] of Object.entries(all_skills)) {
+		if (data.requested_by) {
+			data.requested_by = data.requested_by.filter(r => r !== skill)
+		}
+	}
+
+	const orphans = find_orphans(all_skills, skill)
+	const to_remove = [skill, ...orphans]
+
+	for (const name of to_remove) {
+		const [owner, repo] = name.split('/')
+		const install_dir = skill_install_dir(base_dir, owner, repo)
+		const [rm_errors] = await remove_dir(install_dir)
+		if (rm_errors) throw e(`Failed to remove ${name}`, rm_errors)
+	}
+
+	const updates = {}
+	for (const name of to_remove) {
+		updates[name] = null
+	}
+
+	const new_skills = update_lock_skills(lock_data, updates)
+	const [write_errors] = await write_lock(project_root, new_skills)
+	if (write_errors) throw e('Failed to update lock file', write_errors)
+
+	print_success(`Removed ${skill}`)
+	if (orphans.length > 0) {
+		print_info(`Pruned ${orphans.length} orphaned dependency(s): ${orphans.join(', ')}`)
+	}
+
+	return { removed: to_remove }
+})
+
+module.exports = { uninstall, find_orphans }

package/src/engine/uninstaller.test.js

@@ -0,0 +1,98 @@
+const { describe, it } = require('node:test')
+const assert = require('node:assert')
+const { find_orphans } = require('./uninstaller')
+
+describe('find_orphans', () => {
+	it('returns empty when all skills have requesters in the skills map', () => {
+		const skills = {
+			'acme/app': { requested_by: ['acme/root'] },
+			'acme/root': { requested_by: ['acme/app'] },
+			'acme/auth': { requested_by: ['acme/app'] }
+		}
+		const result = find_orphans(skills, 'acme/other')
+		assert.deepStrictEqual(result, [])
+	})
+
+	it('finds orphans whose only requester is the removed skill', () => {
+		const skills = {
+			'acme/deploy': { requested_by: ['acme/app'] },
+			'acme/app': { requested_by: ['acme/deploy'] },
+			'acme/auth': { requested_by: ['acme/deploy'] }
+		}
+		const result = find_orphans(skills, 'acme/deploy')
+		assert.ok(result.includes('acme/auth'))
+	})
+
+	it('skips the removed skill itself', () => {
+		const skills = {
+			'acme/deploy': { requested_by: ['acme/app'] },
+			'acme/app': { requested_by: ['acme/deploy'] },
+			'acme/auth': { requested_by: ['acme/deploy'] }
+		}
+		const result = find_orphans(skills, 'acme/deploy')
+		assert.ok(!result.includes('acme/deploy'))
+	})
+
+	it('keeps skills that have other valid requesters in the map', () => {
+		const skills = {
+			'acme/deploy': { requested_by: ['acme/monitor'] },
+			'acme/monitor': { requested_by: ['acme/deploy'] },
+			'acme/auth': { requested_by: ['acme/deploy', 'acme/monitor'] }
+		}
+		const result = find_orphans(skills, 'acme/deploy')
+		assert.ok(!result.includes('acme/auth'))
+	})
+
+	it('finds skills with empty requested_by', () => {
+		const skills = {
+			'acme/deploy': { requested_by: ['acme/root'] },
+			'acme/root': { requested_by: ['acme/deploy'] },
+			'acme/orphan': { requested_by: [] }
+		}
+		const result = find_orphans(skills, 'acme/other')
+		assert.ok(result.includes('acme/orphan'))
+	})
+
+	it('finds skills with no requested_by field', () => {
+		const skills = {
+			'acme/deploy': { requested_by: ['acme/root'] },
+			'acme/root': { requested_by: ['acme/deploy'] },
+			'acme/orphan': {}
+		}
+		const result = find_orphans(skills, 'acme/other')
+		assert.ok(result.includes('acme/orphan'))
+	})
+
+	it('handles cascading orphans (only finds direct)', () => {
+		const skills = {
+			'acme/deploy': { requested_by: ['acme/app'] },
+			'acme/app': { requested_by: ['acme/deploy'] },
+			'acme/auth': { requested_by: ['acme/deploy'] },
+			'acme/crypto': { requested_by: ['acme/auth'] }
+		}
+		// find_orphans only finds direct orphans, not cascading
+		const result = find_orphans(skills, 'acme/deploy')
+		// acme/auth is orphaned (only requester is removed skill)
+		assert.ok(result.includes('acme/auth'))
+		// acme/crypto still has acme/auth in skills map, so it's not orphaned yet
+		assert.ok(!result.includes('acme/crypto'))
+	})
+
+	it('filters out requesters that are not in the skills map', () => {
+		const skills = {
+			'acme/auth': { requested_by: ['acme/gone'] }
+		}
+		// acme/gone doesn't exist in skills, so acme/auth is orphaned
+		const result = find_orphans(skills, 'acme/other')
+		assert.ok(result.includes('acme/auth'))
+	})
+
+	it('treats __root__ like any other requester (not in skills map)', () => {
+		const skills = {
+			'acme/deploy': { requested_by: ['__root__'] }
+		}
+		// __root__ is not a key in skills, so deploy is considered orphaned
+		const result = find_orphans(skills, 'acme/other')
+		assert.ok(result.includes('acme/deploy'))
+	})
+})

package/src/index.js

@@ -0,0 +1,118 @@
+const { CLI_VERSION, EXIT_CODES, COMMAND_ALIASES, COMMANDS } = require('./constants')
+const { print_error, print_help } = require('./ui/output')
+
+const parse_args = (argv) => {
+	const args = { _: [], flags: {} }
+	let i = 0
+	while (i < argv.length) {
+		const arg = argv[i]
+		if (arg.startsWith('--')) {
+			const key = arg.slice(2)
+			const next = argv[i + 1]
+			if (!next || next.startsWith('-')) {
+				args.flags[key] = true
+			} else {
+				args.flags[key] = next
+				i++
+			}
+		} else if (arg.startsWith('-') && arg.length === 2) {
+			const key = arg.slice(1)
+			const next = argv[i + 1]
+			if (!next || next.startsWith('-')) {
+				args.flags[key] = true
+			} else {
+				args.flags[key] = next
+				i++
+			}
+		} else {
+			args._.push(arg)
+		}
+		i++
+	}
+	return args
+}
+
+const SHORT_FLAGS = {
+	g: 'global',
+	y: 'yes',
+}
+
+const normalize_flags = (flags) => {
+	const normalized = {}
+	for (const [key, val] of Object.entries(flags)) {
+		const long_name = SHORT_FLAGS[key] || key
+		normalized[long_name] = val
+	}
+	return normalized
+}
+
+const show_version = () => {
+	console.log(`happyskills v${CLI_VERSION}`)
+}
+
+const show_help = () => {
+	print_help(`happyskills v${CLI_VERSION} — Package manager for AI agent skills
+
+Usage: happyskills <command> [options]
+
+Commands:
+  init [name]              Scaffold SKILL.md + skill.json
+  install [owner/skill]    Install skill + dependencies (alias: i, add)
+  uninstall <owner/skill>  Remove skill + prune orphans (alias: rm, remove)
+  list                     List installed skills (alias: ls)
+  search <query>           Search the registry (alias: s)
+  check [owner/skill]      Check for available updates
+  update [owner/skill]     Upgrade to latest versions (alias: up)
+  publish                  Push skill to registry (alias: pub)
+  fork <owner/skill>       Fork a skill to your workspace
+  login                    Authenticate with the registry
+  logout                   Clear stored credentials
+  whoami                   Show current user
+
+Global flags:
+  --help                   Show help for a command
+  --version                Show CLI version
+  -y, --yes                Skip confirmation prompts
+  --json                   Output as JSON (list, search, check)`)
+}
+
+const run = (argv) => {
+	const args = parse_args(argv)
+	args.flags = normalize_flags(args.flags)
+
+	if (args.flags.version) {
+		show_version()
+		return process.exit(EXIT_CODES.SUCCESS)
+	}
+
+	const command_name = args._.shift()
+
+	if (!command_name || args.flags.help && !command_name) {
+		show_help()
+		return process.exit(EXIT_CODES.SUCCESS)
+	}
+
+	const resolved = COMMAND_ALIASES[command_name] || command_name
+
+	if (!COMMANDS.includes(resolved)) {
+		print_error(`Unknown command: ${command_name}`)
+		console.error(`Run 'happyskills --help' for usage information.`)
+		return process.exit(EXIT_CODES.USAGE)
+	}
+
+	if (args.flags.help) {
+		args.flags._show_help = true
+	}
+
+	const command_module = require(`./commands/${resolved}`)
+	const result = command_module.run(args)
+
+	if (result && typeof result.then === 'function') {
+		result.catch((err) => {
+			const { exit_with_error } = require('./utils/errors')
+			exit_with_error(err)
+		})
+	}
+}
+
+module.exports = { run, parse_args }

package/src/index.test.js

@@ -0,0 +1,63 @@
+const { describe, it } = require('node:test')
+const assert = require('node:assert')
+const { parse_args } = require('./index')
+
+describe('parse_args', () => {
+	it('parses positional arguments', () => {
+		const result = parse_args(['install', 'acme/deploy-aws'])
+		assert.deepStrictEqual(result._, ['install', 'acme/deploy-aws'])
+		assert.deepStrictEqual(result.flags, {})
+	})
+
+	it('parses long boolean flags', () => {
+		const result = parse_args(['--force'])
+		assert.deepStrictEqual(result._, [])
+		assert.strictEqual(result.flags.force, true)
+	})
+
+	it('parses long flags with values', () => {
+		const result = parse_args(['--version', '1.2.0'])
+		assert.strictEqual(result.flags.version, '1.2.0')
+		assert.deepStrictEqual(result._, [])
+	})
+
+	it('parses short boolean flags', () => {
+		const result = parse_args(['-g'])
+		assert.strictEqual(result.flags.g, true)
+	})
+
+	it('parses short flags with values', () => {
+		const result = parse_args(['-v', '1.0.0'])
+		assert.strictEqual(result.flags.v, '1.0.0')
+	})
+
+	it('treats flag followed by another flag as boolean', () => {
+		const result = parse_args(['--force', '--yes'])
+		assert.strictEqual(result.flags.force, true)
+		assert.strictEqual(result.flags.yes, true)
+	})
+
+	it('mixes positionals and flags', () => {
+		const result = parse_args(['install', 'acme/deploy-aws', '--version', '1.0.0', '-g'])
+		assert.deepStrictEqual(result._, ['install', 'acme/deploy-aws'])
+		assert.strictEqual(result.flags.version, '1.0.0')
+		assert.strictEqual(result.flags.g, true)
+	})
+
+	it('returns empty result for no arguments', () => {
+		const result = parse_args([])
+		assert.deepStrictEqual(result._, [])
+		assert.deepStrictEqual(result.flags, {})
+	})
+
+	it('treats short flag at end as boolean', () => {
+		const result = parse_args(['install', '-y'])
+		assert.deepStrictEqual(result._, ['install'])
+		assert.strictEqual(result.flags.y, true)
+	})
+
+	it('treats long flag at end as boolean', () => {
+		const result = parse_args(['--json'])
+		assert.strictEqual(result.flags.json, true)
+	})
+})

package/src/lock/integrity.js

@@ -0,0 +1,54 @@
+const crypto = require('crypto')
+const fs = require('fs')
+const path = require('path')
+const { error: { catch_errors } } = require('puffy-core')
+
+const hash_file = (file_path) => catch_errors(`Failed to hash file ${file_path}`, async () => {
+	const content = await fs.promises.readFile(file_path)
+	return crypto.createHash('sha256').update(content).digest('hex')
+})
+
+const hash_directory = (dir_path) => catch_errors(`Failed to hash directory ${dir_path}`, async () => {
+	const hash = crypto.createHash('sha256')
+	const entries = await collect_files(dir_path)
+
+	entries.sort((a, b) => a.relative.localeCompare(b.relative))
+
+	for (const entry of entries) {
+		hash.update(entry.relative)
+		const content = await fs.promises.readFile(entry.absolute)
+		hash.update(content)
+	}
+
+	return `sha256-${hash.digest('hex')}`
+})
+
+const collect_files = async (dir_path, base_path = dir_path) => {
+	const entries = await fs.promises.readdir(dir_path, { withFileTypes: true })
+	const files = []
+
+	for (const entry of entries) {
+		const full_path = path.join(dir_path, entry.name)
+		if (entry.name.startsWith('.')) continue
+
+		if (entry.isDirectory()) {
+			const sub_files = await collect_files(full_path, base_path)
+			files.push(...sub_files)
+		} else if (entry.isFile()) {
+			files.push({
+				relative: path.relative(base_path, full_path),
+				absolute: full_path
+			})
+		}
+	}
+
+	return files
+}
+
+const verify_integrity = (dir_path, expected_hash) => catch_errors('Integrity verification failed', async () => {
+	const [errors, actual_hash] = await hash_directory(dir_path)
+	if (errors) throw errors[0]
+	return actual_hash === expected_hash
+})
+
+module.exports = { hash_file, hash_directory, verify_integrity }

package/src/lock/reader.js

@@ -0,0 +1,29 @@
+const { error: { catch_errors } } = require('puffy-core')
+const { read_json } = require('../utils/fs')
+const { lock_file_path } = require('../config/paths')
+const { LOCK_VERSION } = require('../constants')
+
+const read_lock = (project_root) => catch_errors('Failed to read lock file', async () => {
+	const lock_path = lock_file_path(project_root)
+	const [errors, data] = await read_json(lock_path)
+	if (errors) return null
+
+	if (data.lockVersion !== LOCK_VERSION) {
+		const { print_warn } = require('../ui/output')
+		print_warn(`Lock file version mismatch (found ${data.lockVersion}, expected ${LOCK_VERSION}). Consider running with --fresh.`)
+	}
+
+	return data
+})
+
+const get_locked_skill = (lock_data, skill_name) => {
+	if (!lock_data || !lock_data.skills) return null
+	return lock_data.skills[skill_name] || null
+}
+
+const get_all_locked_skills = (lock_data) => {
+	if (!lock_data || !lock_data.skills) return {}
+	return lock_data.skills
+}
+
+module.exports = { read_lock, get_locked_skill, get_all_locked_skills }

package/src/lock/writer.js

@@ -0,0 +1,31 @@
+const { error: { catch_errors } } = require('puffy-core')
+const { atomic_write_json } = require('../utils/fs')
+const { lock_file_path } = require('../config/paths')
+const { LOCK_VERSION } = require('../constants')
+
+const write_lock = (project_root, skills) => catch_errors('Failed to write lock file', async () => {
+	const lock_path = lock_file_path(project_root)
+	const lock_data = {
+		lockVersion: LOCK_VERSION,
+		generatedAt: new Date().toISOString(),
+		skills: skills || {}
+	}
+	const [errors] = await atomic_write_json(lock_path, lock_data)
+	if (errors) throw errors[0]
+})
+
+const update_lock_skills = (existing_lock, updates) => {
+	const skills = { ...(existing_lock?.skills || {}) }
+
+	for (const [name, data] of Object.entries(updates)) {
+		if (data === null) {
+			delete skills[name]
+		} else {
+			skills[name] = data
+		}
+	}
+
+	return skills
+}
+
+module.exports = { write_lock, update_lock_skills }

package/src/lock/writer.test.js

@@ -0,0 +1,74 @@
+const { describe, it } = require('node:test')
+const assert = require('node:assert')
+const { update_lock_skills } = require('./writer')
+
+describe('update_lock_skills', () => {
+	it('adds new skills to empty lock', () => {
+		const result = update_lock_skills(null, {
+			'acme/deploy': { version: '1.0.0', requested_by: ['__root__'] }
+		})
+		assert.deepStrictEqual(result, {
+			'acme/deploy': { version: '1.0.0', requested_by: ['__root__'] }
+		})
+	})
+
+	it('merges new skills into existing lock', () => {
+		const existing = {
+			skills: {
+				'acme/deploy': { version: '1.0.0', requested_by: ['__root__'] }
+			}
+		}
+		const result = update_lock_skills(existing, {
+			'acme/auth': { version: '2.0.0', requested_by: ['acme/deploy'] }
+		})
+		assert.ok(result['acme/deploy'])
+		assert.ok(result['acme/auth'])
+		assert.strictEqual(result['acme/auth'].version, '2.0.0')
+	})
+
+	it('removes skills when set to null', () => {
+		const existing = {
+			skills: {
+				'acme/deploy': { version: '1.0.0' },
+				'acme/auth': { version: '2.0.0' }
+			}
+		}
+		const result = update_lock_skills(existing, {
+			'acme/deploy': null
+		})
+		assert.strictEqual(result['acme/deploy'], undefined)
+		assert.ok(result['acme/auth'])
+	})
+
+	it('overwrites existing skill data', () => {
+		const existing = {
+			skills: {
+				'acme/deploy': { version: '1.0.0', requested_by: ['__root__'] }
+			}
+		}
+		const result = update_lock_skills(existing, {
+			'acme/deploy': { version: '2.0.0', requested_by: ['__root__'] }
+		})
+		assert.strictEqual(result['acme/deploy'].version, '2.0.0')
+	})
+
+	it('handles empty updates', () => {
+		const existing = {
+			skills: {
+				'acme/deploy': { version: '1.0.0' }
+			}
+		}
+		const result = update_lock_skills(existing, {})
+		assert.deepStrictEqual(result, { 'acme/deploy': { version: '1.0.0' } })
+	})
+
+	it('does not mutate the original lock data', () => {
+		const existing = {
+			skills: {
+				'acme/deploy': { version: '1.0.0' }
+			}
+		}
+		update_lock_skills(existing, { 'acme/deploy': null })
+		assert.ok(existing.skills['acme/deploy'])
+	})
+})

package/src/manifest/reader.js

@@ -0,0 +1,13 @@
+const path = require('path')
+const { error: { catch_errors } } = require('puffy-core')
+const { read_json } = require('../utils/fs')
+const { SKILL_JSON } = require('../constants')
+
+const read_manifest = (dir = process.cwd()) => catch_errors('Failed to read skill.json', async () => {
+	const manifest_path = path.join(dir, SKILL_JSON)
+	const [errors, data] = await read_json(manifest_path)
+	if (errors) throw new Error(`No ${SKILL_JSON} found in ${dir}. Run 'happyskills init' to create one.`)
+	return data
+})
+
+module.exports = { read_manifest }

package/src/manifest/validator.js

@@ -0,0 +1,44 @@
+const { valid } = require('../utils/semver')
+
+const REQUIRED_FIELDS = ['name', 'version']
+const NAME_PATTERN = /^[a-z0-9][a-z0-9_-]*$/
+
+const validate_manifest = (manifest) => {
+	const errors = []
+
+	for (const field of REQUIRED_FIELDS) {
+		if (!manifest[field]) {
+			errors.push(`Missing required field: ${field}`)
+		}
+	}
+
+	if (manifest.name && !NAME_PATTERN.test(manifest.name)) {
+		errors.push(`Invalid name "${manifest.name}". Use lowercase letters, numbers, hyphens, and underscores. Must start with a letter or number.`)
+	}
+
+	if (manifest.version && !valid(manifest.version)) {
+		errors.push(`Invalid version "${manifest.version}". Must be valid semver (e.g., 1.0.0).`)
+	}
+
+	if (manifest.dependencies) {
+		if (typeof manifest.dependencies !== 'object' || Array.isArray(manifest.dependencies)) {
+			errors.push('dependencies must be an object mapping skill names to version ranges.')
+		} else {
+			for (const [dep, range] of Object.entries(manifest.dependencies)) {
+				if (!dep.includes('/')) {
+					errors.push(`Invalid dependency "${dep}". Must be in owner/name format.`)
+				}
+				if (typeof range !== 'string') {
+					errors.push(`Invalid version range for "${dep}". Must be a string.`)
+				}
+			}
+		}
+	}
+
+	return {
+		valid: errors.length === 0,
+		errors
+	}
+}
+
+module.exports = { validate_manifest }