happyskills 0.53.0 → 1.0.0

package/src/utils/errors.js

@@ -1,44 +1,85 @@
-const { EXIT_CODES } = require('../constants')
+'use strict'
+// Error classes + central exit_with_error marshaller. Spec
+// 260525-cli-default-json § 4 + § 5. Every error class carries a closed
+// error.code that emit_envelope writes into the `error` slot. Domain
+// errors not modelled by a dedicated class can be raised as CliError(msg,
+// { code, exit_code, details, context, next_step }).
+//
+// exit_with_error builds the envelope, emits to stdout (json mode) or
+// stderr (text mode), and exits with the mapped exit code.
+
+const { ERROR_CODES, ERROR_CODE_SET } = require('../constants/error_codes')
+const { exit_code_for_error } = require('../constants/exit_codes')
+const { next_step_for_error } = require('../constants/next_step_by_error_code')
 
 class CliError extends Error {
-	constructor(message, code = EXIT_CODES.ERROR) {
+	// Accepts the legacy positional shape `new CliError(msg, exit_code)` and
+	// the new options shape `new CliError(msg, { code, exit_code, details,
+	// context, next_step })`. The legacy form maps to code 'INTERNAL_ERROR'.
+	constructor(message, opts_or_exit_code) {
 		super(message)
 		this.name = 'CliError'
-		this.exit_code = code
+		if (typeof opts_or_exit_code === 'object' && opts_or_exit_code !== null) {
+			const { code, exit_code, details, context, next_step } = opts_or_exit_code
+			this.code      = code || ERROR_CODES.INTERNAL_ERROR
+			this.exit_code = exit_code != null ? exit_code : exit_code_for_error(this.code)
+			if (details)   this.details = details
+			if (context)   this.context = context
+			if (next_step) this.next_step = next_step
+		} else {
+			this.code      = ERROR_CODES.INTERNAL_ERROR
+			this.exit_code = typeof opts_or_exit_code === 'number' ? opts_or_exit_code : 1
+		}
 	}
 }
 
 class UsageError extends CliError {
-	constructor(message) {
-		super(message, EXIT_CODES.USAGE)
+	constructor(message, opts = {}) {
+		super(message, { code: ERROR_CODES.USAGE_ERROR, exit_code: 2, ...opts })
 		this.name = 'UsageError'
 	}
 }
 
 class AuthError extends CliError {
-	constructor(message = 'Authentication required. Run `happyskills login` first.') {
-		super(message, EXIT_CODES.AUTH_REQUIRED)
+	constructor(message = 'Authentication required. Run `happyskills login` first.', opts = {}) {
+		super(message, { code: ERROR_CODES.AUTH_REQUIRED, exit_code: 3, ...opts })
 		this.name = 'AuthError'
 	}
 }
 
 class NetworkError extends CliError {
-	constructor(message = 'Network error. Check your connection and try again.') {
-		super(message, EXIT_CODES.NETWORK)
+	constructor(message = 'Network error. Check your connection and try again.', opts = {}) {
+		super(message, { code: ERROR_CODES.NETWORK_ERROR, exit_code: 4, ...opts })
 		this.name = 'NetworkError'
 	}
 }
 
 class ApiError extends CliError {
-	constructor(message, status_code, error_code) {
-		super(message)
+	constructor(message, status_code, error_code, opts = {}) {
+		const code = (() => {
+			if (error_code && ERROR_CODE_SET.has(error_code)) return error_code
+			if (status_code === 401) return ERROR_CODES.AUTH_REQUIRED
+			if (status_code === 404) return ERROR_CODES.NOT_FOUND
+			if (status_code === 429) return ERROR_CODES.RATE_LIMITED
+			if (error_code) return ERROR_CODES.UNKNOWN_CODE
+			return ERROR_CODES.INTERNAL_ERROR
+		})()
+		// Status-code-driven override: 401 always exits 3 regardless of code.
+		const exit_code = opts.exit_code != null
+			? opts.exit_code
+			: (status_code === 401 ? 3 : exit_code_for_error(code))
+		super(message, { code, exit_code, ...opts })
 		this.name = 'ApiError'
 		this.status_code = status_code
-		this.error_code = error_code
-		if (status_code === 401) this.exit_code = EXIT_CODES.AUTH_REQUIRED
+		this.error_code  = error_code
+		if (error_code && !ERROR_CODE_SET.has(error_code)) {
+			this.details = { ...(this.details || {}), original_code: error_code }
+		}
 	}
 }
 
+// ── Helpers ────────────────────────────────────────────────────────────────
+
 const print_log_hint = (log_path) => {
 	if (log_path) console.error(`  Log: ${log_path}`)
 }
@@ -51,13 +92,8 @@ const is_usage_error = (err) => {
 
 const extract_root_cause = (err) => {
 	if (!Array.isArray(err)) return err?.message || 'An unexpected error occurred'
-	// Walk the error array to find the deepest, most specific message.
-	// catch_errors wraps errors outermost-first: [outermost, ..., root_cause].
-	// We prefer the last error (root cause) for the user-facing message,
-	// but fall back to the first CliError if one exists.
 	const messages = err.map(x => x?.message).filter(Boolean)
 	if (messages.length === 0) return 'An unexpected error occurred'
-	// The last message is typically the root cause (deepest in the chain)
 	return messages[messages.length - 1]
 }
 
@@ -66,54 +102,87 @@ const format_error_chain = (err) => {
 	return err.map(x => x?.stack || x?.message || String(x)).filter(Boolean)
 }
 
-const get_error_info = (err) => {
-	let target = err
-	if (Array.isArray(err)) {
-		target = err.find(e => e instanceof CliError) || err[err.length - 1] || err[0]
+const get_error_target = (err) => {
+	if (!Array.isArray(err)) return err
+	// Prefer the deepest CliError; that is where the structured code lives.
+	for (let i = err.length - 1; i >= 0; i--) {
+		if (err[i] instanceof CliError) return err[i]
 	}
+	return err[err.length - 1] || err[0]
+}
 
-	let code = 'ERROR'
-	let exit_code = EXIT_CODES.ERROR
+const get_error_info = (err) => {
+	const target = get_error_target(err)
 	const message = extract_root_cause(err)
-
-	if (target instanceof UsageError) {
-		code = 'USAGE_ERROR'; exit_code = EXIT_CODES.USAGE
-	} else if (target instanceof AuthError) {
-		code = 'AUTH_REQUIRED'; exit_code = EXIT_CODES.AUTH_REQUIRED
-	} else if (target instanceof NetworkError) {
-		code = 'NETWORK_ERROR'; exit_code = EXIT_CODES.NETWORK
-	} else if (target instanceof ApiError) {
-		code = target.error_code || 'API_ERROR'
-		exit_code = target.exit_code || EXIT_CODES.ERROR
-	} else if (target instanceof CliError) {
-		code = 'ERROR'; exit_code = target.exit_code
+	let code      = ERROR_CODES.INTERNAL_ERROR
+	let exit_code = 1
+	let details   = null
+	let context   = null
+	let next_step = null
+
+	if (target instanceof CliError) {
+		code      = target.code      || code
+		exit_code = target.exit_code != null ? target.exit_code : exit_code_for_error(code)
+		if (target.details)   details   = target.details
+		if (target.context)   context   = target.context
+		if (target.next_step) next_step = target.next_step
+	} else {
+		exit_code = exit_code_for_error(code)
 	}
 
-	return { code, message, exit_code }
+	return { code, message, exit_code, details, context, next_step }
 }
 
+// ── Central marshaller ────────────────────────────────────────────────────
+
 const exit_with_error = (err) => {
 	const { is_json_mode } = require('../state')
+	const { code, message, exit_code, details, context, next_step: explicit_next_step } = get_error_info(err)
 
 	if (is_json_mode()) {
-		const { code, message, exit_code } = get_error_info(err)
-		const chain = format_error_chain(err)
-		const json_err = { code, message, exit_code }
-		if (chain.length > 1) json_err.details = chain
-		console.log(JSON.stringify({ error: json_err }, null, 2))
-		process.exit(exit_code)
+		// Build envelope. Default next_step from the mapping table, unless
+		// the throwing site provided one explicitly.
+		const { emit_and_exit } = require('../ui/envelope')
+		const error_payload = { code, message }
+		if (details) error_payload.details = details
+		// Domain-specific extras land alongside code/message (spec § 4.4).
+		if (context) {
+			for (const k of Object.keys(context)) {
+				if (k === 'commands' || k === 'options' || k === 'suggestion' || k === 'got'
+					|| k === 'available' || k === 'requested' || k === 'modified_files'
+					|| k === 'candidates' || k === 'dependencies' || k === 'would_remove'
+					|| k === 'min_cli_version' || k === 'current_cli_version'
+					|| k === 'retry_after_seconds' || k === 'target_version' || k === 'current_top_entry'
+					|| k === 'disk_version' || k === 'requested_bump' || k === 'lock_version'
+					|| k === 'bump' || k === 'current_version' || k === 'skill') {
+					// These belong on next_step.context, not on error.
+					continue
+				}
+				if (!(k in error_payload)) error_payload[k] = context[k]
+			}
+		}
+		const next_step = explicit_next_step || next_step_for_error(code, message, context || {}) || {}
+		emit_and_exit({
+			data: {},
+			error: error_payload,
+			next_step,
+			meta_overrides: { exit_code },
+		})
 		return
 	}
 
 	const { print_error } = require('../ui/output')
 	const { write_error_log } = require('./logger')
-
 	const log_path = is_usage_error(err) ? null : write_error_log(err)
-	const { message, exit_code } = get_error_info(err)
-
 	print_error(message)
 	print_log_hint(log_path)
 	process.exit(exit_code)
 }
 
-module.exports = { CliError, UsageError, AuthError, NetworkError, ApiError, exit_with_error }
+module.exports = {
+	CliError, UsageError, AuthError, NetworkError, ApiError,
+	exit_with_error,
+	get_error_info,
+	extract_root_cause,
+	format_error_chain,
+}

package/src/utils/intent.js

@@ -39,4 +39,25 @@ const clear_envelope = () => {
 	delete process.env[ENV_VAR]
 }
 
-module.exports = { init_from_env, init_from_flag, get_envelope, set_envelope, clear_envelope, ENV_VAR }
+// Spec 260521-03 addendum § 4 — Extract the intent_id UUID from the active
+// envelope so the CLI can attach it to /telemetry/discovery beacon payloads.
+// The envelope is `<base64url-payload>.<base64url-hmac>`; the CLI doesn't
+// have the HMAC secret and doesn't need to verify — it just reads the
+// payload portion. Returns null when no envelope is active or the payload
+// can't be decoded.
+const get_intent_id = () => {
+	const env = get_envelope()
+	if (!env) return null
+	try {
+		const dot = env.indexOf('.')
+		if (dot <= 0) return null
+		const body = env.slice(0, dot)
+		const json = Buffer.from(body, 'base64url').toString('utf-8')
+		const payload = JSON.parse(json)
+		return payload.intent_id || null
+	} catch {
+		return null
+	}
+}
+
+module.exports = { init_from_env, init_from_flag, get_envelope, set_envelope, clear_envelope, get_intent_id, ENV_VAR }