happyskills 1.16.3 → 1.18.0

package/src/skills_config/cleanup.test.js

@@ -0,0 +1,123 @@
+'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 { cleanup_uninstalled_configs, strip_env_var_lines, read_skill_secret_names } = require('./cleanup')
+
+describe('strip_env_var_lines (pure)', () => {
+	it('removes only the named assignment lines, keeps the rest', () => {
+		const content = 'SLACK_BOT_TOKEN=xoxb-123\nDB_URL=postgres://x\n'
+		const r = strip_env_var_lines(content, ['SLACK_BOT_TOKEN'])
+		assert.equal(r.changed, true)
+		assert.ok(r.next.includes('DB_URL=postgres://x'))
+		assert.ok(!r.next.includes('SLACK_BOT_TOKEN'))
+		assert.equal(r.all_blank, false)
+	})
+
+	it('reports all_blank when nothing but whitespace remains', () => {
+		const r = strip_env_var_lines('SLACK_BOT_TOKEN=xoxb\n', ['SLACK_BOT_TOKEN'])
+		assert.equal(r.changed, true)
+		assert.equal(r.all_blank, true)
+	})
+
+	it('no-op when no named line is present', () => {
+		const r = strip_env_var_lines('DB_URL=x\n', ['NOPE'])
+		assert.equal(r.changed, false)
+	})
+})
+
+// Build a fake project: base_dir holds installed skill dirs (each with skill.json),
+// config_root holds skills-config.json + secrets/*.env + .env.example.
+const scaffold = (root, { skills, config, envFiles, example }) => {
+	const base_dir = path.join(root, 'skills')
+	for (const [key, manifest] of Object.entries(skills)) {
+		const dir = path.join(base_dir, key.split('/')[1])
+		fs.mkdirSync(dir, { recursive: true })
+		fs.writeFileSync(path.join(dir, 'skill.json'), JSON.stringify(manifest))
+	}
+	fs.writeFileSync(path.join(root, 'skills-config.json'), JSON.stringify(config))
+	fs.mkdirSync(path.join(root, 'secrets'), { recursive: true })
+	for (const [rel, body] of Object.entries(envFiles || {})) {
+		fs.writeFileSync(path.join(root, rel), body)
+	}
+	if (example !== undefined) fs.writeFileSync(path.join(root, '.env.example'), example)
+	return base_dir
+}
+
+describe('cleanup_uninstalled_configs', () => {
+	let root
+	beforeEach(() => { root = fs.mkdtempSync(path.join(os.tmpdir(), 'hs-cfg-cleanup-')) })
+	afterEach(() => { fs.rmSync(root, { recursive: true, force: true }) })
+
+	it('removes the uninstalled skill config entry and deletes its now-empty secrets file', async () => {
+		const base_dir = scaffold(root, {
+			skills: {
+				'acme/slack': { name: 'slack', env: { SLACK_BOT_TOKEN: { secret: true, required: true } } },
+				'acme/keep':  { name: 'keep',  env: { DB_URL: { secret: true } } }
+			},
+			config: {
+				'acme/slack': { envFile: './secrets/slack.env', config: { channel: '#ops' } },
+				'acme/keep':  { envFile: './secrets/keep.env' }
+			},
+			envFiles: { 'secrets/slack.env': 'SLACK_BOT_TOKEN=xoxb-123\n', 'secrets/keep.env': 'DB_URL=postgres://x\n' },
+			example: 'SLACK_BOT_TOKEN=\nDB_URL=\n'
+		})
+
+		const [err] = await cleanup_uninstalled_configs({
+			config_root: root,
+			base_dir,
+			removed: [{ key: 'acme/slack', name: 'slack', secret_names: ['SLACK_BOT_TOKEN'] }],
+			surviving_keys: ['acme/keep']
+		})
+		assert.ifError(err)
+
+		const cfg = JSON.parse(fs.readFileSync(path.join(root, 'skills-config.json'), 'utf-8'))
+		assert.ok(!cfg['acme/slack'], 'removed skill entry should be gone')
+		assert.ok(cfg['acme/keep'], 'surviving skill entry should remain')
+		assert.equal(fs.existsSync(path.join(root, 'secrets/slack.env')), false, 'empty secrets file should be deleted')
+		assert.equal(fs.existsSync(path.join(root, 'secrets/keep.env')), true, 'other skill secrets file untouched')
+		const example = fs.readFileSync(path.join(root, '.env.example'), 'utf-8')
+		assert.ok(!example.includes('SLACK_BOT_TOKEN'), 'removed secret name stripped from .env.example')
+		assert.ok(example.includes('DB_URL'), 'surviving secret name kept in .env.example')
+	})
+
+	it('preserves a secret still declared by a surviving skill (shared envFile)', async () => {
+		const base_dir = scaffold(root, {
+			skills: {
+				'acme/slack': { name: 'slack', env: { SLACK_BOT_TOKEN: { secret: true }, SHARED: { secret: true } } },
+				'acme/keep':  { name: 'keep',  env: { SHARED: { secret: true } } }
+			},
+			config: {
+				'acme/slack': { envFile: './secrets/shared.env' },
+				'acme/keep':  { envFile: './secrets/shared.env' }
+			},
+			envFiles: { 'secrets/shared.env': 'SLACK_BOT_TOKEN=xoxb\nSHARED=zzz\n' }
+		})
+
+		const [err] = await cleanup_uninstalled_configs({
+			config_root: root,
+			base_dir,
+			removed: [{ key: 'acme/slack', name: 'slack', secret_names: ['SLACK_BOT_TOKEN', 'SHARED'] }],
+			surviving_keys: ['acme/keep']
+		})
+		assert.ifError(err)
+
+		const env = fs.readFileSync(path.join(root, 'secrets/shared.env'), 'utf-8')
+		assert.ok(!env.includes('SLACK_BOT_TOKEN'), 'unshared secret stripped')
+		assert.ok(env.includes('SHARED=zzz'), 'secret shared with a surviving skill is preserved')
+	})
+
+	it('read_skill_secret_names returns the manifest secret var names', async () => {
+		const base_dir = scaffold(root, {
+			skills: { 'acme/slack': { name: 'slack', env: { SLACK_BOT_TOKEN: { secret: true }, PUBLIC: { secret: false } } } },
+			config: {},
+			envFiles: {}
+		})
+		const [err, names] = await read_skill_secret_names(base_dir, 'acme/slack')
+		assert.ifError(err)
+		assert.deepEqual(names, ['SLACK_BOT_TOKEN'])
+	})
+})

package/src/skills_config/configure.js

@@ -0,0 +1,172 @@
+const path = require('path')
+const { error: { catch_errors } } = require('puffy-core')
+const { file_exists, read_json, ensure_dir, read_file, write_file } = require('../utils/fs')
+const { skill_install_dir } = require('../config/paths')
+const { read_skills_config, get_skill_config_entry } = require('./reader')
+const { set_skill_config_entry, build_config_entry } = require('./writer')
+const { question_prompt } = require('../utils/prompt')
+const { SKILL_JSON } = require('../constants')
+
+const to_posix = (p) => p.split(path.sep).join('/')
+
+const coerce = (raw, type) => {
+	if (type === 'integer' || type === 'number') {
+		const n = Number(raw)
+		return Number.isNaN(n) ? raw : n
+	}
+	if (type === 'boolean') return /^(y|yes|true|1)$/i.test(raw)
+	return raw
+}
+
+const as_object = (value) => (value && typeof value === 'object' && !Array.isArray(value) ? value : null)
+
+// Append missing `NAME=` lines to an env file, never touching lines that already exist —
+// so a value the consumer already set is preserved on reinstall/update.
+const ensure_env_names = (file_path, names) => catch_errors('Failed to scaffold env file', async () => {
+	const [, exists] = await file_exists(file_path)
+	let content = ''
+	if (exists) { const [, c] = await read_file(file_path); content = c || '' }
+
+	const present = new Set(content.split('\n').map(l => l.split('=')[0].trim()).filter(Boolean))
+	const additions = names.filter(n => !present.has(n)).map(n => `${n}=`)
+	if (!additions.length && exists) return
+
+	await ensure_dir(path.dirname(file_path))
+	const base = content.length && !content.endsWith('\n') ? content + '\n' : content
+	await write_file(file_path, `${base}${additions.join('\n')}${additions.length ? '\n' : ''}`)
+})
+
+const ensure_gitignore_entry = (root, pattern) => catch_errors('Failed to update .gitignore', async () => {
+	const gitignore = path.join(root, '.gitignore')
+	const [, exists] = await file_exists(gitignore)
+	let content = ''
+	if (exists) { const [, c] = await read_file(gitignore); content = c || '' }
+
+	const lines = content.split('\n').map(l => l.trim())
+	if (lines.includes(pattern)) return
+
+	const base = content.length && !content.endsWith('\n') ? content + '\n' : content
+	await write_file(gitignore, `${base}${pattern}\n`)
+})
+
+// A required secret is "unset" unless it is present with a non-empty value in ambient
+// process.env or in the scaffolded .env file. Presence gates the fail-loud warning.
+const secret_is_set = (env_abs, name) => catch_errors('Failed to check secret presence', async () => {
+	if (process.env[name] && process.env[name].trim() !== '') return true
+	const [, exists] = await file_exists(env_abs)
+	if (!exists) return false
+	const [, content] = await read_file(env_abs)
+	for (const line of (content || '').split('\n')) {
+		const idx = line.indexOf('=')
+		if (idx === -1) continue
+		if (line.slice(0, idx).trim() === name && line.slice(idx + 1).trim() !== '') return true
+	}
+	return false
+})
+
+// For every installed package that declares a `config`/`env` schema, resolve the consumer's
+// choices and persist them: non-secret overrides → skills-config.json `config`; secret names →
+// the gitignored .env (+ committed .env.example, name only); the pointer → `envFile`. Secret
+// VALUES are never written anywhere by this function — build_config_entry structurally drops
+// anything but envFile/config. Returns warnings naming required secrets still unset.
+const configure_installed_skills = (packages, options = {}) => catch_errors('Failed to configure installed skills', async () => {
+	const { base_dir, config_root, interactive = false, only_required = false, ask = question_prompt } = options
+	const warnings = []
+
+	const [, existing_config_file] = await read_skills_config(config_root)
+
+	for (const pkg of packages || []) {
+		const key = pkg.skill
+		const name = key.split('/')[1]
+		const install_dir = skill_install_dir(base_dir, name)
+		const [, manifest] = await read_json(path.join(install_dir, SKILL_JSON))
+		if (!manifest) continue
+
+		const config_schema = as_object(manifest.config)
+		const env_schema = as_object(manifest.env)
+		if (!config_schema && !env_schema) continue
+
+		// Existing consumer choices are preserved verbatim; we only ever ADD to them.
+		// `only_required` (update/reconcile) narrows prompting to newly-required fields
+		// absent from the existing entry, so unrelated values are never re-asked.
+		const existing_entry = get_skill_config_entry(existing_config_file, key)
+		const existing_overrides = as_object(existing_entry && existing_entry.config) || {}
+		const overrides = { ...existing_overrides }
+
+		const maybe_prompt = async (field, spec) => {
+			if (!interactive) return
+			const already_set = Object.prototype.hasOwnProperty.call(existing_overrides, field)
+			const is_required = spec && spec.required === true
+			if (already_set) return
+			if (only_required && !is_required) return
+			const def = spec && spec.default
+			const label = `${field}${spec && spec.description ? ` — ${spec.description}` : ''} [${def ?? ''}]:`
+			const answer = await ask(label)
+			if (answer !== '' && answer !== String(def ?? '')) overrides[field] = coerce(answer, spec && spec.type)
+		}
+
+		// config fields — prompt (per the rules above); store non-default answers.
+		for (const [field, spec] of Object.entries(config_schema || {})) {
+			await maybe_prompt(field, spec)
+		}
+
+		// env fields — secrets route to the .env; non-secret env is treated like config.
+		const secret_names = []
+		for (const [var_name, spec] of Object.entries(env_schema || {})) {
+			if (spec && spec.secret) {
+				secret_names.push({ name: var_name, required: spec.required === true })
+				continue
+			}
+			await maybe_prompt(var_name, spec)
+		}
+
+		let env_file_rel = (existing_entry && existing_entry.envFile) || null
+		if (secret_names.length) {
+			env_file_rel = env_file_rel || `./secrets/${name}.env`
+			// Resolve the (possibly consumer-chosen) envFile relative to the config root.
+			const env_abs = path.resolve(config_root, env_file_rel)
+			const [scaffold_err] = await ensure_env_names(env_abs, secret_names.map(s => s.name))
+			if (scaffold_err) throw scaffold_err[0]
+			const [example_err] = await ensure_env_names(path.join(config_root, '.env.example'), secret_names.map(s => s.name))
+			if (example_err) throw example_err[0]
+
+			const dir_rel = to_posix(path.relative(config_root, path.dirname(env_abs)))
+			const [gi_err] = await ensure_gitignore_entry(config_root, dir_rel ? `${dir_rel}/*.env` : '*.env')
+			if (gi_err) throw gi_err[0]
+
+			for (const secret of secret_names.filter(s => s.required)) {
+				const [, is_set] = await secret_is_set(env_abs, secret.name)
+				if (!is_set) warnings.push(`Required secret ${secret.name} for ${key} is not set — add it to ${env_file_rel}`)
+			}
+		}
+
+		// Fail-loud (§4.3.2): a required NON-secret config/env field with no value and no
+		// author default would be silently undefined at runtime. Surface it as a warning —
+		// the same discipline the secret loop above applies to required secrets.
+		const warn_required_unset = (field, spec) => {
+			if (!spec || spec.required !== true) return
+			if (spec.default !== undefined) return
+			if (Object.prototype.hasOwnProperty.call(overrides, field)) return
+			warnings.push(`Required config "${field}" for ${key} is not set — no value provided and the skill declares no default.`)
+		}
+		for (const [field, spec] of Object.entries(config_schema || {})) warn_required_unset(field, spec)
+		for (const [var_name, spec] of Object.entries(env_schema || {})) {
+			if (spec && spec.secret) continue
+			warn_required_unset(var_name, spec)
+		}
+
+		const entry = build_config_entry({
+			...(env_file_rel ? { envFile: env_file_rel } : {}),
+			...(Object.keys(overrides).length ? { config: overrides } : {})
+		})
+
+		if (Object.keys(entry).length) {
+			const [set_err] = await set_skill_config_entry(config_root, key, entry)
+			if (set_err) throw set_err[0]
+		}
+	}
+
+	return { warnings }
+})
+
+module.exports = { configure_installed_skills }

package/src/skills_config/configure.test.js

@@ -0,0 +1,165 @@
+'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 { configure_installed_skills } = require('./configure')
+
+const make_tmp = () => fs.mkdtempSync(path.join(os.tmpdir(), 'hs-configure-'))
+
+const write_skill = (base_dir, name, manifest) => {
+	const dir = path.join(base_dir, name)
+	fs.mkdirSync(dir, { recursive: true })
+	fs.writeFileSync(path.join(dir, 'skill.json'), JSON.stringify({ name, version: '1.0.0', ...manifest }, null, '\t'))
+	fs.writeFileSync(path.join(dir, 'SKILL.md'), `# ${name}\n`)
+}
+
+const read = (p) => fs.readFileSync(p, 'utf-8')
+
+let base_dir, config_root
+beforeEach(() => {
+	base_dir = make_tmp()
+	config_root = make_tmp()
+})
+afterEach(() => {
+	fs.rmSync(base_dir, { recursive: true, force: true })
+	fs.rmSync(config_root, { recursive: true, force: true })
+})
+
+const SLACK = {
+	config: { channel: { type: 'string', default: '#general', description: 'Channel' } },
+	env: {
+		SLACK_BOT_TOKEN: { required: true, secret: true, description: 'Slack token' },
+		DEPLOY_TIMEOUT: { required: false, secret: false, type: 'integer', default: 300 }
+	}
+}
+
+describe('configure_installed_skills — non-interactive scaffold', () => {
+	it('scaffolds env + writes an envFile pointer with NO secret value', async () => {
+		write_skill(base_dir, 'slack-notify', SLACK)
+		const [err, result] = await configure_installed_skills(
+			[{ skill: 'acme/slack-notify' }],
+			{ base_dir, config_root, interactive: false }
+		)
+		assert.ifError(err)
+
+		const cfg = JSON.parse(read(path.join(config_root, 'skills-config.json')))
+		const entry = cfg['acme/slack-notify']
+		assert.strictEqual(entry.envFile, './secrets/slack-notify.env')
+		// no config overrides written in non-interactive mode
+		assert.ok(!entry.config || Object.keys(entry.config).length === 0)
+
+		// .env scaffolded (gitignored), .env.example committed with NAME only
+		assert.ok(fs.existsSync(path.join(config_root, 'secrets', 'slack-notify.env')))
+		assert.match(read(path.join(config_root, '.env.example')), /SLACK_BOT_TOKEN=/)
+		// no secret value anywhere in committed files
+		assert.ok(!read(path.join(config_root, '.env.example')).match(/SLACK_BOT_TOKEN=\S/))
+
+		// .gitignore ignores the env glob
+		assert.match(read(path.join(config_root, '.gitignore')), /secrets\/\*\.env/)
+
+		// warning names the required, unset secret
+		assert.ok(result.warnings.some(w => w.includes('SLACK_BOT_TOKEN')))
+	})
+
+	it('is idempotent — re-running yields byte-identical skills-config.json', async () => {
+		write_skill(base_dir, 'slack-notify', SLACK)
+		await configure_installed_skills([{ skill: 'acme/slack-notify' }], { base_dir, config_root, interactive: false })
+		const first = read(path.join(config_root, 'skills-config.json'))
+		await configure_installed_skills([{ skill: 'acme/slack-notify' }], { base_dir, config_root, interactive: false })
+		assert.strictEqual(read(path.join(config_root, 'skills-config.json')), first)
+	})
+
+	it('warns when a required NON-secret field (no default) is left unset — fail-loud, §4.3.2', async () => {
+		write_skill(base_dir, 'deployer', {
+			config: { api_url: { type: 'string', required: true, description: 'API base URL' } },
+			env: { TIMEOUT: { required: true, secret: false, type: 'integer' } }
+		})
+		const [err, result] = await configure_installed_skills(
+			[{ skill: 'acme/deployer' }],
+			{ base_dir, config_root, interactive: false }
+		)
+		assert.ifError(err)
+		assert.ok(result.warnings.some(w => w.includes('api_url')), 'required non-secret config field must be surfaced')
+		assert.ok(result.warnings.some(w => w.includes('TIMEOUT')), 'required non-secret env field must be surfaced')
+	})
+
+	it('does NOT warn for a required field that has a default (the default is its value)', async () => {
+		write_skill(base_dir, 'has-default', {
+			config: { retries: { type: 'integer', required: true, default: 3 } }
+		})
+		const [err, result] = await configure_installed_skills(
+			[{ skill: 'acme/has-default' }],
+			{ base_dir, config_root, interactive: false }
+		)
+		assert.ifError(err)
+		assert.ok(!result.warnings.some(w => w.includes('retries')))
+	})
+
+	it('writes nothing for a skill with no config/env block', async () => {
+		write_skill(base_dir, 'plain', {})
+		await configure_installed_skills([{ skill: 'acme/plain' }], { base_dir, config_root, interactive: false })
+		assert.ok(!fs.existsSync(path.join(config_root, 'skills-config.json')))
+	})
+})
+
+describe('configure_installed_skills — interactive overrides', () => {
+	it('writes only non-default answers to the config map, never the secret value', async () => {
+		write_skill(base_dir, 'slack-notify', SLACK)
+		const answers = { channel: '#deploys', DEPLOY_TIMEOUT: '600' }
+		const ask = async (msg) => {
+			const field = msg.split(/[\s—[]/)[0].trim()
+			return answers[field] ?? ''
+		}
+		const [err] = await configure_installed_skills(
+			[{ skill: 'acme/slack-notify' }],
+			{ base_dir, config_root, interactive: true, ask }
+		)
+		assert.ifError(err)
+
+		const cfg = JSON.parse(read(path.join(config_root, 'skills-config.json')))
+		const entry = cfg['acme/slack-notify']
+		assert.strictEqual(entry.config.channel, '#deploys')
+		assert.strictEqual(entry.config.DEPLOY_TIMEOUT, 600) // coerced to integer
+		assert.ok(!JSON.stringify(cfg).includes('xoxb')) // never prompted/stored a secret value
+	})
+})
+
+describe('configure_installed_skills — reconcile on update (only_required)', () => {
+	it('re-prompts exactly the newly-required field and leaves existing values untouched', async () => {
+		// v1: only `channel` config. Consumer sets it.
+		write_skill(base_dir, 'slack-notify', {
+			config: { channel: { type: 'string', default: '#general', description: 'Channel' } }
+		})
+		await configure_installed_skills(
+			[{ skill: 'acme/slack-notify' }],
+			{ base_dir, config_root, interactive: true, ask: async () => '#deploys' }
+		)
+
+		// v2: adds a new REQUIRED config field `retries`.
+		write_skill(base_dir, 'slack-notify', {
+			config: {
+				channel: { type: 'string', default: '#general', description: 'Channel' },
+				retries: { type: 'integer', required: true, description: 'Retry count' }
+			}
+		})
+
+		const prompted = []
+		const ask = async (msg) => {
+			prompted.push(msg.split(/[\s—[]/)[0].trim())
+			return '3'
+		}
+		await configure_installed_skills(
+			[{ skill: 'acme/slack-notify' }],
+			{ base_dir, config_root, interactive: true, only_required: true, ask }
+		)
+
+		// Only the new required field was asked
+		assert.deepStrictEqual(prompted, ['retries'])
+		const entry = JSON.parse(read(path.join(config_root, 'skills-config.json')))['acme/slack-notify']
+		assert.strictEqual(entry.config.channel, '#deploys') // untouched
+		assert.strictEqual(entry.config.retries, 3)          // merged, coerced
+	})
+})

package/src/skills_config/reader.js

@@ -0,0 +1,27 @@
+const { error: { catch_errors } } = require('puffy-core')
+const { read_json } = require('../utils/fs')
+const { skills_config_file_path, global_skills_config_file_path } = require('../config/paths')
+
+// skills-config.json is a flat map of `owner/name` -> { envFile?, config? }. Unlike the
+// lock file it has no envelope wrapper — the top-level keys ARE the skill keys. A missing
+// file is not an error: it means no skill in this project has been configured yet.
+const read_skills_config = (project_root) => catch_errors('Failed to read skills-config.json', async () => {
+	const config_path = skills_config_file_path(project_root)
+	const [errors, data] = await read_json(config_path)
+	if (errors) return null
+	return data
+})
+
+const read_global_skills_config = () => catch_errors('Failed to read global skills-config.json', async () => {
+	const config_path = global_skills_config_file_path()
+	const [errors, data] = await read_json(config_path)
+	if (errors) return null
+	return data
+})
+
+const get_skill_config_entry = (config_data, key) => {
+	if (!config_data || typeof config_data !== 'object') return null
+	return config_data[key] || null
+}
+
+module.exports = { read_skills_config, read_global_skills_config, get_skill_config_entry }

package/src/skills_config/resolve.js

@@ -0,0 +1,126 @@
+const path = require('path')
+const { error: { catch_errors } } = require('puffy-core')
+const { read_json, file_exists, read_file } = require('../utils/fs')
+const { skills_dir, skill_install_dir, lock_root } = require('../config/paths')
+const { read_skills_config, read_global_skills_config, get_skill_config_entry } = require('./reader')
+const { SKILL_JSON } = require('../constants')
+
+const as_object = (v) => (v && typeof v === 'object' && !Array.isArray(v) ? v : null)
+
+// project ⊕ global ⊕ default deep-merge; later argument wins on key collision.
+const deep_merge = (a, b) => {
+	const out = { ...(as_object(a) || {}) }
+	for (const [k, v] of Object.entries(as_object(b) || {})) {
+		if (as_object(v) && as_object(out[k])) out[k] = deep_merge(out[k], v)
+		else out[k] = v
+	}
+	return out
+}
+
+// Author defaults = config field defaults + NON-secret env defaults. Secrets never carry a
+// committed default (validator warns on it), so they are structurally excluded here too —
+// the resolver can never surface a secret value even via a stray default.
+const author_defaults = (manifest) => {
+	const defaults = {}
+	const config = as_object(manifest && manifest.config)
+	if (config) for (const [field, spec] of Object.entries(config)) {
+		if (spec && spec.default !== undefined) defaults[field] = spec.default
+	}
+	const env = as_object(manifest && manifest.env)
+	if (env) for (const [name, spec] of Object.entries(env)) {
+		if (spec && !spec.secret && spec.default !== undefined) defaults[name] = spec.default
+	}
+	return defaults
+}
+
+const required_secret_names = (manifest) => {
+	const env = as_object(manifest && manifest.env)
+	if (!env) return []
+	return Object.entries(env)
+		.filter(([, spec]) => spec && spec.secret === true && spec.required === true)
+		.map(([name]) => name)
+}
+
+// Read the installed skill.json — project scope first, then global. Best-effort: an
+// unresolved manifest just means no author defaults / no declared secrets.
+const find_installed_manifest = (name, project_root) => catch_errors('Failed to read installed skill.json', async () => {
+	const candidates = [
+		skill_install_dir(skills_dir(false, project_root), name),
+		skill_install_dir(skills_dir(true), name)
+	]
+	for (const dir of candidates) {
+		const [, manifest] = await read_json(path.join(dir, SKILL_JSON))
+		if (manifest) return manifest
+	}
+	return null
+})
+
+// A required secret counts as present when it is a non-empty value in ambient process.env
+// (which takes precedence at load time) OR a non-empty value in the resolved .env. The VALUE
+// is read only to decide presence — it is never returned.
+const secret_present = (name, env_abs_path) => catch_errors('Failed to check secret presence', async () => {
+	if (process.env[name] && process.env[name].trim() !== '') return true
+	if (!env_abs_path) return false
+	const [, exists] = await file_exists(env_abs_path)
+	if (!exists) return false
+	const [, content] = await read_file(env_abs_path)
+	for (const line of (content || '').split('\n')) {
+		const idx = line.indexOf('=')
+		if (idx === -1) continue
+		if (line.slice(0, idx).trim() === name && line.slice(idx + 1).trim() !== '') return true
+	}
+	return false
+})
+
+// The deterministic resolver behind `happyskills skills-config get`. Merges the cascade and
+// reports required-secret NAMES + a present/absent boolean. NEVER reads-and-returns a secret
+// value (§0 hard rule). `options.manifest` / `options.global_config` are injectable for tests.
+const resolve_skill_config = (key, options = {}) => catch_errors('Failed to resolve skill config', async () => {
+	const { project_root = process.cwd() } = options
+	const name = key.split('/')[1]
+
+	const manifest = options.manifest !== undefined
+		? options.manifest
+		: (await find_installed_manifest(name, project_root))[1]
+
+	const [, project_file] = await read_skills_config(project_root)
+	const global_file = options.global_config !== undefined
+		? options.global_config
+		: (await read_global_skills_config())[1]
+
+	const project_entry = get_skill_config_entry(project_file, key)
+	const global_entry = get_skill_config_entry(global_file, key)
+
+	const merged = deep_merge(
+		deep_merge(author_defaults(manifest), as_object(global_entry && global_entry.config) || {}),
+		as_object(project_entry && project_entry.config) || {}
+	)
+
+	// envFile: whichever layer declared it wins (project first), resolved against THAT layer's
+	// root so a global pointer stays correct even when read from a project cwd.
+	let env_file_resolved = null
+	if (project_entry && project_entry.envFile) {
+		env_file_resolved = path.resolve(project_root, project_entry.envFile)
+	} else if (global_entry && global_entry.envFile) {
+		env_file_resolved = path.resolve(lock_root(true), global_entry.envFile)
+	}
+
+	const requiredSecrets = required_secret_names(manifest)
+	let secretsPresent = true
+	for (const secret of requiredSecrets) {
+		const [, present] = await secret_present(secret, env_file_resolved)
+		if (!present) { secretsPresent = false; break }
+	}
+
+	return {
+		config: merged,
+		// Absolute internally — the agent-facing command relativizes this to the caller's cwd so
+		// the emitted path is usable from wherever the agent runs and leaks no absolute local path.
+		envFile: env_file_resolved,
+		requiredSecrets,
+		secretsPresent,
+		manifestFound: !!manifest
+	}
+})
+
+module.exports = { resolve_skill_config, deep_merge, author_defaults, required_secret_names }