happyskills 1.18.0 → 1.19.0

package/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [1.19.0] - 2026-07-06
+
+### Added
+
+- Add constellation-aware shared secrets. A non-kit skill that declares `sharedEnv: true` in `skill.json` now shares a single `./secrets/<core>.env` across itself and its skill-dependencies on install, instead of scaffolding an identical per-skill secrets file for every member (the redundant, drift-prone case for related skills). A consumer-set `envFile` still wins, standalone installs and kits are unaffected, and a collision guard warns when two shared members declare the same secret name with a different type. `happyskills validate` now checks `sharedEnv` (must be a boolean; error on a kit; warning when `true` without dependencies). Documented in `docs/skill-format.md` §4.6.
+
 ## [1.18.0] - 2026-07-05
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "happyskills",
-	"version": "1.18.0",
+	"version": "1.19.0",
 	"description": "Package manager for AI agent skills",
 	"license": "SEE LICENSE IN LICENSE",
 	"author": "Nicolas Dao <nic@cloudlesslabs.com> (https://cloudlesslabs.com)",

package/src/skills_config/configure.js

@@ -75,11 +75,54 @@ const configure_installed_skills = (packages, options = {}) => catch_errors('Fai
 
 	const [, existing_config_file] = await read_skills_config(config_root)
 
+	// Constellation shared-env pre-pass (spec: `sharedEnv`). A non-kit package that declares
+	// `sharedEnv: true` is a constellation root: it and every skill-dependency being installed
+	// share ONE derived `.env` (`./secrets/<root>.env`) instead of a redundant, drift-prone file
+	// each. Kits (unrelated bundles) are excluded and keep per-member files. Deterministic: sorted
+	// iteration, first root wins, and a consumer's own envFile pointer (honored in the loop below)
+	// always overrides the shared default.
+	const pkg_keys = new Set((packages || []).map(p => p.skill))
+	const manifest_by_key = new Map()
+	for (const pkg of packages || []) {
+		const pkg_name = pkg.skill.split('/')[1]
+		const [, m] = await read_json(path.join(skill_install_dir(base_dir, pkg_name), SKILL_JSON))
+		if (m) manifest_by_key.set(pkg.skill, m)
+	}
+
+	const shared_env_file_by_key = new Map()
+	for (const root_key of [...pkg_keys].sort()) {
+		const m = manifest_by_key.get(root_key)
+		if (!m || m.sharedEnv !== true || m.type === 'kit') continue
+		const shared_file = `./secrets/${root_key.split('/')[1]}.env`
+		const dep_keys = Object.keys(as_object(m.dependencies) || {})
+		for (const member_key of [root_key, ...dep_keys]) {
+			if (pkg_keys.has(member_key) && !shared_env_file_by_key.has(member_key)) shared_env_file_by_key.set(member_key, shared_file)
+		}
+	}
+
+	// Collision guard: within one shared file, two members declaring the same secret NAME with a
+	// different `type` may not mean the same secret. Warn once so the author reconciles.
+	const shared_secret_seen = new Map() // `${file}\0${name}` -> { type, owner }
+	for (const member_key of [...shared_env_file_by_key.keys()].sort()) {
+		const shared_file = shared_env_file_by_key.get(member_key)
+		const env = as_object((manifest_by_key.get(member_key) || {}).env) || {}
+		for (const [var_name, spec] of Object.entries(env)) {
+			if (!spec || spec.secret !== true) continue
+			const seen_key = `${shared_file}\0${var_name}`
+			const this_type = spec.type === undefined ? null : spec.type
+			const prev = shared_secret_seen.get(seen_key)
+			if (prev) {
+				if (prev.type !== this_type) warnings.push(`Shared-env collision: secret "${var_name}" is declared by ${prev.owner} and ${member_key} with different types in ${shared_file} — verify they are the same secret.`)
+			} else {
+				shared_secret_seen.set(seen_key, { type: this_type, owner: member_key })
+			}
+		}
+	}
+
 	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))
+		const manifest = manifest_by_key.get(key)
 		if (!manifest) continue
 
 		const config_schema = as_object(manifest.config)
@@ -122,7 +165,7 @@ const configure_installed_skills = (packages, options = {}) => catch_errors('Fai
 
 		let env_file_rel = (existing_entry && existing_entry.envFile) || null
 		if (secret_names.length) {
-			env_file_rel = env_file_rel || `./secrets/${name}.env`
+			env_file_rel = env_file_rel || shared_env_file_by_key.get(key) || `./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))

package/src/skills_config/configure.test.js

@@ -127,6 +127,104 @@ describe('configure_installed_skills — interactive overrides', () => {
 	})
 })
 
+describe('configure_installed_skills — constellation sharedEnv', () => {
+	const TOKEN_ENV = { env: { CLOUDFLARE_API_TOKEN: { required: true, secret: true, description: 'CF token' } } }
+
+	it('routes a shared-env core and its dependency members to ONE derived envFile', async () => {
+		write_skill(base_dir, 'cloudflare', {
+			sharedEnv: true,
+			dependencies: { 'nicolasdao/cloudflare-deploy': '^0.1.0', 'nicolasdao/cloudflare-config': '^0.1.0' },
+			...TOKEN_ENV
+		})
+		write_skill(base_dir, 'cloudflare-deploy', TOKEN_ENV)
+		write_skill(base_dir, 'cloudflare-config', TOKEN_ENV)
+
+		const [err] = await configure_installed_skills(
+			[{ skill: 'nicolasdao/cloudflare' }, { skill: 'nicolasdao/cloudflare-deploy' }, { skill: 'nicolasdao/cloudflare-config' }],
+			{ base_dir, config_root, interactive: false }
+		)
+		assert.ifError(err)
+
+		const cfg = JSON.parse(read(path.join(config_root, 'skills-config.json')))
+		assert.strictEqual(cfg['nicolasdao/cloudflare'].envFile, './secrets/cloudflare.env')
+		assert.strictEqual(cfg['nicolasdao/cloudflare-deploy'].envFile, './secrets/cloudflare.env')
+		assert.strictEqual(cfg['nicolasdao/cloudflare-config'].envFile, './secrets/cloudflare.env')
+
+		// exactly ONE shared secrets file — the redundant per-member files are not created
+		assert.ok(fs.existsSync(path.join(config_root, 'secrets', 'cloudflare.env')))
+		assert.ok(!fs.existsSync(path.join(config_root, 'secrets', 'cloudflare-deploy.env')))
+		assert.ok(!fs.existsSync(path.join(config_root, 'secrets', 'cloudflare-config.env')))
+
+		// the shared file carries the token name exactly once
+		const env_content = read(path.join(config_root, 'secrets', 'cloudflare.env'))
+		assert.strictEqual((env_content.match(/CLOUDFLARE_API_TOKEN=/g) || []).length, 1)
+	})
+
+	it('respects a consumer-set envFile over the shared default', async () => {
+		fs.writeFileSync(
+			path.join(config_root, 'skills-config.json'),
+			JSON.stringify({ 'nicolasdao/cloudflare-deploy': { envFile: './my-secrets/cf.env' } }, null, '\t')
+		)
+		write_skill(base_dir, 'cloudflare', { sharedEnv: true, dependencies: { 'nicolasdao/cloudflare-deploy': '^0.1.0' }, ...TOKEN_ENV })
+		write_skill(base_dir, 'cloudflare-deploy', TOKEN_ENV)
+
+		const [err] = await configure_installed_skills(
+			[{ skill: 'nicolasdao/cloudflare' }, { skill: 'nicolasdao/cloudflare-deploy' }],
+			{ base_dir, config_root, interactive: false }
+		)
+		assert.ifError(err)
+
+		const cfg = JSON.parse(read(path.join(config_root, 'skills-config.json')))
+		assert.strictEqual(cfg['nicolasdao/cloudflare-deploy'].envFile, './my-secrets/cf.env') // consumer override wins
+		assert.strictEqual(cfg['nicolasdao/cloudflare'].envFile, './secrets/cloudflare.env')
+	})
+
+	it('does NOT share when the core lacks sharedEnv (regression: per-skill files)', async () => {
+		write_skill(base_dir, 'cloudflare', { dependencies: { 'nicolasdao/cloudflare-deploy': '^0.1.0' }, ...TOKEN_ENV })
+		write_skill(base_dir, 'cloudflare-deploy', TOKEN_ENV)
+
+		const [err] = await configure_installed_skills(
+			[{ skill: 'nicolasdao/cloudflare' }, { skill: 'nicolasdao/cloudflare-deploy' }],
+			{ base_dir, config_root, interactive: false }
+		)
+		assert.ifError(err)
+
+		const cfg = JSON.parse(read(path.join(config_root, 'skills-config.json')))
+		assert.strictEqual(cfg['nicolasdao/cloudflare'].envFile, './secrets/cloudflare.env')
+		assert.strictEqual(cfg['nicolasdao/cloudflare-deploy'].envFile, './secrets/cloudflare-deploy.env')
+	})
+
+	it('does NOT share for a kit (kit members keep isolated secrets)', async () => {
+		write_skill(base_dir, '_kit-x', { type: 'kit', sharedEnv: true, dependencies: { 'acme/a': '^1.0.0' } })
+		write_skill(base_dir, 'a', TOKEN_ENV)
+
+		const [err] = await configure_installed_skills(
+			[{ skill: 'acme/_kit-x' }, { skill: 'acme/a' }],
+			{ base_dir, config_root, interactive: false }
+		)
+		assert.ifError(err)
+
+		const cfg = JSON.parse(read(path.join(config_root, 'skills-config.json')))
+		assert.strictEqual(cfg['acme/a'].envFile, './secrets/a.env') // NOT the kit's file
+	})
+
+	it('warns when two shared members declare the same secret with a different type', async () => {
+		write_skill(base_dir, 'core', {
+			sharedEnv: true,
+			dependencies: { 'acme/sat': '^1.0.0' },
+			env: { TOK: { required: true, secret: true, type: 'string' } }
+		})
+		write_skill(base_dir, 'sat', { env: { TOK: { required: true, secret: true, type: 'integer' } } })
+
+		const [err, result] = await configure_installed_skills(
+			[{ skill: 'acme/core' }, { skill: 'acme/sat' }],
+			{ base_dir, config_root, interactive: false }
+		)
+		assert.ifError(err)
+		assert.ok(result.warnings.some(w => /TOK/.test(w) && /shared/i.test(w)), 'a same-name/different-type shared secret must warn')
+	})
+})
+
 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.

package/src/validation/skill_json_rules.js

@@ -277,6 +277,40 @@ const validate_env = (manifest) => {
 	return results
 }
 
+// sharedEnv (constellation-only). When a non-kit skill sets `sharedEnv: true`, the CLI points the
+// skill AND its skill-dependencies at one shared `.env` on install — a constellation shares a
+// config namespace, so its members should not each scaffold an identical secrets file. Forbidden
+// on kits: a kit bundles unrelated skills, which keep isolated secrets. A no-op without deps.
+const validate_shared_env = (manifest) => {
+	const results = []
+	if (manifest.sharedEnv === undefined) return results
+
+	if (typeof manifest.sharedEnv !== 'boolean') {
+		results.push(result('sharedEnv', 'type', 'error', 'sharedEnv must be a boolean'))
+		return results
+	}
+
+	if (manifest.sharedEnv !== true) {
+		results.push(result('sharedEnv', 'valid', 'pass', 'sharedEnv is false'))
+		return results
+	}
+
+	if (manifest.type === SKILL_TYPES.KIT) {
+		results.push(result('sharedEnv', 'kit_forbidden', 'error', 'sharedEnv is not allowed on a kit — kit members bundle unrelated skills and keep isolated secrets. Use sharedEnv only on a constellation core.'))
+		return results
+	}
+
+	const deps = manifest.dependencies
+	const dep_count = deps && typeof deps === 'object' && !Array.isArray(deps) ? Object.keys(deps).length : 0
+	if (dep_count === 0) {
+		results.push(result('sharedEnv', 'no_dependencies', 'warning', 'sharedEnv: true has no effect without dependencies — it shares one .env across the skill and its skill-dependencies (a constellation).'))
+		return results
+	}
+
+	results.push(result('sharedEnv', 'valid', 'pass', 'sharedEnv: true — the skill and its dependencies will share one .env on install'))
+	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)
@@ -308,6 +342,7 @@ const validate_skill_json = (skill_dir) => catch_errors('Failed to validate skil
 	results.push(...validate_system_dependencies(manifest))
 	results.push(...validate_config(manifest))
 	results.push(...validate_env(manifest))
+	results.push(...validate_shared_env(manifest))
 
 	const is_kit = manifest.type === SKILL_TYPES.KIT
 	if (is_kit) {

package/src/validation/skill_json_rules.test.js

@@ -69,6 +69,40 @@ describe('validate_skill_json — name', () => {
 	})
 })
 
+describe('validate_skill_json — sharedEnv', () => {
+	it('errors when sharedEnv is not a boolean', async () => {
+		write_json(tmp, { name: 'core', version: '1.0.0', sharedEnv: 'yes', dependencies: { 'a/b': '^1.0.0' } })
+		const [err, data] = await validate_skill_json(tmp)
+		assert.ifError(err)
+		const check = data.results.find(r => r.field === 'sharedEnv' && r.rule === 'type')
+		assert.strictEqual(check.severity, 'error')
+	})
+
+	it('errors when a kit declares sharedEnv: true', async () => {
+		write_json(tmp, { name: '_kit-x', version: '1.0.0', type: 'kit', sharedEnv: true, dependencies: { 'a/b': '^1.0.0' } })
+		const [err, data] = await validate_skill_json(tmp)
+		assert.ifError(err)
+		const check = data.results.find(r => r.field === 'sharedEnv' && r.rule === 'kit_forbidden')
+		assert.strictEqual(check.severity, 'error')
+	})
+
+	it('warns when sharedEnv: true has no dependencies', async () => {
+		write_json(tmp, { name: 'core', version: '1.0.0', sharedEnv: true })
+		const [err, data] = await validate_skill_json(tmp)
+		assert.ifError(err)
+		const check = data.results.find(r => r.field === 'sharedEnv' && r.rule === 'no_dependencies')
+		assert.strictEqual(check.severity, 'warning')
+	})
+
+	it('passes for sharedEnv: true with dependencies', async () => {
+		write_json(tmp, { name: 'core', version: '1.0.0', sharedEnv: true, dependencies: { 'a/b': '^1.0.0' } })
+		const [err, data] = await validate_skill_json(tmp)
+		assert.ifError(err)
+		const check = data.results.find(r => r.field === 'sharedEnv' && r.rule === 'valid')
+		assert.strictEqual(check.severity, 'pass')
+	})
+})
+
 describe('validate_skill_json — version', () => {
 	it('errors when version is missing', async () => {
 		write_json(tmp, { name: 'my-skill' })