happyskills 0.53.0 → 1.0.0

package/src/constants/next_step_by_error_code.js

@@ -0,0 +1,249 @@
+'use strict'
+// Default next_step factories by error code. Spec 260525-cli-default-json
+// § 5 + § 7. Commands MAY override with a more specific next_step
+// (carrying domain context like `available[]` for pick_version), but for
+// the common case the central marshaller fills this in automatically.
+//
+// Each factory takes the original error message + an optional context blob
+// and returns the populated next_step object (or null when no default
+// applies — agent falls back to "explain to principal").
+
+const {
+	RECOVERY, DECISION, CONFIRMATION,
+	LOGIN, RETRY, RECONCILE_FIRST, PULL_REBASE_FIRST, FIX_VALIDATION_ERRORS,
+	PROVIDE_CHANGELOG, SELF_UPDATE, SHOW_FORMAT,
+	RESOLVE_REGRESSION, RESOLVE_MISSING_SKILL_JSON, RESOLVE_MISSING_DIR,
+	RESOLVE_CONFLICTS, RESOLVE_PATCH_REJECTIONS, SPECIFY_WORKSPACE,
+	SPECIFY_BUMP_TYPE, RESOLVE_BUMP_DISAGREEMENT, PICK_VERSION,
+	CONFIRM_DISCARD_OR_SNAPSHOT_FIRST, CONFIRM_CASCADE, CONFIRM_DESTRUCTIVE,
+	PASS_YES_FLAG,
+} = require('./next_step_actions')
+
+const recovery = (action, instructions, context = {}, opts = {}) => ({
+	kind:         RECOVERY,
+	action,
+	instructions,
+	context,
+	...(opts.principal_authorization_required ? { principal_authorization_required: true } : {}),
+	...(opts.route_to_skill ? { route_to_skill: opts.route_to_skill } : {}),
+})
+
+const decision = (action, instructions, context = {}, opts = {}) => ({
+	kind:         DECISION,
+	action,
+	instructions,
+	context,
+	principal_authorization_required: opts.principal_authorization_required !== false,
+	...(opts.route_to_skill ? { route_to_skill: opts.route_to_skill } : {}),
+})
+
+const confirmation = (action, instructions, context = {}) => ({
+	kind:         CONFIRMATION,
+	action,
+	instructions,
+	context,
+	principal_authorization_required: true,
+})
+
+const NEXT_STEP_BY_ERROR_CODE = Object.freeze({
+	AUTH_REQUIRED: () => recovery(
+		LOGIN,
+		'Sign in to HappySkills, then re-run the command.',
+		{ commands: ['npx happyskills login --browser --json'] }
+	),
+	EXPIRED_TOKEN: () => recovery(
+		LOGIN,
+		'Your session has expired. Sign in again, then re-run the command.',
+		{ commands: ['npx happyskills login --browser --json'] }
+	),
+	NETWORK_ERROR: () => recovery(
+		RETRY,
+		'A network error interrupted the request. Retry shortly.',
+		{ retry_after_seconds: 5, max_attempts: 3 }
+	),
+	RATE_LIMITED: (msg, ctx = {}) => recovery(
+		RETRY,
+		'Rate limit reached. Retry after the suggested interval.',
+		{ retry_after_seconds: ctx.retry_after_seconds || 30, max_attempts: 3 }
+	),
+	DB_UNAVAILABLE: () => recovery(
+		RETRY,
+		'The registry database is temporarily unavailable. Retry shortly.',
+		{ retry_after_seconds: 10, max_attempts: 3 }
+	),
+	REGISTRY_UNAVAILABLE: () => recovery(
+		RETRY,
+		'The registry is temporarily unavailable. Retry shortly.',
+		{ retry_after_seconds: 10, max_attempts: 3 }
+	),
+	GITHUB_UNAVAILABLE: () => recovery(
+		RETRY,
+		'GitHub is temporarily unavailable. Retry shortly.',
+		{ retry_after_seconds: 10, max_attempts: 3 }
+	),
+	EMBEDDING_UNAVAILABLE: () => recovery(
+		RETRY,
+		'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.',
+		{
+			got: ctx.got,
+			...(ctx.suggestion ? { suggestion: ctx.suggestion } : {}),
+			commands: ['npx happyskills --help'],
+		}
+	),
+	INVALID_SLUG: () => recovery(
+		SHOW_FORMAT,
+		'Skill identifiers use the `<owner>/<name>` format. Re-run with the corrected slug.',
+		{ expected: '<owner>/<name>' }
+	),
+	INVALID_VERSION: () => recovery(
+		SHOW_FORMAT,
+		'Version values must be valid semver (e.g. 1.2.3). Re-run with a corrected version.',
+		{ expected: 'semver (MAJOR.MINOR.PATCH)' }
+	),
+	MIN_CLI_VERSION: (_msg, ctx = {}) => recovery(
+		SELF_UPDATE,
+		'This CLI is older than the API requires. Upgrade and re-run.',
+		{
+			...(ctx.min_cli_version ? { min_cli_version: ctx.min_cli_version } : {}),
+			...(ctx.current_cli_version ? { current_cli_version: ctx.current_cli_version } : {}),
+			commands: ['npm install -g happyskills@latest'],
+		},
+		{ principal_authorization_required: true }
+	),
+	DRIFT_DETECTED: (_msg, ctx = {}) => recovery(
+		RECONCILE_FIRST,
+		'Drift must be resolved before this operation. Run reconcile, follow its next_step, then retry.',
+		{
+			commands: [`npx happyskills reconcile ${ctx.skill || '<skill>'} --json`],
+			...(ctx.drift ? { drift: ctx.drift } : {}),
+		},
+		{ route_to_skill: 'happyskills-sync' }
+	),
+	DIVERGED: (_msg, ctx = {}) => recovery(
+		PULL_REBASE_FIRST,
+		'The local skill has diverged from the registry. Pull with --rebase, resolve any rejected patches, then retry.',
+		{ commands: [`npx happyskills pull ${ctx.skill || '<skill>'} --rebase --json`] },
+		{ route_to_skill: 'happyskills-sync' }
+	),
+	VALIDATION_FAILED: (_msg, ctx = {}) => recovery(
+		FIX_VALIDATION_ERRORS,
+		'Validation failed. Fix the listed errors and re-run.',
+		{
+			...(ctx.validation_errors ? { validation_errors: ctx.validation_errors } : {}),
+			...(ctx.skill ? { commands: [`npx happyskills validate ${ctx.skill} --json`] } : {}),
+		}
+	),
+	DEPENDENCY_VALIDATION_FAILED: (_msg, ctx = {}) => recovery(
+		FIX_VALIDATION_ERRORS,
+		'Dependency validation failed. Fix the listed dependency issues and re-run.',
+		{
+			...(ctx.validation_errors ? { validation_errors: ctx.validation_errors } : {}),
+		}
+	),
+	MISSING_CHANGELOG_ENTRY: (_msg, ctx = {}) => recovery(
+		PROVIDE_CHANGELOG,
+		'CHANGELOG.md is missing an entry for the target version. Add the entry and re-run.',
+		{
+			...(ctx.target_version ? { target_version: ctx.target_version } : {}),
+			...(ctx.current_top_entry ? { current_top_entry: ctx.current_top_entry } : {}),
+		},
+		{ principal_authorization_required: true }
+	),
+	CHANGELOG_SOURCE_UNREADABLE: () => recovery(
+		PROVIDE_CHANGELOG,
+		'CHANGELOG.md could not be read. Restore the file and re-run.',
+		{},
+		{ principal_authorization_required: true }
+	),
+
+	// Decision-kind defaults
+	VERSION_NOT_FOUND: (_msg, ctx = {}) => decision(
+		PICK_VERSION,
+		'The requested version does not exist. Pick from the available versions and re-run.',
+		{
+			...(ctx.requested ? { requested: ctx.requested } : {}),
+			...(ctx.available ? { available: ctx.available } : {}),
+			...(ctx.skill && ctx.available && ctx.available.length
+				? { commands: [`npx happyskills install ${ctx.skill}@${ctx.available[ctx.available.length - 1]} --json`] }
+				: {}),
+		}
+	),
+	MISSING_VERSION: (_msg, ctx = {}) => decision(
+		SPECIFY_BUMP_TYPE,
+		'No target version determined. Pick a bump type and re-run.',
+		{
+			options: ['patch', 'minor', 'major'],
+			...(ctx.current_version ? { current_version: ctx.current_version } : {}),
+		}
+	),
+	INVALID_BUMP: (_msg, ctx = {}) => decision(
+		SPECIFY_BUMP_TYPE,
+		'The provided bump value is not valid. Pick a bump type and re-run.',
+		{
+			options: ['patch', 'minor', 'major'],
+			...(ctx.bump ? { got: ctx.bump } : {}),
+		}
+	),
+	BUMP_DISAGREEMENT: (_msg, ctx = {}) => decision(
+		RESOLVE_BUMP_DISAGREEMENT,
+		'The --bump value disagrees with the disk version. Pick one and re-run.',
+		{
+			...(ctx.disk_version ? { disk_version: ctx.disk_version } : {}),
+			...(ctx.requested_bump ? { requested_bump: ctx.requested_bump } : {}),
+			...(ctx.lock_version ? { lock_version: ctx.lock_version } : {}),
+		}
+	),
+	WORKSPACE_UNRESOLVED: (_msg, ctx = {}) => decision(
+		SPECIFY_WORKSPACE,
+		'Could not resolve a workspace from the input. Pick one and re-run.',
+		{
+			...(ctx.candidates ? { candidates: ctx.candidates } : {}),
+		}
+	),
+
+	// Confirmation-kind defaults
+	LOCAL_EDITS_PRESENT: (_msg, ctx = {}) => confirmation(
+		CONFIRM_DISCARD_OR_SNAPSHOT_FIRST,
+		'Local edits exist. The principal must choose: snapshot first (safe), or discard the edits (destructive).',
+		{
+			commands: [
+				`npx happyskills snapshot create ${ctx.skill || '<skill>'} --json`,
+				`npx happyskills install ${ctx.skill || '<skill>'}${ctx.version ? '@' + ctx.version : ''} --fresh --force-discard-local --json`,
+			],
+			...(ctx.modified_files ? { modified_files: ctx.modified_files } : {}),
+		}
+	),
+	CONFIRMATION_REQUIRED: (_msg, ctx = {}) => confirmation(
+		CONFIRM_DESTRUCTIVE,
+		'This is a destructive operation. Re-run with -y to confirm.',
+		{
+			...(ctx.commands ? { commands: ctx.commands } : {}),
+			...(ctx.would_remove ? { would_remove: ctx.would_remove } : {}),
+		}
+	),
+	DEPENDENCY_CASCADE_REQUIRED: (_msg, ctx = {}) => confirmation(
+		CONFIRM_CASCADE,
+		'This operation cascades to dependencies. Re-run with --confirm to proceed.',
+		{
+			...(ctx.dependencies ? { dependencies: ctx.dependencies } : {}),
+			...(ctx.commands ? { commands: ctx.commands } : {}),
+		}
+	),
+})
+
+const next_step_for_error = (code, message, context) => {
+	const factory = NEXT_STEP_BY_ERROR_CODE[code]
+	if (!factory) return null
+	try {
+		return factory(message, context || {})
+	} catch (_) {
+		return null
+	}
+}
+
+module.exports = { NEXT_STEP_BY_ERROR_CODE, next_step_for_error }

package/src/constants.js

@@ -79,7 +79,8 @@ const COMMANDS = [
 	'snapshot',
 	'reconcile',
 	'release',
-	'feedback'
+	'feedback',
+	'schema'
 ]
 
 module.exports = {

package/src/index.js

@@ -2,6 +2,18 @@ const { CLI_VERSION, EXIT_CODES, COMMAND_ALIASES, COMMANDS } = require('./consta
 const { print_error, print_help } = require('./ui/output')
 const { dim, yellow } = require('./ui/colors')
 
+// Mode resolution — spec 260525-cli-default-json § 8.1. Explicit flags
+// always win; CI=true forces JSON; non-TTY stdout forces JSON; interactive
+// TTY falls back to text. Mutual exclusion of --json + --text is a
+// USAGE_ERROR raised in run().
+const resolve_mode = (flags, env = process.env) => {
+	if (flags.json) return 'json'
+	if (flags.text) return 'text'
+	if (env.CI === 'true' || env.CI === '1') return 'json'
+	if (!process.stdout.isTTY) return 'json'
+	return 'text'
+}
+
 const levenshtein = (a, b) => {
 	const m = a.length, n = b.length
 	const dp = Array.from({ length: m + 1 }, (_, i) =>
@@ -129,15 +141,27 @@ const run = (argv) => {
 	const args = parse_args(argv)
 	args.flags = normalize_flags(args.flags)
 
-	if (args.flags.json) {
+	// § 8.1 — resolve emission mode. --json + --text together is a USAGE_ERROR.
+	if (args.flags.json && args.flags.text) {
+		const { exit_with_error, UsageError } = require('./utils/errors')
+		const { set_json_mode } = require('./state')
+		set_json_mode()
+		exit_with_error(new UsageError('--json and --text are mutually exclusive.'))
+		return
+	}
+	const mode = resolve_mode(args.flags)
+	if (mode === 'json') {
 		const { set_json_mode } = require('./state')
 		set_json_mode()
+		// Reflect the auto-flip back onto args.flags so command modules that
+		// check args.flags.json see a consistent view.
+		args.flags.json = true
 	}
 
 	// Spec 260521-03 § 8.4 — propagate intent envelope from --intent flag or
-	// the HAPPYSKILLS_INTENT_ENVELOPE env var (set by a parent process such
-	// as the MCP server). Initializing here makes the envelope visible to
-	// every subsequent API call within this CLI invocation.
+	// the HAPPYSKILLS_INTENT_ENVELOPE env var (set by a parent process that
+	// shells out to `happyskills`). Initializing here makes the envelope
+	// visible to every subsequent API call within this CLI invocation.
 	if (args.flags.intent || process.env.HAPPYSKILLS_INTENT_ENVELOPE) {
 		const { init_from_flag, init_from_env } = require('./utils/intent')
 		if (args.flags.intent) init_from_flag(args.flags.intent)
@@ -160,13 +184,25 @@ const run = (argv) => {
 
 	if (!COMMANDS.includes(resolved)) {
 		const { is_json_mode } = require('./state')
+		const suggestion = suggest_command(command_name)
 		if (is_json_mode()) {
-			const { exit_with_error, UsageError } = require('./utils/errors')
-			exit_with_error(new UsageError(`Unknown command: "${command_name}"`))
+			const { exit_with_error, CliError } = require('./utils/errors')
+			const { ERROR_CODES } = require('./constants/error_codes')
+			const { set_command } = require('./ui/envelope')
+			set_command('<unknown>')
+			exit_with_error(new CliError(
+				suggestion
+					? `Unknown command: "${command_name}". Did you mean: ${suggestion}?`
+					: `Unknown command: "${command_name}"`,
+				{
+					code: ERROR_CODES.COMMAND_NOT_FOUND,
+					exit_code: 2,
+					context: { got: command_name, ...(suggestion ? { suggestion } : {}) },
+				}
+			))
 			return
 		}
 		print_error(`Unknown command: "${command_name}"`)
-		const suggestion = suggest_command(command_name)
 		if (suggestion) {
 			console.error(dim(`  Did you mean: happyskills ${suggestion}?`))
 		} else {
@@ -175,6 +211,14 @@ const run = (argv) => {
 		return process.exit(EXIT_CODES.USAGE)
 	}
 
+	// Stamp the command name into the envelope helper's module state so every
+	// emit_envelope call within this invocation carries meta.command.
+	{
+		const { set_command, set_workspace } = require('./ui/envelope')
+		set_command(resolved)
+		if (args.flags.workspace) set_workspace(args.flags.workspace)
+	}
+
 	if (args.flags.help) {
 		args.flags._show_help = true
 	}