happyskills 1.12.0 → 1.13.0

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() }
+	})
+})

package/src/integration/update_scopes.test.js

@@ -0,0 +1,100 @@
+'use strict'
+/**
+ * Integration tests for `happyskills update --all-scopes`.
+ *
+ * `update` / `update -g` act on a single scope. `--all-scopes` runs the update
+ * for BOTH project-local and global skills (local first, then global) and
+ * reports a per-scope result envelope — the mission's "transparency over magic"
+ * applied to a cross-scope write: the caller can see exactly what happened in
+ * each scope, including partial failure.
+ *
+ * The global scope is isolated per-test via $HOME (os.homedir() honours it on
+ * POSIX). With no skills installed in either scope, the update short-circuits
+ * before any registry call, so these tests are deterministic and offline.
+ *
+ * Guards:
+ *   - --all-scopes returns `{ all_scopes: true, scopes: [local, global], ... }`.
+ *   - each scope entry is tagged with its `scope` and carries the per-scope payload.
+ *   - the single-scope shape is unchanged (no `all_scopes` / `scopes` keys).
+ */
+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
+}
+
+describe('update --all-scopes', () => {
+	it('returns a per-scope envelope covering both local and global', () => {
+		const project_root = make_tmp('up-proj')
+		const home_dir = make_tmp('up-home')
+		try {
+			const { code, stdout } = run(['update', '--all', '--all-scopes', '--json'], { cwd: project_root, env: { HOME: home_dir } })
+			assert.strictEqual(code, 0, 'update --all-scopes should exit 0')
+			const out = parse_json(stdout, 'update --all --all-scopes --json')
+
+			assert.strictEqual(out.data.all_scopes, true)
+			assert.ok(Array.isArray(out.data.scopes), 'data.scopes must be an array')
+			assert.strictEqual(out.data.scopes.length, 2)
+			assert.deepStrictEqual(out.data.scopes.map(s => s.scope), ['local', 'global'])
+			// Each scope carries its own per-scope payload.
+			for (const s of out.data.scopes) {
+				assert.ok(Array.isArray(s.results), `scope ${s.scope} must carry results[]`)
+				assert.strictEqual(typeof s.outdated_count, 'number')
+			}
+			// Convenience aggregates.
+			assert.strictEqual(out.data.updated_count, 0)
+			assert.strictEqual(out.data.outdated_count, 0)
+		} finally {
+			fs.rmSync(project_root, { recursive: true, force: true })
+			fs.rmSync(home_dir, { recursive: true, force: true })
+		}
+	})
+
+	it('single-scope update keeps the historical shape (no all_scopes / scopes keys)', () => {
+		const project_root = make_tmp('up-proj')
+		const home_dir = make_tmp('up-home')
+		try {
+			const { code, stdout } = run(['update', '--all', '--json'], { cwd: project_root, env: { HOME: home_dir } })
+			assert.strictEqual(code, 0)
+			const out = parse_json(stdout, 'update --all --json single')
+			assert.strictEqual(out.data.all_scopes, undefined, 'single-scope output must not carry all_scopes')
+			assert.strictEqual(out.data.scopes, undefined, 'single-scope output must not carry scopes[]')
+			assert.ok(Array.isArray(out.data.results))
+			assert.strictEqual(out.data.outdated_count, 0)
+		} finally {
+			fs.rmSync(project_root, { recursive: true, force: true })
+			fs.rmSync(home_dir, { recursive: true, force: true })
+		}
+	})
+})

package/src/ui/envelope.js

@@ -18,11 +18,23 @@ const { validate_envelope } = require('../schema/envelope_validator')
 let command_name = '<unknown>'
 let workspace   = null
 let request_id  = null
+// Cross-cutting drift verdict — set once by index.js (from the cached, fire-and-forget
+// skill-update probe) and appended as a warnings[] entry to EVERY command's envelope.
+// Same module-state pattern as command/workspace: avoids threading it through call
+// sites and is what makes the nudge fire "regardless of command". null = nothing to say.
+let skill_drift = null
 const set_command   = (name) => { command_name = name || '<unknown>' }
 const set_workspace = (slug) => { workspace = slug || null }
 const set_request_id = (id) => { request_id = id || null }
+const set_skill_drift = (verdict) => {
+	skill_drift = (verdict && Array.isArray(verdict.outdated) && verdict.outdated.length) ? verdict : null
+}
 const get_command   = () => command_name
 
+// Human-readable advisory for the SKILLS_UPDATE_AVAILABLE warning — shared with the
+// stderr nudge in index.js so the two faces of the verdict never diverge.
+const { format_skill_drift } = require('../utils/skill_update_check')
+
 const is_plain_object = (x) => x !== null && typeof x === 'object' && !Array.isArray(x)
 
 // Generic instructions per action — used to auto-fill the dependentRequired
@@ -102,6 +114,13 @@ const build_envelope = ({
 	const raw_next_step = is_plain_object(next_step) && Object.keys(next_step).length > 0 ? next_step : {}
 	const safe_next_step = enrich_next_step(raw_next_step)
 	const safe_warnings = Array.isArray(warnings) ? warnings : []
+	// Append the cross-cutting drift advisory (if any) to the command's own
+	// warnings — never touches `data` (the command's actual response), so it
+	// cannot collide with it. `code` is a free-form Warning string, not a closed
+	// enum, so this needs no constants mirror and no schema-version bump.
+	const drift_warnings = skill_drift
+		? [{ code: 'SKILLS_UPDATE_AVAILABLE', message: format_skill_drift(skill_drift) }]
+		: []
 
 	const ok = !('code' in safe_error)
 	const exit_code = ok
@@ -125,7 +144,7 @@ const build_envelope = ({
 		data:      safe_data,
 		error:     safe_error,
 		next_step: safe_next_step,
-		warnings:  safe_warnings,
+		warnings:  [...safe_warnings, ...drift_warnings],
 		meta,
 	}
 
@@ -167,6 +186,7 @@ module.exports = {
 	set_command,
 	set_workspace,
 	set_request_id,
+	set_skill_drift,
 	get_command,
 	json_active,
 	ENVELOPE_SCHEMA_VERSION,

package/src/ui/envelope.test.js

@@ -0,0 +1,63 @@
+const { test } = require('node:test')
+const assert = require('node:assert')
+
+const { build_envelope, set_skill_drift } = require('./envelope')
+
+// set_skill_drift mutates module state shared across the process, so every test
+// resets it to null on the way out to stay independent of ordering.
+const with_drift = (verdict, fn) => {
+	set_skill_drift(verdict)
+	try { fn() }
+	finally { set_skill_drift(null) }
+}
+
+test('no drift set → warnings stays exactly as the command passed it', () => {
+	with_drift(null, () => {
+		const env = build_envelope({ data: { skills: {} } })
+		assert.deepStrictEqual(env.warnings, [])
+	})
+})
+
+test('drift set → appends a SKILLS_UPDATE_AVAILABLE warning without touching data', () => {
+	const verdict = { outdated: [
+		{ skill: 'acme/x', installed: '1.0.0', latest: '1.1.0' },
+		{ skill: 'acme/y', installed: '2.0.0', latest: '2.1.0' },
+	] }
+	with_drift(verdict, () => {
+		const env = build_envelope({ data: { skills: { a: 1 } } })
+		// data (the command's real response) is untouched
+		assert.deepStrictEqual(env.data, { skills: { a: 1 } })
+		// the envelope still has exactly the six canonical keys
+		assert.deepStrictEqual(Object.keys(env).sort(), ['data', 'error', 'meta', 'next_step', 'ok', 'warnings'])
+		// the advisory rode along in warnings
+		assert.strictEqual(env.warnings.length, 1)
+		assert.strictEqual(env.warnings[0].code, 'SKILLS_UPDATE_AVAILABLE')
+		assert.match(env.warnings[0].message, /2 installed skill\(s\) behind the registry/)
+		assert.match(env.warnings[0].message, /acme\/x, acme\/y/)
+		assert.match(env.warnings[0].message, /npx happyskills update --all/)
+	})
+})
+
+test('drift advisory is appended after the command-supplied warnings', () => {
+	with_drift({ outdated: [{ skill: 'acme/x', installed: '1.0.0', latest: '1.1.0' }] }, () => {
+		const env = build_envelope({ warnings: [{ code: 'OWN_WARNING', message: 'from the command' }] })
+		assert.strictEqual(env.warnings.length, 2)
+		assert.strictEqual(env.warnings[0].code, 'OWN_WARNING')
+		assert.strictEqual(env.warnings[1].code, 'SKILLS_UPDATE_AVAILABLE')
+	})
+})
+
+test('more than three outdated skills collapse to a "+N more" summary', () => {
+	const outdated = ['a', 'b', 'c', 'd', 'e'].map(n => ({ skill: `acme/${n}`, installed: '1.0.0', latest: '1.1.0' }))
+	with_drift({ outdated }, () => {
+		const env = build_envelope({})
+		assert.match(env.warnings[0].message, /\+2 more/)
+	})
+})
+
+test('set_skill_drift ignores an empty outdated list', () => {
+	with_drift({ outdated: [] }, () => {
+		const env = build_envelope({})
+		assert.deepStrictEqual(env.warnings, [])
+	})
+})

package/src/utils/skill_update_check.js

@@ -0,0 +1,150 @@
+const os = require('os')
+const fs = require('fs')
+const path = require('path')
+
+// Passive, non-blocking drift awareness for INSTALLED skills — the registry-side
+// analogue of utils/update_check.js (which checks npm for a newer CLI). The shown
+// verdict is ALWAYS read synchronously from a 24h cache (zero latency); a stale
+// cache fires a fire-and-forget background refresh whose result is used next time.
+// The current command never waits on the network. Mirrors update_check.js: this is
+// the second sanctioned exception to the catch_errors golden rule — every failure
+// path is swallowed because a drift probe must never break the command it rode in on.
+
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000
+
+const get_cache_path = () => {
+	const base = process.env.XDG_CONFIG_HOME
+		? path.join(process.env.XDG_CONFIG_HOME, 'happyskills')
+		: path.join(os.homedir(), '.config', 'happyskills')
+	return path.join(base, 'skill-update-check.json')
+}
+
+// The cache is a map keyed by scope, because a project's installed skills differ
+// from the global set and from another project's — unlike the CLI self-check, which
+// is one-version-per-machine. Each scope entry: { outdated: [...], checked_at }.
+const scope_key = ({ is_global, project_root }) => is_global ? 'global' : `project:${project_root}`
+
+const read_cache = () => {
+	try {
+		return JSON.parse(fs.readFileSync(get_cache_path(), 'utf8'))
+	} catch {
+		return null
+	}
+}
+
+const write_scope = (key, outdated) => {
+	try {
+		const cache = read_cache() || {}
+		cache[key] = { outdated, checked_at: Date.now() }
+		const cache_path = get_cache_path()
+		fs.mkdirSync(path.dirname(cache_path), { recursive: true })
+		fs.writeFileSync(cache_path, JSON.stringify(cache), 'utf8')
+	} catch {
+		// silently ignore write errors
+	}
+}
+
+// Background refresh — NOT awaited, all errors swallowed. Reads the lock directly
+// (NOT via lock/reader.read_lock, which prints a stderr warning on version mismatch
+// — unwanted noise from a silent background task), batch-checks root skills against
+// the registry, and records ONLY the genuinely-outdated ones. It never reads the
+// working tree, so it can never mistake an `ahead` (locally-bumped, unpublished) or
+// regression-drifted skill for "outdated": a local bump leaves base_commit untouched,
+// so only a real registry advance is recorded (the §2.4 guardrail, enforced here).
+const refresh_cache = (key, opts) => {
+	;(async () => {
+		const { read_json } = require('./fs')
+		const { lock_file_path, lock_root } = require('../config/paths')
+		const repos_api = require('../api/repos')
+
+		const lock_path = lock_file_path(lock_root(opts.is_global, opts.project_root))
+		const [, lock_data] = await read_json(lock_path)
+		const skills = (lock_data && lock_data.skills) || {}
+		const candidates = Object.entries(skills)
+			.filter(([, d]) => d && Array.isArray(d.requested_by) && d.requested_by.includes('__root__'))
+
+		if (candidates.length === 0) { write_scope(key, []); return }
+
+		const [err, batch] = await repos_api.check_updates(candidates.map(([name]) => name))
+		if (err) return // leave the cache untouched; retry on the next stale invocation
+
+		const outdated = []
+		for (const [name, data] of candidates) {
+			const info = batch && batch.results && batch.results[name]
+			if (!info || info.access_denied || !info.latest_version) continue
+			const registry_advanced = data.base_commit && info.commit
+				? data.base_commit !== info.commit
+				: info.latest_version !== data.version // fallback for pre-base_commit locks
+			if (registry_advanced) outdated.push({ skill: name, installed: data.version, latest: info.latest_version })
+		}
+		write_scope(key, outdated)
+	})().catch(() => {})
+}
+
+// Synchronous — reads the cache and returns the verdict immediately, then fires a
+// background refresh for any stale scope. ALWAYS checks BOTH the project-local and the
+// global lock, because a globally-installed constellation is "always there" and should
+// be nudged about even during project-scoped work (and vice versa). The shown verdict
+// is the merged, name-deduped set of outdated skills across both scopes; `has_local` /
+// `has_global` record which scopes contributed, so the message can point at the right
+// command (`update --all` vs `update --all -g`). Returns null when nothing is outdated.
+const check_skills_for_update = (opts) => {
+	if (process.env.HAPPYSKILLS_NO_SKILL_UPDATE_CHECK === '1') return null
+	// Integration tests spawn the CLI against http://localhost:0; never probe there
+	// (and never let a developer's real cache leak into an envelope-shape assertion).
+	const api = process.env.HAPPYSKILLS_API_URL || ''
+	if (api.includes('localhost:0') || api.includes('127.0.0.1:0')) return null
+
+	const project_root = opts.project_root
+	const cache = read_cache() || {}
+	const scopes = [
+		{ is_global: false, project_root },
+		{ is_global: true, project_root },
+	]
+
+	// Tag each outdated item with the scope it came from BEFORE deduping, so
+	// has_local / has_global stay accurate even for a skill outdated in both.
+	const raw = []
+	for (const s of scopes) {
+		const key = scope_key(s)
+		const entry = cache[key]
+		const is_stale = !entry || !entry.checked_at || (Date.now() - entry.checked_at > CACHE_TTL_MS)
+		if (is_stale) refresh_cache(key, s)
+		if (entry && Array.isArray(entry.outdated)) {
+			const label = s.is_global ? 'global' : 'local'
+			for (const item of entry.outdated) raw.push({ ...item, scope: label })
+		}
+	}
+
+	const has_local = raw.some(i => i.scope === 'local')
+	const has_global = raw.some(i => i.scope === 'global')
+
+	// Dedupe by skill name for the display list / count (a skill installed in both
+	// scopes is one concern); has_local/has_global above already captured both.
+	const seen = new Set()
+	const outdated = []
+	for (const item of raw) {
+		if (seen.has(item.skill)) continue
+		seen.add(item.skill)
+		outdated.push(item)
+	}
+
+	return outdated.length ? { outdated, has_local, has_global } : null
+}
+
+// Shared human-readable advisory — used by BOTH the stderr nudge (index.js, text mode)
+// and the SKILLS_UPDATE_AVAILABLE envelope warning (ui/envelope.js, JSON mode), so the
+// two faces never drift. The command hint is scope-aware: `-g` is added only when the
+// outdated set actually includes globally-installed skills.
+const format_skill_drift = (verdict) => {
+	const items = verdict.outdated
+	const names = items.slice(0, 3).map(s => s.skill).join(', ')
+	const more = items.length > 3 ? `, +${items.length - 3} more` : ''
+	let cmd
+	if (verdict.has_global && verdict.has_local) cmd = 'npx happyskills update --all (and add -g for the global ones)'
+	else if (verdict.has_global) cmd = 'npx happyskills update --all -g'
+	else cmd = 'npx happyskills update --all'
+	return `${items.length} installed skill(s) behind the registry (${names}${more}). Run: ${cmd}`
+}
+
+module.exports = { check_skills_for_update, format_skill_drift, get_cache_path, scope_key }

package/src/utils/skill_update_check.test.js

@@ -0,0 +1,118 @@
+const { test } = require('node:test')
+const assert = require('node:assert')
+const fs = require('fs')
+const os = require('os')
+const path = require('path')
+
+const { check_skills_for_update, format_skill_drift, get_cache_path, scope_key } = require('./skill_update_check')
+
+const PROJECT_ROOT = '/proj'
+const PKEY = scope_key({ is_global: false, project_root: PROJECT_ROOT })
+const GKEY = scope_key({ is_global: true, project_root: PROJECT_ROOT })
+
+// Isolate the cache into a temp XDG dir, run fn, restore env. Also neutralises the
+// two short-circuit guards (env opt-out + localhost sentinel) so the cache path runs.
+const with_tmp = (fn) => {
+	const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'hs-skilldrift-'))
+	const saved = {
+		xdg: process.env.XDG_CONFIG_HOME,
+		api: process.env.HAPPYSKILLS_API_URL,
+		off: process.env.HAPPYSKILLS_NO_SKILL_UPDATE_CHECK,
+	}
+	process.env.XDG_CONFIG_HOME = dir
+	process.env.HAPPYSKILLS_API_URL = 'https://api.example.test'
+	delete process.env.HAPPYSKILLS_NO_SKILL_UPDATE_CHECK
+	try { fn(dir) }
+	finally {
+		const restore = (k, v) => { if (v === undefined) delete process.env[k]; else process.env[k] = v }
+		restore('XDG_CONFIG_HOME', saved.xdg)
+		restore('HAPPYSKILLS_API_URL', saved.api)
+		restore('HAPPYSKILLS_NO_SKILL_UPDATE_CHECK', saved.off)
+		fs.rmSync(dir, { recursive: true, force: true })
+	}
+}
+
+// Seed BOTH scopes FRESH (checked_at = now) so the sync read returns them without
+// firing any background network refresh. Pass the outdated arrays per scope.
+const seed = ({ local = [], global = [] }) => {
+	const p = get_cache_path()
+	fs.mkdirSync(path.dirname(p), { recursive: true })
+	fs.writeFileSync(p, JSON.stringify({
+		[PKEY]: { outdated: local, checked_at: Date.now() },
+		[GKEY]: { outdated: global, checked_at: Date.now() },
+	}), 'utf8')
+}
+
+const item = (skill) => ({ skill, installed: '1.0.0', latest: '1.1.0' })
+
+test('project-only drift → verdict flagged local, no -g in the message', () => {
+	with_tmp(() => {
+		seed({ local: [item('acme/x')], global: [] })
+		const v = check_skills_for_update({ project_root: PROJECT_ROOT })
+		assert.ok(v)
+		assert.strictEqual(v.outdated.length, 1)
+		assert.strictEqual(v.has_local, true)
+		assert.strictEqual(v.has_global, false)
+		assert.match(format_skill_drift(v), /update --all$/)
+	})
+})
+
+test('global-only drift → verdict flagged global, message uses -g', () => {
+	with_tmp(() => {
+		seed({ local: [], global: [item('happyskillsai/happyskills')] })
+		const v = check_skills_for_update({ project_root: PROJECT_ROOT })
+		assert.ok(v)
+		assert.strictEqual(v.has_local, false)
+		assert.strictEqual(v.has_global, true)
+		assert.match(format_skill_drift(v), /update --all -g$/)
+	})
+})
+
+test('drift in BOTH scopes → merged, both flags set, message mentions -g for global', () => {
+	with_tmp(() => {
+		seed({ local: [item('acme/x')], global: [item('happyskillsai/happyskills')] })
+		const v = check_skills_for_update({ project_root: PROJECT_ROOT })
+		assert.strictEqual(v.outdated.length, 2)
+		assert.strictEqual(v.has_local, true)
+		assert.strictEqual(v.has_global, true)
+		assert.match(format_skill_drift(v), /add -g for the global ones/)
+	})
+})
+
+test('a skill outdated in both scopes is name-deduped but both flags stay accurate', () => {
+	with_tmp(() => {
+		seed({ local: [item('acme/x')], global: [item('acme/x')] })
+		const v = check_skills_for_update({ project_root: PROJECT_ROOT })
+		assert.strictEqual(v.outdated.length, 1)        // counted once
+		assert.strictEqual(v.has_local, true)
+		assert.strictEqual(v.has_global, true)          // ...but both scopes still acknowledged
+	})
+})
+
+test('nothing outdated in either scope → null', () => {
+	with_tmp(() => {
+		seed({ local: [], global: [] })
+		assert.strictEqual(check_skills_for_update({ project_root: PROJECT_ROOT }), null)
+	})
+})
+
+test('format collapses more than three skills to a "+N more" summary', () => {
+	const outdated = ['a', 'b', 'c', 'd', 'e'].map(n => ({ ...item(`acme/${n}`), scope: 'local' }))
+	assert.match(format_skill_drift({ outdated, has_local: true, has_global: false }), /\+2 more/)
+})
+
+test('env opt-out short-circuits to null', () => {
+	with_tmp(() => {
+		seed({ local: [item('acme/x')], global: [] })
+		process.env.HAPPYSKILLS_NO_SKILL_UPDATE_CHECK = '1'
+		assert.strictEqual(check_skills_for_update({ project_root: PROJECT_ROOT }), null)
+	})
+})
+
+test('localhost:0 test API sentinel short-circuits to null', () => {
+	with_tmp(() => {
+		seed({ local: [item('acme/x')], global: [] })
+		process.env.HAPPYSKILLS_API_URL = 'http://localhost:0'
+		assert.strictEqual(check_skills_for_update({ project_root: PROJECT_ROOT }), null)
+	})
+})