happyskills 1.16.3 → 1.17.0

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 }

package/src/skills_config/resolve.test.js

@@ -0,0 +1,112 @@
+'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 { resolve_skill_config, deep_merge, author_defaults } = require('./resolve')
+const { set_skill_config_entry } = require('./writer')
+
+const make_tmp = () => fs.mkdtempSync(path.join(os.tmpdir(), 'hs-resolve-'))
+
+const MANIFEST = {
+	name: 'slack-notify',
+	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 }
+	}
+}
+
+let root
+beforeEach(() => { root = make_tmp() })
+afterEach(() => { fs.rmSync(root, { recursive: true, force: true }) })
+
+describe('deep_merge + author_defaults', () => {
+	it('project wins over global wins over defaults', () => {
+		const merged = deep_merge(deep_merge({ a: 1, b: 1, c: 1 }, { b: 2, c: 2 }), { c: 3 })
+		assert.deepStrictEqual(merged, { a: 1, b: 2, c: 3 })
+	})
+
+	it('author_defaults pulls config defaults + NON-secret env defaults, never secret defaults', () => {
+		const d = author_defaults(MANIFEST)
+		assert.strictEqual(d.channel, '#general')
+		assert.strictEqual(d.max_chars, 500)
+		assert.strictEqual(d.DEPLOY_TIMEOUT, 300)
+		assert.ok(!('SLACK_BOT_TOKEN' in d))
+	})
+})
+
+describe('resolve_skill_config — cascade + secrets', () => {
+	it('merges project ⊕ global ⊕ author-default and returns required secret NAMES only', async () => {
+		await set_skill_config_entry(root, 'acme/slack-notify', {
+			envFile: './secrets/slack-notify.env',
+			config: { channel: '#deploys' } // project override
+		})
+
+		const [err, resolved] = await resolve_skill_config('acme/slack-notify', {
+			project_root: root,
+			manifest: MANIFEST,
+			global_config: { 'acme/slack-notify': { config: { max_chars: 900 } } } // global override
+		})
+		assert.ifError(err)
+
+		// project channel wins; global max_chars wins over default; DEPLOY_TIMEOUT falls to default
+		assert.strictEqual(resolved.config.channel, '#deploys')
+		assert.strictEqual(resolved.config.max_chars, 900)
+		assert.strictEqual(resolved.config.DEPLOY_TIMEOUT, 300)
+
+		// required secret NAME only — never a value
+		assert.deepStrictEqual(resolved.requiredSecrets, ['SLACK_BOT_TOKEN'])
+		assert.strictEqual(resolved.secretsPresent, false) // .env has no value
+
+		// resolver returns the ABSOLUTE envFile internally; the command relativizes it to the
+		// caller's cwd for output (see skills-config.test.js)
+		assert.strictEqual(resolved.envFile, path.resolve(root, 'secrets/slack-notify.env'))
+
+		// the whole resolved object never contains a secret value
+		assert.ok(!JSON.stringify(resolved).includes('xoxb'))
+	})
+
+	it('reports secretsPresent:true when the secret is set in the .env', async () => {
+		fs.mkdirSync(path.join(root, 'secrets'), { recursive: true })
+		fs.writeFileSync(path.join(root, 'secrets', 'slack-notify.env'), 'SLACK_BOT_TOKEN=xoxb-real\n')
+		await set_skill_config_entry(root, 'acme/slack-notify', { envFile: './secrets/slack-notify.env', config: {} })
+
+		const [err, resolved] = await resolve_skill_config('acme/slack-notify', {
+			project_root: root, manifest: MANIFEST, global_config: null
+		})
+		assert.ifError(err)
+		assert.strictEqual(resolved.secretsPresent, true)
+		// value is read for presence, but never surfaced
+		assert.ok(!JSON.stringify(resolved).includes('xoxb'))
+	})
+
+	it('NEVER surfaces a secret value even when the author wrongly gives a secret a default (§0 hard rule)', async () => {
+		const bad_manifest = {
+			name: 'leaky',
+			env: { API_KEY: { required: true, secret: true, default: 'sk-LEAKED-DEFAULT' } }
+		}
+		const [err, resolved] = await resolve_skill_config('acme/leaky', {
+			project_root: root, manifest: bad_manifest, global_config: null
+		})
+		assert.ifError(err)
+		assert.ok(!('API_KEY' in resolved.config), 'secret default must not appear in resolved config')
+		assert.ok(!JSON.stringify(resolved).includes('sk-LEAKED-DEFAULT'), 'secret value must never appear anywhere in the resolved object')
+		assert.deepStrictEqual(resolved.requiredSecrets, ['API_KEY'])
+	})
+
+	it('resolves to author defaults when no consumer config exists', async () => {
+		const [err, resolved] = await resolve_skill_config('acme/slack-notify', {
+			project_root: root, manifest: MANIFEST, global_config: null
+		})
+		assert.ifError(err)
+		assert.strictEqual(resolved.config.channel, '#general')
+		assert.strictEqual(resolved.envFile, null)
+		assert.strictEqual(resolved.secretsPresent, false) // required secret, none set
+	})
+})

package/src/skills_config/skills_config.test.js

@@ -0,0 +1,92 @@
+'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 { read_skills_config, get_skill_config_entry } = require('./reader')
+const { write_skills_config, upsert_skill_config, set_skill_config_entry, build_config_entry } = require('./writer')
+const { SKILLS_CONFIG_FILE } = require('../constants')
+
+const make_tmp = () => fs.mkdtempSync(path.join(os.tmpdir(), 'hs-skills-config-'))
+const read_raw = (root) => fs.readFileSync(path.join(root, SKILLS_CONFIG_FILE), 'utf-8')
+
+let root
+beforeEach(() => { root = make_tmp() })
+afterEach(() => { fs.rmSync(root, { recursive: true, force: true }) })
+
+describe('skills_config reader', () => {
+	it('returns null when the file does not exist', async () => {
+		const [err, data] = await read_skills_config(root)
+		assert.ifError(err)
+		assert.strictEqual(data, null)
+	})
+
+	it('reads back a written entry', async () => {
+		await set_skill_config_entry(root, 'acme/slack-notify', { envFile: './secrets/x.env', config: { channel: '#deploys' } })
+		const [err, data] = await read_skills_config(root)
+		assert.ifError(err)
+		const entry = get_skill_config_entry(data, 'acme/slack-notify')
+		assert.strictEqual(entry.envFile, './secrets/x.env')
+		assert.deepStrictEqual(entry.config, { channel: '#deploys' })
+	})
+})
+
+describe('skills_config writer — key-scoped writes', () => {
+	it('adding skill B leaves skill A byte-identical', async () => {
+		await set_skill_config_entry(root, 'acme/aaa', { envFile: './secrets/a.env', config: { x: 1 } })
+		const raw_a_before = read_raw(root)
+		const block_a_before = JSON.stringify(JSON.parse(raw_a_before)['acme/aaa'])
+
+		await set_skill_config_entry(root, 'acme/bbb', { envFile: './secrets/b.env', config: { y: 2 } })
+		const parsed = JSON.parse(read_raw(root))
+		assert.strictEqual(JSON.stringify(parsed['acme/aaa']), block_a_before)
+		assert.ok(parsed['acme/bbb'])
+	})
+
+	it('produces sorted, byte-stable output across two identical writes', async () => {
+		await set_skill_config_entry(root, 'acme/zzz', { envFile: './z.env', config: { b: 2, a: 1 } })
+		await set_skill_config_entry(root, 'acme/aaa', { envFile: './a.env', config: { d: 4, c: 3 } })
+		const first = read_raw(root)
+
+		// Top-level keys sorted: acme/aaa before acme/zzz
+		assert.ok(first.indexOf('acme/aaa') < first.indexOf('acme/zzz'))
+		// Nested config keys sorted too
+		assert.ok(first.indexOf('"c"') < first.indexOf('"d"'))
+
+		// Re-writing the same entry yields identical bytes
+		await set_skill_config_entry(root, 'acme/aaa', { envFile: './a.env', config: { d: 4, c: 3 } })
+		assert.strictEqual(read_raw(root), first)
+	})
+
+	it('never persists a secret value — build_config_entry drops everything but envFile and config', () => {
+		const entry = build_config_entry({
+			envFile: './secrets/x.env',
+			config: { channel: '#deploys' },
+			SLACK_BOT_TOKEN: 'xoxb-super-secret',
+			secrets: { SLACK_BOT_TOKEN: 'xoxb-super-secret' }
+		})
+		assert.deepStrictEqual(Object.keys(entry).sort(), ['config', 'envFile'])
+		assert.ok(!JSON.stringify(entry).includes('xoxb-super-secret'))
+	})
+
+	it('upsert with null removes the key', () => {
+		const next = upsert_skill_config({ 'acme/a': { config: {} }, 'acme/b': { config: {} } }, 'acme/a', null)
+		assert.deepStrictEqual(Object.keys(next), ['acme/b'])
+	})
+
+	it('refuses to clobber an existing but corrupt skills-config.json (data-loss guard)', async () => {
+		fs.writeFileSync(path.join(root, SKILLS_CONFIG_FILE), '{ this is not valid json ')
+		const [err] = await set_skill_config_entry(root, 'acme/new', { config: { x: 1 } })
+		assert.ok(err, 'a corrupt existing file must surface an error, not be silently overwritten')
+		// original corrupt content is preserved, not replaced
+		assert.strictEqual(read_raw(root), '{ this is not valid json ')
+	})
+
+	it('write_skills_config sorts keys deeply', async () => {
+		await write_skills_config(root, { 'z/z': { config: { b: 1, a: 2 } }, 'a/a': { envFile: './a.env' } })
+		const raw = read_raw(root)
+		assert.ok(raw.indexOf('a/a') < raw.indexOf('z/z'))
+	})
+})

package/src/skills_config/writer.js

@@ -0,0 +1,59 @@
+const { error: { catch_errors } } = require('puffy-core')
+const { atomic_write_json, read_json, file_exists } = require('../utils/fs')
+const { skills_config_file_path } = require('../config/paths')
+
+// Deterministic serialization: recursively sort object keys so concurrent git additions
+// merge cleanly and re-writing an unchanged entry is byte-stable. Arrays and scalars pass
+// through untouched.
+const sort_keys_deep = (value) => {
+	if (Array.isArray(value)) return value.map(sort_keys_deep)
+	if (value === null || typeof value !== 'object') return value
+	const out = {}
+	for (const key of Object.keys(value).sort()) out[key] = sort_keys_deep(value[key])
+	return out
+}
+
+// A skills-config.json entry carries ONLY a non-secret `envFile` pointer and non-secret
+// `config` overrides. This helper is the structural guard that a secret value can never
+// leak into the committed file — anything but envFile/config is dropped here.
+const build_config_entry = ({ envFile, config } = {}) => {
+	const entry = {}
+	if (envFile !== undefined) entry.envFile = envFile
+	if (config !== undefined) entry.config = config
+	return entry
+}
+
+const upsert_skill_config = (existing, key, entry) => {
+	const out = { ...(existing || {}) }
+	if (entry === null) delete out[key]
+	else out[key] = entry
+	return out
+}
+
+const write_skills_config = (project_root, config_data) => catch_errors('Failed to write skills-config.json', async () => {
+	const config_path = skills_config_file_path(project_root)
+	const [errors] = await atomic_write_json(config_path, sort_keys_deep(config_data || {}))
+	if (errors) throw errors[0]
+})
+
+// Read-modify-write a single `owner/name` subtree: read the current file, replace only that
+// key's block (leaving every other skill's block untouched), and atomically re-serialize with
+// sorted keys. Pass `entry: null` to remove the key.
+const set_skill_config_entry = (project_root, key, entry) => catch_errors('Failed to set skills-config.json entry', async () => {
+	const config_path = skills_config_file_path(project_root)
+	const [read_errors, existing] = await read_json(config_path)
+	// Distinguish "no file yet" (start fresh) from "file exists but is corrupt". Clobbering a
+	// corrupt file would silently discard every OTHER skill's block — the exact opposite of the
+	// key-scoped guarantee. On a corrupt existing file, fail loud instead of overwriting.
+	if (read_errors) {
+		const [, exists] = await file_exists(config_path)
+		if (exists) throw new Error(`skills-config.json exists but could not be parsed at ${config_path} — refusing to overwrite it. Fix or remove the file, then retry.`)
+	}
+	const current = read_errors ? {} : (existing || {})
+	const next = upsert_skill_config(current, key, entry)
+	const [write_errors] = await atomic_write_json(config_path, sort_keys_deep(next))
+	if (write_errors) throw write_errors[0]
+	return next
+})
+
+module.exports = { write_skills_config, upsert_skill_config, set_skill_config_entry, build_config_entry, sort_keys_deep }

package/src/utils/prompt.js

@@ -13,4 +13,19 @@ const confirm_prompt = (message) => new Promise((resolve) => {
 	})
 })
 
-module.exports = { confirm_prompt }
+// Free-text prompt. Returns the trimmed answer, or '' when there is no TTY (so callers
+// fall back to the schema default). Writes to stderr to keep stdout envelope-clean.
+const question_prompt = (message) => new Promise((resolve) => {
+	if (!process.stdin.isTTY) {
+		resolve('')
+		return
+	}
+
+	const rl = createInterface({ input: process.stdin, output: process.stderr })
+	rl.question(`${message} `, (answer) => {
+		rl.close()
+		resolve(answer.trim())
+	})
+})
+
+module.exports = { confirm_prompt, question_prompt }