happyskills 0.52.1 → 0.54.0

package/CHANGELOG.md

@@ -7,6 +7,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.54.0] - 2026-05-26
+
+### Added
+
+- **`intent_id` is now attached to every `/telemetry/discovery` beacon payload** (spec 260521-03 addendum § 4 — CLI half of Phase A). The CLI sources the value from the active intent envelope via a new `get_intent_id()` helper in `cli/src/utils/intent.js`, which decodes the envelope's base64url payload portion and extracts `intent_id`. Sent on all four beacon types fired from `search` and `postlex`: `rerank_started`, `rerank_completed`, `clarify_triggered`, `clarify_completed`. When no envelope is active the payload includes `intent_id: null`. Before this change, every `search.rerank` and `search.clarify` row in `analytics.events` landed with `intent_id = NULL`, defeating the addendum's goal of correlating beacons with the discovery chain.
+
+## [0.53.0] - 2026-05-25
+
+### Added
+
+- **First-launch attribution prompt on `happyskills login`** (spec 260521-03 § 10.1). The first successful login from a fresh install prints a one-shot, single-keypress prompt asking "what brought you here?" (Reddit / HN / Twitter / YouTube / blog / podcast / friend / AI search / other). Skippable (Enter). The answer is emitted as a `cli.attribution_answered` event to the API and updates `users.signup_source` (only when previously NULL — never overwrites). A marker file at `$XDG_CONFIG_HOME/happyskills/attribution-prompted` prevents re-prompting on subsequent logins.
+- **`auth.cli_first_link` event** emitted alongside the attribution prompt — the principal-to-operator handoff signal for the time-to-CLI-link metric.
+- **Surface tagging on every API request.** All API calls now carry `X-Client-Surface: cli` and `X-Client-Version: <cli_version>` headers so the API can bucket analytics events by source.
+- **Intent envelope threading** (spec 260521-03 § 8.4) — every API call attaches the active `X-Intent-Envelope` request header; the refreshed value returned by the server is captured from the response and used on the next call (sliding TTL). The envelope is propagated to subprocesses via the `HAPPYSKILLS_INTENT_ENVELOPE` env var or the new top-level `--intent <base64>` flag, so a parent process (e.g. MCP server) can correlate a multi-step discovery workflow into one trace.
+- **Install/uninstall analytics events** — `install.started` / `install.completed` / `install.failed` (with `error_code` on failure) emitted from `happyskills install`; `uninstall` emitted from `happyskills uninstall`. Fire-and-forget — never block the user-visible flow.
+- **`cli/src/utils/{analytics,attribution,intent}.js`** — internal modules powering the above. All three are CommonJS, lazy-loaded, and fail silently on network errors so analytics never affects exit codes.
+
 ## [0.52.1] - 2026-05-25
 
 ### Fixed

package/package.json

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

package/src/api/client.js

@@ -3,6 +3,7 @@ const { error: { catch_errors, wrap_errors: e } } = require('puffy-core')
 const { API_URL, CLI_VERSION } = require('../constants')
 const { ApiError, NetworkError, AuthError } = require('../utils/errors')
 const { load_token } = require('../auth/token_store')
+const { get_envelope, set_envelope } = require('../utils/intent')
 
 const get_base_url = () => process.env.HAPPYSKILLS_API_URL || API_URL
 const USER_AGENT = `happyskills-cli/${CLI_VERSION}`
@@ -12,7 +13,19 @@ const request = (method, path, options = {}) => catch_errors(`API ${method} ${pa
 	const url = `${get_base_url()}${path}`
 	// User-Agent enables the API to identify CLI traffic (e.g. feedback API
 	// derives `source = 'cli'` from this header). Spec 260524-01 § 12.
-	const headers = { 'User-Agent': USER_AGENT, ...extra_headers }
+	// X-Client-Surface / X-Client-Version are required by spec 260521-03 § 10.2
+	// so analytics rows can be bucketed by source. X-Intent-Envelope threads
+	// the active discovery intent across calls per § 8.4.
+	const headers = {
+		'User-Agent': USER_AGENT,
+		'X-Client-Surface': 'cli',
+		'X-Client-Version': CLI_VERSION,
+		...extra_headers,
+	}
+	const active_envelope = get_envelope()
+	if (active_envelope && !headers['X-Intent-Envelope']) {
+		headers['X-Intent-Envelope'] = active_envelope
+	}
 
 	if (auth) {
 		const [, token_data] = await load_token()
@@ -42,6 +55,13 @@ const request = (method, path, options = {}) => catch_errors(`API ${method} ${pa
 		throw new NetworkError(`Failed to connect to API: ${err.message}`)
 	}
 
+	// Capture refreshed X-Intent-Envelope so subsequent calls (and any
+	// subprocess we later spawn via HAPPYSKILLS_INTENT_ENVELOPE) carry the
+	// updated TTL. Best-effort: missing header just means the endpoint
+	// doesn't refresh the envelope (most endpoints don't).
+	const refreshed_envelope = res.headers && res.headers.get && res.headers.get('x-intent-envelope')
+	if (refreshed_envelope) set_envelope(refreshed_envelope)
+
 	if (raw_response) return res
 
 	const data = await res.json().catch(() => null)

package/src/commands/install.js

@@ -12,6 +12,8 @@ const { file_exists } = require('../utils/fs')
 const { hash_directory } = require('../lock/integrity')
 const { get_all_locked_skills } = require('../lock/reader')
 const snapshot_storage = require('../snapshot/storage')
+const { emit: emit_analytics } = require('../utils/analytics')
+const { CLI_VERSION } = require('../constants')
 
 const HELP_TEXT = `Usage: happyskills install [<owner>/<skill>[@<version>]] [...] [options]
 
@@ -184,14 +186,17 @@ const run = (args) => catch_errors('Install failed', async () => {
 	const failures = []
 	for (const { skill, version: inline_version } of parsed) {
 		const version = flag_version || inline_version
+		emit_analytics('install.started', { cli_version: CLI_VERSION })
 		const [errors, result] = await install(skill, { ...base_options, version })
 		if (errors) {
 			const chain = errors?.map ? errors.map(x => x?.message).filter(Boolean) : [errors?.message || String(errors)]
 			const msg = chain[chain.length - 1] || chain[0] || 'Unknown error'
 			print_warn(`Failed to install ${skill}: ${msg}`)
 			failures.push({ skill, error: msg })
+			emit_analytics('install.failed', { error_code: 'INSTALL_FAILED', cli_version: CLI_VERSION })
 		} else {
 			results.push({ skill, result })
+			emit_analytics('install.completed', { cli_version: CLI_VERSION })
 		}
 	}
 

package/src/commands/login.js

@@ -1,3 +1,5 @@
+const fs = require('fs')
+const path = require('path')
 const readline = require('readline')
 const { error: { catch_errors, wrap_errors: e } } = require('puffy-core')
 const auth_api = require('../api/auth')
@@ -5,8 +7,44 @@ const { save_token, load_token } = require('../auth/token_store')
 const { create_spinner } = require('../ui/spinner')
 const { print_help, print_success, print_info, print_hint, print_json, code } = require('../ui/output')
 const { exit_with_error } = require('../utils/errors')
-const { EXIT_CODES } = require('../constants')
+const { EXIT_CODES, CLI_VERSION } = require('../constants')
 const { run_browser_flow } = require('./login_device')
+const { config_dir } = require('../config/paths')
+const { prompt_for_source } = require('../utils/attribution')
+const { emit } = require('../utils/analytics')
+
+// Spec 260521-03 § 10.1 — One-shot first-launch attribution prompt. After
+// the user has answered (or skipped), this marker file prevents re-prompting
+// across subsequent logins on the same install.
+const ATTRIBUTION_MARKER = () => path.join(config_dir(), 'attribution-prompted')
+
+const attribution_already_prompted = () => {
+	try { return fs.existsSync(ATTRIBUTION_MARKER()) } catch { return false }
+}
+
+const mark_attribution_prompted = () => {
+	try {
+		fs.mkdirSync(config_dir(), { recursive: true })
+		fs.writeFileSync(ATTRIBUTION_MARKER(), new Date().toISOString())
+	} catch {
+		// Best-effort. Re-prompting once is annoying but not catastrophic.
+	}
+}
+
+// Fire-and-forget. Emits cli.attribution_answered + auth.cli_first_link.
+const handle_post_login_telemetry = async () => {
+	// Always emit auth.cli_first_link on the first successful login from this
+	// install (gated by the same marker — once we've prompted/marked, we
+	// don't fire again).
+	if (attribution_already_prompted()) return
+	emit('auth.cli_first_link', { cli_version: CLI_VERSION })
+
+	const source = await prompt_for_source()
+	mark_attribution_prompted()
+	if (source) {
+		emit('cli.attribution_answered', { source })
+	}
+}
 
 const HELP_TEXT = `Usage: happyskills login [options]
 
@@ -95,6 +133,7 @@ const run_password_flow = () => catch_errors('Password login failed', async () =
 	if (save_err) { spinner.fail('Failed to save credentials'); throw e('Failed to save token', save_err) }
 
 	spinner.succeed('Logged in successfully')
+	await handle_post_login_telemetry()
 })
 
 const decode_jwt_payload = (token) => {
@@ -170,6 +209,9 @@ const run = (args) => catch_errors('Login failed', async () => {
 	} else {
 		const [errors] = await run_browser_flow()
 		if (errors) throw e('Browser login failed', errors)
+		// Browser flow doesn't go through run_password_flow's success branch,
+		// so we trigger the post-login telemetry here.
+		await handle_post_login_telemetry()
 	}
 
 	console.log()

package/src/commands/postlex.js

@@ -15,6 +15,7 @@ const { exit_with_error, UsageError, CliError } = require('../utils/errors')
 const { EXIT_CODES } = require('../constants')
 const { slug_token_set, compute_lex_tier } = require('../utils/slug_tokens')
 const { fire_discovery_telemetry } = require('../api/telemetry')
+const { get_intent_id } = require('../utils/intent')
 
 const HELP_TEXT = `Usage: happyskills postlex --query <q> --ranking <file|-> [options]
 
@@ -425,9 +426,13 @@ const run = (args) => catch_errors('Postlex failed', async () => {
 	const next_step = determine_next_step(final_ordering, query, clarification_turns_used)
 
 	// Fire telemetry — rerank_completed first (the rerank step succeeded);
-	// clarify_triggered separately if applicable.
+	// clarify_triggered separately if applicable. `intent_id` is sourced from
+	// the active intent envelope so these beacons correlate with the same
+	// discovery chain (spec 260521-03 addendum § 4).
+	const intent_id = get_intent_id()
 	fire_discovery_telemetry({
 		event:                       'rerank_completed',
+		intent_id,
 		query,
 		promoted,
 		promoted_from_rank,
@@ -436,6 +441,7 @@ const run = (args) => catch_errors('Postlex failed', async () => {
 	if (next_step.action === 'clarify') {
 		fire_discovery_telemetry({
 			event:        'clarify_triggered',
+			intent_id,
 			query,
 			reason:       'post_rerank_weak',
 			turn_number:  clarification_turns_used + 1,

package/src/commands/search.js

@@ -6,6 +6,7 @@ const { exit_with_error, UsageError, AuthError } = require('../utils/errors')
 const { EXIT_CODES, VALID_SKILL_TYPES } = require('../constants')
 const { load_token } = require('../auth/token_store')
 const { fire_discovery_telemetry } = require('../api/telemetry')
+const { get_intent_id } = require('../utils/intent')
 
 const HELP_TEXT = `Usage: happyskills search [query] [options]
 
@@ -221,9 +222,14 @@ const run_smart_search = (args, query, options) => catch_errors('Smart search fa
 	const next_step = build_search_next_step(response, query, { with_rerank, clarification_turns_used })
 
 	// Telemetry beacons (fire-and-forget). Spec § 5.1 + § 5.3.
+	// `intent_id` is sourced from the active intent envelope (spec 260521-03
+	// addendum § 4) so search.rerank / search.clarify rows correlate with
+	// the same discovery chain as the search.query that minted the envelope.
+	const intent_id = get_intent_id()
 	if (with_rerank && next_step?.action === 'rank_digests_inline') {
 		fire_discovery_telemetry({
 			event: 'rerank_started',
+			intent_id,
 			query,
 			rerank_prompt_version: response?.rerank_prompt_version || null,
 		})
@@ -231,6 +237,7 @@ const run_smart_search = (args, query, options) => catch_errors('Smart search fa
 	if (with_rerank && next_step?.action === 'clarify') {
 		fire_discovery_telemetry({
 			event:       'clarify_triggered',
+			intent_id,
 			query,
 			reason:      'match_notice',
 			turn_number: clarification_turns_used + 1,
@@ -241,6 +248,7 @@ const run_smart_search = (args, query, options) => catch_errors('Smart search fa
 		// with a refined query.
 		fire_discovery_telemetry({
 			event:       'clarify_completed',
+			intent_id,
 			query,
 			turn_number: clarification_turns_used,
 		})

package/src/commands/uninstall.js

@@ -4,6 +4,7 @@ const { print_help, print_json, print_warn } = require('../ui/output')
 const { exit_with_error, UsageError } = require('../utils/errors')
 const { find_project_root } = require('../config/paths')
 const { EXIT_CODES } = require('../constants')
+const { emit: emit_analytics } = require('../utils/analytics')
 
 const HELP_TEXT = `Usage: happyskills uninstall <owner/skill> [...] [options]
 
@@ -59,6 +60,7 @@ const run = (args) => catch_errors('Uninstall failed', async () => {
 			failures.push({ skill, error: msg })
 		} else {
 			results.push({ skill, result })
+			emit_analytics('uninstall', {})
 		}
 	}
 

package/src/index.js

@@ -134,6 +134,16 @@ const run = (argv) => {
 		set_json_mode()
 	}
 
+	// Spec 260521-03 § 8.4 — propagate intent envelope from --intent flag or
+	// the HAPPYSKILLS_INTENT_ENVELOPE env var (set by a parent process such
+	// as the MCP server). Initializing here makes the envelope visible to
+	// every subsequent API call within this CLI invocation.
+	if (args.flags.intent || process.env.HAPPYSKILLS_INTENT_ENVELOPE) {
+		const { init_from_flag, init_from_env } = require('./utils/intent')
+		if (args.flags.intent) init_from_flag(args.flags.intent)
+		else init_from_env()
+	}
+
 	if (args.flags.version === true) {
 		show_version()
 		return process.exit(EXIT_CODES.SUCCESS)

package/src/utils/analytics.js

@@ -0,0 +1,31 @@
+// Spec 260521-03 § 7.3 — CLI client-emitted events.
+//
+// Fire-and-forget. Each event is its own POST to /events (no batching —
+// CLI volume is low). A failure logs to stderr at debug level and never
+// affects the user-visible flow. Lazy-loads the API client to keep startup
+// fast.
+
+const { error: { catch_errors } } = require('puffy-core')
+
+const post_event = (event_type, metadata) => catch_errors('Failed to post analytics event', async () => {
+	const { post } = require('../api/client')
+	// Use unwrap:false so we don't trip on the empty body.
+	await post('/events', { events: [{
+		event_type,
+		metadata: metadata || {},
+		client_ts: Date.now(),
+	}] }, { auth: true, unwrap: false })
+})
+
+// Caller-friendly wrapper. Errors are swallowed — engagement telemetry must
+// never block the user.
+const emit = (event_type, metadata) => {
+	// Don't return the promise — fire-and-forget. Errors stay quiet.
+	post_event(event_type, metadata).then(([errors]) => {
+		if (errors && process.env.HAPPYSKILLS_DEBUG) {
+			process.stderr.write(`[analytics] ${event_type} failed: ${errors[0]?.message || 'unknown'}\n`)
+		}
+	}).catch(() => {})
+}
+
+module.exports = { emit }

package/src/utils/attribution.js

@@ -0,0 +1,55 @@
+// Spec 260521-03 § 10.1, § 18.6 — First-launch attribution prompt.
+//
+// Shown once after the first successful `happyskills login` for a fresh
+// install. Single keypress, skippable, no re-prompt.
+
+const readline = require('readline')
+
+const SOURCES = [
+	{ key: '1', value: 'reddit',          label: 'Reddit' },
+	{ key: '2', value: 'hacker_news',     label: 'Hacker News' },
+	{ key: '3', value: 'twitter',         label: 'Twitter / X' },
+	{ key: '4', value: 'youtube',         label: 'YouTube' },
+	{ key: '5', value: 'blog',            label: 'Blog or article' },
+	{ key: '6', value: 'podcast',         label: 'Podcast' },
+	{ key: '7', value: 'friend',          label: 'A friend / colleague' },
+	{ key: '8', value: 'ai_search',       label: 'Search (Google / ChatGPT / Claude / Perplexity)' },
+	{ key: '9', value: 'other',           label: 'Other' },
+]
+
+const read_single_keypress = () => new Promise((resolve) => {
+	if (!process.stdin.isTTY) return resolve('')
+	const rl = readline.createInterface({ input: process.stdin, output: process.stderr })
+	process.stdin.setRawMode(true)
+	const on_data = (chunk) => {
+		const c = chunk.toString()
+		process.stdin.setRawMode(false)
+		process.stdin.removeListener('data', on_data)
+		rl.close()
+		// Ctrl-C → treat as skip but stop the process so callers don't continue.
+		if (c === '\x03') { process.stderr.write('\n'); process.exit(0) }
+		resolve(c)
+	}
+	process.stdin.on('data', on_data)
+	process.stdin.resume()
+})
+
+// Returns the chosen source value (one of SOURCES[].value), or null if
+// the user skipped (Enter or non-TTY).
+const prompt_for_source = async () => {
+	process.stderr.write('\n')
+	process.stderr.write('  One quick thing — what brought you here? Choose one (or press Enter to skip):\n')
+	for (const s of SOURCES) {
+		process.stderr.write(`    ${s.key}) ${s.label}\n`)
+	}
+	process.stderr.write('\n  > ')
+
+	const keypress = await read_single_keypress()
+	process.stderr.write('\n')
+
+	if (!keypress || keypress === '\n' || keypress === '\r') return null
+	const match = SOURCES.find(s => s.key === keypress)
+	return match ? match.value : null
+}
+
+module.exports = { prompt_for_source, SOURCES }

package/src/utils/intent.js

@@ -0,0 +1,63 @@
+// Spec 260521-03 § 8.4 — Process-local intent envelope state.
+//
+// The CLI propagates the active envelope to subprocesses via the
+// HAPPYSKILLS_INTENT_ENVELOPE env var or the --intent CLI flag. Within a
+// single CLI process, the envelope lives in memory and is updated whenever
+// the server sends back a refreshed value on the X-Intent-Envelope response
+// header.
+
+let _current = null
+
+const ENV_VAR = 'HAPPYSKILLS_INTENT_ENVELOPE'
+
+const init_from_env = () => {
+	if (_current) return _current
+	const from_env = process.env[ENV_VAR]
+	if (from_env) _current = from_env
+	return _current
+}
+
+const init_from_flag = (envelope) => {
+	if (envelope) _current = envelope
+}
+
+const get_envelope = () => init_from_env()
+
+const set_envelope = (envelope) => {
+	if (envelope) {
+		_current = envelope
+		// Propagate to subprocesses spawned from this point on. We mutate
+		// process.env intentionally — child_process spawn() copies env at
+		// fork time, so setting it here makes the refreshed value visible
+		// to any subprocess started later in the same CLI invocation.
+		process.env[ENV_VAR] = envelope
+	}
+}
+
+const clear_envelope = () => {
+	_current = null
+	delete process.env[ENV_VAR]
+}
+
+// Spec 260521-03 addendum § 4 — Extract the intent_id UUID from the active
+// envelope so the CLI can attach it to /telemetry/discovery beacon payloads.
+// The envelope is `<base64url-payload>.<base64url-hmac>`; the CLI doesn't
+// have the HMAC secret and doesn't need to verify — it just reads the
+// payload portion. Returns null when no envelope is active or the payload
+// can't be decoded.
+const get_intent_id = () => {
+	const env = get_envelope()
+	if (!env) return null
+	try {
+		const dot = env.indexOf('.')
+		if (dot <= 0) return null
+		const body = env.slice(0, dot)
+		const json = Buffer.from(body, 'base64url').toString('utf-8')
+		const payload = JSON.parse(json)
+		return payload.intent_id || null
+	} catch {
+		return null
+	}
+}
+
+module.exports = { init_from_env, init_from_flag, get_envelope, set_envelope, clear_envelope, get_intent_id, ENV_VAR }