happyskills 1.16.3 → 1.17.0

package/src/validation/skill_json_rules.js

@@ -7,6 +7,7 @@ const { SKILL_JSON, VALID_SKILL_TYPES, SKILL_TYPES, KIT_PREFIX } = require('../c
 const NAME_PATTERN = /^[a-z0-9][a-z0-9_-]*$/
 const KIT_NAME_PATTERN = /^_kit-[a-z0-9][a-z0-9-]*$/
 const REQUIRED_PLATFORMS = ['darwin', 'linux', 'win32']
+const CONFIG_TYPES = ['string', 'integer', 'number', 'boolean']
 
 const result = (field, rule, severity, message, value) => ({
 	file: SKILL_JSON, field, rule, severity, message, ...(value !== undefined ? { value } : {})
@@ -180,6 +181,102 @@ const validate_system_dependencies = (manifest) => {
 	return results
 }
 
+// config: map of field -> { type, default?, description?, required? }. Non-secret,
+// typed tunables that override the skill's hardcoded defaults. `type` is required.
+const validate_config = (manifest) => {
+	const results = []
+	const config = manifest.config
+
+	if (config === undefined) return results
+
+	if (typeof config !== 'object' || Array.isArray(config)) {
+		results.push(result('config', 'type', 'error', 'config must be an object'))
+		return results
+	}
+
+	for (const [key, entry] of Object.entries(config)) {
+		if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+			results.push(result('config', 'entry_structure', 'error', `config field "${key}" must be an object`, key))
+			continue
+		}
+
+		if (!CONFIG_TYPES.includes(entry.type)) {
+			results.push(result('config', 'type_value', 'error', `config field "${key}" must declare a "type" of: ${CONFIG_TYPES.join(', ')} — got "${entry.type}"`, key))
+		}
+
+		if (entry.required !== undefined && typeof entry.required !== 'boolean') {
+			results.push(result('config', 'required_flag', 'error', `config field "${key}" "required" must be a boolean`, key))
+		}
+
+		if (entry.description !== undefined && typeof entry.description !== 'string') {
+			results.push(result('config', 'description_type', 'error', `config field "${key}" "description" must be a string`, key))
+		}
+	}
+
+	return results
+}
+
+// env: map of VAR_NAME -> { required?, secret?, description?, type?, default?, validate? }.
+// `required: true` entries are the activation gate. Secrets are routed to the .env, never
+// committed — so a secret with an inline default is a warning, not a hard error.
+const validate_env = (manifest) => {
+	const results = []
+	const env = manifest.env
+
+	if (env === undefined) return results
+
+	if (typeof env !== 'object' || Array.isArray(env)) {
+		results.push(result('env', 'type', 'error', 'env must be an object'))
+		return results
+	}
+
+	const seen_lower = new Map()
+
+	for (const [key, entry] of Object.entries(env)) {
+		if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+			results.push(result('env', 'entry_structure', 'error', `env var "${key}" must be an object`, key))
+			continue
+		}
+
+		if (entry.required !== undefined && typeof entry.required !== 'boolean') {
+			results.push(result('env', 'required_flag', 'error', `env var "${key}" "required" must be a boolean`, key))
+		}
+
+		if (entry.secret !== undefined && typeof entry.secret !== 'boolean') {
+			results.push(result('env', 'secret_flag', 'error', `env var "${key}" "secret" must be a boolean`, key))
+		}
+
+		if (entry.secret === true && entry.default !== undefined) {
+			results.push(result('env', 'secret_default', 'warning', `env var "${key}" is secret but carries a committed default — secret fields must not carry a committed default`, key))
+		}
+
+		if (entry.type !== undefined && !CONFIG_TYPES.includes(entry.type)) {
+			results.push(result('env', 'type_value', 'error', `env var "${key}" has unknown type "${entry.type}" (allowed: ${CONFIG_TYPES.join(', ')})`, key))
+		}
+
+		if (entry.validate !== undefined) {
+			if (typeof entry.validate !== 'string') {
+				results.push(result('env', 'validate_regex', 'error', `env var "${key}" "validate" must be a string regex`, key))
+			} else {
+				try {
+					new RegExp(entry.validate)
+				} catch (err) {
+					results.push(result('env', 'validate_regex', 'error', `env var "${key}" "validate" is not a valid regex: ${err.message}`, key))
+				}
+			}
+		}
+
+		const lower = key.toLowerCase()
+		if (seen_lower.has(lower)) {
+			results.push(result('env', 'case_collision', 'error', `env var "${key}" collides case-insensitively with "${seen_lower.get(lower)}" — env names must be unique regardless of case`, key))
+		} else {
+			seen_lower.set(lower, key)
+		}
+	}
+
+	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)
@@ -209,6 +306,8 @@ const validate_skill_json = (skill_dir) => catch_errors('Failed to validate skil
 	results.push(...validate_description(manifest))
 	results.push(...validate_dependencies(manifest))
 	results.push(...validate_system_dependencies(manifest))
+	results.push(...validate_config(manifest))
+	results.push(...validate_env(manifest))
 
 	const is_kit = manifest.type === SKILL_TYPES.KIT
 	if (is_kit) {

package/src/validation/skill_json_rules.test.js

@@ -334,3 +334,133 @@ describe('validate_skill_json — systemDependencies', () => {
 		assert.strictEqual(check.severity, 'pass')
 	})
 })
+
+describe('validate_skill_json — config schema', () => {
+	it('errors when config is an array', async () => {
+		write_json(tmp, { name: 'my-skill', version: '1.0.0', config: [] })
+		const [err, data] = await validate_skill_json(tmp)
+		assert.ifError(err)
+		const check = data.results.find(r => r.field === 'config' && r.rule === 'type')
+		assert.strictEqual(check.severity, 'error')
+	})
+
+	it('errors when a config field has an unknown type', async () => {
+		write_json(tmp, {
+			name: 'my-skill', version: '1.0.0',
+			config: { channel: { type: 'colour', default: '#general' } }
+		})
+		const [err, data] = await validate_skill_json(tmp)
+		assert.ifError(err)
+		const check = data.results.find(r => r.field === 'config' && r.rule === 'type_value')
+		assert.strictEqual(check.severity, 'error')
+		assert.ok(check.message.includes('colour'))
+	})
+
+	it('errors when a config field omits type', async () => {
+		write_json(tmp, {
+			name: 'my-skill', version: '1.0.0',
+			config: { channel: { default: '#general' } }
+		})
+		const [err, data] = await validate_skill_json(tmp)
+		assert.ifError(err)
+		const check = data.results.find(r => r.field === 'config' && r.rule === 'type_value')
+		assert.strictEqual(check.severity, 'error')
+	})
+
+	it('errors when a config field required flag is non-boolean', async () => {
+		write_json(tmp, {
+			name: 'my-skill', version: '1.0.0',
+			config: { channel: { type: 'string', required: 'yes' } }
+		})
+		const [err, data] = await validate_skill_json(tmp)
+		assert.ifError(err)
+		const check = data.results.find(r => r.field === 'config' && r.rule === 'required_flag')
+		assert.strictEqual(check.severity, 'error')
+	})
+})
+
+describe('validate_skill_json — env schema', () => {
+	it('errors when env is an array', async () => {
+		write_json(tmp, { name: 'my-skill', version: '1.0.0', env: [] })
+		const [err, data] = await validate_skill_json(tmp)
+		assert.ifError(err)
+		const check = data.results.find(r => r.field === 'env' && r.rule === 'type')
+		assert.strictEqual(check.severity, 'error')
+	})
+
+	it('errors when required is non-boolean', async () => {
+		write_json(tmp, {
+			name: 'my-skill', version: '1.0.0',
+			env: { SLACK_BOT_TOKEN: { required: 'true', secret: true } }
+		})
+		const [err, data] = await validate_skill_json(tmp)
+		assert.ifError(err)
+		const check = data.results.find(r => r.field === 'env' && r.rule === 'required_flag')
+		assert.strictEqual(check.severity, 'error')
+	})
+
+	it('errors when secret is non-boolean', async () => {
+		write_json(tmp, {
+			name: 'my-skill', version: '1.0.0',
+			env: { SLACK_BOT_TOKEN: { required: true, secret: 'yes' } }
+		})
+		const [err, data] = await validate_skill_json(tmp)
+		assert.ifError(err)
+		const check = data.results.find(r => r.field === 'env' && r.rule === 'secret_flag')
+		assert.strictEqual(check.severity, 'error')
+	})
+
+	it('warns when a secret env var carries an inline default', async () => {
+		write_json(tmp, {
+			name: 'my-skill', version: '1.0.0',
+			env: { SLACK_BOT_TOKEN: { required: true, secret: true, default: 'xoxb-hardcoded' } }
+		})
+		const [err, data] = await validate_skill_json(tmp)
+		assert.ifError(err)
+		const check = data.results.find(r => r.field === 'env' && r.rule === 'secret_default')
+		assert.strictEqual(check.severity, 'warning')
+	})
+
+	it('errors when a validate regex does not compile', async () => {
+		write_json(tmp, {
+			name: 'my-skill', version: '1.0.0',
+			env: { DEPLOY_TIMEOUT: { type: 'integer', validate: '([0-9' } }
+		})
+		const [err, data] = await validate_skill_json(tmp)
+		assert.ifError(err)
+		const check = data.results.find(r => r.field === 'env' && r.rule === 'validate_regex')
+		assert.strictEqual(check.severity, 'error')
+	})
+
+	it('errors when two env vars differ only by case', async () => {
+		write_json(tmp, {
+			name: 'my-skill', version: '1.0.0',
+			env: { TOKEN: { required: true }, token: { required: false } }
+		})
+		const [err, data] = await validate_skill_json(tmp)
+		assert.ifError(err)
+		const check = data.results.find(r => r.field === 'env' && r.rule === 'case_collision')
+		assert.strictEqual(check.severity, 'error')
+	})
+})
+
+describe('validate_skill_json — well-formed config + env', () => {
+	it('emits no error or warning results for a well-formed config + env block', async () => {
+		write_json(tmp, {
+			name: 'slack-notify', version: '1.0.0',
+			config: {
+				channel: { type: 'string', default: '#general', description: 'Channel to post to' },
+				max_chars: { type: 'integer', default: 500, description: 'Truncate longer messages' }
+			},
+			env: {
+				SLACK_BOT_TOKEN: { required: true, secret: true, description: 'Slack bot token' },
+				DEPLOY_TIMEOUT: { required: false, secret: false, type: 'integer', default: 300, validate: '^[0-9]+$' }
+			}
+		})
+		const [err, data] = await validate_skill_json(tmp)
+		assert.ifError(err)
+		const config_env_problems = data.results.filter(r =>
+			(r.field === 'config' || r.field === 'env') && (r.severity === 'error' || r.severity === 'warning'))
+		assert.deepStrictEqual(config_env_problems, [])
+	})
+})