happyskills 0.53.0 → 1.0.0

package/src/integration/cli.test.js

@@ -16,6 +16,11 @@ const { spawnSync } = require('child_process')
 const fs = require('fs')
 const os = require('os')
 const path = require('path')
+const {
+	parse_envelope,
+	assert_success_envelope,
+	assert_error_envelope,
+} = require('../schema/envelope_test_helpers')
 
 const CLI = path.resolve(__dirname, '../../bin/happyskills.js')
 const NODE = process.execPath
@@ -28,11 +33,21 @@ const NODE = process.execPath
  * opts.cwd lets individual tests run in an isolated directory.
  */
 const run = (args = [], env_override = {}, opts = {}) => {
-	const result = spawnSync(NODE, [CLI, ...args], {
+	// Per spec § 8.1, a spawned process (isTTY=false) auto-flips to JSON
+	// mode. The integration tests need an EXPLICIT mode declaration so each
+	// test asserts on the surface it claims to test. Tests that exercise
+	// text-mode behaviour (stderr messages, "Did you mean", help text)
+	// inherit --text by default; tests that exercise the JSON envelope pass
+	// --json explicitly. CI=false is also set so the CI heuristic doesn't
+	// silently flip the mode in pipelines that export CI=true.
+	const has_mode_flag = args.includes('--json') || args.includes('--text')
+	const final_args = has_mode_flag ? args : [...args, '--text']
+	const result = spawnSync(NODE, [CLI, ...final_args], {
 		env: {
 			...process.env,
-			NO_COLOR: '1',
+			NO_COLOR: '1', HAPPYSKILLS_ENVELOPE_STRICT: '1',
 			HAPPYSKILLS_API_URL: 'http://localhost:0',
+			CI: '',
 			...env_override
 		},
 		encoding: 'utf-8',
@@ -47,15 +62,12 @@ const run = (args = [], env_override = {}, opts = {}) => {
 }
 
 /**
- * Parse stdout as JSON. Throws a descriptive assertion error if parsing fails.
+ * Parse stdout as a CLI envelope. Validates against the closed envelope
+ * schema (spec 260525-cli-default-json). Throws on parse OR shape failure.
+ * Every --json CLI output in this suite goes through this helper — that is
+ * the test-suite-level invariant required by spec § 13 Session 1b.
  */
-const parse_json_output = (stdout, label = '') => {
-	try {
-		return JSON.parse(stdout)
-	} catch {
-		assert.fail(`${label ? label + ': ' : ''}stdout is not valid JSON:\n${stdout}`)
-	}
-}
+const parse_json_output = (stdout, label = '') => parse_envelope(stdout, label)
 
 /**
  * Create a temporary directory for a test and return its path.
@@ -249,37 +261,45 @@ describe('CLI — exit codes', () => {
 // ─── --json flag: output envelope ─────────────────────────────────────────────
 
 describe('CLI — --json: stdout is always valid JSON', () => {
-	it('stdout is valid JSON for a usage error (install bad-skill --json)', () => {
+	it('emits an envelope-shaped error for a usage error (install bad-skill --json)', () => {
 		const { stdout, code } = run(['install', 'no-slash', '--json'])
 		assert.strictEqual(code, 2)
-		const out = parse_json_output(stdout, 'install bad-skill --json')
-		assert.ok('error' in out, 'top-level key should be "error"')
-		assert.ok(!('data' in out), 'should not have a "data" key')
+		const env = parse_json_output(stdout, 'install bad-skill --json')
+		// Envelope is uniformly six-keyed — error AND data both present.
+		assert_error_envelope(env, 'USAGE_ERROR', 'install bad-skill')
+		assert.deepStrictEqual(env.data, {}, 'data must be the empty object on a usage error')
 	})
 
-	it('usage error JSON contains code, message, exit_code', () => {
+	it('usage error envelope carries code, message, meta.exit_code, and meta.command', () => {
 		const { stdout } = run(['install', 'no-slash', '--json'])
-		const out = parse_json_output(stdout)
-		assert.strictEqual(out.error.code, 'USAGE_ERROR')
-		assert.strictEqual(out.error.exit_code, 2)
-		assert.ok(typeof out.error.message === 'string' && out.error.message.length > 0)
+		const env = parse_json_output(stdout)
+		assert.strictEqual(env.error.code, 'USAGE_ERROR')
+		assert.strictEqual(env.meta.exit_code, 2, 'exit_code lives on meta, not error')
+		assert.ok(!('exit_code' in env.error), 'exit_code must NOT live on error any more')
+		assert.strictEqual(env.meta.command, 'install')
+		assert.ok(typeof env.error.message === 'string' && env.error.message.length > 0)
 	})
 
-	it('unknown command with --json emits JSON error (not plain text)', () => {
+	it('unknown command with --json emits the COMMAND_NOT_FOUND envelope', () => {
 		const { stdout, code } = run(['not-a-command', '--json'])
 		assert.strictEqual(code, 2)
-		const out = parse_json_output(stdout, 'unknown-command --json')
-		assert.strictEqual(out.error.code, 'USAGE_ERROR')
+		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')))
 	})
 
-	it('network error produces JSON with code NETWORK_ERROR', () => {
+	it('network error produces an envelope with code NETWORK_ERROR + retry next_step', () => {
 		// search requires a network call; localhost:0 always fails.
 		// --limit is required, so it must be passed to reach the network call.
 		const { stdout, code } = run(['search', 'anything', '--json', '--limit', '10'])
 		assert.strictEqual(code, 4)
-		const out = parse_json_output(stdout, 'search --json network failure')
-		assert.strictEqual(out.error.code, 'NETWORK_ERROR')
-		assert.strictEqual(out.error.exit_code, 4)
+		const env = parse_json_output(stdout, 'search --json network failure')
+		assert_error_envelope(env, 'NETWORK_ERROR', 'search network')
+		assert.strictEqual(env.meta.exit_code, 4)
+		assert.strictEqual(env.next_step.action, 'retry', 'NETWORK_ERROR must carry the retry recovery next_step')
+		assert.strictEqual(env.next_step.kind, 'recovery')
 	})
 
 	it('no stdout noise when --json is active (only one JSON object)', () => {
@@ -292,25 +312,26 @@ describe('CLI — --json: stdout is always valid JSON', () => {
 
 // ─── --json flag: success data envelope ───────────────────────────────────────
 
-describe('CLI — --json: success responses use { data } envelope', () => {
-	it('init --json returns { data: { name, files_created, directory } }', () => {
+describe('CLI — --json: success envelopes', () => {
+	it('init --json emits a success envelope with name, files_created, directory', () => {
 		const tmp = make_tmp()
 		try {
 			const { stdout, code } = run(['init', 'my-skill', '--json'], {}, { cwd: tmp })
 			assert.strictEqual(code, 0)
-			const out = parse_json_output(stdout, 'init --json')
-			assert.ok('data' in out, 'should have top-level "data" key')
-			assert.strictEqual(out.data.name, 'my-skill')
-			assert.ok(Array.isArray(out.data.files_created))
-			assert.ok(out.data.files_created.includes('skill.json'))
-			assert.ok(out.data.files_created.includes('SKILL.md'))
-			assert.ok(typeof out.data.directory === 'string')
+			const env = parse_json_output(stdout, 'init --json')
+			assert_success_envelope(env, 'init --json')
+			assert.strictEqual(env.meta.command, 'init')
+			assert.strictEqual(env.data.name, 'my-skill')
+			assert.ok(Array.isArray(env.data.files_created))
+			assert.ok(env.data.files_created.includes('skill.json'))
+			assert.ok(env.data.files_created.includes('SKILL.md'))
+			assert.ok(typeof env.data.directory === 'string')
 		} finally {
 			fs.rmSync(tmp, { recursive: true, force: true })
 		}
 	})
 
-	it('init --json error when skill.json already exists returns { error }', () => {
+	it('init --json when skill.json already exists emits an ALREADY_EXISTS error envelope', () => {
 		const tmp = make_tmp()
 		try {
 			// Create .agents/skills/test-skill/skill.json first
@@ -319,37 +340,36 @@ describe('CLI — --json: success responses use { data } envelope', () => {
 			fs.writeFileSync(path.join(skill_dir, 'skill.json'), '{}')
 			const { stdout, code } = run(['init', 'test-skill', '--json'], {}, { cwd: tmp })
 			assert.strictEqual(code, 1)
-			const out = parse_json_output(stdout, 'init --json duplicate')
-			assert.ok('error' in out)
-			assert.strictEqual(out.error.exit_code, 1)
+			const env = parse_json_output(stdout, 'init --json duplicate')
+			assert_error_envelope(env, 'ALREADY_EXISTS', 'init duplicate')
+			assert.strictEqual(env.meta.exit_code, 1)
 		} finally {
 			fs.rmSync(tmp, { recursive: true, force: true })
 		}
 	})
 
-	it('logout --json returns { data: { status: "logged_out" } }', () => {
+	it('logout --json emits success envelope with data.status', () => {
 		// Use an isolated XDG dir — clear_token on a missing file still succeeds
 		const { stdout, code } = run(['logout', '--json'], { XDG_CONFIG_HOME: ISOLATED_XDG })
 		assert.strictEqual(code, 0)
-		const out = parse_json_output(stdout, 'logout --json')
-		assert.ok('data' in out)
-		assert.strictEqual(out.data.status, 'logged_out')
+		const env = parse_json_output(stdout, 'logout --json')
+		assert_success_envelope(env)
+		assert.strictEqual(env.data.status, 'logged_out')
 	})
 
-	it('login --json with no stored credentials returns { error: { code: "INTERACTIVE_REQUIRED" } }', () => {
+	it('login --json with no stored credentials emits INTERACTIVE_REQUIRED', () => {
 		const tmp_xdg = make_tmp()
 		try {
 			const { stdout, code } = run(['login', '--json'], { XDG_CONFIG_HOME: tmp_xdg })
 			assert.strictEqual(code, 1)
-			const out = parse_json_output(stdout, 'login --json not authenticated')
-			assert.ok('error' in out)
-			assert.strictEqual(out.error.code, 'INTERACTIVE_REQUIRED')
+			const env = parse_json_output(stdout, 'login --json not authenticated')
+			assert_error_envelope(env, 'INTERACTIVE_REQUIRED', 'login --json')
 		} finally {
 			fs.rmSync(tmp_xdg, { recursive: true, force: true })
 		}
 	})
 
-	it('login --json --browser with stored credentials returns already_logged_in', () => {
+	it('login --json --browser with stored credentials emits success with data.status=already_logged_in', () => {
 		const tmp_xdg = make_tmp()
 		try {
 			const creds_dir = path.join(tmp_xdg, 'happyskills')
@@ -365,11 +385,11 @@ describe('CLI — --json: success responses use { data } envelope', () => {
 			}, null, '\t'))
 			const { stdout, code } = run(['login', '--json', '--browser'], { XDG_CONFIG_HOME: tmp_xdg })
 			assert.strictEqual(code, 0)
-			const out = parse_json_output(stdout, 'login --json --browser with credentials')
-			assert.ok('data' in out)
-			assert.strictEqual(out.data.status, 'already_logged_in')
-			assert.strictEqual(out.data.username, 'testuser')
-			assert.strictEqual(out.data.email, 'test@example.com')
+			const env = parse_json_output(stdout, 'login --json --browser with credentials')
+			assert_success_envelope(env)
+			assert.strictEqual(env.data.status, 'already_logged_in')
+			assert.strictEqual(env.data.username, 'testuser')
+			assert.strictEqual(env.data.email, 'test@example.com')
 		} finally {
 			fs.rmSync(tmp_xdg, { recursive: true, force: true })
 		}
@@ -378,30 +398,27 @@ describe('CLI — --json: success responses use { data } envelope', () => {
 
 // ─── --json flag: existing commands use { data } envelope ─────────────────────
 
-describe('CLI — --json: existing json commands now use { data } envelope', () => {
-	it('list --json returns { data: { skills, drafts, external } }', () => {
+describe('CLI — --json: existing json commands use the envelope', () => {
+	it('list --json returns success envelope with data.{skills,drafts,external}', () => {
 		// Run in a temp dir with no lock file — produces empty result
 		const tmp = make_tmp()
 		try {
 			const { stdout, code } = run(['list', '--json'], {}, { cwd: tmp })
 			assert.strictEqual(code, 0)
-			const out = parse_json_output(stdout, 'list --json empty')
-			assert.ok('data' in out, 'should have top-level "data" key')
-			assert.ok('skills' in out.data, 'data.skills should exist')
-			assert.ok('drafts' in out.data, 'data.drafts should exist')
-			assert.ok('external' in out.data, 'data.external should exist')
-			assert.ok(typeof out.data.skills === 'object' && !Array.isArray(out.data.skills))
-			assert.ok(Array.isArray(out.data.drafts))
-			assert.ok(Array.isArray(out.data.external))
+			const env = parse_json_output(stdout, 'list --json empty')
+			assert_success_envelope(env)
+			assert.ok('skills' in env.data, 'data.skills should exist')
+			assert.ok('drafts' in env.data, 'data.drafts should exist')
+			assert.ok('external' in env.data, 'data.external should exist')
+			assert.ok(typeof env.data.skills === 'object' && !Array.isArray(env.data.skills))
+			assert.ok(Array.isArray(env.data.drafts))
+			assert.ok(Array.isArray(env.data.external))
 		} finally {
 			fs.rmSync(tmp, { recursive: true, force: true })
 		}
 	})
 
 	it('list --json classifies init-scaffolded skills as drafts, foreign-shaped ones as external', () => {
-		// Two on-disk skills, no lock file:
-		//   - "my-draft"   has a HappySkills-shaped skill.json (init-style)
-		//   - "my-foreign" has only SKILL.md (foreign / hand-rolled)
 		const tmp = make_tmp()
 		try {
 			const draft_dir = path.join(tmp, '.agents', 'skills', 'my-draft')
@@ -422,35 +439,35 @@ describe('CLI — --json: existing json commands now use { data } envelope', ()
 
 			const { stdout, code } = run(['list', '--json'], {}, { cwd: tmp })
 			assert.strictEqual(code, 0)
-			const out = parse_json_output(stdout, 'list --json mixed')
-			assert.strictEqual(out.data.drafts.length, 1, 'should have exactly one draft')
-			assert.strictEqual(out.data.drafts[0].name, 'my-draft')
-			assert.strictEqual(out.data.drafts[0].version, '0.1.0')
-			assert.strictEqual(out.data.external.length, 1, 'should have exactly one external')
-			assert.strictEqual(out.data.external[0].name, 'my-foreign')
+			const env = parse_json_output(stdout, 'list --json mixed')
+			assert_success_envelope(env)
+			assert.strictEqual(env.data.drafts.length, 1, 'should have exactly one draft')
+			assert.strictEqual(env.data.drafts[0].name, 'my-draft')
+			assert.strictEqual(env.data.drafts[0].version, '0.1.0')
+			assert.strictEqual(env.data.external.length, 1, 'should have exactly one external')
+			assert.strictEqual(env.data.external[0].name, 'my-foreign')
 		} finally {
 			fs.rmSync(tmp, { recursive: true, force: true })
 		}
 	})
 
-	it('search --json usage error returns { error } not raw text', () => {
+	it('search --json usage error emits a USAGE_ERROR envelope', () => {
 		const { stdout, code } = run(['search', '--json'])
 		assert.strictEqual(code, 2)
-		const out = parse_json_output(stdout, 'search --json no query')
-		assert.ok('error' in out)
-		assert.strictEqual(out.error.code, 'USAGE_ERROR')
+		const env = parse_json_output(stdout, 'search --json no query')
+		assert_error_envelope(env, 'USAGE_ERROR')
 	})
 
-	it('check --json with no skills returns { data: { results: [], outdated_count, up_to_date_count } }', () => {
+	it('check --json with no skills returns success envelope with results, outdated_count, up_to_date_count', () => {
 		const tmp = make_tmp()
 		try {
 			const { stdout, code } = run(['check', '--json'], {}, { cwd: tmp })
 			assert.strictEqual(code, 0)
-			const out = parse_json_output(stdout, 'check --json empty')
-			assert.ok('data' in out)
-			assert.ok(Array.isArray(out.data.results))
-			assert.strictEqual(out.data.outdated_count, 0)
-			assert.strictEqual(out.data.up_to_date_count, 0)
+			const env = parse_json_output(stdout, 'check --json empty')
+			assert_success_envelope(env)
+			assert.ok(Array.isArray(env.data.results))
+			assert.strictEqual(env.data.outdated_count, 0)
+			assert.strictEqual(env.data.up_to_date_count, 0)
 		} finally {
 			fs.rmSync(tmp, { recursive: true, force: true })
 		}
@@ -460,15 +477,15 @@ describe('CLI — --json: existing json commands now use { data } envelope', ()
 // ─── update --all (smart batch-check) ─────────────────────────────────────────
 
 describe('CLI — --json: update --all command', () => {
-	it('update --all --json with no installed skills returns { data: { results, outdated_count, ... } }', () => {
+	it('update --all --json with no installed skills returns success envelope with results', () => {
 		const tmp = make_tmp()
 		try {
 			const { stdout, code } = run(['update', '--all', '--json'], {}, { cwd: tmp })
 			assert.strictEqual(code, 0)
-			const out = parse_json_output(stdout, 'update --all --json empty')
-			assert.ok('data' in out)
-			assert.ok(Array.isArray(out.data.results))
-			assert.strictEqual(out.data.outdated_count, 0)
+			const env = parse_json_output(stdout, 'update --all --json empty')
+			assert_success_envelope(env)
+			assert.ok(Array.isArray(env.data.results))
+			assert.strictEqual(env.data.outdated_count, 0)
 		} finally {
 			fs.rmSync(tmp, { recursive: true, force: true })
 		}
@@ -486,13 +503,12 @@ describe('CLI — setup command', () => {
 		assert.match(stdout, /Examples:/)
 	})
 
-	it('setup --json produces a network error (JSON) when API is unreachable', () => {
+	it('setup --json produces a NETWORK_ERROR envelope when API is unreachable', () => {
 		const { stdout, code } = run(['setup', '--json'])
 		assert.strictEqual(code, 4)
-		const out = parse_json_output(stdout, 'setup --json network failure')
-		assert.ok('error' in out)
-		assert.strictEqual(out.error.code, 'NETWORK_ERROR')
-		assert.strictEqual(out.error.exit_code, 4)
+		const env = parse_json_output(stdout, 'setup --json network failure')
+		assert_error_envelope(env, 'NETWORK_ERROR')
+		assert.strictEqual(env.meta.exit_code, 4)
 	})
 })
 
@@ -507,16 +523,15 @@ describe('CLI — self-update command', () => {
 		assert.match(stdout, /Examples:/)
 	})
 
-	it('self-update --json produces a network error (JSON) when npm registry is unreachable', () => {
+	it('self-update --json produces a NETWORK_ERROR envelope when npm registry is unreachable', () => {
 		const { stdout, code } = run(
 			['self-update', '--json'],
 			{ HAPPYSKILLS_NPM_REGISTRY_URL: 'http://localhost:0' }
 		)
 		assert.strictEqual(code, 4)
-		const out = parse_json_output(stdout, 'self-update --json network failure')
-		assert.ok('error' in out)
-		assert.strictEqual(out.error.code, 'NETWORK_ERROR')
-		assert.strictEqual(out.error.exit_code, 4)
+		const env = parse_json_output(stdout, 'self-update --json network failure')
+		assert_error_envelope(env, 'NETWORK_ERROR')
+		assert.strictEqual(env.meta.exit_code, 4)
 	})
 })
 
@@ -553,14 +568,13 @@ describe('CLI — validate command', () => {
 		}
 	})
 
-	it('exits 2 (JSON) when skill does not exist', () => {
+	it('emits USAGE_ERROR envelope (exit 2) when skill does not exist', () => {
 		const tmp = make_tmp()
 		try {
 			const { stdout, code } = run(['validate', 'nonexistent', '--json'], {}, { cwd: tmp })
 			assert.strictEqual(code, 2)
-			const out = parse_json_output(stdout, 'validate nonexistent --json')
-			assert.ok('error' in out)
-			assert.strictEqual(out.error.code, 'USAGE_ERROR')
+			const env = parse_json_output(stdout, 'validate nonexistent --json')
+			assert_error_envelope(env, 'USAGE_ERROR')
 		} finally {
 			fs.rmSync(tmp, { recursive: true, force: true })
 		}
@@ -598,7 +612,7 @@ describe('CLI — validate command', () => {
 		}
 	})
 
-	it('--json returns correct schema for a valid skill', () => {
+	it('--json returns a success envelope for a valid skill', () => {
 		const tmp = make_tmp()
 		const skill_dir = path.join(tmp, '.agents', 'skills', 'test-skill')
 		fs.mkdirSync(skill_dir, { recursive: true })
@@ -610,22 +624,24 @@ describe('CLI — validate command', () => {
 		try {
 			const { stdout, code } = run(['validate', 'test-skill', '--json'], {}, { cwd: tmp })
 			assert.strictEqual(code, 0)
-			const out = parse_json_output(stdout, 'validate --json valid skill')
-			assert.ok('data' in out)
-			assert.strictEqual(out.data.skill, 'test-skill')
-			assert.strictEqual(out.data.valid, true)
-			assert.ok(Array.isArray(out.data.errors))
-			assert.ok(Array.isArray(out.data.warnings))
-			assert.strictEqual(typeof out.data.checks_passed, 'number')
-			assert.strictEqual(typeof out.data.checks_failed, 'number')
-			assert.strictEqual(typeof out.data.checks_warned, 'number')
-			assert.strictEqual(out.data.checks_failed, 0)
+			const env = parse_json_output(stdout, 'validate --json valid skill')
+			assert_success_envelope(env)
+			assert.strictEqual(env.data.skill, 'test-skill')
+			assert.strictEqual(env.data.valid, true)
+			assert.ok(Array.isArray(env.data.errors))
+			// Note: validate's content-level warnings live INSIDE data, NOT in
+			// the top-level envelope.warnings (those are envelope-level).
+			assert.ok(Array.isArray(env.data.warnings))
+			assert.strictEqual(typeof env.data.checks_passed, 'number')
+			assert.strictEqual(typeof env.data.checks_failed, 'number')
+			assert.strictEqual(typeof env.data.checks_warned, 'number')
+			assert.strictEqual(env.data.checks_failed, 0)
 		} finally {
 			fs.rmSync(tmp, { recursive: true, force: true })
 		}
 	})
 
-	it('--json returns errors for an invalid skill', () => {
+	it('--json returns a VALIDATION_FAILED error envelope for an invalid skill', () => {
 		const tmp = make_tmp()
 		const skill_dir = path.join(tmp, '.agents', 'skills', 'bad-skill')
 		fs.mkdirSync(skill_dir, { recursive: true })
@@ -634,10 +650,13 @@ describe('CLI — validate command', () => {
 		try {
 			const { stdout, code } = run(['validate', 'bad-skill', '--json'], {}, { cwd: tmp })
 			assert.strictEqual(code, 1)
-			const out = parse_json_output(stdout, 'validate --json invalid skill')
-			assert.strictEqual(out.data.valid, false)
-			assert.ok(out.data.errors.length > 0)
-			assert.ok(out.data.checks_failed > 0)
+			const env = parse_json_output(stdout, 'validate --json invalid skill')
+			assert_error_envelope(env, 'VALIDATION_FAILED')
+			// Field-level violations live under error.validation_errors per
+			// spec § 4.4 (domain-specific extras alongside code/message).
+			assert.ok(Array.isArray(env.error.validation_errors) && env.error.validation_errors.length > 0)
+			// fix_validation_errors recovery action.
+			assert.strictEqual(env.next_step.action, 'fix_validation_errors')
 		} finally {
 			fs.rmSync(tmp, { recursive: true, force: true })
 		}
@@ -674,7 +693,7 @@ describe('CLI — delete command', () => {
 		assert.ok(stdout.toLowerCase().includes('delete'))
 	})
 
-	it('delete acme/deploy-aws --json without -y exits with code 1 (confirmation required)', () => {
+	it('delete acme/deploy-aws --json without -y emits CONFIRMATION_REQUIRED with confirm_destructive', () => {
 		const tmp_xdg = make_tmp()
 		try {
 			const creds_dir = path.join(tmp_xdg, 'happyskills')
@@ -690,15 +709,18 @@ describe('CLI — delete command', () => {
 			}, null, '\t'))
 			const { stdout, code } = run(['delete', 'acme/deploy-aws', '--json'], { XDG_CONFIG_HOME: tmp_xdg })
 			assert.strictEqual(code, 1)
-			const out = parse_json_output(stdout, 'delete --json no -y')
-			assert.ok('error' in out)
-			assert.ok(out.error.message.toLowerCase().includes('confirmation'))
+			const env = parse_json_output(stdout, 'delete --json no -y')
+			assert_error_envelope(env, 'CONFIRMATION_REQUIRED')
+			assert.strictEqual(env.next_step.kind, 'confirmation')
+			assert.strictEqual(env.next_step.action, 'confirm_destructive')
+			assert.ok(env.next_step.context.commands.some(c => /\-y/.test(c)))
+			assert.strictEqual(env.next_step.principal_authorization_required, true)
 		} finally {
 			fs.rmSync(tmp_xdg, { recursive: true, force: true })
 		}
 	})
 
-	it('delete acme/deploy-aws --json -y exits with code 4 (network error)', () => {
+	it('delete acme/deploy-aws --json -y emits NETWORK_ERROR envelope when registry is unreachable', () => {
 		const tmp_xdg = make_tmp()
 		try {
 			const creds_dir = path.join(tmp_xdg, 'happyskills')
@@ -714,10 +736,9 @@ describe('CLI — delete command', () => {
 			}, null, '\t'))
 			const { stdout, code } = run(['delete', 'acme/deploy-aws', '--json', '-y'], { XDG_CONFIG_HOME: tmp_xdg })
 			assert.strictEqual(code, 4)
-			const out = parse_json_output(stdout, 'delete --json -y network failure')
-			assert.ok('error' in out)
-			assert.strictEqual(out.error.code, 'NETWORK_ERROR')
-			assert.strictEqual(out.error.exit_code, 4)
+			const env = parse_json_output(stdout, 'delete --json -y network failure')
+			assert_error_envelope(env, 'NETWORK_ERROR')
+			assert.strictEqual(env.meta.exit_code, 4)
 		} finally {
 			fs.rmSync(tmp_xdg, { recursive: true, force: true })
 		}
@@ -916,35 +937,35 @@ describe('enable / disable commands', () => {
 		}
 	})
 
-	it('disable --json returns structured results', () => {
+	it('disable --json returns a success envelope with data.results', () => {
 		const { root, cleanup: clean } = scaffold_project([
 			{ full: 'acme/deploy-aws', short: 'deploy-aws' }
 		])
 		try {
 			const { code, stdout } = run(['disable', 'acme/deploy-aws', '--agents', 'claude', '--json'], {}, { cwd: root })
 			assert.strictEqual(code, 0)
-			const out = parse_json_output(stdout, 'disable --json')
-			assert.ok(out.data)
-			assert.ok(Array.isArray(out.data.results))
-			assert.strictEqual(out.data.results[0].skill, 'acme/deploy-aws')
-			assert.strictEqual(out.data.results[0].status, 'disabled')
+			const env = parse_json_output(stdout, 'disable --json')
+			assert_success_envelope(env)
+			assert.ok(Array.isArray(env.data.results))
+			assert.strictEqual(env.data.results[0].skill, 'acme/deploy-aws')
+			assert.strictEqual(env.data.results[0].status, 'disabled')
 		} finally {
 			clean()
 		}
 	})
 
-	it('enable --json returns structured results', () => {
+	it('enable --json returns a success envelope with data.results', () => {
 		const { root, cleanup: clean } = scaffold_project([
 			{ full: 'acme/deploy-aws', short: 'deploy-aws', enabled: false }
 		])
 		try {
 			const { code, stdout } = run(['enable', 'acme/deploy-aws', '--agents', 'claude', '--json'], {}, { cwd: root })
 			assert.strictEqual(code, 0)
-			const out = parse_json_output(stdout, 'enable --json')
-			assert.ok(out.data)
-			assert.ok(Array.isArray(out.data.results))
-			assert.strictEqual(out.data.results[0].skill, 'acme/deploy-aws')
-			assert.strictEqual(out.data.results[0].status, 'enabled')
+			const env = parse_json_output(stdout, 'enable --json')
+			assert_success_envelope(env)
+			assert.ok(Array.isArray(env.data.results))
+			assert.strictEqual(env.data.results[0].skill, 'acme/deploy-aws')
+			assert.strictEqual(env.data.results[0].status, 'enabled')
 		} finally {
 			clean()
 		}
@@ -960,9 +981,10 @@ describe('list — enabled column', () => {
 		try {
 			const { code, stdout } = run(['list', '--json', '--agents', 'claude'], {}, { cwd: root })
 			assert.strictEqual(code, 0)
-			const out = parse_json_output(stdout, 'list --json')
-			assert.strictEqual(out.data.skills['acme/deploy-aws'].enabled, true)
-			assert.strictEqual(out.data.skills['acme/monitoring'].enabled, false)
+			const env = parse_json_output(stdout, 'list --json')
+			assert_success_envelope(env)
+			assert.strictEqual(env.data.skills['acme/deploy-aws'].enabled, true)
+			assert.strictEqual(env.data.skills['acme/monitoring'].enabled, false)
 		} finally {
 			clean()
 		}
@@ -1014,11 +1036,11 @@ describe('CLI — versions command', () => {
 		assert.ok(stderr.toLowerCase().includes('limit'))
 	})
 
-	it('versions acme/deploy-aws --json fails with NETWORK_ERROR (no server)', () => {
+	it('versions acme/deploy-aws --json fails with NETWORK_ERROR envelope (no server)', () => {
 		const { stdout, code } = run(['versions', 'acme/deploy-aws', '--json'])
 		assert.strictEqual(code, 4)
-		const out = parse_json_output(stdout, 'versions --json network failure')
-		assert.strictEqual(out.error.code, 'NETWORK_ERROR')
+		const env = parse_json_output(stdout, 'versions --json network failure')
+		assert_error_envelope(env, 'NETWORK_ERROR')
 	})
 })
 
@@ -1042,10 +1064,10 @@ describe('CLI — changelog command', () => {
 		assert.ok(stderr.includes('owner/name format'))
 	})
 
-	it('changelog acme/deploy-aws --json fails with NETWORK_ERROR (no server)', () => {
+	it('changelog acme/deploy-aws --json fails with NETWORK_ERROR envelope (no server)', () => {
 		const { stdout, code } = run(['changelog', 'acme/deploy-aws', '--json'])
 		assert.strictEqual(code, 4)
-		const out = parse_json_output(stdout, 'changelog --json network failure')
-		assert.strictEqual(out.error.code, 'NETWORK_ERROR')
+		const env = parse_json_output(stdout, 'changelog --json network failure')
+		assert_error_envelope(env, 'NETWORK_ERROR')
 	})
 })

package/src/integration/drift.test.js

@@ -29,6 +29,10 @@ const { spawnSync } = require('child_process')
 const fs = require('fs')
 const os = require('os')
 const path = require('path')
+const {
+	parse_envelope,
+	assert_success_envelope,
+} = require('../schema/envelope_test_helpers')
 
 const CLI = path.resolve(__dirname, '../../bin/happyskills.js')
 const NODE = process.execPath
@@ -36,11 +40,14 @@ const NODE = process.execPath
 const make_tmp = () => fs.mkdtempSync(path.join(os.tmpdir(), 'happyskills-drift-test-'))
 
 const run = (args, opts) => {
-	const result = spawnSync(NODE, [CLI, ...args], {
+	const has_mode_flag = args.includes('--json') || args.includes('--text')
+	const final_args = has_mode_flag ? args : [...args, '--text']
+	const result = spawnSync(NODE, [CLI, ...final_args], {
 		env: {
 			...process.env,
-			NO_COLOR: '1',
+			NO_COLOR: '1', HAPPYSKILLS_ENVELOPE_STRICT: '1',
 			HAPPYSKILLS_API_URL: 'http://localhost:0',
+			CI: '',
 			...(opts?.env || {})
 		},
 		encoding: 'utf-8',
@@ -50,9 +57,14 @@ const run = (args, opts) => {
 	return { stdout: result.stdout || '', stderr: result.stderr || '', code: result.status }
 }
 
+// Validates envelope shape + parses. Each --json output below is also a
+// conformance test for the spec 260525 envelope.
 const parse_json = (stdout, label) => {
-	try { return JSON.parse(stdout) }
-	catch { assert.fail(`${label}: stdout is not valid JSON:\n${stdout}`) }
+	const env = parse_envelope(stdout, label)
+	// Status/check/list emit success envelopes regardless of drift — drift
+	// is data, not error. Locking that down here.
+	assert_success_envelope(env, label)
+	return env
 }
 
 /**