happyskills 0.7.3 → 0.9.0

package/src/integration/cli.test.js

@@ -92,7 +92,7 @@ describe('CLI — global flags', () => {
 
 	it('--help lists all expected commands', () => {
 		const { stdout } = run(['--help'])
-		const expected_commands = ['install', 'uninstall', 'list', 'search', 'check', 'update', 'publish', 'fork', 'login', 'logout', 'whoami', 'init', 'setup', 'self-update']
+		const expected_commands = ['install', 'uninstall', 'list', 'search', 'check', 'refresh', 'update', 'publish', 'validate', 'fork', 'login', 'logout', 'whoami', 'init', 'setup', 'self-update']
 		for (const cmd of expected_commands) {
 			assert.ok(stdout.includes(cmd), `help output should mention "${cmd}"`)
 		}
@@ -160,8 +160,14 @@ describe('CLI — command --help', () => {
 		['search',    'Arguments:'],
 		['search',    'Aliases:'],
 		['check',     'Examples:'],
+		['refresh',   'Options:'],
+		['refresh',   'Examples:'],
+		['refresh',   'Aliases:'],
 		['update',    'Aliases:'],
 		['publish',   'Aliases:'],
+		['validate',  'Arguments:'],
+		['validate',  'Aliases:'],
+		['validate',  'Examples:'],
 		['fork',      'Arguments:'],
 		['init',          'Examples:'],
 		['setup',         'Options:'],
@@ -193,8 +199,10 @@ describe('CLI — command aliases', () => {
 		['remove', 'uninstall'],
 		['ls',     'list'],
 		['s',      'search'],
+		['r',      'refresh'],
 		['up',     'update'],
 		['pub',    'publish'],
+		['v',      'validate'],
 	]
 
 	for (const [alias, canonical] of alias_cases) {
@@ -412,6 +420,24 @@ describe('CLI — --json: existing json commands now use { data } envelope', ()
 	})
 })
 
+// ─── refresh command ──────────────────────────────────────────────────────────
+
+describe('CLI — --json: refresh command', () => {
+	it('refresh --json with no skills returns { data: { results, outdated_count, ... } }', () => {
+		const tmp = make_tmp()
+		try {
+			const { stdout, code } = run(['refresh', '--json'], {}, { cwd: tmp })
+			assert.strictEqual(code, 0)
+			const out = parse_json_output(stdout, 'refresh --json empty')
+			assert.ok('data' in out)
+			assert.ok(Array.isArray(out.data.results))
+			assert.strictEqual(out.data.outdated_count, 0)
+		} finally {
+			fs.rmSync(tmp, { recursive: true, force: true })
+		}
+	})
+})
+
 // ─── setup command ─────────────────────────────────────────────────────────────
 
 describe('CLI — setup command', () => {
@@ -456,3 +482,127 @@ describe('CLI — self-update command', () => {
 		assert.strictEqual(out.error.exit_code, 4)
 	})
 })
+
+// ─── validate command ─────────────────────────────────────────────────────────
+
+describe('CLI — validate command', () => {
+	it('validate --help exits 0 and shows usage', () => {
+		const { stdout, code } = run(['validate', '--help'])
+		assert.strictEqual(code, 0)
+		assert.ok(stdout.includes('Arguments:'))
+		assert.ok(stdout.includes('Aliases:'))
+		assert.ok(stdout.includes('Examples:'))
+	})
+
+	it('v alias resolves to validate (shows correct --help)', () => {
+		const { stdout, code } = run(['v', '--help'])
+		assert.strictEqual(code, 0)
+		assert.ok(stdout.toLowerCase().includes('validate'))
+	})
+
+	it('exits 2 when no skill name is given', () => {
+		const { stderr, code } = run(['validate'])
+		assert.strictEqual(code, 2)
+		assert.ok(stderr.includes('Skill name required'))
+	})
+
+	it('exits 2 when skill does not exist', () => {
+		const tmp = make_tmp()
+		try {
+			const { code } = run(['validate', 'nonexistent'], {}, { cwd: tmp })
+			assert.strictEqual(code, 2)
+		} finally {
+			fs.rmSync(tmp, { recursive: true, force: true })
+		}
+	})
+
+	it('exits 2 (JSON) when skill does not exist', () => {
+		const tmp = make_tmp()
+		try {
+			const { stdout, code } = run(['validate', 'nonexistent', '--json'], {}, { cwd: tmp })
+			assert.strictEqual(code, 2)
+			const out = parse_json_output(stdout, 'validate nonexistent --json')
+			assert.ok('error' in out)
+			assert.strictEqual(out.error.code, 'USAGE_ERROR')
+		} finally {
+			fs.rmSync(tmp, { recursive: true, force: true })
+		}
+	})
+
+	it('exits 0 for a valid skill and reports all checks passed', () => {
+		const tmp = make_tmp()
+		const skill_dir = path.join(tmp, '.claude', 'skills', 'test-skill')
+		fs.mkdirSync(skill_dir, { recursive: true })
+		fs.writeFileSync(path.join(skill_dir, 'SKILL.md'), '---\nname: test-skill\ndescription: A valid test skill for unit testing\n---\n\n# Test Skill\n')
+		fs.writeFileSync(path.join(skill_dir, 'skill.json'), JSON.stringify({
+			name: 'test-skill', version: '1.0.0', description: 'A test skill',
+			keywords: ['testing']
+		}, null, '\t'))
+		try {
+			const { stdout, code } = run(['validate', 'test-skill'], {}, { cwd: tmp })
+			assert.strictEqual(code, 0)
+			assert.ok(stdout.includes('test-skill'))
+		} finally {
+			fs.rmSync(tmp, { recursive: true, force: true })
+		}
+	})
+
+	it('exits 1 for an invalid skill', () => {
+		const tmp = make_tmp()
+		const skill_dir = path.join(tmp, '.claude', 'skills', 'bad-skill')
+		fs.mkdirSync(skill_dir, { recursive: true })
+		fs.writeFileSync(path.join(skill_dir, 'SKILL.md'), '---\nname: bad-skill\n---\n')
+		fs.writeFileSync(path.join(skill_dir, 'skill.json'), JSON.stringify({ name: 'bad-skill' }, null, '\t'))
+		try {
+			const { code } = run(['validate', 'bad-skill'], {}, { cwd: tmp })
+			assert.strictEqual(code, 1)
+		} finally {
+			fs.rmSync(tmp, { recursive: true, force: true })
+		}
+	})
+
+	it('--json returns correct schema for a valid skill', () => {
+		const tmp = make_tmp()
+		const skill_dir = path.join(tmp, '.claude', 'skills', 'test-skill')
+		fs.mkdirSync(skill_dir, { recursive: true })
+		fs.writeFileSync(path.join(skill_dir, 'SKILL.md'), '---\nname: test-skill\ndescription: A valid test skill for unit testing\n---\n\n# Test\n')
+		fs.writeFileSync(path.join(skill_dir, 'skill.json'), JSON.stringify({
+			name: 'test-skill', version: '1.0.0', description: 'A test skill',
+			keywords: ['testing']
+		}, null, '\t'))
+		try {
+			const { stdout, code } = run(['validate', 'test-skill', '--json'], {}, { cwd: tmp })
+			assert.strictEqual(code, 0)
+			const out = parse_json_output(stdout, 'validate --json valid skill')
+			assert.ok('data' in out)
+			assert.strictEqual(out.data.skill, 'test-skill')
+			assert.strictEqual(out.data.valid, true)
+			assert.ok(Array.isArray(out.data.errors))
+			assert.ok(Array.isArray(out.data.warnings))
+			assert.strictEqual(typeof out.data.checks_passed, 'number')
+			assert.strictEqual(typeof out.data.checks_failed, 'number')
+			assert.strictEqual(typeof out.data.checks_warned, 'number')
+			assert.strictEqual(out.data.checks_failed, 0)
+		} finally {
+			fs.rmSync(tmp, { recursive: true, force: true })
+		}
+	})
+
+	it('--json returns errors for an invalid skill', () => {
+		const tmp = make_tmp()
+		const skill_dir = path.join(tmp, '.claude', 'skills', 'bad-skill')
+		fs.mkdirSync(skill_dir, { recursive: true })
+		fs.writeFileSync(path.join(skill_dir, 'SKILL.md'), '---\nname: bad-skill\n---\n')
+		fs.writeFileSync(path.join(skill_dir, 'skill.json'), JSON.stringify({ name: 'bad-skill' }, null, '\t'))
+		try {
+			const { stdout, code } = run(['validate', 'bad-skill', '--json'], {}, { cwd: tmp })
+			assert.strictEqual(code, 1)
+			const out = parse_json_output(stdout, 'validate --json invalid skill')
+			assert.strictEqual(out.data.valid, false)
+			assert.ok(out.data.errors.length > 0)
+			assert.ok(out.data.checks_failed > 0)
+		} finally {
+			fs.rmSync(tmp, { recursive: true, force: true })
+		}
+	})
+})

package/src/validation/cross_rules.js

@@ -0,0 +1,76 @@
+const fs = require('fs')
+const path = require('path')
+const { error: { catch_errors } } = require('puffy-core')
+
+const EXEC_LANGS = new Set(['python', 'bash', 'sh', 'javascript', 'js', 'typescript', 'ts', 'ruby', 'go', 'rust'])
+const SCRIPT_MARKERS = /^\s*(#!\/|import |from |require\(|def |class |function |const |let |var |export |module\.|package |fn |func |pub fn)/
+
+const result = (file, field, rule, severity, message, value) => ({
+	file, field, rule, severity, message, ...(value !== undefined ? { value } : {})
+})
+
+const scan_code_blocks = (content, file_label) => {
+	const results = []
+	const block_rx = /```(\w+)?\n([\s\S]*?)```/g
+	let match
+
+	while ((match = block_rx.exec(content)) !== null) {
+		const lang = (match[1] || '').toLowerCase()
+		if (!EXEC_LANGS.has(lang)) continue
+
+		const body = match[2]
+		const lines = body.split('\n')
+		const line_count = lines.filter(l => l.trim()).length
+		const marker_count = lines.filter(l => SCRIPT_MARKERS.test(l)).length
+
+		if (marker_count >= 2 || line_count > 10) {
+			results.push(result(file_label, null, 'no_executable_code', 'warning',
+				`Found ${lang} code block (${line_count} lines) that looks like an executable script — consider moving to scripts/`,
+				lang
+			))
+		}
+	}
+
+	return results
+}
+
+const validate_cross = (skill_dir, frontmatter, manifest, skill_md_content) => catch_errors('Failed cross-file validation', async () => {
+	const results = []
+
+	// Name match
+	if (frontmatter && manifest) {
+		if (frontmatter.name !== manifest.name) {
+			results.push(result('Cross-file', 'name', 'name_match', 'warning',
+				`SKILL.md name "${frontmatter.name}" does not match skill.json name "${manifest.name}"`,
+				`${frontmatter.name} vs ${manifest.name}`
+			))
+		} else {
+			results.push(result('Cross-file', 'name', 'name_match', 'pass',
+				`Names match: "${frontmatter.name}"`
+			))
+		}
+	}
+
+	// Executable code in SKILL.md
+	if (skill_md_content) {
+		results.push(...scan_code_blocks(skill_md_content, 'SKILL.md'))
+	}
+
+	// Executable code in references/*.md
+	const refs_dir = path.join(skill_dir, 'references')
+	try {
+		const entries = await fs.promises.readdir(refs_dir, { withFileTypes: true })
+		for (const entry of entries) {
+			if (!entry.isFile() || !entry.name.endsWith('.md')) continue
+			const ref_path = path.join(refs_dir, entry.name)
+			const ref_content = await fs.promises.readFile(ref_path, 'utf-8')
+			results.push(...scan_code_blocks(ref_content, `references/${entry.name}`))
+		}
+	} catch {
+		// No references dir — that's fine
+	}
+
+	return results
+})
+
+module.exports = { validate_cross }

package/src/validation/cross_rules.test.js

@@ -0,0 +1,88 @@
+'use strict'
+const { describe, it, beforeEach, afterEach } = require('node:test')
+const assert = require('node:assert/strict')
+const fs = require('fs')
+const os = require('os')
+const path = require('path')
+
+const { validate_cross } = require('./cross_rules')
+
+const make_tmp = () => fs.mkdtempSync(path.join(os.tmpdir(), 'hs-validate-cross-'))
+
+let tmp
+beforeEach(() => { tmp = make_tmp() })
+afterEach(() => { fs.rmSync(tmp, { recursive: true, force: true }) })
+
+describe('validate_cross — name match', () => {
+	it('passes when names match', async () => {
+		const [err, results] = await validate_cross(tmp, { name: 'my-skill' }, { name: 'my-skill' }, '')
+		assert.ifError(err)
+		const check = results.find(r => r.rule === 'name_match')
+		assert.strictEqual(check.severity, 'pass')
+	})
+
+	it('warns when names differ', async () => {
+		const [err, results] = await validate_cross(tmp, { name: 'skill-a' }, { name: 'skill-b' }, '')
+		assert.ifError(err)
+		const check = results.find(r => r.rule === 'name_match')
+		assert.strictEqual(check.severity, 'warning')
+		assert.ok(check.message.includes('skill-a'))
+		assert.ok(check.message.includes('skill-b'))
+	})
+
+	it('skips name match when frontmatter is null', async () => {
+		const [err, results] = await validate_cross(tmp, null, { name: 'my-skill' }, '')
+		assert.ifError(err)
+		assert.ok(!results.some(r => r.rule === 'name_match'))
+	})
+
+	it('skips name match when manifest is null', async () => {
+		const [err, results] = await validate_cross(tmp, { name: 'my-skill' }, null, '')
+		assert.ifError(err)
+		assert.ok(!results.some(r => r.rule === 'name_match'))
+	})
+})
+
+describe('validate_cross — executable code detection', () => {
+	it('warns for a long python code block in SKILL.md', async () => {
+		const code_block = '```python\nimport os\nimport sys\n' + 'print("hello")\n'.repeat(10) + '```'
+		const [err, results] = await validate_cross(tmp, { name: 'x' }, { name: 'x' }, code_block)
+		assert.ifError(err)
+		const check = results.find(r => r.rule === 'no_executable_code')
+		assert.strictEqual(check.severity, 'warning')
+		assert.ok(check.message.includes('python'))
+	})
+
+	it('does not flag short documentation code blocks', async () => {
+		const code_block = '```python\nprint("hello")\n```'
+		const [err, results] = await validate_cross(tmp, { name: 'x' }, { name: 'x' }, code_block)
+		assert.ifError(err)
+		assert.ok(!results.some(r => r.rule === 'no_executable_code'))
+	})
+
+	it('does not flag non-executable language blocks', async () => {
+		const code_block = '```yaml\nname: test\nversion: 1.0.0\n```'
+		const [err, results] = await validate_cross(tmp, { name: 'x' }, { name: 'x' }, code_block)
+		assert.ifError(err)
+		assert.ok(!results.some(r => r.rule === 'no_executable_code'))
+	})
+
+	it('warns for executable code in references/*.md', async () => {
+		const refs_dir = path.join(tmp, 'references')
+		fs.mkdirSync(refs_dir)
+		const code = '```bash\n#!/bin/bash\nimport os\nset -e\necho "deploy"\n' + 'echo "step"\n'.repeat(8) + '```'
+		fs.writeFileSync(path.join(refs_dir, 'deploy.md'), code)
+
+		const [err, results] = await validate_cross(tmp, { name: 'x' }, { name: 'x' }, '')
+		assert.ifError(err)
+		const check = results.find(r => r.rule === 'no_executable_code' && r.file === 'references/deploy.md')
+		assert.strictEqual(check.severity, 'warning')
+	})
+
+	it('does not error when references dir is missing', async () => {
+		const [err, results] = await validate_cross(tmp, { name: 'x' }, { name: 'x' }, '')
+		assert.ifError(err)
+		// Should not throw or produce error results — just no code block warnings
+		assert.ok(!results.some(r => r.severity === 'error'))
+	})
+})

package/src/validation/skill_json_rules.js

@@ -0,0 +1,202 @@
+const path = require('path')
+const { error: { catch_errors } } = require('puffy-core')
+const { file_exists, read_file } = require('../utils/fs')
+const { valid } = require('../utils/semver')
+const { SKILL_JSON } = require('../constants')
+
+const NAME_PATTERN = /^[a-z0-9][a-z0-9_-]*$/
+const CANONICAL_SLUGS = ['deployment', 'database', 'security', 'ai', 'api', 'monitoring', 'testing', 'devops', 'cloud', 'analytics']
+const REQUIRED_PLATFORMS = ['darwin', 'linux', 'win32']
+
+const result = (field, rule, severity, message, value) => ({
+	file: SKILL_JSON, field, rule, severity, message, ...(value !== undefined ? { value } : {})
+})
+
+const validate_name = (manifest) => {
+	const results = []
+	const name = manifest.name
+
+	if (!name) {
+		results.push(result('name', 'present', 'error', 'skill.json must include a "name" field'))
+		return results
+	}
+
+	results.push(result('name', 'present', 'pass', `name: "${name}"`, name))
+
+	if (!NAME_PATTERN.test(name)) {
+		results.push(result('name', 'format', 'error', 'Name must match /^[a-z0-9][a-z0-9_-]*$/', name))
+	} else {
+		results.push(result('name', 'format', 'pass', 'Name format valid', name))
+	}
+
+	return results
+}
+
+const validate_version = (manifest) => {
+	const results = []
+	const ver = manifest.version
+
+	if (!ver) {
+		results.push(result('version', 'present', 'error', 'skill.json must include a "version" field'))
+		return results
+	}
+
+	results.push(result('version', 'present', 'pass', `version: "${ver}"`, ver))
+
+	if (!valid(ver)) {
+		results.push(result('version', 'valid_semver', 'error', `"${ver}" is not valid semver`, ver))
+	} else {
+		results.push(result('version', 'valid_semver', 'pass', `version "${ver}" is valid semver`, ver))
+	}
+
+	return results
+}
+
+const validate_description = (manifest) => {
+	const results = []
+	const desc = manifest.description
+
+	if (!desc) {
+		results.push(result('description', 'recommended_field', 'warning', 'Description is recommended for registry search'))
+		return results
+	}
+
+	results.push(result('description', 'recommended_field', 'pass', 'Description present'))
+
+	if (desc.length > 200) {
+		results.push(result('description', 'max_length', 'warning', `Description is ${desc.length} chars (recommended max 200)`, desc))
+	} else {
+		results.push(result('description', 'max_length', 'pass', `Description: ${desc.length} chars (max 200)`))
+	}
+
+	return results
+}
+
+const validate_keywords = (manifest) => {
+	const results = []
+	const kw = manifest.keywords
+
+	if (!kw || !Array.isArray(kw)) {
+		results.push(result('keywords', 'recommended_field', 'warning', 'Keywords array is recommended — include at least one canonical slug'))
+		return results
+	}
+
+	results.push(result('keywords', 'recommended_field', 'pass', `keywords: ${kw.length} entries`))
+
+	const has_slug = kw.some(k => CANONICAL_SLUGS.includes(k))
+	if (!has_slug) {
+		results.push(result('keywords', 'canonical_slug', 'warning', `Keywords should include at least one canonical slug: ${CANONICAL_SLUGS.join(', ')}`))
+	} else {
+		results.push(result('keywords', 'canonical_slug', 'pass', 'Contains canonical slug'))
+	}
+
+	return results
+}
+
+const validate_dependencies = (manifest) => {
+	const results = []
+	const deps = manifest.dependencies
+
+	if (deps === undefined) return results
+
+	if (typeof deps !== 'object' || Array.isArray(deps)) {
+		results.push(result('dependencies', 'type', 'error', 'dependencies must be an object (not array)'))
+		return results
+	}
+
+	results.push(result('dependencies', 'type', 'pass', 'dependencies is an object'))
+
+	for (const [key, val] of Object.entries(deps)) {
+		if (!key.includes('/')) {
+			results.push(result('dependencies', 'key_format', 'error', `Dependency key "${key}" must be in owner/name format`, key))
+		}
+		if (typeof val !== 'string') {
+			results.push(result('dependencies', 'value_type', 'error', `Dependency "${key}" value must be a string (semver range)`, String(val)))
+		}
+	}
+
+	const entries = Object.entries(deps)
+	const all_valid = entries.every(([k, v]) => k.includes('/') && typeof v === 'string')
+	if (entries.length > 0 && all_valid) {
+		results.push(result('dependencies', 'entries', 'pass', `${entries.length} dependencies valid`))
+	}
+
+	return results
+}
+
+const validate_system_dependencies = (manifest) => {
+	const results = []
+	const sys = manifest.systemDependencies
+
+	if (sys === undefined) return results
+
+	if (typeof sys !== 'object' || Array.isArray(sys)) {
+		results.push(result('systemDependencies', 'type', 'error', 'systemDependencies must be an object'))
+		return results
+	}
+
+	results.push(result('systemDependencies', 'type', 'pass', 'systemDependencies is an object'))
+
+	for (const [key, entry] of Object.entries(sys)) {
+		if (!entry || typeof entry !== 'object') {
+			results.push(result('systemDependencies', 'entry_structure', 'warning', `"${key}" should be an object with description, check, and install`))
+			continue
+		}
+
+		const has_desc = typeof entry.description === 'string'
+		const has_check = typeof entry.check === 'string'
+		const has_install = entry.install && typeof entry.install === 'object'
+
+		if (!has_desc || !has_check || !has_install) {
+			const missing = [!has_desc && 'description', !has_check && 'check', !has_install && 'install'].filter(Boolean)
+			results.push(result('systemDependencies', 'entry_structure', 'warning', `"${key}" is missing: ${missing.join(', ')}`))
+		}
+
+		if (has_install) {
+			const platforms = Object.keys(entry.install)
+			const missing_platforms = REQUIRED_PLATFORMS.filter(p => !platforms.includes(p))
+			if (missing_platforms.length > 0) {
+				results.push(result('systemDependencies', 'platform_coverage', 'warning', `"${key}" install is missing platforms: ${missing_platforms.join(', ')}`))
+			} else {
+				results.push(result('systemDependencies', 'platform_coverage', 'pass', `"${key}" covers all platforms`))
+			}
+		}
+	}
+
+	return results
+}
+
+const validate_skill_json = (skill_dir) => catch_errors('Failed to validate skill.json', async () => {
+	const results = []
+	const json_path = path.join(skill_dir, SKILL_JSON)
+
+	const [, exists] = await file_exists(json_path)
+	if (!exists) {
+		results.push(result(null, 'exists', 'error', 'skill.json not found'))
+		return { results, manifest: null }
+	}
+
+	results.push(result(null, 'exists', 'pass', 'skill.json exists'))
+
+	const [, raw] = await read_file(json_path)
+	let manifest
+	try {
+		manifest = JSON.parse(raw)
+	} catch (err) {
+		results.push(result(null, 'valid_json', 'error', `Invalid JSON: ${err.message}`))
+		return { results, manifest: null }
+	}
+
+	results.push(result(null, 'valid_json', 'pass', 'Valid JSON'))
+
+	results.push(...validate_name(manifest))
+	results.push(...validate_version(manifest))
+	results.push(...validate_description(manifest))
+	results.push(...validate_keywords(manifest))
+	results.push(...validate_dependencies(manifest))
+	results.push(...validate_system_dependencies(manifest))
+
+	return { results, manifest }
+})
+
+module.exports = { validate_skill_json }