happyskills 1.12.0 → 1.13.0

package/src/commands/update.js

@@ -26,6 +26,8 @@ Arguments:
 
 Options:
   --all             Update all installed root-level skills
+  --all-scopes      Update BOTH project-local and global skills (in that order),
+                    reporting per-scope results. Overrides -g.
   --force           Re-install regardless of version. Also overwrites skills
                     with local modifications.
   -g, --global      Update globally installed skills
@@ -37,7 +39,9 @@ Aliases: up
 
 Examples:
   happyskills update acme/deploy-aws       # update one skill if outdated
-  happyskills up --all                     # check + update all outdated skills
+  happyskills up --all                     # check + update all outdated skills (local)
+  happyskills up --all -g                   # ...global scope
+  happyskills up --all --all-scopes         # ...both scopes, per-scope report
   happyskills up --all --force             # force re-install everything
   happyskills up --all -y --json           # batch mode, no prompt`
 
@@ -62,26 +66,28 @@ const confirm_prompt = (question) => new Promise((resolve) => {
 	})
 })
 
-const run = (args) => catch_errors('Update failed', async () => {
-	if (args.flags._show_help) {
-		print_help(HELP_TEXT)
-		return process.exit(EXIT_CODES.SUCCESS)
-	}
-
-	const project_root = find_project_root()
-	const target_skill = args._[0]
-	const update_all = args.flags.all || false
-	const force = args.flags.force || false
-	const auto_yes = args.flags.yes || false
-	const is_global = args.flags.global || false
-
-	if (!target_skill && !update_all) {
-		throw new UsageError("Specify a skill to update or use --all (e.g., 'happyskills update acme/deploy-aws' or 'happyskills update --all').")
+/**
+ * Run the full update flow for ONE scope (project-local or global) and return
+ * `{ scope, data }` — where `data` is exactly the JSON `data` payload that
+ * single-scope `update` has always emitted for that path (force / empty /
+ * smart). In text mode it prints that scope's output directly; under
+ * `multi_scope` it prefixes a scope header and scopes its confirmation prompt.
+ * The caller (run) either prints `data` as-is (single scope, byte-identical to
+ * the historical contract) or aggregates the per-scope objects (--all-scopes).
+ */
+const run_scope = (scope_is_global, ctx) => catch_errors('Update scope failed', async () => {
+	const { project_root, target_skill, force, auto_yes, json_mode, agents_flag, multi_scope } = ctx
+	const scope = scope_is_global ? 'global' : 'local'
+	const print_header = () => {
+		if (multi_scope && !json_mode) {
+			console.log()
+			print_info(`── ${scope_is_global ? 'Global' : 'Local'} scope ──`)
+		}
 	}
 
-	const [, lock_data] = await read_lock(lock_root(is_global, project_root))
+	const [, lock_data] = await read_lock(lock_root(scope_is_global, project_root))
 	const skills = get_all_locked_skills(lock_data)
-	const base_dir = skills_dir(is_global, project_root)
+	const base_dir = skills_dir(scope_is_global, project_root)
 
 	// Determine which skills to consider.
 	// For --all, only root-level skills (transitive deps come along through their parents).
@@ -91,24 +97,24 @@ const run = (args) => catch_errors('Update failed', async () => {
 		: Object.entries(skills).filter(([, data]) => data && data.requested_by?.includes('__root__'))
 
 	if (candidates.length === 0) {
-		if (target_skill) {
+		// A missing target is only a hard error in single-scope mode. Across
+		// scopes, "not installed in this scope" is normal — report it empty.
+		if (target_skill && !multi_scope) {
 			throw new UsageError(`${target_skill} is not installed. Run 'happyskills install ${target_skill}' first.`)
 		}
-		if (args.flags.json) {
-			print_json({ data: { results: [], outdated_count: 0, up_to_date_count: 0, updated: [], already_up_to_date: [], errors: [] } })
-			return
-		}
-		print_info('No skills installed.')
-		return
+		print_header()
+		if (!json_mode) print_info(multi_scope ? `No skills installed in the ${scope} scope.` : 'No skills installed.')
+		return { scope, data: { results: [], outdated_count: 0, up_to_date_count: 0, updated: [], already_up_to_date: [], errors: [] } }
 	}
 
 	// ─── --force path: skip the version check, re-install everything ─────────
 	if (force) {
-		const options = { global: is_global, fresh: true, force: true, agents: args.flags.agents || undefined, project_root }
+		print_header()
+		const options = { global: scope_is_global, fresh: true, force: true, agents: agents_flag || undefined, project_root }
 		const updated = []
 		for (const [name, data] of candidates) {
 			const before_version = data?.version || null
-			const spinner = !args.flags.json ? create_spinner(`Re-installing ${name}…`) : null
+			const spinner = !json_mode ? create_spinner(`Re-installing ${name}…`) : null
 			const [errors, result] = await install(name, options)
 			if (errors) {
 				spinner?.fail(`Failed to re-install ${name}`)
@@ -117,18 +123,15 @@ const run = (args) => catch_errors('Update failed', async () => {
 			spinner?.succeed(`Re-installed ${name}@${result.version}`)
 			updated.push({ skill: name, from: before_version, to: result.version, via: get_via(data) })
 		}
-		if (args.flags.json) {
-			print_json({ data: { updated, count: updated.length, forced: true } })
-			return
-		}
-		if (updated.length > 0) {
+		if (!json_mode && updated.length > 0) {
 			print_success(`Re-installed ${updated.length} skill(s) (--force).`)
 		}
-		return
+		return { scope, data: { updated, count: updated.length, forced: true } }
 	}
 
 	// ─── Default smart path: batch-check, then install only outdated ─────────
-	const spinner = !args.flags.json ? create_spinner('Checking for updates…') : null
+	print_header()
+	const spinner = !json_mode ? create_spinner('Checking for updates…') : null
 	const skill_names = candidates.map(([name]) => name)
 	const [batch_err, batch_data] = await repos_api.check_updates(skill_names)
 
@@ -184,7 +187,7 @@ const run = (args) => catch_errors('Update failed', async () => {
 	const drifted = results.filter(r => r.status === 'drift')
 
 	// Verify and repair symlinks (even when nothing is outdated)
-	const [, agents_data] = await resolve_agents(args.flags.agents, { global: is_global, project_root })
+	const [, agents_data] = await resolve_agents(agents_flag, { global: scope_is_global, project_root })
 	const detected_agents = agents_data?.agents || []
 	let symlink_repairs = []
 	if (detected_agents.length > 0) {
@@ -193,14 +196,14 @@ const run = (args) => catch_errors('Update failed', async () => {
 			if (data?.type === SKILL_TYPES.KIT) continue
 			const short_name = name.split('/')[1] || name
 			const source_dir = skill_install_dir(base_dir, short_name)
-			const [, enabled] = await is_skill_enabled(short_name, detected_agents, is_global, project_root)
+			const [, enabled] = await is_skill_enabled(short_name, detected_agents, scope_is_global, project_root)
 			if (enabled) {
 				skills_to_check.push({ skill_name: short_name, source_dir })
 			}
 		}
 		if (skills_to_check.length > 0) {
-			const link_spinner = !args.flags.json ? create_spinner('Verifying symlinks…') : null
-			const [, repair_result] = await verify_and_repair_symlinks(skills_to_check, detected_agents, { global: is_global, project_root })
+			const link_spinner = !json_mode ? create_spinner('Verifying symlinks…') : null
+			const [, repair_result] = await verify_and_repair_symlinks(skills_to_check, detected_agents, { global: scope_is_global, project_root })
 			symlink_repairs = repair_result?.repaired || []
 			if (symlink_repairs.length > 0) {
 				link_spinner?.succeed(`Repaired ${symlink_repairs.length} symlink(s)`)
@@ -212,30 +215,28 @@ const run = (args) => catch_errors('Update failed', async () => {
 
 	// If nothing to update, report and exit
 	if (outdated.length === 0) {
-		if (args.flags.json) {
-			print_json({ data: { results, outdated_count: 0, up_to_date_count: up_to_date.length, drift_count: drifted.length, updated: [], already_up_to_date: up_to_date.map(r => ({ skill: r.skill, version: r.installed })), symlink_repairs, errors: [] } })
-			return
-		}
-		print_table(['Skill', 'Installed', 'Latest', 'Status'], results.map(r => [
-			r.skill, r.installed, r.latest, r.status === 'drift' ? red('drift') : green(r.status)
-		]))
-		console.log()
-		if (drifted.length > 0) {
-			print_warn(`${drifted.length} skill(s) drifted: lock and on-disk skill.json disagree.`)
-			for (const r of drifted) {
-				console.error(`  - ${r.skill} (lock ${r.drift?.lock_version}, disk ${r.drift?.disk_version || 'none'})`)
+		if (!json_mode) {
+			print_table(['Skill', 'Installed', 'Latest', 'Status'], results.map(r => [
+				r.skill, r.installed, r.latest, r.status === 'drift' ? red('drift') : green(r.status)
+			]))
+			console.log()
+			if (drifted.length > 0) {
+				print_warn(`${drifted.length} skill(s) drifted: lock and on-disk skill.json disagree.`)
+				for (const r of drifted) {
+					console.error(`  - ${r.skill} (lock ${r.drift?.lock_version}, disk ${r.drift?.disk_version || 'none'})`)
+				}
+				print_hint(`Restore each one with ${code('happyskills install <skill> --fresh')} before updating.`)
+			} else if (symlink_repairs.length > 0) {
+				print_success(`All skills are up to date. Repaired ${symlink_repairs.length} symlink(s).`)
+			} else {
+				print_success(multi_scope ? `All ${scope} skills are up to date.` : 'All skills are up to date.')
 			}
-			print_hint(`Restore each one with ${code('happyskills install <skill> --fresh')} before updating.`)
-		} else if (symlink_repairs.length > 0) {
-			print_success(`All skills are up to date. Repaired ${symlink_repairs.length} symlink(s).`)
-		} else {
-			print_success('All skills are up to date.')
 		}
-		return
+		return { scope, data: { results, outdated_count: 0, up_to_date_count: up_to_date.length, drift_count: drifted.length, updated: [], already_up_to_date: up_to_date.map(r => ({ skill: r.skill, version: r.installed })), symlink_repairs, errors: [] } }
 	}
 
 	// Show results table (non-json)
-	if (!args.flags.json) {
+	if (!json_mode) {
 		const status_colors = { 'up-to-date': green, 'outdated': yellow, 'drift': red, 'no-access': yellow, 'error': red, 'unknown': (s) => s }
 		print_table(['Skill', 'Installed', 'Latest', 'Status'], results.map(r => [
 			r.skill, r.installed, r.latest, (status_colors[r.status] || ((s) => s))(r.status)
@@ -248,16 +249,16 @@ const run = (args) => catch_errors('Update failed', async () => {
 			}
 			print_hint(`Restore each one with ${code('happyskills install <skill> --fresh')} to update them.`)
 		}
-		print_info(`${outdated.length} skill(s) can be updated.`)
+		print_info(`${outdated.length} skill(s) can be updated${multi_scope ? ` in the ${scope} scope` : ''}.`)
 	}
 
 	// Confirm
 	const should_update = auto_yes || !process.stdin.isTTY
-	if (!should_update && !args.flags.json) {
-		const answer = await confirm_prompt(`\nUpdate ${outdated.length} skill(s)? [y/N] `)
+	if (!should_update && !json_mode) {
+		const answer = await confirm_prompt(`\nUpdate ${outdated.length} skill(s)${multi_scope ? ` in the ${scope} scope` : ''}? [y/N] `)
 		if (answer !== 'y' && answer !== 'yes') {
 			print_info('Skipped.')
-			return
+			return { scope, data: { results, outdated_count: outdated.length, up_to_date_count: up_to_date.length, drift_count: drifted.length, updated: [], skipped: [], already_up_to_date: up_to_date.map(r => ({ skill: r.skill, version: r.installed })), symlink_repairs, errors: [], canceled: true } }
 		}
 	}
 
@@ -266,7 +267,7 @@ const run = (args) => catch_errors('Update failed', async () => {
 		const lock_entry = skills[r.skill]
 		const short_name = r.skill.split('/')[1] || r.skill
 		const dir = skill_install_dir(base_dir, short_name)
-		return detect_status(lock_entry, dir, { skill_name: r.skill, project_root, is_global }).then(([, det]) => ({ r, det }))
+		return detect_status(lock_entry, dir, { skill_name: r.skill, project_root, is_global: scope_is_global }).then(([, det]) => ({ r, det }))
 	}))
 
 	const skipped = []
@@ -280,12 +281,12 @@ const run = (args) => catch_errors('Update failed', async () => {
 	}
 
 	// Install only the outdated, non-modified skills
-	const options = { global: is_global, fresh: true, agents: args.flags.agents || undefined, project_root }
+	const options = { global: scope_is_global, fresh: true, agents: agents_flag || undefined, project_root }
 	const updated = []
 	const update_errors = []
 
 	for (const r of safe_to_update) {
-		const update_spinner = !args.flags.json ? create_spinner(`Updating ${r.skill}…`) : null
+		const update_spinner = !json_mode ? create_spinner(`Updating ${r.skill}…`) : null
 		const [errors, result] = await install(r.skill, options)
 		if (errors) {
 			update_spinner?.fail(`Failed to update ${r.skill}`)
@@ -298,51 +299,108 @@ const run = (args) => catch_errors('Update failed', async () => {
 		}
 	}
 
-	// Output
-	if (args.flags.json) {
-		print_json({
-			data: {
-				results,
-				outdated_count: outdated.length,
-				up_to_date_count: up_to_date.length,
-				drift_count: drifted.length,
-				updated,
-				skipped,
-				already_up_to_date: up_to_date.map(r => ({ skill: r.skill, version: r.installed })),
-				errors: update_errors
+	if (!json_mode) {
+		if (skipped.length > 0) {
+			console.log()
+			print_warn(`Skipped ${skipped.length} skill(s) with local modifications:`)
+			for (const s of skipped) {
+				print_info(`  ${s.skill}`)
 			}
-		})
-		return
+			print_hint(`Use ${code('happyskills pull <skill>')} to merge remote changes.`)
+		}
+		if (updated.length > 0) {
+			console.log()
+			print_success(`Updated ${updated.length} skill(s)${multi_scope ? ` in the ${scope} scope` : ''}.`)
+		}
+		if (update_errors.length > 0) {
+			console.log()
+			print_info(`${update_errors.length} skill(s) failed to update. Run ${code('happyskills check')} for details.`)
+		}
 	}
 
-	if (skipped.length > 0) {
-		console.log()
-		print_warn(`Skipped ${skipped.length} skill(s) with local modifications:`)
-		for (const s of skipped) {
-			print_info(`  ${s.skill}`)
-		}
-		print_hint(`Use ${code('happyskills pull <skill>')} to merge remote changes.`)
+	return { scope, data: {
+		results,
+		outdated_count: outdated.length,
+		up_to_date_count: up_to_date.length,
+		drift_count: drifted.length,
+		updated,
+		skipped,
+		already_up_to_date: up_to_date.map(r => ({ skill: r.skill, version: r.installed })),
+		errors: update_errors,
+	} }
+}).then(([errors, result]) => {
+	if (errors) throw e('Update scope failed', errors)
+	return result
+})
+
+const run = (args) => catch_errors('Update failed', async () => {
+	if (args.flags._show_help) {
+		print_help(HELP_TEXT)
+		return process.exit(EXIT_CODES.SUCCESS)
 	}
-	if (updated.length > 0) {
-		console.log()
-		print_success(`Updated ${updated.length} skill(s).`)
+
+	const project_root = find_project_root()
+	const target_skill = args._[0]
+	const update_all = args.flags.all || false
+	const force = args.flags.force || false
+	const auto_yes = args.flags.yes || false
+	const is_global = args.flags.global || false
+	const all_scopes = args.flags['all-scopes'] || false
+	const json_mode = args.flags.json || false
+
+	if (!target_skill && !update_all) {
+		throw new UsageError("Specify a skill to update or use --all (e.g., 'happyskills update acme/deploy-aws' or 'happyskills update --all').")
 	}
-	if (update_errors.length > 0) {
-		console.log()
-		print_info(`${update_errors.length} skill(s) failed to update. Run ${code('happyskills check')} for details.`)
+
+	// --all-scopes overrides -g and runs project-local first, then global. The
+	// scopes run sequentially — these are writes, and a shared global mutation
+	// should not race a project one.
+	const scope_flags = all_scopes ? [false, true] : [is_global]
+	const ctx = { project_root, target_skill, force, auto_yes, json_mode, agents_flag: args.flags.agents, multi_scope: all_scopes }
+
+	const scope_results = []
+	for (const g of scope_flags) {
+		scope_results.push(await run_scope(g, ctx))
+	}
+
+	if (!all_scopes) {
+		// Single scope: emit exactly the historical per-scope data payload.
+		if (json_mode) print_json({ data: scope_results[0].data })
+		return
 	}
+
+	// --all-scopes: per-scope results plus convenience aggregates. A skill
+	// installed in both scopes appears once under each scope's result.
+	const count_updated = (d) => d.updated?.length || 0
+	if (json_mode) {
+		const scopes = scope_results.map(r => ({ scope: r.scope, ...r.data }))
+		print_json({ data: {
+			all_scopes: true,
+			scopes,
+			updated_count: scope_results.reduce((n, r) => n + count_updated(r.data), 0),
+			outdated_count: scope_results.reduce((n, r) => n + (r.data.outdated_count || 0), 0),
+		} })
+		return
+	}
+
+	const total_updated = scope_results.reduce((n, r) => n + count_updated(r.data), 0)
+	console.log()
+	print_success(total_updated > 0
+		? `Done — updated ${total_updated} skill(s) across the local and global scopes.`
+		: 'Done — everything is already up to date across both scopes.')
 }).then(([errors]) => { if (errors) { exit_with_error(errors); return } })
 
 const schema = {
 	name: 'update',
 	audience: 'consumer',
-	purpose: 'Bring installed skills up to date by batch-checking the registry and re-installing only outdated skills.',
+	purpose: 'Bring installed skills up to date by batch-checking the registry and re-installing only outdated skills. With --all-scopes, updates project-local and global skills in one run and reports per-scope results.',
 	mutation: true,
 	interactive_in_text_mode: true,
 	input: {
 		positional: [{ name: 'skill', required: false, type: 'string', pattern: '<owner>/<name>' }],
 		flags: [
 			{ name: 'all', type: 'boolean', default: false },
+			{ name: 'all-scopes', type: 'boolean', default: false, description: 'Update both project-local and global skills; reports per-scope results. Overrides --global.' },
 			{ name: 'force', type: 'boolean', default: false },
 			{ name: 'global', type: 'boolean', default: false },
 			{ name: 'yes', type: 'boolean', default: false },
@@ -352,6 +410,7 @@ const schema = {
 	},
 	output: {
 		data_shape: {
+			// Single scope (default / -g): the historical payload.
 			results: 'array<{ skill: string, installed: string, latest: string, status: string }>',
 			outdated_count: 'number',
 			up_to_date_count: 'number',
@@ -360,7 +419,8 @@ const schema = {
 			skipped: 'array<{ skill: string, reason: string, suggestion: string }>',
 			already_up_to_date: 'array<{ skill: string, version: string }>',
 			symlink_repairs: 'array',
-			errors: 'array<{ skill: string, message: string }>'
+			errors: 'array<{ skill: string, message: string }>',
+			// With --all-scopes: { all_scopes: true, scopes: array<{ scope, ...the single-scope payload above }>, updated_count, outdated_count }
 		}
 	},
 	errors: [
@@ -368,7 +428,8 @@ const schema = {
 	],
 	examples: [
 		'happyskills update acme/deploy-aws',
-		'happyskills up --all -y --json'
+		'happyskills up --all -y --json',
+		'happyskills up --all --all-scopes -y --json'
 	]
 }
 

package/src/constants/next_step_by_error_code.js

@@ -74,11 +74,24 @@ const NEXT_STEP_BY_ERROR_CODE = Object.freeze({
 		'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 }
-	),
+	// An anonymous caller throttled on a per-IP bucket gets a much higher cap (and
+	// their own per-user budget) once signed in, so when the API flags `login_helps`
+	// we steer them to authenticate instead of just retrying. Authenticated trips
+	// (and the pre-login /auth/* limiter) fall through to the plain retry recovery.
+	RATE_LIMITED: (_msg, ctx = {}) => ctx.login_helps
+		? recovery(
+			LOGIN,
+			'You hit the anonymous rate limit. Sign in or create a free account for a much higher limit, then re-run.',
+			{
+				retry_after_seconds: ctx.retry_after_seconds || 30,
+				commands: ['npx happyskills login --browser --json'],
+			}
+		)
+		: 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.',

package/src/constants/next_step_by_error_code.test.js

@@ -7,7 +7,7 @@
 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')
+const { DISCOVER_SCHEMA, ROUTING, RECOVERY, LOGIN, RETRY, kind_for_action } = require('./next_step_actions')
 
 describe('next_step_by_error_code — schema discovery routing', () => {
 	it('discover_schema is a routing-kind action', () => {
@@ -28,3 +28,19 @@ describe('next_step_by_error_code — schema discovery routing', () => {
 		})
 	}
 })
+
+describe('next_step_by_error_code — RATE_LIMITED steers anonymous callers to sign in', () => {
+	it('login_helps → a LOGIN recovery that points at `happyskills login`', () => {
+		const ns = next_step_for_error('RATE_LIMITED', 'Too many requests.', { login_helps: true, retry_after_seconds: 42 })
+		assert.strictEqual(ns.kind, RECOVERY)
+		assert.strictEqual(ns.action, LOGIN)
+		assert.ok(ns.context.commands.some(c => c.includes('login')), 'must point at the login command')
+		assert.strictEqual(ns.context.retry_after_seconds, 42)
+	})
+
+	it('without login_helps → a plain RETRY recovery (authenticated / auth-path trips)', () => {
+		const ns = next_step_for_error('RATE_LIMITED', 'Too many requests.', { retry_after_seconds: 30 })
+		assert.strictEqual(ns.kind, RECOVERY)
+		assert.strictEqual(ns.action, RETRY)
+	})
+})

package/src/index.js

@@ -237,6 +237,29 @@ const run = (argv) => {
 		}
 	}
 
+	// Skill-drift awareness — the registry-side counterpart of the npm self-check
+	// above, for INSTALLED skills. Unlike npx (which always pulls the latest CLI),
+	// installed skills are pinned in the lock by design, so the only honest mechanism
+	// is passive notification + opt-in update. The verdict is a synchronous read of a
+	// 24h cache (zero latency); a stale cache fires a background refresh for next time.
+	// It ALWAYS spans both the project-local and the global lock, so a globally-installed
+	// constellation is surfaced even during project-scoped work. Two faces, one verdict:
+	// a stderr nudge for the human (text mode) and a warnings[] entry on every command's
+	// envelope for the agent (set_skill_drift → build_envelope). Suppressed for
+	// self-update only (consistent with the npm banner).
+	if (resolved !== 'self-update') {
+		const { check_skills_for_update, format_skill_drift } = require('./utils/skill_update_check')
+		const { find_project_root } = require('./config/paths')
+		const { set_skill_drift } = require('./ui/envelope')
+		const drift = check_skills_for_update({ project_root: find_project_root() })
+		set_skill_drift(drift)
+		if (!args.flags.json && drift) {
+			process.stderr.write('\n')
+			process.stderr.write(yellow(`  ${format_skill_drift(drift)}\n`))
+			process.stderr.write('\n')
+		}
+	}
+
 	const command_module = require(`./commands/${resolved}`)
 	const result = command_module.run(args)