happyskills 0.53.0 → 1.0.0

package/src/schema/envelope_validator.test.js

@@ -0,0 +1,333 @@
+'use strict'
+// Tests for the hand-rolled envelope validator. These should PASS on the
+// branch even before Session 2 — the validator is pure logic over a closed
+// schema, so the contract is testable in isolation. Failures here mean the
+// validator itself is wrong, not that the CLI implementation lags.
+
+const { describe, it } = require('node:test')
+const assert = require('node:assert/strict')
+const {
+	validate_envelope,
+	ENVELOPE_SCHEMA_VERSION,
+} = require('./envelope_validator')
+
+const success_envelope = (overrides = {}) => ({
+	ok:        true,
+	data:      {},
+	error:     {},
+	next_step: {},
+	warnings:  [],
+	meta: {
+		command:                 'whoami',
+		exit_code:               0,
+		envelope_schema_version: ENVELOPE_SCHEMA_VERSION,
+	},
+	...overrides,
+})
+
+const error_envelope = (overrides = {}) => ({
+	ok:    false,
+	data:  {},
+	error: { code: 'USAGE_ERROR', message: 'bad args' },
+	next_step: {},
+	warnings:  [],
+	meta: {
+		command:                 'install',
+		exit_code:               2,
+		envelope_schema_version: ENVELOPE_SCHEMA_VERSION,
+	},
+	...overrides,
+})
+
+describe('validate_envelope — happy paths', () => {
+	it('accepts a minimal success envelope', () => {
+		const r = validate_envelope(success_envelope())
+		assert.strictEqual(r.ok, true, JSON.stringify(r.errors))
+	})
+
+	it('accepts a minimal error envelope', () => {
+		const r = validate_envelope(error_envelope())
+		assert.strictEqual(r.ok, true, JSON.stringify(r.errors))
+	})
+
+	it('accepts a success-with-followup envelope', () => {
+		const env = success_envelope({
+			data: { skill: 'acme/regressed', drift_state: 'regression' },
+			next_step: {
+				kind:         'decision',
+				action:       'resolve_regression',
+				instructions: 'Pick a resolution.',
+				context:      { options: ['restore_from_lock_version', 'abandon'] },
+				principal_authorization_required: true,
+				route_to_skill: 'happyskills-sync',
+			},
+			meta: {
+				command:                 'reconcile',
+				exit_code:               0,
+				envelope_schema_version: ENVELOPE_SCHEMA_VERSION,
+				cli_version:             '1.0.0',
+			},
+		})
+		const r = validate_envelope(env)
+		assert.strictEqual(r.ok, true, JSON.stringify(r.errors))
+	})
+
+	it('accepts a failure-with-recovery envelope', () => {
+		const env = error_envelope({
+			error: { code: 'DRIFT_DETECTED', message: 'Regression drift.' },
+			next_step: {
+				kind:         'recovery',
+				action:       'reconcile_first',
+				instructions: 'Reconcile before retrying.',
+				context:      { commands: ['npx happyskills reconcile foo --json'] },
+			},
+			meta: {
+				command:                 'release',
+				exit_code:               1,
+				envelope_schema_version: ENVELOPE_SCHEMA_VERSION,
+			},
+		})
+		const r = validate_envelope(env)
+		assert.strictEqual(r.ok, true, JSON.stringify(r.errors))
+	})
+
+	it('accepts non-empty warnings', () => {
+		const env = success_envelope({
+			warnings: [
+				{ code: 'integrity_skipped', message: 'Skipped integrity check.' },
+			],
+		})
+		const r = validate_envelope(env)
+		assert.strictEqual(r.ok, true, JSON.stringify(r.errors))
+	})
+})
+
+describe('validate_envelope — top-level shape', () => {
+	it('rejects when not an object', () => {
+		assert.strictEqual(validate_envelope(null).ok, false)
+		assert.strictEqual(validate_envelope([]).ok, false)
+		assert.strictEqual(validate_envelope('hi').ok, false)
+	})
+
+	it('rejects when a required key is missing', () => {
+		for (const k of ['ok', 'data', 'error', 'next_step', 'warnings', 'meta']) {
+			const env = success_envelope()
+			delete env[k]
+			const r = validate_envelope(env)
+			assert.strictEqual(r.ok, false, `expected failure when ${k} is missing`)
+			assert.ok(r.errors.some(e => e.path === k), `expected an error mentioning ${k}`)
+		}
+	})
+
+	it('rejects unexpected top-level keys', () => {
+		const env = success_envelope()
+		env.extra = 1
+		const r = validate_envelope(env)
+		assert.strictEqual(r.ok, false)
+		assert.ok(r.errors.some(e => e.path === 'extra'))
+	})
+
+	it('rejects data: null', () => {
+		const env = success_envelope({ data: null })
+		const r = validate_envelope(env)
+		assert.strictEqual(r.ok, false)
+		assert.ok(r.errors.some(e => e.path === 'data'))
+	})
+
+	it('rejects data as a bare array', () => {
+		const env = success_envelope({ data: [{ x: 1 }] })
+		const r = validate_envelope(env)
+		assert.strictEqual(r.ok, false)
+		assert.ok(r.errors.some(e => e.path === 'data'))
+	})
+
+	it('rejects warnings as a non-array', () => {
+		const env = success_envelope({ warnings: 'oops' })
+		const r = validate_envelope(env)
+		assert.strictEqual(r.ok, false)
+		assert.ok(r.errors.some(e => e.path === 'warnings'))
+	})
+})
+
+describe('validate_envelope — error slot', () => {
+	it('rejects error.code not in the closed enum', () => {
+		const env = error_envelope({
+			error: { code: 'NOT_A_REAL_CODE', message: 'invented' },
+		})
+		const r = validate_envelope(env)
+		assert.strictEqual(r.ok, false)
+		assert.ok(r.errors.some(e => e.path === 'error.code'))
+	})
+
+	it('rejects error with only code (missing message)', () => {
+		const env = error_envelope({
+			error: { code: 'USAGE_ERROR' },
+		})
+		const r = validate_envelope(env)
+		assert.strictEqual(r.ok, false)
+		assert.ok(r.errors.some(e => e.path === 'error'))
+	})
+
+	it('rejects error with only message (missing code)', () => {
+		const env = error_envelope({
+			error: { message: 'orphan message' },
+		})
+		const r = validate_envelope(env)
+		assert.strictEqual(r.ok, false)
+	})
+
+	it('accepts error.details when present and an object', () => {
+		const env = error_envelope({
+			error: {
+				code: 'RATE_LIMITED',
+				message: 'Rate limited.',
+				details: { retry_after_seconds: 30 },
+			},
+		})
+		const r = validate_envelope(env)
+		assert.strictEqual(r.ok, true, JSON.stringify(r.errors))
+	})
+
+	it('rejects error.details when not an object', () => {
+		const env = error_envelope({
+			error: { code: 'USAGE_ERROR', message: 'bad', details: 'not an object' },
+		})
+		const r = validate_envelope(env)
+		assert.strictEqual(r.ok, false)
+		assert.ok(r.errors.some(e => e.path === 'error.details'))
+	})
+
+	it('accepts the UNKNOWN_CODE forward-compat escape hatch', () => {
+		const env = error_envelope({
+			error: {
+				code: 'UNKNOWN_CODE',
+				message: 'Unknown to this CLI version.',
+				details: { original_code: 'NEW_API_CODE_2027' },
+			},
+		})
+		const r = validate_envelope(env)
+		assert.strictEqual(r.ok, true, JSON.stringify(r.errors))
+	})
+})
+
+describe('validate_envelope — next_step slot', () => {
+	it('rejects next_step.kind not in the closed enum', () => {
+		const env = success_envelope({
+			next_step: { kind: 'feedback_created', action: 'login', instructions: 'go' },
+		})
+		const r = validate_envelope(env)
+		assert.strictEqual(r.ok, false)
+		assert.ok(r.errors.some(e => e.path === 'next_step.kind'))
+	})
+
+	it('rejects next_step.action not in the closed enum', () => {
+		const env = success_envelope({
+			next_step: { kind: 'recovery', action: 'do_a_thing', instructions: 'go' },
+		})
+		const r = validate_envelope(env)
+		assert.strictEqual(r.ok, false)
+		assert.ok(r.errors.some(e => e.path === 'next_step.action'))
+	})
+
+	it('rejects next_step missing instructions when kind+action are present', () => {
+		const env = success_envelope({
+			next_step: { kind: 'recovery', action: 'login' },
+		})
+		const r = validate_envelope(env)
+		assert.strictEqual(r.ok, false)
+	})
+
+	it('rejects mismatched kind/action pair', () => {
+		// `login` is kind=recovery; `decision` is wrong.
+		const env = success_envelope({
+			next_step: { kind: 'decision', action: 'login', instructions: 'go' },
+		})
+		const r = validate_envelope(env)
+		assert.strictEqual(r.ok, false)
+	})
+
+	it('accepts the empty next_step {}', () => {
+		const r = validate_envelope(success_envelope({ next_step: {} }))
+		assert.strictEqual(r.ok, true)
+	})
+
+	it('rejects stray sibling keys on an empty next_step', () => {
+		const env = success_envelope({ next_step: { not_a_real_key: 1 } })
+		const r = validate_envelope(env)
+		assert.strictEqual(r.ok, false)
+	})
+})
+
+describe('validate_envelope — meta slot', () => {
+	it('rejects when meta.command is missing', () => {
+		const env = success_envelope()
+		delete env.meta.command
+		const r = validate_envelope(env)
+		assert.strictEqual(r.ok, false)
+		assert.ok(r.errors.some(e => e.path === 'meta.command'))
+	})
+
+	it('rejects when meta.envelope_schema_version is missing', () => {
+		const env = success_envelope()
+		delete env.meta.envelope_schema_version
+		const r = validate_envelope(env)
+		assert.strictEqual(r.ok, false)
+	})
+
+	it('rejects negative meta.exit_code', () => {
+		const env = success_envelope()
+		env.meta.exit_code = -1
+		const r = validate_envelope(env)
+		assert.strictEqual(r.ok, false)
+	})
+})
+
+describe('validate_envelope — derived invariants', () => {
+	it('rejects ok=true paired with a populated error', () => {
+		const env = success_envelope({
+			error: { code: 'USAGE_ERROR', message: 'oops' },
+		})
+		const r = validate_envelope(env)
+		assert.strictEqual(r.ok, false)
+		assert.ok(r.errors.some(e => e.path === 'ok'))
+	})
+
+	it('rejects ok=false paired with an empty error', () => {
+		const env = error_envelope({
+			ok: false,
+			error: {},
+		})
+		const r = validate_envelope(env)
+		assert.strictEqual(r.ok, false)
+	})
+
+	it('rejects ok=true with non-zero exit_code', () => {
+		const env = success_envelope()
+		env.meta.exit_code = 1
+		const r = validate_envelope(env)
+		assert.strictEqual(r.ok, false)
+	})
+
+	it('rejects ok=false with exit_code=0', () => {
+		const env = error_envelope()
+		env.meta.exit_code = 0
+		const r = validate_envelope(env)
+		assert.strictEqual(r.ok, false)
+	})
+})
+
+describe('validate_envelope — warnings slot', () => {
+	it('rejects warning entries missing code or message', () => {
+		const env = success_envelope({ warnings: [{ message: 'no code' }] })
+		const r = validate_envelope(env)
+		assert.strictEqual(r.ok, false)
+	})
+
+	it('warning codes are free-form (not the closed enum)', () => {
+		const env = success_envelope({
+			warnings: [{ code: 'whatever_we_want_here', message: 'free-form code' }],
+		})
+		const r = validate_envelope(env)
+		assert.strictEqual(r.ok, true, JSON.stringify(r.errors))
+	})
+})

package/src/ui/envelope.js

@@ -0,0 +1,171 @@
+'use strict'
+// The single chokepoint for CLI JSON output. Spec 260525-cli-default-json
+// § 4 + § 8. Every command's --json path goes through emit_envelope; the
+// helper builds the canonical six-key envelope, derives `ok`, mirrors the
+// exit code into `meta`, validates against the closed schema (dev
+// assertion only — never throws in prod), serialises with 2-space indent,
+// writes to stdout, and (when called via emit_and_exit) calls process.exit.
+
+const { is_json_mode } = require('../state')
+const { CLI_VERSION } = require('../constants')
+const { ENVELOPE_SCHEMA_VERSION, TOP_LEVEL_KEYS } = require('../schema/envelope_validator')
+const { exit_code_for_error } = require('../constants/exit_codes')
+const { validate_envelope } = require('../schema/envelope_validator')
+
+// Module-level command context. Set once by index.js immediately after
+// alias resolution, read by every emit_envelope call. Avoids threading the
+// command name through every call site.
+let command_name = '<unknown>'
+let workspace   = null
+let request_id  = null
+const set_command   = (name) => { command_name = name || '<unknown>' }
+const set_workspace = (slug) => { workspace = slug || null }
+const set_request_id = (id) => { request_id = id || null }
+const get_command   = () => command_name
+
+const is_plain_object = (x) => x !== null && typeof x === 'object' && !Array.isArray(x)
+
+// Generic instructions per action — used to auto-fill the dependentRequired
+// cluster when a command emits a partial next_step ({ action, context }
+// without kind/instructions). Keeps per-command code terse and lets the
+// envelope helper enforce the closed-schema contract centrally.
+const DEFAULT_INSTRUCTIONS = {
+	login:              'Sign in to HappySkills, then retry.',
+	retry:              'Transient failure. Retry shortly.',
+	reconcile_first:    'Drift must be resolved before this operation. Run reconcile, follow its next_step, then retry.',
+	pull_rebase_first:  'The local skill has diverged from the registry. Pull with --rebase, resolve any rejected patches, then retry.',
+	fix_validation_errors: 'Fix the listed validation errors and re-run.',
+	provide_changelog:  'CHANGELOG.md is missing the target version entry. Add it and re-run.',
+	self_update:        'Upgrade the happyskills CLI and re-run.',
+	show_format:        'Format the input correctly and re-run.',
+	retry_rank:         'Re-emit the ranking matching the response schema and re-pipe.',
+	clarify_query:      'Ask the principal a clarifying question, then re-run search.',
+	resolve_regression: 'Pick a resolution and re-run with --apply <option>.',
+	resolve_missing_skill_json: 'Pick a resolution and re-run with --apply <option>.',
+	resolve_missing_dir:        'Pick a resolution and re-run with --apply <option>.',
+	resolve_conflicts:          'Pick a conflict-resolution strategy and re-run.',
+	resolve_patch_rejections:   'Resolve the rejected patches and continue, or abandon and restore.',
+	specify_workspace:          'Pick a workspace and re-run.',
+	specify_bump_type:          'Pick a bump type and re-run.',
+	resolve_bump_disagreement:  'Reconcile the --bump value with the disk version and re-run.',
+	pick_version:               'Pick an available version and re-run.',
+	confirm_discard_or_snapshot_first: 'Snapshot the local edits, or re-run with --force-discard-local to discard them.',
+	confirm_cascade:    'Confirm the cascading operation by re-running with --confirm.',
+	confirm_destructive:'Confirm the destructive operation by re-running with -y.',
+	pass_yes_flag:      'Re-run with -y to bypass the interactive prompt.',
+	rank_digests_inline:'Rank the candidates per the system prompt and pipe to postlex.',
+	present_to_user:    'Render the data to the principal — no further protocol action required.',
+	attach_screenshot:  'Optionally attach a screenshot via the feedback attach flow.',
+	install_first:      'Install the skill first, then retry.',
+}
+
+// Look up the canonical kind for a given action — used by enrich_next_step.
+const kind_for_action = (action) => {
+	const { ACTION_KIND } = require('../constants/next_step_actions')
+	return ACTION_KIND[action] || null
+}
+
+const enrich_next_step = (ns) => {
+	if (!is_plain_object(ns) || Object.keys(ns).length === 0) return ns || {}
+	if (!ns.action) return ns
+	const out = { ...ns }
+	if (!out.kind) out.kind = kind_for_action(out.action) || 'decision'
+	if (!out.instructions) out.instructions = DEFAULT_INSTRUCTIONS[out.action] || 'Follow the protocol step indicated by `action`.'
+	return out
+}
+
+// Sentinel for unrecoverable schema violations during development. In
+// production we still emit (lossy is better than crash); tests can opt in
+// via HAPPYSKILLS_ENVELOPE_STRICT=1.
+const STRICT = process.env.HAPPYSKILLS_ENVELOPE_STRICT === '1'
+
+const build_envelope = ({
+	data        = {},
+	error       = null,
+	next_step   = null,
+	warnings    = [],
+	meta_overrides = {},
+} = {}) => {
+	// `data` must always be an object on the wire (spec § 4.3). When a
+	// caller passes a bare array, wrap as `{ results: [...] }` to match the
+	// API helper's `normalise_data` and the spec's canonical array key.
+	// Other non-object scalars (string/number/boolean) fall back to `value`.
+	const safe_data = is_plain_object(data)
+		? data
+		: (data == null
+			? {}
+			: (Array.isArray(data) ? { results: data } : { value: data }))
+	const safe_error = is_plain_object(error) && Object.keys(error).length > 0 ? error : {}
+	const raw_next_step = is_plain_object(next_step) && Object.keys(next_step).length > 0 ? next_step : {}
+	const safe_next_step = enrich_next_step(raw_next_step)
+	const safe_warnings = Array.isArray(warnings) ? warnings : []
+
+	const ok = !('code' in safe_error)
+	const exit_code = ok
+		? 0
+		: (meta_overrides.exit_code != null ? meta_overrides.exit_code : exit_code_for_error(safe_error.code))
+
+	const meta = {
+		command:                 meta_overrides.command || command_name,
+		cli_version:             CLI_VERSION,
+		exit_code,
+		envelope_schema_version: ENVELOPE_SCHEMA_VERSION,
+		...(workspace ? { workspace } : {}),
+		...(request_id ? { request_id } : {}),
+		...(meta_overrides.workspace ? { workspace: meta_overrides.workspace } : {}),
+		...(meta_overrides.api_version ? { api_version: meta_overrides.api_version } : {}),
+		...(meta_overrides.min_cli_version ? { min_cli_version: meta_overrides.min_cli_version } : {}),
+	}
+
+	const envelope = {
+		ok,
+		data:      safe_data,
+		error:     safe_error,
+		next_step: safe_next_step,
+		warnings:  safe_warnings,
+		meta,
+	}
+
+	if (STRICT) {
+		const { ok: valid, errors } = validate_envelope(envelope)
+		if (!valid) {
+			process.stderr.write(`[envelope] schema violation:\n${errors.map(e => '  - ' + (e.path || '<root>') + ': ' + e.message).join('\n')}\n`)
+		}
+	}
+
+	return envelope
+}
+
+// Print the envelope to stdout. Uses console.log so tests stubbing it
+// observe the output, and so it composes with NO_COLOR / TTY conventions
+// the rest of the UI layer relies on.
+const emit_envelope = (input) => {
+	const env = build_envelope(input)
+	console.log(JSON.stringify(env, null, 2))
+	return env
+}
+
+// Convenience: build the envelope, emit it, then exit with the mirrored
+// exit code. Used by the central exit_with_error path.
+const emit_and_exit = (input) => {
+	const env = emit_envelope(input)
+	process.exit(env.meta.exit_code)
+}
+
+// JSON-mode guard helper for commands that want to short-circuit non-JSON
+// rendering when the user passed --json. Kept here so command modules can
+// import a single helper.
+const json_active = () => is_json_mode()
+
+module.exports = {
+	emit_envelope,
+	emit_and_exit,
+	build_envelope,
+	set_command,
+	set_workspace,
+	set_request_id,
+	get_command,
+	json_active,
+	ENVELOPE_SCHEMA_VERSION,
+	TOP_LEVEL_KEYS,
+}

package/src/ui/output.js

@@ -108,8 +108,72 @@ const summarize_warnings = (warnings, skill_name) => {
 	return `${warnings.length} warning${warnings.length === 1 ? '' : 's'}: ${parts.join(', ')} — run 'happyskills validate ${skill_name}' for details`
 }
 
-const print_json = (data) => {
-	console.log(JSON.stringify(data, null, 2))
+// print_json now routes through the central envelope chokepoint when given
+// an envelope-shaped input ({ data }, { error }, { next_step }, or a full
+// six-key envelope). This retrofits every legacy `print_json({ data: ... })`
+// call site to emit the new schema without changing the call. Raw inputs
+// (e.g. a bare array) fall through to the legacy JSON.stringify path so
+// scripts/validators that print free-form JSON still work.
+//
+// Audit follow-up #6 — dev-mode strict assertion. When
+// HAPPYSKILLS_ENVELOPE_STRICT=1 (or NODE_ENV=test), any top-level key
+// outside the six-key envelope is written to stderr as a warning. This
+// catches the `uninstall.js:79` / `install.js:244` class bug — callers
+// passing a sibling field (`errors:` plural, `attachments:`, etc.) that
+// the retrofit would silently drop. Production stays quiet.
+const ENVELOPE_KEYS = new Set(['ok', 'data', 'error', 'next_step', 'warnings', 'meta'])
+const print_json = (input) => {
+	const is_obj = input !== null && typeof input === 'object' && !Array.isArray(input)
+	if (!is_obj) {
+		console.log(JSON.stringify(input, null, 2))
+		return
+	}
+	const has_envelope_key =
+		'data' in input || 'error' in input || 'next_step' in input ||
+		'warnings' in input || 'meta' in input || 'ok' in input
+	if (!has_envelope_key) {
+		console.log(JSON.stringify(input, null, 2))
+		return
+	}
+	// Strict-mode warning. Dropped keys are not just noise — they are
+	// per-row failures, attachment lists, or other domain payload the
+	// caller meant to surface and the retrofit silently swallows.
+	// Opt in via HAPPYSKILLS_ENVELOPE_STRICT=1; tests turn it on globally
+	// (see cli/src/integration/* spawn helpers).
+	if (process.env.HAPPYSKILLS_ENVELOPE_STRICT === '1') {
+		const dropped = Object.keys(input).filter(k => !ENVELOPE_KEYS.has(k))
+		if (dropped.length > 0) {
+			process.stderr.write(
+				`[print_json] retrofit ignored top-level key(s): ${dropped.join(', ')}. ` +
+				`Fold them into data.* or into the envelope per spec § 4.\n`
+			)
+		}
+	}
+	const { emit_envelope } = require('./envelope')
+	const { error } = input
+	// Legacy error shape carried { error: { code, message, exit_code } }. The
+	// new envelope keeps code+message inside error and moves exit_code to
+	// meta. Strip exit_code here so the schema-validator stays happy.
+	let meta_overrides = {}
+	if (error && typeof error === 'object' && 'exit_code' in error) {
+		meta_overrides = { exit_code: error.exit_code }
+		const cleaned = { ...error }
+		delete cleaned.exit_code
+		emit_envelope({
+			data:      input.data || {},
+			error:     cleaned,
+			next_step: input.next_step,
+			warnings:  input.warnings,
+			meta_overrides,
+		})
+		return
+	}
+	emit_envelope({
+		data:      input.data,
+		error:     input.error,
+		next_step: input.next_step,
+		warnings:  input.warnings,
+	})
 }
 
 const print_label = (label, value) => {