happyskills 1.16.1 → 1.17.0

package/src/integration/install_dep_closure.test.js

@@ -0,0 +1,122 @@
+'use strict'
+/**
+ * Integration test — install must not report "already installed" for a skill whose
+ * locked dependency closure is not materialized on disk.
+ *
+ * The production bug: a `skills-lock.json` recorded a kit as an installed root
+ * skill (`requested_by: ['__root__']`, valid integrity, present on disk) with a
+ * populated `dependencies` map — but those dependencies were never resolved into
+ * their own lock entries and never landed under `.agents/skills/`. Every
+ * subsequent `install` then hit the pre-resolve skip check, which inspected only
+ * the kit's own directory + integrity and returned "already installed" BEFORE
+ * dependency resolution ran. The missing deps were never backfilled: the lock and
+ * the on-disk `.agents/skills/` were permanently out of sync.
+ *
+ * These tests run the REAL CLI with an unreachable registry (localhost:0). That
+ * isolates the skip decision from the network:
+ *   - If the skip fires, the command SUCCEEDS with "already installed" and never
+ *     touches the network (the buggy behavior).
+ *   - If the skip is correctly declined, the command falls through to resolution
+ *     and FAILS on the unreachable registry (the fixed behavior).
+ * We assert on that difference, plus the inverse: a fully-materialized closure
+ * must still skip (no over-triggering, fast-path preserved).
+ */
+const { describe, it } = require('node:test')
+const assert = require('node:assert/strict')
+const { spawnSync } = require('child_process')
+const fs = require('fs')
+const os = require('os')
+const path = require('path')
+
+const CLI = path.resolve(__dirname, '../../bin/happyskills.js')
+const NODE = process.execPath
+
+const make_tmp = () => fs.mkdtempSync(path.join(os.tmpdir(), 'hs-dep-closure-test-'))
+const run = (args, opts) => {
+	const result = spawnSync(NODE, [CLI, ...args, '--text'], {
+		env: { ...process.env, NO_COLOR: '1', HAPPYSKILLS_API_URL: 'http://localhost:0', CI: '', ...(opts?.env || {}) },
+		encoding: 'utf-8',
+		timeout: 15000,
+		cwd: opts?.cwd
+	})
+	return { stdout: result.stdout || '', stderr: result.stderr || '', code: result.status }
+}
+
+// Write a skill directory under <root>/.agents/skills/<name> and return the dir.
+const write_skill = (root, name, manifest) => {
+	const dir = path.join(root, '.agents', 'skills', name)
+	fs.mkdirSync(dir, { recursive: true })
+	fs.writeFileSync(path.join(dir, 'SKILL.md'), `---\nname: ${name}\ndescription: dep-closure test skill\n---\nbody\n`)
+	fs.writeFileSync(path.join(dir, 'skill.json'), JSON.stringify(manifest, null, '\t'))
+	return dir
+}
+
+// Build a project whose lock records `kit` as a __root__ skill (valid integrity,
+// on disk) with the given dependency map. `present_deps` names the deps that are
+// ALSO created on disk + locked; any dep in the map but not in present_deps is
+// declared-but-missing.
+const scaffold = async ({ kit, kit_deps, present_deps }) => {
+	const { hash_directory, clear_integrity_cache } = require('../lock/integrity')
+	const root = make_tmp()
+	const skills = {}
+
+	const kit_dir = write_skill(root, kit, {
+		name: kit, version: '1.0.0', type: 'kit',
+		description: 'dep-closure test kit',
+		dependencies: Object.fromEntries(kit_deps.map(d => [`acme/${d}`, '*']))
+	})
+	clear_integrity_cache()
+	const [, kit_integrity] = await hash_directory(kit_dir)
+	skills[`acme/${kit}`] = {
+		version: '1.0.0', ref: 'refs/tags/v1.0.0', commit: 'c', integrity: kit_integrity,
+		base_commit: 'c', base_integrity: kit_integrity,
+		requested_by: ['__root__'],
+		dependencies: Object.fromEntries(kit_deps.map(d => [`acme/${d}`, '*'])),
+		type: 'kit'
+	}
+
+	for (const dep of present_deps) {
+		const dep_dir = write_skill(root, dep, { name: dep, version: '1.0.0', type: 'skill', description: 'dep' })
+		clear_integrity_cache()
+		const [, dep_integrity] = await hash_directory(dep_dir)
+		skills[`acme/${dep}`] = {
+			version: '1.0.0', ref: 'refs/tags/v1.0.0', commit: 'c', integrity: dep_integrity,
+			base_commit: 'c', base_integrity: dep_integrity,
+			requested_by: [`acme/${kit}`], dependencies: {}, type: 'skill'
+		}
+	}
+
+	fs.writeFileSync(
+		path.join(root, 'skills-lock.json'),
+		JSON.stringify({ lockVersion: 2, generatedAt: new Date().toISOString(), skills }, null, '\t')
+	)
+	return { root, cleanup: () => fs.rmSync(root, { recursive: true, force: true }) }
+}
+
+describe('install — dependency-closure skip guard', () => {
+	it('does NOT report "already installed" when a locked dependency was never materialized', async () => {
+		// kit declares acme/dep-a but dep-a is neither locked nor on disk.
+		const ctx = await scaffold({ kit: 'thekit', kit_deps: ['dep-a'], present_deps: [] })
+		try {
+			const { code, stdout, stderr } = run(['install', 'acme/thekit'], { cwd: ctx.root })
+			const out = stdout + stderr
+			// Fixed behavior: the skip is declined, so install falls through to
+			// resolution and fails against the unreachable registry.
+			assert.doesNotMatch(out, /already installed/i,
+				'must not claim already-installed while a declared dependency is missing')
+			assert.notStrictEqual(code, 0, 'must attempt resolution (and fail on the unreachable registry), not skip')
+		} finally { ctx.cleanup() }
+	})
+
+	it('still skips (already installed, no network) when the whole closure is present', async () => {
+		// Regression guard: a fully-materialized closure must keep the fast path —
+		// skip without any resolution/network call, even with the registry down.
+		const ctx = await scaffold({ kit: 'fullkit', kit_deps: ['dep-a'], present_deps: ['dep-a'] })
+		try {
+			const { code, stdout, stderr } = run(['install', 'acme/fullkit'], { cwd: ctx.root })
+			const out = stdout + stderr
+			assert.match(out, /already installed/i, 'a complete closure must still short-circuit')
+			assert.strictEqual(code, 0, 'skip path must not touch the network')
+		} finally { ctx.cleanup() }
+	})
+})

package/src/integration/skills-config.test.js

@@ -0,0 +1,98 @@
+'use strict'
+// Conformance test for `happyskills skills-config get` — spec 260704-01 Tier 3 §4.4.
+// Exercises the real command end-to-end (spawned CLI) against a tmp project: envelope
+// conformance (STRICT), owner/name validation, and the §0 hard rule that no secret VALUE
+// ever reaches stdout/stderr.
+
+const { describe, it, beforeEach, afterEach } = require('node:test')
+const assert = require('node:assert/strict')
+const { spawnSync } = require('child_process')
+const fs = require('fs')
+const os = require('os')
+const path = require('path')
+
+const CLI = path.resolve(__dirname, '../../bin/happyskills.js')
+const NODE = process.execPath
+
+const run = (args, cwd) => {
+	const result = spawnSync(NODE, [CLI, ...args], {
+		cwd,
+		env: { ...process.env, NO_COLOR: '1', HAPPYSKILLS_ENVELOPE_STRICT: '1', HAPPYSKILLS_API_URL: 'http://localhost:0', CI: '' },
+		encoding: 'utf-8',
+		timeout: 10000,
+	})
+	return { stdout: result.stdout || '', stderr: result.stderr || '', code: result.status }
+}
+
+const SECRET = 'xoxb-SUPER-SECRET-DO-NOT-LEAK'
+
+let proj
+beforeEach(() => {
+	proj = fs.mkdtempSync(path.join(os.tmpdir(), 'hs-sc-cmd-'))
+	const skill_dir = path.join(proj, '.agents', 'skills', 'slack-notify')
+	fs.mkdirSync(skill_dir, { recursive: true })
+	fs.writeFileSync(path.join(skill_dir, 'skill.json'), JSON.stringify({
+		name: 'slack-notify', version: '1.0.0',
+		config: { channel: { type: 'string', default: '#general' }, max_chars: { type: 'integer', default: 500 } },
+		env: { SLACK_BOT_TOKEN: { required: true, secret: true }, DEPLOY_TIMEOUT: { required: false, secret: false, type: 'integer', default: 300 } }
+	}))
+	fs.writeFileSync(path.join(skill_dir, 'SKILL.md'), '# slack\n')
+	fs.writeFileSync(path.join(proj, 'skills-config.json'), JSON.stringify({
+		'acme/slack-notify': { envFile: './secrets/slack-notify.env', config: { channel: '#deploys' } }
+	}))
+	fs.mkdirSync(path.join(proj, 'secrets'), { recursive: true })
+	fs.writeFileSync(path.join(proj, 'secrets', 'slack-notify.env'), `SLACK_BOT_TOKEN=${SECRET}\n`)
+})
+afterEach(() => { fs.rmSync(proj, { recursive: true, force: true }) })
+
+describe('happyskills skills-config get', () => {
+	it('emits a valid success envelope with the resolved non-secret config — and NO secret value', () => {
+		const { stdout, stderr, code } = run(['skills-config', 'get', 'acme/slack-notify', '--json'], proj)
+		assert.strictEqual(code, 0)
+		const env = JSON.parse(stdout)
+		assert.strictEqual(env.ok, true)
+		assert.strictEqual(env.meta.command, 'skills-config')
+		assert.strictEqual(typeof env.data, 'object')
+		assert.ok(!Array.isArray(env.data))
+		assert.strictEqual(env.data.config.channel, '#deploys')      // project override wins
+		assert.strictEqual(env.data.config.max_chars, 500)           // author default
+		assert.deepStrictEqual(env.data.requiredSecrets, ['SLACK_BOT_TOKEN'])
+		assert.strictEqual(env.data.secretsPresent, true)
+		assert.strictEqual(env.data.envFile, './secrets/slack-notify.env')
+
+		// §0 hard rule: the secret VALUE must never appear in any output stream
+		assert.ok(!stdout.includes(SECRET), 'secret leaked to stdout')
+		assert.ok(!stderr.includes(SECRET), 'secret leaked to stderr')
+	})
+
+	it('resolves from a SUBDIRECTORY by walking up to the project root (§6 #7)', () => {
+		const sub = path.join(proj, 'services', 'api')
+		fs.mkdirSync(sub, { recursive: true })
+		const { stdout, code } = run(['skills-config', 'get', 'acme/slack-notify', '--json'], sub)
+		assert.strictEqual(code, 0)
+		const env = JSON.parse(stdout)
+		assert.strictEqual(env.ok, true)
+		// same resolution as from the root — proves the CLI now matches the file-fallback walk-up
+		assert.strictEqual(env.data.config.channel, '#deploys')
+		assert.strictEqual(env.data.secretsPresent, true)
+		// envFile is relative to the caller's cwd (the subdir), so it stays usable from here
+		assert.strictEqual(env.data.envFile, '../../secrets/slack-notify.env')
+	})
+
+	it('rejects a non-owner/name argument with a USAGE_ERROR envelope', () => {
+		const { stdout, code } = run(['skills-config', 'get', 'not-a-scoped-name', '--json'], proj)
+		assert.strictEqual(code, 2)
+		const env = JSON.parse(stdout)
+		assert.strictEqual(env.ok, false)
+		assert.strictEqual(env.error.code, 'USAGE_ERROR')
+		assert.strictEqual(typeof env.data, 'object')
+	})
+
+	it('rejects an unknown subcommand', () => {
+		const { stdout, code } = run(['skills-config', 'wat', '--json'], proj)
+		assert.strictEqual(code, 2)
+		const env = JSON.parse(stdout)
+		assert.strictEqual(env.ok, false)
+		assert.strictEqual(env.error.code, 'USAGE_ERROR')
+	})
+})

package/src/lock/verify.js

@@ -118,6 +118,58 @@ const detect_ahead_state = (lock_entry, install_dir) => catch_errors('Failed to
 	}
 })
 
+// dependency_closure_satisfied — walk the locked dependency graph starting at
+// `skill` and confirm every reachable skill is BOTH present in the lock AND
+// materialized on disk. Returns { satisfied: bool, missing: [full skill names] }.
+//
+// This closes the "lock declares deps that were never installed" gap. A lock
+// entry can carry a populated `dependencies` map whose referenced skills have no
+// lock entry and no install directory — e.g. an entry authored by `publish`
+// (which records `manifest.dependencies` but installs nothing), or any install
+// that recorded a root skill while its transitive deps were skipped. In that
+// state the lock and `.agents/skills/` are out of sync.
+//
+// The install skip-check ("already installed") uses this to decide whether a
+// locked-and-present root is actually COMPLETE. If any transitive dependency is
+// missing, the caller must decline the skip and re-resolve so the missing deps
+// get backfilled — the lock must always match what is on disk.
+//
+// `resolve_dir(full_skill_name)` maps `owner/name` to its install directory.
+// Cycle-safe via a visited set. A dependency that is referenced but absent from
+// the lock, or locked but missing on disk, is reported in `missing`.
+const dependency_closure_satisfied = (lock_data, skill, resolve_dir) => catch_errors('Failed to verify dependency closure', async () => {
+	const skills = (lock_data && lock_data.skills) || {}
+	const missing = []
+	const visited = new Set()
+	const queue = [skill]
+
+	while (queue.length > 0) {
+		const current = queue.shift()
+		if (visited.has(current)) continue
+		visited.add(current)
+
+		const entry = skills[current]
+		if (!entry) {
+			// Referenced as a dependency but never locked.
+			missing.push(current)
+			continue
+		}
+
+		const [, dir_present] = await file_exists(resolve_dir(current))
+		if (!dir_present) {
+			// Locked but not materialized on disk.
+			missing.push(current)
+			continue
+		}
+
+		for (const dep_name of Object.keys(entry.dependencies || {})) {
+			if (!visited.has(dep_name)) queue.push(dep_name)
+		}
+	}
+
+	return { satisfied: missing.length === 0, missing }
+})
+
 // Plain-language description of a drift result, suitable for the principal-facing
 // table cell (status column). Returns null when ok or ahead.
 const describe_drift = (verify_result) => {
@@ -179,5 +231,6 @@ module.exports = {
 	detect_ahead_state,
 	describe_drift,
 	classify_lock_disk,
-	parse_changelog_top_version
+	parse_changelog_top_version,
+	dependency_closure_satisfied
 }

package/src/lock/verify.test.js

@@ -10,7 +10,8 @@ const {
 	detect_ahead_state,
 	describe_drift,
 	classify_lock_disk,
-	parse_changelog_top_version
+	parse_changelog_top_version,
+	dependency_closure_satisfied
 } = require('./verify')
 
 const make_tmp = () => fs.mkdtempSync(path.join(os.tmpdir(), 'hs-verify-test-'))
@@ -276,6 +277,113 @@ describe('classify_lock_disk', () => {
 	})
 })
 
+describe('dependency_closure_satisfied', () => {
+	// A skill directory is "present" iff it exists on disk. We model the disk with a
+	// temp root and create a sub-dir per skill that is supposed to be installed.
+	const make_root = () => make_tmp()
+	const present = (root, skill) => {
+		const dir = path.join(root, skill.replace('/', '__'))
+		fs.mkdirSync(dir, { recursive: true })
+		return dir
+	}
+	const resolver = (root) => (skill) => path.join(root, skill.replace('/', '__'))
+
+	const lock = (skills) => ({ lockVersion: 2, skills })
+
+	it('is satisfied when the root and its whole locked dep closure are present on disk', async () => {
+		const root = make_root()
+		try {
+			present(root, 'acme/kit')
+			present(root, 'acme/dep-a')
+			present(root, 'acme/dep-b')
+			const data = lock({
+				'acme/kit': { version: '1.0.0', dependencies: { 'acme/dep-a': '*', 'acme/dep-b': '*' } },
+				'acme/dep-a': { version: '1.0.0', dependencies: {} },
+				'acme/dep-b': { version: '1.0.0', dependencies: {} }
+			})
+			const [err, result] = await dependency_closure_satisfied(data, 'acme/kit', resolver(root))
+			assert.strictEqual(err, null)
+			assert.deepEqual(result, { satisfied: true, missing: [] })
+		} finally { cleanup(root) }
+	})
+
+	it('is NOT satisfied when a declared dependency has no lock entry (the kit-deps-never-installed bug)', async () => {
+		// This is the exact production shape: the kit is locked + on disk, its
+		// `dependencies` map is populated, but those deps were never resolved into
+		// their own lock entries and never landed on disk.
+		const root = make_root()
+		try {
+			present(root, 'acme/kit')
+			const data = lock({
+				'acme/kit': { version: '1.0.0', dependencies: { 'acme/dep-a': '*', 'acme/dep-b': '*' } }
+			})
+			const [err, result] = await dependency_closure_satisfied(data, 'acme/kit', resolver(root))
+			assert.strictEqual(err, null)
+			assert.strictEqual(result.satisfied, false)
+			assert.deepEqual(result.missing.sort(), ['acme/dep-a', 'acme/dep-b'])
+		} finally { cleanup(root) }
+	})
+
+	it('is NOT satisfied when a dependency is locked but its directory is missing on disk', async () => {
+		const root = make_root()
+		try {
+			present(root, 'acme/kit')
+			// acme/dep-a is locked but NOT created on disk.
+			const data = lock({
+				'acme/kit': { version: '1.0.0', dependencies: { 'acme/dep-a': '*' } },
+				'acme/dep-a': { version: '1.0.0', dependencies: {} }
+			})
+			const [err, result] = await dependency_closure_satisfied(data, 'acme/kit', resolver(root))
+			assert.strictEqual(err, null)
+			assert.strictEqual(result.satisfied, false)
+			assert.deepEqual(result.missing, ['acme/dep-a'])
+		} finally { cleanup(root) }
+	})
+
+	it('walks transitively — a missing dep-of-a-dep still fails the closure', async () => {
+		const root = make_root()
+		try {
+			present(root, 'acme/kit')
+			present(root, 'acme/dep-a')
+			// acme/dep-a depends on acme/deep, which is neither locked nor on disk.
+			const data = lock({
+				'acme/kit': { version: '1.0.0', dependencies: { 'acme/dep-a': '*' } },
+				'acme/dep-a': { version: '1.0.0', dependencies: { 'acme/deep': '*' } }
+			})
+			const [err, result] = await dependency_closure_satisfied(data, 'acme/kit', resolver(root))
+			assert.strictEqual(err, null)
+			assert.strictEqual(result.satisfied, false)
+			assert.deepEqual(result.missing, ['acme/deep'])
+		} finally { cleanup(root) }
+	})
+
+	it('is cycle-safe (A → B → A) and does not loop forever', async () => {
+		const root = make_root()
+		try {
+			present(root, 'acme/a')
+			present(root, 'acme/b')
+			const data = lock({
+				'acme/a': { version: '1.0.0', dependencies: { 'acme/b': '*' } },
+				'acme/b': { version: '1.0.0', dependencies: { 'acme/a': '*' } }
+			})
+			const [err, result] = await dependency_closure_satisfied(data, 'acme/a', resolver(root))
+			assert.strictEqual(err, null)
+			assert.deepEqual(result, { satisfied: true, missing: [] })
+		} finally { cleanup(root) }
+	})
+
+	it('is satisfied for a leaf skill with no dependencies', async () => {
+		const root = make_root()
+		try {
+			present(root, 'acme/solo')
+			const data = lock({ 'acme/solo': { version: '1.0.0', dependencies: {} } })
+			const [err, result] = await dependency_closure_satisfied(data, 'acme/solo', resolver(root))
+			assert.strictEqual(err, null)
+			assert.deepEqual(result, { satisfied: true, missing: [] })
+		} finally { cleanup(root) }
+	})
+})
+
 describe('describe_drift', () => {
 	it('returns null for ok results', () => {
 		assert.strictEqual(describe_drift({ ok: true }), null)

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 }