happyskills 1.0.1 → 1.1.0

package/CHANGELOG.md

@@ -7,6 +7,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [1.1.0] - 2026-06-02
+
+### Added
+
+- Add `discover_schema` routing action (`next_step.kind: routing`) so a confused agent is steered to the machine-readable CLI surface. Every `--help` output (global and per-command) now ends with a footer pointing to `happyskills schema --json`, and the text-mode unknown-command message points there too — agents reach for the conventional `help`, not the unconventional `schema`, so every help-seeking path now leads back to it. Added to both the CLI and API closed-enum mirrors (additive, non-breaking).
+
+### Changed
+
+- Route the `COMMAND_NOT_FOUND` and `USAGE_ERROR` `--json` envelopes to `discover_schema` (previously `show_format` / none), with `context.commands: ["npx happyskills schema --json"]` — a mistyped-command or bad-flags agent now receives the full CLI contract through the structured `next_step` channel it is already parsing.
+
+## [1.0.2] - 2026-06-01
+
+### Fixed
+
+- Stop `uninstall` from deleting a shared dependency that another installed skill still needs. When a skill depended on by two parents (e.g. `happyskills-design`, required by both `happyskills` and another skill) was resolved across separate install passes, the second pass overwrote its `requested_by` instead of unioning the parents — so uninstalling one parent orphan-pruned the dependency even though the other parent still declared it. Two fixes: `requested_by` is now unioned across install passes, and the orphan pruner additionally cross-checks every surviving skill's `dependencies` map before removing anything.
+
 ## [1.0.1] - 2026-06-01
 
 ### Fixed

package/package.json

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

package/src/constants/next_step_actions.js

@@ -59,6 +59,7 @@ const ATTACH_SCREENSHOT        = 'attach_screenshot'   // § 15.3.4
 
 // kind: routing
 const INSTALL_FIRST            = 'install_first'
+const DISCOVER_SCHEMA          = 'discover_schema'
 
 // kind lookup ──────────────────────────────────────────────────────────────
 const ACTION_KIND = Object.freeze({
@@ -94,6 +95,7 @@ const ACTION_KIND = Object.freeze({
 	[ATTACH_SCREENSHOT]:                  CONTINUATION,
 
 	[INSTALL_FIRST]:                      ROUTING,
+	[DISCOVER_SCHEMA]:                    ROUTING,
 })
 
 const NEXT_STEP_ACTIONS = Object.freeze({
@@ -106,7 +108,7 @@ const NEXT_STEP_ACTIONS = Object.freeze({
 	CONFIRM_DISCARD_OR_SNAPSHOT_FIRST, CONFIRM_CASCADE, CONFIRM_DESTRUCTIVE,
 	PASS_YES_FLAG,
 	RANK_DIGESTS_INLINE, PRESENT_TO_USER, ATTACH_SCREENSHOT,
-	INSTALL_FIRST,
+	INSTALL_FIRST, DISCOVER_SCHEMA,
 })
 
 const NEXT_STEP_ACTION_LIST = Object.freeze(Object.values(NEXT_STEP_ACTIONS).slice().sort())

package/src/constants/next_step_by_error_code.js

@@ -9,9 +9,9 @@
 // applies — agent falls back to "explain to principal").
 
 const {
-	RECOVERY, DECISION, CONFIRMATION,
+	RECOVERY, DECISION, CONFIRMATION, ROUTING,
 	LOGIN, RETRY, RECONCILE_FIRST, PULL_REBASE_FIRST, FIX_VALIDATION_ERRORS,
-	PROVIDE_CHANGELOG, SELF_UPDATE, SHOW_FORMAT,
+	PROVIDE_CHANGELOG, SELF_UPDATE, SHOW_FORMAT, DISCOVER_SCHEMA,
 	RESOLVE_REGRESSION, RESOLVE_MISSING_SKILL_JSON, RESOLVE_MISSING_DIR,
 	RESOLVE_CONFLICTS, RESOLVE_PATCH_REJECTIONS, SPECIFY_WORKSPACE,
 	SPECIFY_BUMP_TYPE, RESOLVE_BUMP_DISAGREEMENT, PICK_VERSION,
@@ -45,6 +45,14 @@ const confirmation = (action, instructions, context = {}) => ({
 	principal_authorization_required: true,
 })
 
+const routing = (action, instructions, context = {}, opts = {}) => ({
+	kind:         ROUTING,
+	action,
+	instructions,
+	context,
+	...(opts.route_to_skill ? { route_to_skill: opts.route_to_skill } : {}),
+})
+
 const NEXT_STEP_BY_ERROR_CODE = Object.freeze({
 	AUTH_REQUIRED: () => recovery(
 		LOGIN,
@@ -86,13 +94,21 @@ const NEXT_STEP_BY_ERROR_CODE = Object.freeze({
 		'The embedding service is temporarily unavailable. Retry shortly.',
 		{ retry_after_seconds: 10, max_attempts: 3 }
 	),
-	COMMAND_NOT_FOUND: (_msg, ctx = {}) => recovery(
-		SHOW_FORMAT,
-		'The command does not exist. Suggest the principal run `happyskills --help` to see available commands, or pick from the suggestion if it matches their intent.',
+	COMMAND_NOT_FOUND: (_msg, ctx = {}) => routing(
+		DISCOVER_SCHEMA,
+		'The command does not exist. Run `happyskills schema --json` to discover every available command with its exact input, output, and error contract. If a suggestion is present and it matches the intent, you may re-run with that command instead.',
 		{
 			got: ctx.got,
 			...(ctx.suggestion ? { suggestion: ctx.suggestion } : {}),
-			commands: ['npx happyskills --help'],
+			commands: ['npx happyskills schema --json'],
+		}
+	),
+	USAGE_ERROR: (_msg, ctx = {}) => routing(
+		DISCOVER_SCHEMA,
+		'The command was invoked with invalid arguments or flags. Run `happyskills schema --json` to see the exact input contract for every command, then re-run with corrected arguments.',
+		{
+			...(ctx.got ? { got: ctx.got } : {}),
+			commands: ['npx happyskills schema --json'],
 		}
 	),
 	INVALID_SLUG: () => recovery(

package/src/constants/next_step_by_error_code.test.js

@@ -0,0 +1,30 @@
+'use strict'
+// Unit coverage for the schema-discovery routing defaults. A generic agent
+// that reaches for the conventional `help` fallback must be routed to the
+// `schema --json` surface — the machine-readable contract is what gives it
+// clarity and correctness on how to use the CLI, not just discoverability.
+
+const { describe, it } = require('node:test')
+const assert = require('node:assert/strict')
+const { next_step_for_error } = require('./next_step_by_error_code')
+const { DISCOVER_SCHEMA, ROUTING, kind_for_action } = require('./next_step_actions')
+
+describe('next_step_by_error_code — schema discovery routing', () => {
+	it('discover_schema is a routing-kind action', () => {
+		assert.strictEqual(kind_for_action(DISCOVER_SCHEMA), ROUTING)
+	})
+
+	for (const code of ['COMMAND_NOT_FOUND', 'USAGE_ERROR']) {
+		it(`${code} routes the agent to \`schema --json\``, () => {
+			const ns = next_step_for_error(code, 'boom', { got: 'foo' })
+			assert.ok(ns, `${code} must produce a next_step`)
+			assert.strictEqual(ns.kind, ROUTING)
+			assert.strictEqual(ns.action, DISCOVER_SCHEMA)
+			assert.ok(Array.isArray(ns.context.commands))
+			assert.ok(
+				ns.context.commands.some(c => c.includes('schema --json')),
+				`${code} next_step must point at \`happyskills schema --json\``
+			)
+		})
+	}
+})

package/src/engine/installer.js

@@ -22,6 +22,34 @@ const _format_warnings = (missing_deps) => (missing_deps || []).map(dep => {
 	return `Missing system dependency: ${dep.name} required by ${dep.skill}${hint}`
 })
 
+// Order-preserving, de-duplicated union of requester lists.
+const _union = (...lists) => {
+	const seen = new Set()
+	const out = []
+	for (const list of lists) {
+		for (const requester of (list || [])) {
+			if (!seen.has(requester)) {
+				seen.add(requester)
+				out.push(requester)
+			}
+		}
+	}
+	return out
+}
+
+// Compute the `requested_by` for a package's lock entry. A package is requested
+// either by the user directly (`__root__`) when it IS the skill being installed,
+// or by `root_skill` when it is a (transitive) dependency. We union that with
+// whatever the lock already recorded so a SHARED dependency keeps every parent
+// across separate install passes — install() resolves one root's tree at a time,
+// so a dependency of two roots (e.g. happyskills + create-release-skill both
+// needing happyskills-design) would otherwise have its `requested_by` clobbered
+// by the last pass, and later be wrongly orphan-pruned on uninstall.
+const merge_requested_by = (prev_requested_by, pkg_skill, root_skill) => {
+	const own = pkg_skill === root_skill ? ['__root__'] : [root_skill]
+	return _union(own, prev_requested_by)
+}
+
 const install = (skill, options = {}) => catch_errors('Install failed', async () => {
 	const { version, global: is_global = false, force = false, fresh = false, project_root, agents: agents_flag } = options
 	const base_dir = skills_dir(is_global, project_root)
@@ -246,7 +274,7 @@ const install = (skill, options = {}) => catch_errors('Install failed', async ()
 				integrity: integrity || null,
 				base_commit: pkg.commit || null,
 				base_integrity: integrity || null,
-				requested_by: pkg.skill === skill ? ['__root__'] : [skill],
+				requested_by: merge_requested_by(lock_data?.skills?.[pkg.skill]?.requested_by, pkg.skill, skill),
 				dependencies: pkg.dependencies || {},
 				...(pkg_type ? { type: pkg_type } : {}),
 				...(pkg.forced ? { forced: true } : {})
@@ -378,4 +406,4 @@ const install_from_lock = (lock_data, options = {}) => catch_errors('Install fro
 	return { source: 'skills-lock.json', installed: all_installed, skipped: all_skipped, warnings: all_warnings }
 })
 
-module.exports = { install, install_from_manifest, install_from_lock }
+module.exports = { install, install_from_manifest, install_from_lock, merge_requested_by }

package/src/engine/installer.test.js

@@ -0,0 +1,41 @@
+const { describe, it } = require('node:test')
+const assert = require('node:assert')
+const { merge_requested_by } = require('./installer')
+
+describe('merge_requested_by', () => {
+	it('records the root skill for a fresh dependency', () => {
+		const result = merge_requested_by(undefined, 'happyskillsai/happyskills-design', 'happyskillsai/happyskills')
+		assert.deepStrictEqual(result, ['happyskillsai/happyskills'])
+	})
+
+	it('records __root__ when the package IS the skill being installed', () => {
+		const result = merge_requested_by(['__root__'], 'happyskillsai/happyskills', 'happyskillsai/happyskills')
+		assert.deepStrictEqual(result, ['__root__'])
+	})
+
+	it('unions a shared dependency across separate install passes', () => {
+		// Pass 1 wrote design as a dependency of happyskills.
+		// Pass 2 re-resolves design as a dependency of create-release-skill and
+		// must NOT clobber the existing parent — both must be retained.
+		const result = merge_requested_by(
+			['happyskillsai/happyskills'],
+			'happyskillsai/happyskills-design',
+			'nicolasdao/create-release-skill'
+		)
+		assert.deepStrictEqual(result, ['nicolasdao/create-release-skill', 'happyskillsai/happyskills'])
+	})
+
+	it('de-duplicates when the same requester reappears', () => {
+		const result = merge_requested_by(
+			['happyskillsai/happyskills'],
+			'happyskillsai/happyskills-design',
+			'happyskillsai/happyskills'
+		)
+		assert.deepStrictEqual(result, ['happyskillsai/happyskills'])
+	})
+
+	it('tolerates a null/empty previous list', () => {
+		assert.deepStrictEqual(merge_requested_by(null, 'a/dep', 'a/root'), ['a/root'])
+		assert.deepStrictEqual(merge_requested_by([], 'a/dep', 'a/root'), ['a/root'])
+	})
+})

package/src/engine/uninstaller.js

@@ -7,12 +7,29 @@ const { resolve_agents, unlink_from_agents } = require('../agents')
 const { print_success, print_info } = require('../ui/output')
 
 const find_orphans = (skills, removed_skill) => {
+	// A skill is still needed if a SURVIVING skill (anything other than the one
+	// being removed) declares it in its `dependencies` map. The dependencies map
+	// mirrors each skill's skill.json and is the authoritative statement of what a
+	// skill needs — independent of `requested_by`, which can be stale or clobbered
+	// when a shared dependency is resolved across multiple install passes. Without
+	// this cross-check, a dependency whose `requested_by` was overwritten to point
+	// only at the removed skill gets pruned even though another installed skill
+	// still requires it (the happyskills-design data-loss bug).
+	const declared_by_survivor = (name) => {
+		for (const [other_name, other] of Object.entries(skills)) {
+			if (other_name === removed_skill) continue
+			const deps = (other && other.dependencies) || {}
+			if (Object.prototype.hasOwnProperty.call(deps, name)) return true
+		}
+		return false
+	}
+
 	const orphans = []
 	for (const [name, data] of Object.entries(skills)) {
 		if (name === removed_skill) continue
 		const requested_by = data.requested_by || []
 		const remaining = requested_by.filter(r => r === '__root__' || (r !== removed_skill && skills[r]))
-		if (remaining.length === 0) {
+		if (remaining.length === 0 && !declared_by_survivor(name)) {
 			orphans.push(name)
 		}
 	}

package/src/engine/uninstaller.test.js

@@ -95,4 +95,42 @@ describe('find_orphans', () => {
 		const result = find_orphans(skills, 'acme/other')
 		assert.ok(!result.includes('acme/deploy'))
 	})
+
+	it('keeps a shared dependency a surviving skill still declares, even when requested_by points only at the removed skill', () => {
+		// Reproduces the happyskills-design data-loss bug: design's requested_by was
+		// clobbered to point only at create-release-skill, but happyskills still
+		// declares it in its dependencies map. Uninstalling create-release-skill must
+		// NOT prune design.
+		const skills = {
+			'happyskillsai/happyskills': {
+				requested_by: ['__root__'],
+				dependencies: { 'happyskillsai/happyskills-design': '^0.1.0' }
+			},
+			'nicolasdao/create-release-skill': {
+				requested_by: ['__root__'],
+				dependencies: { 'happyskillsai/happyskills-design': '^0.9.0' }
+			},
+			'happyskillsai/happyskills-design': {
+				requested_by: ['nicolasdao/create-release-skill']
+			}
+		}
+		const result = find_orphans(skills, 'nicolasdao/create-release-skill')
+		assert.ok(!result.includes('happyskillsai/happyskills-design'))
+	})
+
+	it('prunes a dependency once no surviving skill declares it', () => {
+		// Same shape, but happyskills does NOT declare design — removing its sole
+		// remaining requester should orphan it.
+		const skills = {
+			'nicolasdao/create-release-skill': {
+				requested_by: ['__root__'],
+				dependencies: { 'happyskillsai/happyskills-design': '^0.9.0' }
+			},
+			'happyskillsai/happyskills-design': {
+				requested_by: ['nicolasdao/create-release-skill']
+			}
+		}
+		const result = find_orphans(skills, 'nicolasdao/create-release-skill')
+		assert.ok(result.includes('happyskillsai/happyskills-design'))
+	})
 })

package/src/index.js

@@ -206,7 +206,7 @@ const run = (argv) => {
 		if (suggestion) {
 			console.error(dim(`  Did you mean: happyskills ${suggestion}?`))
 		} else {
-			console.error(dim(`  Run happyskills --help for available commands.`))
+			console.error(dim(`  Run happyskills --help for available commands, or happyskills schema --json for the full machine-readable surface.`))
 		}
 		return process.exit(EXIT_CODES.USAGE)
 	}

package/src/integration/cli.test.js

@@ -280,14 +280,27 @@ describe('CLI — --json: stdout is always valid JSON', () => {
 		assert.ok(typeof env.error.message === 'string' && env.error.message.length > 0)
 	})
 
-	it('unknown command with --json emits the COMMAND_NOT_FOUND envelope', () => {
+	it('unknown command with --json routes the agent to schema discovery', () => {
 		const { stdout, code } = run(['not-a-command', '--json'])
 		assert.strictEqual(code, 2)
 		const env = parse_json_output(stdout, 'unknown-command --json')
 		assert_error_envelope(env, 'COMMAND_NOT_FOUND', 'unknown command')
-		// Recovery hint: show_format with --help in commands[].
-		assert.strictEqual(env.next_step.action, 'show_format')
-		assert.ok(env.next_step.context.commands.some(c => c.includes('--help')))
+		// Routing hint: discover_schema, pointing at `schema --json`. A confused
+		// agent that hit a bad command is handed the full machine-readable surface.
+		assert.strictEqual(env.next_step.kind, 'routing')
+		assert.strictEqual(env.next_step.action, 'discover_schema')
+		assert.ok(env.next_step.context.commands.some(c => c.includes('schema --json')))
+	})
+
+	it('usage error with --json routes the agent to schema discovery', () => {
+		// `--json --text` is mutually exclusive → USAGE_ERROR with no command-
+		// specific next_step, so the default discover_schema routing applies.
+		const { stdout, code } = run(['--json', '--text'])
+		assert.strictEqual(code, 2)
+		const env = parse_json_output(stdout, 'usage-error --json')
+		assert_error_envelope(env, 'USAGE_ERROR', 'mutually exclusive')
+		assert.strictEqual(env.next_step.action, 'discover_schema')
+		assert.ok(env.next_step.context.commands.some(c => c.includes('schema --json')))
 	})
 
 	it('network error produces an envelope with code NETWORK_ERROR + retry next_step', () => {

package/src/ui/output.js

@@ -44,8 +44,15 @@ const format_help = (text) => {
 	}).join('\n')
 }
 
+// Every --help (global and per-command) ends with a pointer to `schema
+// --json`. An agent that reaches for the conventional `help` as a fallback
+// then discovers the machine-readable surface, which is what it actually
+// wants for clarity and correctness on how to use the CLI.
+const SCHEMA_HINT = 'For the complete machine-readable CLI surface — every command\'s inputs, outputs, and error contracts in one call — run: happyskills schema --json'
+
 const print_help = (text) => {
 	console.log(format_help(text))
+	if (!is_json_mode()) console.log(dim(`\n${SCHEMA_HINT}`))
 }
 
 // Visible length of a string, ignoring ANSI escape codes