happyskills 1.7.0 → 1.8.0

package/CHANGELOG.md

@@ -7,6 +7,18 @@ 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
+
+- Stop double-counting a single install. The install pipeline tries an archive download first and falls back to a JSON clone when the archive is missing or unusable; both hit the clone endpoint, which counts (`repo.clone` + `download_count`) per request. The fallback now sends `?no_count=1` so one install registers exactly once. Only the install fallback sets it — `fork`, `pull`, and normal installs are unchanged. Takes effect against API v5.4.1+ (older APIs ignore the flag and still count both); forward-only.
+
 ## [1.7.0] - 2026-06-04
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "happyskills",
-	"version": "1.7.0",
+	"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/api/repos.js

@@ -61,6 +61,9 @@ const clone = (owner, repo, ref, options = {}) => catch_errors(`Clone ${owner}/$
 	if (options.commit) params.set('commit', options.commit)
 	else if (ref) params.set('ref', ref)
 	if (options.format) params.set('format', options.format)
+	// Fallback retries (install archive→JSON) mark themselves so the server
+	// counts the install only once (the primary attempt already counted).
+	if (options.no_count) params.set('no_count', '1')
 	const qs = params.toString() ? `?${params}` : ''
 	const [errors, data] = await client.get(`/repos/${owner}/${repo}/clone${qs}`)
 	if (errors) throw errors[errors.length - 1]

package/src/api/repos.test.js

@@ -217,3 +217,19 @@ describe('repos.star / repos.unstar — endpoint + path', () => {
 		assert.strictEqual(calls[0][1], `/repos/${encodeURIComponent('acme corp')}/${encodeURIComponent('deploy/aws')}/star`)
 	})
 })
+
+// Bug B fix: a fallback retry marks itself no_count so the server counts the
+// install only once (the primary archive attempt already counted).
+describe('repos.clone — no_count flag (double-count prevention)', () => {
+	afterEach(restore)
+
+	it('adds ?no_count=1 only when options.no_count is set', async () => {
+		const { repos, calls } = stub_client_capture()
+		await repos.clone('acme', 'deploy', 'refs/tags/v1.0.0', { no_count: true })
+		await repos.clone('acme', 'deploy', 'refs/tags/v1.0.0', {})
+		await repos.clone('acme', 'deploy', 'refs/tags/v1.0.0', { format: 'archive' })
+		assert.match(calls[0][1], /[?&]no_count=1/)
+		assert.doesNotMatch(calls[1][1], /no_count/)
+		assert.doesNotMatch(calls[2][1], /no_count/) // archive is the primary attempt — counts
+	})
+})

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/downloader.js

@@ -1,8 +1,8 @@
 const { error: { catch_errors, wrap_errors: e } } = require('puffy-core')
 const repos_api = require('../api/repos')
 
-const download = (owner, repo, ref) => catch_errors(`Download ${owner}/${repo} failed`, async () => {
-	const [errors, data] = await repos_api.clone(owner, repo, ref)
+const download = (owner, repo, ref, options = {}) => catch_errors(`Download ${owner}/${repo} failed`, async () => {
+	const [errors, data] = await repos_api.clone(owner, repo, ref, options)
 	if (errors) throw e(`Failed to clone ${owner}/${repo}`, errors)
 	return data
 })

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})` : ''
@@ -204,8 +206,11 @@ const install = (skill, options = {}) => catch_errors('Install failed', async ()
 				clone_ref = arch_result.ref
 				clone_commit = arch_result.commit
 			} else {
-				// Fall back to JSON clone
-				const [dl_errors, clone_data] = await download(owner, name, pkg.ref)
+				// Fall back to JSON clone. The archive attempt above already hit the
+				// clone endpoint (and counted the install), so mark this retry
+				// no_count to avoid double-counting one install (download_count +
+				// repo.clone). See repos.js clone handler.
+				const [dl_errors, clone_data] = await download(owner, name, pkg.ref, { no_count: true })
 				if (dl_errors) { spinner.fail(`Download failed: ${pkg.skill}`); throw e(`Download ${pkg.skill} failed`, dl_errors) }
 
 				const [ext_errors] = await extract(clone_data, pkg_tmp)
@@ -313,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()
+	})
+})