happyskills 1.2.1 → 1.3.0

package/CHANGELOG.md

@@ -7,6 +7,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [1.3.0] - 2026-06-03
+
+### Added
+
+- `login` now returns the full identity payload — `username`, `email`, and `workspaces` — on every success path (`logged_in` and `already_logged_in`), so an agent no longer needs a follow-up `whoami` call after authenticating. Both commands build the block from one shared assembler, so their shapes stay identical. The workspace lookup is best-effort: a failed `GET /workspaces` degrades to an empty list plus `workspace_error` and never fails the login.
+- Detect circular dependencies in the dependency graph. `validate` and `publish` run a `dep-circular` rule that resolves each dependency's published subtree, grafts the local skill's own edges, and DFS-searches for cycles — so it also catches a cycle created by the edge being published. A detected cycle is a hard error that blocks publish. Registry-scoped checks run only when authenticated.
+
+### Changed
+
+- Text-mode `login` now short-circuits when a valid session already exists — it prints the identity block instead of launching a fresh auth flow, mirroring the `--json` path. Run `happyskills logout` to force a fresh login.
+- `install` is now loop-safe: a cycle among already-published skills never causes infinite recursion. Every skill in the tree is still installed, and the CLI prints a circular-dependency warning (also surfaced in `--json` under `warnings`).
+
+## [1.2.2] - 2026-06-02
+
+### Changed
+
+- `validate` no longer warns when `skill.json` `keywords` is missing or omits a canonical slug. The `keywords` field is deprecated — it is not used for search, ranking, or discovery — so the warning and the canonical-slug check were removed. The field is still accepted in the manifest.
+
 ## [1.2.1] - 2026-06-02
 
 ### Fixed

package/package.json

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

package/src/auth/identity.js

@@ -0,0 +1,58 @@
+const { error: { catch_errors } } = require('puffy-core')
+const workspaces_api = require('../api/workspaces')
+const { print_label, print_warn, print_hint } = require('../ui/output')
+
+// Decode a JWT payload for display only — no signature verification. Returns
+// null on any malformed input.
+const decode_jwt_payload = (token) => {
+	try {
+		const parts = (token || '').split('.')
+		if (parts.length !== 3) return null
+		const payload = Buffer.from(parts[1], 'base64url').toString('utf-8')
+		return JSON.parse(payload)
+	} catch {
+		return null
+	}
+}
+
+// Assemble the canonical identity payload shared by `whoami` and `login`, so
+// the two commands can never disagree on shape or content. Identity fields
+// (username/email) come straight off the in-hand id_token; workspaces are
+// fetched best-effort — a failed lookup degrades to an empty list plus a
+// `workspace_error` string and NEVER fails the caller. A network hiccup must
+// not turn a valid session into an error: the user is logged in regardless.
+const resolve_identity = (token_data) => catch_errors('Resolve identity failed', async () => {
+	const payload = decode_jwt_payload(token_data?.id_token)
+	const email = payload?.email || 'unknown'
+	const username = payload?.['cognito:username'] || payload?.sub || 'unknown'
+
+	const [ws_err, workspaces] = await workspaces_api.list_workspaces()
+	const identity = { username, email, workspaces: ws_err ? [] : (workspaces || []) }
+	if (ws_err) identity.workspace_error = ws_err.map(er => er.message).join(': ')
+	return identity
+})
+
+// Render an identity payload to the human (text-mode) surface. Both `whoami`
+// and `login` use this so the warm output stays content-equal with `--json`:
+// the format differs, the information does not.
+const render_identity_text = (identity) => {
+	print_label('Username', identity.username)
+	print_label('Email', identity.email)
+
+	if (identity.workspace_error) {
+		console.log()
+		print_warn(`Failed to list workspaces: ${identity.workspace_error}`)
+		print_hint('Check your authentication with happyskills login')
+	} else if (identity.workspaces && identity.workspaces.length > 0) {
+		console.log()
+		print_label('Workspaces', '')
+		for (const ws of identity.workspaces) {
+			const type_label = ws.is_owner
+				? ws.type === 'personal' ? ' (personal)' : ' (organization)'
+				: ''
+			console.log(`  ${ws.slug}${type_label}`)
+		}
+	}
+}
+
+module.exports = { decode_jwt_payload, resolve_identity, render_identity_text }

package/src/commands/login.js

@@ -4,8 +4,9 @@ const readline = require('readline')
 const { error: { catch_errors, wrap_errors: e } } = require('puffy-core')
 const auth_api = require('../api/auth')
 const { save_token, load_token } = require('../auth/token_store')
+const { resolve_identity, render_identity_text } = require('../auth/identity')
 const { create_spinner } = require('../ui/spinner')
-const { print_help, print_success, print_info, print_hint, print_json, code } = require('../ui/output')
+const { print_help, print_success, print_info, print_json } = require('../ui/output')
 const { exit_with_error } = require('../utils/errors')
 const { EXIT_CODES, CLI_VERSION } = require('../constants')
 const { run_browser_flow } = require('./login_device')
@@ -136,17 +137,6 @@ const run_password_flow = () => catch_errors('Password login failed', async () =
 	await handle_post_login_telemetry()
 })
 
-const decode_jwt_payload = (token) => {
-	try {
-		const parts = token.split('.')
-		if (parts.length !== 3) return null
-		const payload = Buffer.from(parts[1], 'base64url').toString('utf-8')
-		return JSON.parse(payload)
-	} catch {
-		return null
-	}
-}
-
 const run = (args) => catch_errors('Login failed', async () => {
 	if (args.flags._show_help) {
 		print_help(HELP_TEXT)
@@ -156,10 +146,8 @@ const run = (args) => catch_errors('Login failed', async () => {
 	if (args.flags.json) {
 		const [, token_data] = await load_token()
 		if (token_data) {
-			const payload = decode_jwt_payload(token_data.id_token)
-			const email = payload?.email || 'unknown'
-			const username = payload?.['cognito:username'] || payload?.sub || 'unknown'
-			print_json({ data: { status: 'already_logged_in', username, email } })
+			const [, identity] = await resolve_identity(token_data)
+			print_json({ data: { status: 'already_logged_in', ...identity } })
 			return
 		}
 
@@ -181,10 +169,8 @@ const run = (args) => catch_errors('Login failed', async () => {
 		// Browser flow succeeded — read saved token
 		const [, new_token] = await load_token()
 		if (new_token) {
-			const payload = decode_jwt_payload(new_token.id_token)
-			const email = payload?.email || 'unknown'
-			const username = payload?.['cognito:username'] || payload?.sub || 'unknown'
-			print_json({ data: { status: 'logged_in', username, email } })
+			const [, identity] = await resolve_identity(new_token)
+			print_json({ data: { status: 'logged_in', ...identity } })
 		} else {
 			print_json({ error: { code: 'AUTH_FAILED', message: 'Login flow completed but token could not be loaded', exit_code: EXIT_CODES.ERROR } })
 			process.exit(EXIT_CODES.ERROR)
@@ -192,6 +178,20 @@ const run = (args) => catch_errors('Login failed', async () => {
 		return
 	}
 
+	// Text mode short-circuits on an existing session, mirroring the --json
+	// path (which returns `already_logged_in` before consulting any flow flag).
+	// "Already logged in" must mean the same thing in text as in JSON — same
+	// information, different encoding. To force a fresh login, run `logout`
+	// first. The workspace lookup stays best-effort and never fails the check.
+	const [, existing_token] = await load_token()
+	if (existing_token) {
+		const [, identity] = await resolve_identity(existing_token)
+		print_info('You are already logged in.')
+		console.log()
+		render_identity_text(identity)
+		return
+	}
+
 	let use_password = args.flags.password === true
 	let use_browser = args.flags.browser === true
 
@@ -214,8 +214,16 @@ const run = (args) => catch_errors('Login failed', async () => {
 		await handle_post_login_telemetry()
 	}
 
-	console.log()
-	print_hint(`Verify your identity: ${code('happyskills whoami')}`)
+	// Show the same identity block `whoami` shows, so login fully answers
+	// "who am I" on the human surface too — no redundant follow-up call. This
+	// keeps text mode content-equal with `--json` (same information, different
+	// encoding). Best-effort: a workspace lookup failure never fails the login.
+	const [, token_data] = await load_token()
+	if (token_data) {
+		const [, identity] = await resolve_identity(token_data)
+		console.log()
+		render_identity_text(identity)
+	}
 }).then(([errors]) => { if (errors) { exit_with_error(errors); return } })
 
 const schema = {
@@ -234,9 +242,10 @@ const schema = {
 	},
 	output: {
 		data_shape: {
-			status:   'string',
-			username: 'string',
-			email:    'string',
+			status:     'string',
+			username:   'string',
+			email:      'string',
+			workspaces: 'array',
 		},
 	},
 	errors: [

package/src/commands/whoami.js

@@ -1,7 +1,7 @@
-const { error: { catch_errors, wrap_errors: e } } = require('puffy-core')
+const { error: { catch_errors } } = require('puffy-core')
 const { require_token } = require('../auth/token_store')
-const workspaces_api = require('../api/workspaces')
-const { print_help, print_label, print_json, print_warn, print_hint } = require('../ui/output')
+const { resolve_identity, render_identity_text } = require('../auth/identity')
+const { print_help, print_json } = require('../ui/output')
 const { exit_with_error } = require('../utils/errors')
 const { EXIT_CODES } = require('../constants')
 
@@ -16,17 +16,6 @@ Examples:
   happyskills whoami
   happyskills whoami --json`
 
-const decode_jwt_payload = (token) => {
-	try {
-		const parts = token.split('.')
-		if (parts.length !== 3) return null
-		const payload = Buffer.from(parts[1], 'base64url').toString('utf-8')
-		return JSON.parse(payload)
-	} catch {
-		return null
-	}
-}
-
 const run = (args) => catch_errors('Whoami failed', async () => {
 	if (args.flags._show_help) {
 		print_help(HELP_TEXT)
@@ -34,37 +23,14 @@ const run = (args) => catch_errors('Whoami failed', async () => {
 	}
 
 	const token_data = await require_token()
-
-	const payload = decode_jwt_payload(token_data.id_token)
-	const email = payload?.email || 'unknown'
-	const username = payload?.['cognito:username'] || payload?.sub || 'unknown'
-
-	const [ws_err, workspaces] = await workspaces_api.list_workspaces()
+	const [, identity] = await resolve_identity(token_data)
 
 	if (args.flags.json) {
-		const json_data = { username, email, workspaces: ws_err ? [] : workspaces }
-		if (ws_err) json_data.workspace_error = ws_err.map(er => er.message).join(': ')
-		print_json({ data: json_data })
+		print_json({ data: identity })
 		return
 	}
 
-	print_label('Username', username)
-	print_label('Email', email)
-
-	if (ws_err) {
-		console.log()
-		print_warn(`Failed to list workspaces: ${ws_err.map(er => er.message).join(': ')}`)
-		print_hint('Check your authentication with happyskills login')
-	} else if (workspaces && workspaces.length > 0) {
-		console.log()
-		print_label('Workspaces', '')
-		for (const ws of workspaces) {
-			const type_label = ws.is_owner
-				? ws.type === 'personal' ? ' (personal)' : ' (organization)'
-				: ''
-			console.log(`  ${ws.slug}${type_label}`)
-		}
-	}
+	render_identity_text(identity)
 }).then(([errors]) => { if (errors) { exit_with_error(errors); return } })
 
 const schema = {

package/src/engine/installer.js

@@ -22,6 +22,13 @@ const _format_warnings = (missing_deps) => (missing_deps || []).map(dep => {
 	return `Missing system dependency: ${dep.name} required by ${dep.skill}${hint}`
 })
 
+// Circular dependencies the resolver broke automatically. The install is safe and terminates,
+// but the author should remove one edge — so we surface a warning rather than failing silently.
+const _format_cycle_warnings = (cycles) => (cycles || []).map(({ from, to }) =>
+	`Circular dependency detected: ${from} depends on ${to}, which depends back on ${from}. ` +
+	`The install completed safely (the cycle was broken automatically), but you should remove one ` +
+	`direction of the dependency.`)
+
 // Order-preserving, de-duplicated union of requester lists.
 const _union = (...lists) => {
 	const seen = new Set()
@@ -103,16 +110,19 @@ const install = (skill, options = {}) => catch_errors('Install failed', async ()
 
 	let packages
 	let skipped_deps = []
+	let cycles = []
 	if (force) {
 		const [errors, result] = await resolve_with_force(skill, version || 'latest', {})
 		if (errors) { spinner.fail('Resolution failed'); throw e('Resolution failed', errors) }
 		packages = result.packages
 		skipped_deps = result.skipped || []
+		cycles = result.cycles || []
 	} else {
 		const [errors, result] = await resolve(skill, version || 'latest', {})
 		if (errors) { spinner.fail('Resolution failed'); throw e('Resolution failed', errors) }
 		packages = result.packages
 		skipped_deps = result.skipped || []
+		cycles = result.cycles || []
 	}
 
 	// Filter out packages already installed at the resolved version (handles @latest efficiently)
@@ -343,10 +353,15 @@ const install = (skill, options = {}) => catch_errors('Install failed', async ()
 			}
 		}
 
+		// Warn about circular dependencies. The resolver broke the cycle automatically (so the
+		// install is safe and terminates), but the author should still remove one edge.
+		const cycle_warnings = _format_cycle_warnings(cycles)
+		for (const w of cycle_warnings) print_warn(w)
+
 		const installed_set = new Set(packages_to_install.map(p => p.skill))
 		const installed = packages_to_install.map(p => ({ skill: p.skill, version: p.version }))
 		const skipped = packages.filter(p => !installed_set.has(p.skill)).map(p => ({ skill: p.skill, version: p.version, reason: 'already installed' }))
-		const warnings = _format_warnings(missing_deps)
+		const warnings = [..._format_warnings(missing_deps), ...cycle_warnings]
 		const forced = forced_pkgs.map(p => ({ skill: p.skill, version: p.version }))
 
 		const linked_agents = agents.map(a => a.id)

package/src/engine/resolver.js

@@ -12,7 +12,7 @@ const resolve = (skill, version, installed = {}) => catch_errors('Dependency res
 		throw new Error(`Dependency conflicts detected:\n${conflict_msg}\n\nUse --force to install anyway (takes highest version).`)
 	}
 
-	return { packages: result.packages || [], skipped: result.skipped || [] }
+	return { packages: result.packages || [], skipped: result.skipped || [], cycles: result.cycles || [] }
 })
 
 const resolve_with_force = (skill, version, installed = {}) => catch_errors('Forced resolution failed', async () => {
@@ -30,7 +30,7 @@ const resolve_with_force = (skill, version, installed = {}) => catch_errors('For
 		}
 	}
 
-	return { packages, skipped: result.skipped || [] }
+	return { packages, skipped: result.skipped || [], cycles: result.cycles || [] }
 })
 
 module.exports = { resolve, resolve_with_force }

package/src/integration/cli.test.js

@@ -403,6 +403,10 @@ describe('CLI — --json: success envelopes', () => {
 			assert.strictEqual(env.data.status, 'already_logged_in')
 			assert.strictEqual(env.data.username, 'testuser')
 			assert.strictEqual(env.data.email, 'test@example.com')
+			// Content parity with whoami: login carries the workspaces block too.
+			// The dummy API host (localhost:0) is unreachable, so the best-effort
+			// lookup degrades to an empty list — it must never fail the login.
+			assert.ok(Array.isArray(env.data.workspaces), 'login data.workspaces must be an array')
 		} finally {
 			fs.rmSync(tmp_xdg, { recursive: true, force: true })
 		}

package/src/validation/dependency_rules.js

@@ -172,27 +172,40 @@ const check_visibility_transitive = async (manifest, visibility, repos_api) => {
 const check_circular = async (manifest, repos_api) => {
 	const results = []
 	const deps = manifest.dependencies || {}
+	const dep_names = Object.keys(deps)
 
-	if (Object.keys(deps).length === 0) return results
+	if (dep_names.length === 0) return results
 
 	const skill_name = manifest._full_name
 	if (!skill_name) return results
 
-	const [err, data] = await repos_api.resolve_dependencies(skill_name, manifest.version || 'latest', {})
-	if (err) return results
-
-	const packages = data.packages || []
-
-	// Build adjacency map from declared dependencies
+	// Resolve each DIRECT dependency's published subtree — NOT the root's. The root's published
+	// manifest can be stale: when you publish the very edge that closes a cycle, the registry's
+	// view of the root does not yet contain that edge, so resolving the root would hide the
+	// cycle. Resolving the dependencies' subtrees and then grafting the LOCAL (about-to-be-
+	// published) root edges on top reflects the graph as it will be AFTER this publish — which
+	// is exactly what we must validate.
+	const subtrees = await Promise.all(
+		dep_names.map(dep => repos_api.resolve_dependencies(dep, 'latest', {}))
+	)
+
+	// Merge every resolved package into one adjacency map (the registry's current view).
 	const adj = {}
-	for (const pkg of packages) {
-		adj[pkg.skill] = Object.keys(pkg.dependencies || {})
+	for (const [sub_err, data] of subtrees) {
+		if (sub_err || !data) continue
+		for (const pkg of (data.packages || [])) {
+			if (adj[pkg.skill] === undefined) adj[pkg.skill] = Object.keys(pkg.dependencies || {})
+		}
 	}
 
-	// DFS cycle detection
+	// Graft the LOCAL edges for the root. This overrides any stale published view of the root
+	// that a dependency's subtree may have included, making a cycle the new edges create visible.
+	adj[skill_name] = dep_names
+
+	// DFS cycle detection (WHITE/GRAY/BLACK colouring). Start from the root so reported cycles
+	// are rooted at the skill being published; then cover any unreachable nodes defensively.
 	const WHITE = 0, GRAY = 1, BLACK = 2
 	const color = {}
-	const parent = {}
 	const cycles = []
 
 	const dfs = (node, path_so_far) => {
@@ -213,16 +226,20 @@ const check_circular = async (manifest, repos_api) => {
 		color[node] = BLACK
 	}
 
+	dfs(skill_name, [skill_name])
 	for (const node of Object.keys(adj)) {
-		if ((color[node] || WHITE) === WHITE) {
-			dfs(node, [node])
-		}
+		if ((color[node] || WHITE) === WHITE) dfs(node, [node])
 	}
 
 	if (cycles.length > 0) {
+		// De-duplicate identical cycle paths (the same cycle can be reached from multiple starts).
+		const seen = new Set()
 		for (const cycle of cycles) {
+			const key = cycle.join(' → ')
+			if (seen.has(key)) continue
+			seen.add(key)
 			results.push(result('dependencies', 'dep-circular', 'error',
-				`Circular dependency detected: ${cycle.join(' → ')}. ` +
+				`Circular dependency detected: ${key}. ` +
 				`Remove one direction of the dependency to break the cycle.`,
 				cycle))
 		}

package/src/validation/dependency_rules.test.js

@@ -158,6 +158,30 @@ describe('dep-circular (registry)', () => {
 		const check = results.find(r => r.rule === 'dep-circular')
 		assert.strictEqual(check.severity, 'pass')
 	})
+
+	it('detects a cycle created by the very edge being published (stale root view)', async () => {
+		// Registry view: the dependency (acme/b) depends back on the root (acme/a), but the
+		// root's PUBLISHED manifest still has empty deps — the cycle-closing edge (acme/a → acme/b)
+		// exists only in the LOCAL manifest being validated. The check must graft the local edge
+		// onto the resolved subtree, otherwise this cycle slips into the registry undetected.
+		const manifest = { name: 'a', version: '0.2.0', dependencies: { 'acme/b': '*' } }
+		const resolve_result = {
+			packages: [
+				{ skill: 'acme/b', version: '1.0.0', dependencies: { 'acme/a': '*' } },
+				{ skill: 'acme/a', version: '1.0.0', dependencies: {} } // stale: published root has no deps yet
+			],
+			skipped: []
+		}
+		const api = make_mock_api({ 'acme/b': { visibility: 'public' } }, resolve_result)
+		const [err, results] = await validate_dependencies(tmp, manifest, {
+			registry: true, full_name: 'acme/a', repos_api: api
+		})
+		assert.ifError(err)
+		const check = results.find(r => r.rule === 'dep-circular' && r.severity === 'error')
+		assert.ok(check, 'should detect the cycle created by the local closing edge')
+		assert.ok(check.message.includes('acme/a'))
+		assert.ok(check.message.includes('acme/b'))
+	})
 })
 
 describe('dep-visibility-transitive (registry)', () => {

package/src/validation/skill_json_rules.js

@@ -6,7 +6,6 @@ const { SKILL_JSON, VALID_SKILL_TYPES, SKILL_TYPES, KIT_PREFIX } = require('../c
 
 const NAME_PATTERN = /^[a-z0-9][a-z0-9_-]*$/
 const KIT_NAME_PATTERN = /^_kit-[a-z0-9][a-z0-9-]*$/
-const CANONICAL_SLUGS = ['deployment', 'database', 'security', 'ai', 'api', 'monitoring', 'testing', 'devops', 'cloud', 'analytics']
 const REQUIRED_PLATFORMS = ['darwin', 'linux', 'win32']
 
 const result = (field, rule, severity, message, value) => ({
@@ -90,27 +89,6 @@ const validate_description = (manifest) => {
 	return results
 }
 
-const validate_keywords = (manifest) => {
-	const results = []
-	const kw = manifest.keywords
-
-	if (!kw || !Array.isArray(kw)) {
-		results.push(result('keywords', 'recommended_field', 'warning', 'Keywords array is recommended — include at least one canonical slug'))
-		return results
-	}
-
-	results.push(result('keywords', 'recommended_field', 'pass', `keywords: ${kw.length} entries`))
-
-	const has_slug = kw.some(k => CANONICAL_SLUGS.includes(k))
-	if (!has_slug) {
-		results.push(result('keywords', 'canonical_slug', 'warning', `Keywords should include at least one canonical slug: ${CANONICAL_SLUGS.join(', ')}`))
-	} else {
-		results.push(result('keywords', 'canonical_slug', 'pass', 'Contains canonical slug'))
-	}
-
-	return results
-}
-
 const validate_type = (manifest) => {
 	const results = []
 	const type = manifest.type
@@ -229,7 +207,6 @@ const validate_skill_json = (skill_dir) => catch_errors('Failed to validate skil
 	results.push(...validate_version(manifest))
 	results.push(...validate_type(manifest))
 	results.push(...validate_description(manifest))
-	results.push(...validate_keywords(manifest))
 	results.push(...validate_dependencies(manifest))
 	results.push(...validate_system_dependencies(manifest))
 

package/src/validation/skill_json_rules.test.js

@@ -121,32 +121,6 @@ describe('validate_skill_json — description', () => {
 	})
 })
 
-describe('validate_skill_json — keywords', () => {
-	it('warns when keywords are missing', async () => {
-		write_json(tmp, { name: 'my-skill', version: '1.0.0' })
-		const [err, data] = await validate_skill_json(tmp)
-		assert.ifError(err)
-		const check = data.results.find(r => r.field === 'keywords' && r.rule === 'recommended_field')
-		assert.strictEqual(check.severity, 'warning')
-	})
-
-	it('warns when no canonical slug is present', async () => {
-		write_json(tmp, { name: 'my-skill', version: '1.0.0', keywords: ['custom'] })
-		const [err, data] = await validate_skill_json(tmp)
-		assert.ifError(err)
-		const check = data.results.find(r => r.rule === 'canonical_slug')
-		assert.strictEqual(check.severity, 'warning')
-	})
-
-	it('passes when a canonical slug is present', async () => {
-		write_json(tmp, { name: 'my-skill', version: '1.0.0', keywords: ['deployment', 'custom'] })
-		const [err, data] = await validate_skill_json(tmp)
-		assert.ifError(err)
-		const check = data.results.find(r => r.rule === 'canonical_slug')
-		assert.strictEqual(check.severity, 'pass')
-	})
-})
-
 describe('validate_skill_json — dependencies', () => {
 	it('errors when dependencies is an array', async () => {
 		write_json(tmp, { name: 'my-skill', version: '1.0.0', dependencies: ['acme/deploy'] })