happyskills 1.12.1 → 1.13.0

package/CHANGELOG.md

@@ -7,6 +7,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [1.13.0] - 2026-06-29
+
+### Added
+
+- Add `list --all-scopes`, which merges project-local and global skills into one listing instead of showing a single scope at a time (`list` = project, `list -g` = global). Every entry is tagged with `scope` (`local`/`global`) and `native` (`true` for managed/draft HappySkills skills, `false` for manually-added external/agent-orphan skills), and the human table gains **Scope** and **Native** columns — so you can see at a glance where each skill is installed and whether it's a native HappySkills skill or one added by hand. In this mode `data.skills` becomes an array (a skill installed in both scopes surfaces once per scope, rather than colliding on a shared `owner/name` key); the single-scope output shape is unchanged for backward compatibility.
+- Add `update --all-scopes`, which updates outdated skills in **both** the project-local and global scopes in one run (local first, then global) and returns a per-scope report: `{ all_scopes: true, scopes: [{ scope: "local", … }, { scope: "global", … }], updated_count, outdated_count }`. Each `scopes[]` entry carries the same payload a single-scope update emits, so partial failure (e.g. local succeeds, global has an error) is visible per scope. Unlike `list --all-scopes`, this is opt-in, not the default — a write should not touch shared global state implicitly, so `update` stays project-local unless `-g` (global) or `--all-scopes` (both) is passed. The single-scope output shape is unchanged.
+- Add passive skill-drift awareness, so you're told when your installed skills have fallen behind the registry without having to remember to check. Before each command, the CLI does a once-per-24h, fire-and-forget, zero-latency check (a synchronous read of a `~/.config/happyskills/skill-update-check.json` cache; a stale cache triggers a background refresh for next time, never blocking the current command) of installed root skills against the registry, spanning **both** the project-local and global locks so a globally-installed constellation is surfaced even during project-scoped work. Outdated skills appear two ways: a one-line nudge on stderr (text mode) and a `SKILLS_UPDATE_AVAILABLE` entry in the existing `warnings[]` array of every command's envelope (`--json` mode) — `data` is untouched and the envelope schema is unchanged. The suggested command is scope-aware (`update --all`, adding `-g` when global skills are behind). Only registry-advance (`outdated`) is reported — never a locally-bumped (`ahead`) or drifted skill. Disable with `HAPPYSKILLS_NO_SKILL_UPDATE_CHECK=1`.
+
 ## [1.12.1] - 2026-06-23
 
 ### Changed

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "happyskills",
-	"version": "1.12.1",
+	"version": "1.13.0",
 	"description": "Package manager for AI agent skills",
 	"license": "SEE LICENSE IN LICENSE",
 	"author": "Nicolas Dao <nic@cloudlesslabs.com> (https://cloudlesslabs.com)",

package/src/commands/list.js

@@ -1,3 +1,4 @@
+const path = require('path')
 const { error: { catch_errors, wrap_errors: e } } = require('puffy-core')
 const { read_lock, get_all_locked_skills } = require('../lock/reader')
 const { verify_lock_disk_consistency, detect_ahead_state } = require('../lock/verify')
@@ -17,7 +18,10 @@ const HELP_TEXT = `Usage: happyskills list [options]
 List installed skills.
 
 Options:
-  -g, --global      List globally installed skills
+  -g, --global      List globally installed skills (~/.agents/skills/)
+  --all-scopes      List BOTH project-local and global skills in one view,
+                    each row tagged with its scope (local/global) and whether
+                    it is a native HappySkills skill or a manually-added one
   --json            Output as JSON
 
 Aliases: ls
@@ -25,16 +29,23 @@ Aliases: ls
 Examples:
   happyskills list
   happyskills ls --json
-  happyskills ls -g`
+  happyskills ls -g
+  happyskills ls --all-scopes --json`
 
-const run = (args) => catch_errors('List failed', async () => {
-	if (args.flags._show_help) {
-		print_help(HELP_TEXT)
-		return process.exit(EXIT_CODES.SUCCESS)
-	}
+// scope_tag — the public, machine-readable scope label for an entry.
+const scope_tag = (is_global) => (is_global ? 'global' : 'local')
+// scope_label — the human, title-cased scope label for the table.
+const scope_label = (is_global) => (is_global ? 'Global' : 'Local')
 
-	const is_global = args.flags.global || false
-	const project_root = find_project_root()
+// gather_scope — collect the full, render-ready inventory for ONE scope
+// (project or global). Returns normalized "views" so the JSON and human
+// renderers share one computation of status / type / enabled, rather than
+// each re-deriving it. The four buckets mirror `list`'s data contract:
+//   managed_views  → native, recorded in skills-lock.json (data.skills)
+//   draft_skills   → native, scaffolded by `init`, not yet published (data.drafts)
+//   external_skills→ manual/foreign on disk (data.external)
+//   orphan_skills  → manual/foreign dropped into an agent folder (data.agent_orphans)
+const gather_scope = (is_global, project_root, agents_flag) => catch_errors('Gather scope failed', async () => {
 	const base_dir = skills_dir(is_global, project_root)
 
 	const [, lock_data] = await read_lock(lock_root(is_global, project_root))
@@ -42,7 +53,7 @@ const run = (args) => catch_errors('List failed', async () => {
 	const managed_entries = Object.entries(skills)
 
 	// Resolve agents and build enabled/disabled map for managed skills
-	const [, agents_result] = await resolve_agents(args.flags.agents, { global: is_global, project_root })
+	const [, agents_result] = await resolve_agents(agents_flag, { global: is_global, project_root })
 	const agents = agents_result?.agents || []
 	const managed_short_names = managed_entries.map(([k]) => k.split('/')[1])
 	const [, enabled_map] = agents.length > 0
@@ -65,31 +76,13 @@ const run = (args) => catch_errors('List failed', async () => {
 	const [, agent_orphans] = await scan_agent_orphan_skills(AGENTS, is_global, project_root, all_known_names)
 	const orphan_skills = agent_orphans || []
 
-	if (managed_entries.length === 0 && draft_skills.length === 0 && external_skills.length === 0 && orphan_skills.length === 0) {
-		if (args.flags.json) {
-			print_json({ data: { skills: {}, drafts: [], external: [], agent_orphans: [] } })
-			return
-		}
-		print_info('No skills installed.')
-		return
-	}
-
-	// Resolve type for each managed entry from lock data or skill.json on disk
-	const resolve_type = async (name, data) => {
-		if (data.type) return data.type
-		const dir = skill_install_dir(base_dir, name.split('/')[1])
-		const json_path = require('path').join(dir, SKILL_JSON)
-		const [, manifest] = await read_json(json_path)
-		return manifest?.type || SKILL_TYPES.SKILL
-	}
-
 	// Compute drift AND ahead state up-front for every managed entry. Cheap
 	// (one skill.json read per skill, plus an optional CHANGELOG read) and lets
 	// both the JSON and human paths report identically.
 	//
 	// §10.5: drift is narrowed to genuine inconsistency (regression, missing
-	// files); the disk-greater-than-lock case is reported under top-level
-	// status:ahead, not under drift.
+	// files); the disk-greater-than-lock case is reported under status:ahead,
+	// not under drift.
 	const drift_by_skill = {}
 	const ahead_by_skill = {}
 	await Promise.all(managed_entries.map(async ([name, data]) => {
@@ -104,86 +97,167 @@ const run = (args) => catch_errors('List failed', async () => {
 		if (ahead && ahead.ahead) ahead_by_skill[name] = ahead
 	}))
 
-	if (args.flags.json) {
-		const skills_map = {}
-		for (const [name, data] of managed_entries) {
-			const short = name.split('/')[1]
-			const dir = skill_install_dir(base_dir, short)
-			const [, exists] = await file_exists(dir)
-			const drift = drift_by_skill[name]
-			const ahead = ahead_by_skill[name]
-			let status
-			if (drift) status = 'drift'
-			else if (ahead) status = 'ahead'
-			else if (exists) status = 'installed'
-			else status = 'missing'
-			const source = data.requested_by?.includes('__root__') ? 'direct' : 'dep'
-			const type = await resolve_type(name, data)
-			const enabled = enabled_map?.get(short) ?? true
-			const entry = { version: data.version, type, source, status, enabled }
-			if (drift) entry.drift = { reason: drift.reason, lock_version: drift.expected, disk_version: drift.actual }
-			if (ahead) entry.ahead = {
-				lock_version: ahead.lock_version,
-				disk_version: ahead.disk_version,
-				has_changelog_entry: ahead.has_changelog_entry || false,
-				changelog_version: ahead.changelog_version || null
-			}
-			skills_map[name] = entry
-		}
-		const drafts = draft_skills.map(s => ({
-			name: s.name,
-			description: s.description || '',
-			version: s.version || null,
-			type: s.type || SKILL_TYPES.SKILL
-		}))
-		const external = external_skills.map(s => ({ name: s.name, description: s.description || '' }))
-		const agent_orphan_list = orphan_skills.map(s => ({
-			name: s.name,
-			description: s.description || '',
-			agents: s.agents
-		}))
-		print_json({ data: { skills: skills_map, drafts, external, agent_orphans: agent_orphan_list } })
-		return
+	const resolve_type = async (name, data) => {
+		if (data.type) return data.type
+		const dir = skill_install_dir(base_dir, name.split('/')[1])
+		const [, manifest] = await read_json(path.join(dir, SKILL_JSON))
+		return manifest?.type || SKILL_TYPES.SKILL
 	}
 
-	const rows = []
-	for (const [name, data] of managed_entries) {
+	// Normalize each managed entry into a single render-ready view. Both the
+	// JSON and human renderers consume these, so status/type/enabled are
+	// computed exactly once.
+	const managed_views = await Promise.all(managed_entries.map(async ([name, data]) => {
 		const short = name.split('/')[1]
 		const dir = skill_install_dir(base_dir, short)
 		const [, exists] = await file_exists(dir)
 		const drift = drift_by_skill[name]
 		const ahead = ahead_by_skill[name]
-		let status_label
-		if (drift) status_label = red(`drift (${drift.reason})`)
-		else if (ahead) status_label = `ahead (disk ${ahead.disk_version})`
-		else if (exists) status_label = 'installed'
-		else status_label = yellow('missing')
+		let status
+		if (drift) status = 'drift'
+		else if (ahead) status = 'ahead'
+		else if (exists) status = 'installed'
+		else status = 'missing'
 		const source = data.requested_by?.includes('__root__') ? 'direct' : 'dep'
 		const type = await resolve_type(name, data)
-		const display_name = type === SKILL_TYPES.KIT ? `${name} [kit]` : name
 		const enabled = enabled_map?.get(short) ?? true
-		const enabled_label = enabled ? green('enabled') : yellow('disabled')
-		rows.push([display_name, data.version, source, status_label, enabled_label])
+		return { name, short, version: data.version, type, source, status, enabled, drift, ahead }
+	}))
+
+	return {
+		is_global,
+		managed_views,
+		draft_skills,
+		external_skills,
+		orphan_skills,
 	}
+}).then(([errors, result]) => {
+	if (errors) throw e('Failed to gather scope', errors)
+	return result
+})
 
-	for (const s of draft_skills) {
-		const type_label = s.type === SKILL_TYPES.KIT ? `${s.name} [kit]` : s.name
-		rows.push([type_label, s.version || '-', 'draft', 'unpublished', '-'])
+// json_managed_entry — the canonical per-skill JSON shape, shared by the
+// object form (single scope) and the array form (--all-scopes).
+const json_managed_entry = (v) => {
+	const entry = { version: v.version, type: v.type, source: v.source, status: v.status, enabled: v.enabled }
+	if (v.drift) entry.drift = { reason: v.drift.reason, lock_version: v.drift.expected, disk_version: v.drift.actual }
+	if (v.ahead) entry.ahead = {
+		lock_version: v.ahead.lock_version,
+		disk_version: v.ahead.disk_version,
+		has_changelog_entry: v.ahead.has_changelog_entry || false,
+		changelog_version: v.ahead.changelog_version || null,
 	}
+	return entry
+}
+
+const run = (args) => catch_errors('List failed', async () => {
+	if (args.flags._show_help) {
+		print_help(HELP_TEXT)
+		return process.exit(EXIT_CODES.SUCCESS)
+	}
+
+	const all_scopes = args.flags['all-scopes'] || false
+	const is_global = args.flags.global || false
+	const project_root = find_project_root()
+
+	// --all-scopes overrides -g: it always covers BOTH project and global.
+	const scope_flags = all_scopes ? [false, true] : [is_global]
+	const scopes = await Promise.all(scope_flags.map(g => gather_scope(g, project_root, args.flags.agents)))
+
+	const total_entries = scopes.reduce((n, s) =>
+		n + s.managed_views.length + s.draft_skills.length + s.external_skills.length + s.orphan_skills.length, 0)
 
-	for (const s of external_skills) {
-		rows.push([s.name, '-', 'external', 'installed', '-'])
+	if (total_entries === 0) {
+		if (args.flags.json) {
+			print_json({ data: all_scopes
+				? { skills: [], drafts: [], external: [], agent_orphans: [] }
+				: { skills: {}, drafts: [], external: [], agent_orphans: [] } })
+			return
+		}
+		print_info('No skills installed.')
+		return
 	}
 
-	for (const s of orphan_skills) {
-		const agent_label = s.agents.map(a => a.name).join(', ')
-		rows.push([s.name, '-', `agent-orphan (${agent_label})`, 'installed', '-'])
+	if (args.flags.json) {
+		if (all_scopes) {
+			// Merged, collision-safe ARRAY form: a skill installed in BOTH scopes
+			// is genuinely two installs (separate lock files, possibly different
+			// versions / enabled state) and surfaces as two entries.
+			const skills = []
+			const drafts = []
+			const external = []
+			const agent_orphans = []
+			for (const s of scopes) {
+				const tag = scope_tag(s.is_global)
+				for (const v of s.managed_views) skills.push({ name: v.name, scope: tag, native: true, ...json_managed_entry(v) })
+				for (const d of s.draft_skills) drafts.push({ name: d.name, scope: tag, native: true, description: d.description || '', version: d.version || null, type: d.type || SKILL_TYPES.SKILL })
+				for (const x of s.external_skills) external.push({ name: x.name, scope: tag, native: false, description: x.description || '' })
+				for (const o of s.orphan_skills) agent_orphans.push({ name: o.name, scope: tag, native: false, description: o.description || '', agents: o.agents })
+			}
+			print_json({ data: { skills, drafts, external, agent_orphans } })
+			return
+		}
+
+		// Single-scope (default / -g): object-keyed `skills`, unchanged contract.
+		const s = scopes[0]
+		const skills_map = {}
+		for (const v of s.managed_views) skills_map[v.name] = json_managed_entry(v)
+		const drafts = s.draft_skills.map(d => ({
+			name: d.name,
+			description: d.description || '',
+			version: d.version || null,
+			type: d.type || SKILL_TYPES.SKILL,
+		}))
+		const external = s.external_skills.map(x => ({ name: x.name, description: x.description || '' }))
+		const agent_orphan_list = s.orphan_skills.map(o => ({
+			name: o.name,
+			description: o.description || '',
+			agents: o.agents,
+		}))
+		print_json({ data: { skills: skills_map, drafts, external, agent_orphans: agent_orphan_list } })
+		return
+	}
+
+	// ── Human output ──────────────────────────────────────────────────────
+	// In --all-scopes mode each row is prefixed with Scope + Native cells
+	// (after the Skill name); push_row handles that uniformly so the per-bucket
+	// loops only describe the trailing columns.
+	const rows = []
+	const push_row = (s_label, native_cell, name_cell, tail) => {
+		rows.push(all_scopes ? [name_cell, s_label, native_cell, ...tail] : [name_cell, ...tail])
+	}
+	for (const s of scopes) {
+		const s_label = scope_label(s.is_global)
+		for (const v of s.managed_views) {
+			let status_label
+			if (v.drift) status_label = red(`drift (${v.drift.reason})`)
+			else if (v.ahead) status_label = `ahead (disk ${v.ahead.disk_version})`
+			else if (v.status === 'missing') status_label = yellow('missing')
+			else status_label = 'installed'
+			const display_name = v.type === SKILL_TYPES.KIT ? `${v.name} [kit]` : v.name
+			const enabled_label = v.enabled ? green('enabled') : yellow('disabled')
+			push_row(s_label, green('yes'), display_name, [v.version, v.source, status_label, enabled_label])
+		}
+		for (const d of s.draft_skills) {
+			const type_label = d.type === SKILL_TYPES.KIT ? `${d.name} [kit]` : d.name
+			push_row(s_label, green('yes'), type_label, [d.version || '-', 'draft', 'unpublished', '-'])
+		}
+		for (const x of s.external_skills) {
+			push_row(s_label, yellow('no'), x.name, ['-', 'external', 'installed', '-'])
+		}
+		for (const o of s.orphan_skills) {
+			const agent_label = o.agents.map(a => a.name).join(', ')
+			push_row(s_label, yellow('no'), o.name, ['-', `agent-orphan (${agent_label})`, 'installed', '-'])
+		}
 	}
 
-	print_table(['Skill', 'Version', 'Source', 'Status', 'Enabled'], rows)
+	if (all_scopes) print_table(['Skill', 'Scope', 'Native', 'Version', 'Source', 'Status', 'Enabled'], rows)
+	else print_table(['Skill', 'Version', 'Source', 'Status', 'Enabled'], rows)
 
-	const drift_count = Object.keys(drift_by_skill).length
-	const ahead_count = Object.keys(ahead_by_skill).length
+	// Aggregate the advisory tails across every gathered scope.
+	const drift_count = scopes.reduce((n, s) => n + s.managed_views.filter(v => v.drift).length, 0)
+	const ahead_count = scopes.reduce((n, s) => n + s.managed_views.filter(v => v.ahead && !v.drift).length, 0)
+	const draft_count = scopes.reduce((n, s) => n + s.draft_skills.length, 0)
 	if (drift_count > 0) {
 		console.log()
 		print_warn(`${drift_count} skill(s) drifted: lock and on-disk skill.json disagree.`)
@@ -193,37 +267,46 @@ const run = (args) => catch_errors('List failed', async () => {
 		console.log()
 		print_info(`${ahead_count} skill(s) ahead of lock — bumped locally, not yet published. Run publish when ready.`)
 	}
-	if (draft_skills.length > 0) {
+	if (draft_count > 0) {
 		console.log()
-		print_info(`${draft_skills.length} draft(s) ready to publish — run ${code('happyskills release <name>')} to ship.`)
+		print_info(`${draft_count} draft(s) ready to publish — run ${code('happyskills release <name>')} to ship.`)
 	}
 }).then(([errors]) => { if (errors) { exit_with_error(errors); return } })
 
 const schema = {
 	name:     'list',
 	audience: 'consumer',
-	purpose:  'List installed skills, showing version, source, drift/ahead status, and agent-enabled state.',
+	purpose:  'List installed skills, showing version, source, drift/ahead status, and agent-enabled state. With --all-scopes, merges project-local and global skills into one view, each tagged with its scope and whether it is a native HappySkills skill.',
 	mutation: false,
 	interactive_in_text_mode: false,
 	input: {
 		positional: [],
 		flags: [
 			{ name: 'global', alias: 'g', type: 'boolean', default: false, description: 'List globally installed skills' },
+			{ name: 'all-scopes',         type: 'boolean', default: false, description: 'List both project-local and global skills, tagged with scope (local/global) and native (true/false)' },
 			{ name: 'json',               type: 'boolean', default: false, description: 'Output as JSON' },
 		],
 	},
 	output: {
 		data_shape: {
+			// Default / -g (single scope): `skills` is an object keyed by owner/name.
 			skills:       'object<string, { version: string, type: string, source: string, status: string, enabled: boolean, drift?: object, ahead?: object }>',
 			drafts:       'array<{ name: string, description: string, version: string|null, type: string }>',
 			external:     'array<{ name: string, description: string }>',
 			agent_orphans: 'array<{ name: string, description: string, agents: string[] }>',
+			// With --all-scopes: `skills` becomes an ARRAY and every bucket entry
+			// carries `scope: "local"|"global"` and `native: boolean`.
+			// skills:       'array<{ name, scope, native: true,  version, type, source, status, enabled, drift?, ahead? }>'
+			// drafts:       'array<{ name, scope, native: true,  description, version, type }>'
+			// external:     'array<{ name, scope, native: false, description }>'
+			// agent_orphans:'array<{ name, scope, native: false, description, agents }>'
 		},
 	},
 	errors: [],
 	examples: [
 		'happyskills list',
 		'happyskills ls --json',
+		'happyskills ls --all-scopes --json',
 	],
 }