happyskills 1.12.1 → 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/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)
 

package/src/integration/list_scopes.test.js

@@ -0,0 +1,171 @@
+'use strict'
+/**
+ * Integration tests for `happyskills list --all-scopes`.
+ *
+ * `list` and `list -g` each show ONE scope (project or global). `--all-scopes`
+ * merges both into a single view, tagging every entry with:
+ *   - `scope`  → "local" (project) | "global" (~/.agents)
+ *   - `native` → true for HappySkills-managed/draft skills, false for
+ *                manually-added foreign skills (external / agent-orphan)
+ *
+ * The global scope is isolated per-test by pointing $HOME at a temp dir — Node's
+ * os.homedir() honours $HOME on POSIX, and paths.js derives ~/.agents from it.
+ *
+ * Guards:
+ *   - --all-scopes returns `data.skills` as an ARRAY carrying both scopes.
+ *   - every entry carries the right `scope` + `native` flags.
+ *   - foreign (no skill.json) skills land in `external` with native:false.
+ *   - the default (single-scope) shape is unchanged: `data.skills` is an OBJECT
+ *     and a global-only skill does NOT leak into the project listing.
+ */
+const { describe, it } = require('node:test')
+const assert = require('node:assert/strict')
+const { spawnSync } = require('child_process')
+const fs = require('fs')
+const os = require('os')
+const path = require('path')
+const { parse_envelope, assert_success_envelope } = require('../schema/envelope_test_helpers')
+
+const CLI = path.resolve(__dirname, '../../bin/happyskills.js')
+const NODE = process.execPath
+
+const make_tmp = (tag) => fs.mkdtempSync(path.join(os.tmpdir(), `happyskills-${tag}-`))
+
+const run = (args, opts) => {
+	const has_mode_flag = args.includes('--json') || args.includes('--text')
+	const final_args = has_mode_flag ? args : [...args, '--text']
+	const result = spawnSync(NODE, [CLI, ...final_args], {
+		env: {
+			...process.env,
+			NO_COLOR: '1', HAPPYSKILLS_ENVELOPE_STRICT: '1',
+			HAPPYSKILLS_API_URL: 'http://localhost:0',
+			CI: '',
+			...(opts?.env || {}),
+		},
+		encoding: 'utf-8',
+		timeout: 10000,
+		cwd: opts?.cwd,
+	})
+	return { stdout: result.stdout || '', stderr: result.stderr || '', code: result.status }
+}
+
+const parse_json = (stdout, label) => {
+	const env = parse_envelope(stdout, label)
+	assert_success_envelope(env, label)
+	return env
+}
+
+// Write a HappySkills-shaped (native) skill onto disk under <skills_base>/<short>.
+const write_native_skill = (skills_base, short, version) => {
+	const dir = path.join(skills_base, short)
+	fs.mkdirSync(dir, { recursive: true })
+	fs.writeFileSync(path.join(dir, 'SKILL.md'), `---\nname: ${short}\ndescription: test skill\n---\nBody\n`)
+	fs.writeFileSync(path.join(dir, 'skill.json'), JSON.stringify({ name: short, version, type: 'skill', description: 'test skill' }, null, '\t'))
+}
+
+// Write a foreign skill (SKILL.md, NO skill.json) → classified external/native:false.
+const write_foreign_skill = (skills_base, short) => {
+	const dir = path.join(skills_base, short)
+	fs.mkdirSync(dir, { recursive: true })
+	fs.writeFileSync(path.join(dir, 'SKILL.md'), `---\nname: ${short}\ndescription: foreign skill\n---\nBody\n`)
+}
+
+const write_lock = (lock_path, entries) => {
+	const skills = {}
+	for (const [full, version] of entries) {
+		skills[full] = {
+			version, type: 'skill', ref: `refs/tags/v${version}`, commit: 'c',
+			integrity: null, base_commit: 'c', base_integrity: null,
+			requested_by: ['__root__'], dependencies: {},
+		}
+	}
+	fs.writeFileSync(lock_path, JSON.stringify({ lockVersion: 2, generatedAt: new Date().toISOString(), skills }, null, '\t'))
+}
+
+// Scaffold both scopes: a project root (cwd) and an isolated home ($HOME).
+const scaffold = () => {
+	const project_root = make_tmp('list-proj')
+	const home_dir = make_tmp('list-home')
+
+	// Project scope: one managed native skill + one foreign skill.
+	const proj_skills = path.join(project_root, '.agents', 'skills')
+	write_native_skill(proj_skills, 'local-skill', '1.0.0')
+	write_foreign_skill(proj_skills, 'foreign-local')
+	write_lock(path.join(project_root, 'skills-lock.json'), [['acme/local-skill', '1.0.0']])
+
+	// Global scope: one managed native skill (lock lives at ~/.agents/skills-lock.json).
+	const global_skills = path.join(home_dir, '.agents', 'skills')
+	write_native_skill(global_skills, 'global-skill', '2.1.0')
+	write_lock(path.join(home_dir, '.agents', 'skills-lock.json'), [['acme/global-skill', '2.1.0']])
+
+	return {
+		project_root,
+		home_dir,
+		cleanup: () => {
+			fs.rmSync(project_root, { recursive: true, force: true })
+			fs.rmSync(home_dir, { recursive: true, force: true })
+		},
+	}
+}
+
+describe('list --all-scopes', () => {
+	it('merges project + global skills into an array, each tagged with scope + native', () => {
+		const { project_root, home_dir, cleanup } = scaffold()
+		try {
+			const { code, stdout } = run(['list', '--all-scopes', '--json'], { cwd: project_root, env: { HOME: home_dir } })
+			assert.strictEqual(code, 0, 'list --all-scopes should exit 0')
+			const out = parse_json(stdout, 'list --all-scopes --json')
+
+			assert.ok(Array.isArray(out.data.skills), 'data.skills must be an ARRAY in --all-scopes mode')
+
+			const local = out.data.skills.find(s => s.name === 'acme/local-skill')
+			assert.ok(local, 'project-local managed skill must be present')
+			assert.strictEqual(local.scope, 'local')
+			assert.strictEqual(local.native, true)
+			assert.strictEqual(local.version, '1.0.0')
+
+			const global = out.data.skills.find(s => s.name === 'acme/global-skill')
+			assert.ok(global, 'global managed skill must be present in the SAME view')
+			assert.strictEqual(global.scope, 'global')
+			assert.strictEqual(global.native, true)
+			assert.strictEqual(global.version, '2.1.0')
+		} finally { cleanup() }
+	})
+
+	it('classifies a foreign (no skill.json) skill as external + native:false, scoped local', () => {
+		const { project_root, home_dir, cleanup } = scaffold()
+		try {
+			const { stdout } = run(['list', '--all-scopes', '--json'], { cwd: project_root, env: { HOME: home_dir } })
+			const out = parse_json(stdout, 'list --all-scopes --json external')
+			assert.ok(Array.isArray(out.data.external))
+			const foreign = out.data.external.find(s => s.name === 'foreign-local')
+			assert.ok(foreign, 'foreign skill must appear under data.external')
+			assert.strictEqual(foreign.scope, 'local')
+			assert.strictEqual(foreign.native, false)
+		} finally { cleanup() }
+	})
+
+	it('default (single-scope) list keeps the object shape and does NOT leak global skills', () => {
+		const { project_root, home_dir, cleanup } = scaffold()
+		try {
+			const { stdout } = run(['list', '--json'], { cwd: project_root, env: { HOME: home_dir } })
+			const out = parse_json(stdout, 'list --json default')
+			assert.ok(!Array.isArray(out.data.skills) && typeof out.data.skills === 'object', 'default data.skills must remain an OBJECT')
+			assert.ok(out.data.skills['acme/local-skill'], 'project skill present')
+			assert.ok(!out.data.skills['acme/global-skill'], 'global skill must NOT appear in the project-scoped listing')
+			// Backward-compat: no scope/native fields injected in single-scope mode.
+			assert.strictEqual(out.data.skills['acme/local-skill'].scope, undefined)
+			assert.strictEqual(out.data.skills['acme/local-skill'].native, undefined)
+		} finally { cleanup() }
+	})
+
+	it('list -g shows only the global scope (object shape)', () => {
+		const { project_root, home_dir, cleanup } = scaffold()
+		try {
+			const { stdout } = run(['list', '-g', '--json'], { cwd: project_root, env: { HOME: home_dir } })
+			const out = parse_json(stdout, 'list -g --json')
+			assert.ok(out.data.skills['acme/global-skill'], 'global skill present under -g')
+			assert.ok(!out.data.skills['acme/local-skill'], 'project skill must NOT appear under -g')
+		} finally { cleanup() }
+	})
+})