happyskills 1.7.1 → 1.8.0

package/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [1.8.0] - 2026-06-05
+
+### Changed
+
+- Record installs via a cache-immune `install.completed` beacon. The install engine now emits one `install.completed` event per newly-installed skill — the root **and** each transitive dependency — batched into a single `POST /events`, carrying the skill's `repo_id`, version, and a root-vs-dependency flag. Because it fires from the engine, `setup` is now counted too (previously it emitted nothing). This replaces the per-command `install.completed` event and is the new source of truth for install/download counts, fixing the under-count caused by CDN cache hits on the clone endpoint silently skipping the old counting path. Fire-and-forget — a telemetry failure never blocks or fails an install; an already-up-to-date (no-op) install emits nothing. Requires API v5.5.0+ for `repo_id` stamping and download-count crediting; against older APIs the events are still sent (forward-compatible).
+
 ## [1.7.1] - 2026-06-04
 
 ### Fixed

package/package.json

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

package/src/commands/install.js

@@ -214,7 +214,10 @@ const run = (args) => catch_errors('Install failed', async () => {
 			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 })
+			// install.completed is now emitted per-skill from the install engine
+			// (cli/src/engine/installer.js, spec 260604-01) — carrying repo_id,
+			// version, and a root-vs-dependency flag — so setup (which bypasses
+			// this command) is covered too. No per-command emit here.
 		}
 	}
 

package/src/engine/installer.js

@@ -16,6 +16,8 @@ const { resolve_agents, link_to_agents, verify_and_repair_symlinks } = require('
 const { is_skill_enabled } = require('../agents/status')
 const { create_spinner } = require('../ui/spinner')
 const { print_success, print_warn, print_info } = require('../ui/output')
+const { emit_batch } = require('../utils/analytics')
+const { CLI_VERSION } = require('../constants')
 
 const _format_warnings = (missing_deps) => (missing_deps || []).map(dep => {
 	const hint = dep.install_hint ? ` (install: ${dep.install_hint})` : ''
@@ -316,6 +318,26 @@ const install = (skill, options = {}) => catch_errors('Install failed', async ()
 			}
 		}
 
+		// Cache-immune install counting (spec 260604-01). Fire one
+		// install.completed beacon per newly-installed skill — root AND each
+		// transitive dependency — batched into a single POST /events. This is the
+		// source of truth for install/download counts: it replaces the clone-
+		// endpoint side-effect that CloudFront cache HITs silently dropped. Only
+		// reached on a genuine install (no_op paths returned earlier and emit
+		// nothing). Fire-and-forget — never blocks or fails the install.
+		emit_batch(downloaded.map(({ pkg }) => {
+			const requested_by = updates[pkg.skill]?.requested_by || []
+			return {
+				event_type: 'install.completed',
+				repo_id: pkg.repo_id || null,
+				metadata: {
+					version: pkg.version,
+					dependency: !requested_by.includes('__root__'),
+					cli_version: CLI_VERSION,
+				},
+			}
+		}))
+
 		spinner.succeed(`Installed ${packages_to_install.length} package(s)`)
 
 		const linked_count = downloaded.length - disabled_skills.size

package/src/utils/analytics.js

@@ -7,25 +7,35 @@
 
 const { error: { catch_errors } } = require('puffy-core')
 
-const post_event = (event_type, metadata) => catch_errors('Failed to post analytics event', async () => {
+const post_events = (events) => catch_errors('Failed to post analytics events', 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 || {},
+	const stamped = events.map(ev => ({
+		event_type: ev.event_type,
+		...(ev.repo_id ? { repo_id: ev.repo_id } : {}),
+		metadata: ev.metadata || {},
 		client_ts: Date.now(),
-	}] }, { auth: true, unwrap: false })
+	}))
+	// Use unwrap:false so we don't trip on the empty body.
+	await post('/events', { events: stamped }, { auth: true, unwrap: false })
 })
 
 // Caller-friendly wrapper. Errors are swallowed — engagement telemetry must
 // never block the user.
-const emit = (event_type, metadata) => {
+const emit = (event_type, metadata) => emit_batch([{ event_type, metadata }])
+
+// Batched emit — sends N events in a single POST /events. Used by the install
+// engine to record one install.completed per installed skill (root + each
+// transitive dependency) in one request (spec 260604-01). Each event may carry
+// a top-level `repo_id` (UUID); per-event metadata is passed through as-is.
+const emit_batch = (events) => {
+	if (!Array.isArray(events) || events.length === 0) return
 	// Don't return the promise — fire-and-forget. Errors stay quiet.
-	post_event(event_type, metadata).then(([errors]) => {
+	post_events(events).then(([errors]) => {
 		if (errors && process.env.HAPPYSKILLS_DEBUG) {
-			process.stderr.write(`[analytics] ${event_type} failed: ${errors[0]?.message || 'unknown'}\n`)
+			const types = events.map(e => e.event_type).join(',')
+			process.stderr.write(`[analytics] ${types} failed: ${errors[0]?.message || 'unknown'}\n`)
 		}
 	}).catch(() => {})
 }
 
-module.exports = { emit }
+module.exports = { emit, emit_batch }

package/src/utils/analytics.test.js

@@ -0,0 +1,89 @@
+// Run with: node --test src/utils/analytics.test.js  (also covered by `npm test`)
+//
+// Unit tests for the batched analytics emitter (spec 260604-01). The install
+// engine fires one install.completed event per installed skill (root + each
+// dependency) batched into a SINGLE POST /events, with repo_id riding the
+// top-level event field and version/dependency/cli_version in metadata. The
+// emitter is fire-and-forget — it must never throw into the caller.
+
+const { describe, it, afterEach } = require('node:test')
+const assert = require('node:assert')
+
+// Stub the API client before requiring the module under test, so we capture the
+// exact POST payload emit_batch produces. analytics.js lazy-requires the client
+// inside the post, so seeding require.cache here is enough.
+const stub_client = (calls) => {
+	const client_path = require.resolve('../api/client')
+	require.cache[client_path] = {
+		id: client_path,
+		filename: client_path,
+		loaded: true,
+		exports: {
+			post: async (path, body, opts) => { calls.push({ path, body, opts }); return [null, null] },
+		},
+	}
+	delete require.cache[require.resolve('./analytics')]
+	return require('./analytics')
+}
+
+const restore = () => {
+	delete require.cache[require.resolve('../api/client')]
+	delete require.cache[require.resolve('./analytics')]
+}
+
+// emit_batch is fire-and-forget — give the microtask/promise chain a tick.
+const tick = () => new Promise(r => setImmediate(r))
+
+describe('emit_batch — install.completed beacon', () => {
+	afterEach(restore)
+
+	it('sends ONE POST /events for N skills, repo_id top-level, version+dependency in metadata', async () => {
+		const calls = []
+		const { emit_batch } = stub_client(calls)
+		emit_batch([
+			{ event_type: 'install.completed', repo_id: 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa', metadata: { version: '1.0.0', dependency: false, cli_version: '9.9.9' } },
+			{ event_type: 'install.completed', repo_id: 'bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb', metadata: { version: '2.0.0', dependency: true, cli_version: '9.9.9' } },
+		])
+		await tick()
+
+		assert.equal(calls.length, 1, 'a constellation install is a single batched request')
+		assert.equal(calls[0].path, '/events')
+		assert.equal(calls[0].opts.auth, true)
+		const evts = calls[0].body.events
+		assert.equal(evts.length, 2)
+		assert.equal(evts[0].repo_id, 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa')
+		assert.equal(evts[0].metadata.dependency, false)
+		assert.equal(evts[0].metadata.version, '1.0.0')
+		assert.equal(evts[1].repo_id, 'bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb')
+		assert.equal(evts[1].metadata.dependency, true)
+		assert.ok(typeof evts[0].client_ts === 'number', 'each event is timestamped')
+	})
+
+	it('no-ops on an empty batch (zero installed skills → no request)', async () => {
+		const calls = []
+		const { emit_batch } = stub_client(calls)
+		emit_batch([])
+		await tick()
+		assert.equal(calls.length, 0)
+	})
+
+	it('omits repo_id from the wire when it is null/absent', async () => {
+		const calls = []
+		const { emit_batch } = stub_client(calls)
+		emit_batch([{ event_type: 'install.completed', repo_id: null, metadata: { version: '1.0.0' } }])
+		await tick()
+		assert.equal('repo_id' in calls[0].body.events[0], false)
+	})
+
+	it('swallows a client error — telemetry never throws into the install flow', async () => {
+		const client_path = require.resolve('../api/client')
+		require.cache[client_path] = {
+			id: client_path, filename: client_path, loaded: true,
+			exports: { post: async () => { throw new Error('network down') } },
+		}
+		delete require.cache[require.resolve('./analytics')]
+		const { emit_batch } = require('./analytics')
+		assert.doesNotThrow(() => emit_batch([{ event_type: 'install.completed', metadata: {} }]))
+		await tick()
+	})
+})