happyskills 1.4.1 → 1.5.0

package/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [1.5.0] - 2026-06-04
+
+### Added
+
+- Add `stats` command for read-only consumption stats over a bounded time window. Two scopes: `--scope my_activity` (your own installs / updates / searches / uninstalls) and `--scope my_skills_reach` (aggregate reach of skills you authored — never identifies *who* consumed them). Flags: `--metric`, `--period <7d|30d|90d|6mo|12mo>` or `--from`/`--to`, `--group-by`, `--skill <owner/skill>` (`my_skills_reach` only; resolved to its id server-side), and `--json`. Requires auth; calls `POST /me/stats:query` (API v5.3.0+). Surfaced in `happyskills schema`.
+
 ## [1.4.1] - 2026-06-03
 
 ### Fixed

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "happyskills",
-	"version": "1.4.1",
+	"version": "1.5.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/schema.js

@@ -58,6 +58,7 @@ const AUDIENCE_HINT = {
 	diff: 'consumer', pull: 'consumer', snapshot: 'consumer',
 	reconcile: 'consumer', enable: 'consumer', disable: 'consumer',
 	versions: 'consumer', changelog: 'consumer', bump: 'consumer',
+	stats: 'consumer',
 	// author
 	publish: 'author', convert: 'author', fork: 'author',
 	validate: 'author', delete: 'author', visibility: 'author',

package/src/commands/stats.js

@@ -0,0 +1,199 @@
+const { error: { catch_errors, wrap_errors: e } } = require('puffy-core')
+const client = require('../api/client')
+const { print_help, print_table, print_json, print_info, print_warn, print_label } = require('../ui/output')
+const { bold, dim, cyan, gray } = require('../ui/colors')
+const { exit_with_error, UsageError, AuthError } = require('../utils/errors')
+const { EXIT_CODES } = require('../constants')
+const token_store = require('../auth/token_store')
+
+// happyskills stats (spec 260603-03) — authenticated, read-only consumption
+// stats. Flags map 1:1 onto the closed API grammar (POST /me/stats:query); the
+// server validates and is the source of truth. Two scopes:
+//   my_activity      — your own actions (installs/updates/searches/uninstalls).
+//   my_skills_reach  — how OTHER people consume skills you authored
+//                      (aggregate-only, never names a consumer).
+
+const METRICS_BY_SCOPE = {
+	my_activity:     ['installs', 'updates', 'searches', 'uninstalls'],
+	my_skills_reach: ['installs_by_others', 'distinct_installers'],
+}
+const GROUP_BY_BY_SCOPE = {
+	my_activity:     ['none', 'day', 'week', 'month', 'surface'],
+	my_skills_reach: ['none', 'day', 'week', 'month', 'skill'],
+}
+const VALID_PRESETS = ['7d', '30d', '90d', '6mo', '12mo']
+
+const HELP_TEXT = `Usage: happyskills stats --scope <scope> --metric <metric> [options]
+
+Retrieve your HappySkills usage over a bounded time window. Requires login.
+
+Two scopes:
+  my_activity       Your own actions: installs, updates, searches, uninstalls.
+  my_skills_reach   How others consume skills you authored (aggregate only —
+                    never identifies who installed).
+
+Options:
+  --scope <scope>         my_activity | my_skills_reach (required)
+  --metric <metric>       my_activity:     installs, updates, searches, uninstalls
+                          my_skills_reach: installs_by_others, distinct_installers
+  --period <preset>       ${VALID_PRESETS.join(' | ')}
+  --from <ISO date>       Explicit window start (use instead of --period)
+  --to <ISO date>         Explicit window end (default: now)
+  --group-by <bucket>     my_activity:     none, day, week, month, surface
+                          my_skills_reach: none, day, week, month, skill
+                          (default: none)
+  --skill <owner/skill>   Limit my_skills_reach to one skill you authored
+  --json                  Output as JSON envelope
+
+Examples:
+  happyskills stats --scope my_activity --metric installs --period 30d
+  happyskills stats --scope my_activity --metric searches --period 90d --group-by week --json
+  happyskills stats --scope my_skills_reach --metric distinct_installers --period 12mo
+  happyskills stats --scope my_skills_reach --metric installs_by_others --period 12mo --group-by skill
+  happyskills stats --scope my_skills_reach --metric distinct_installers --period 12mo --skill acme/deploy-aws
+  happyskills stats --scope my_activity --metric installs --from 2026-05-01 --to 2026-06-01`
+
+// Validate flags against the closed grammar and build the request body. Throws
+// UsageError on bad input (server re-validates regardless). Returns the body.
+const build_request = (flags) => {
+	const scope = flags.scope
+	if (!scope || !METRICS_BY_SCOPE[scope])
+		throw new UsageError('--scope is required and must be one of: my_activity, my_skills_reach')
+
+	const metric = flags.metric
+	if (!metric || !METRICS_BY_SCOPE[scope].includes(metric))
+		throw new UsageError(`--metric for ${scope} must be one of: ${METRICS_BY_SCOPE[scope].join(', ')}`)
+
+	const group_by = flags['group-by'] || 'none'
+	if (!GROUP_BY_BY_SCOPE[scope].includes(group_by))
+		throw new UsageError(`--group-by for ${scope} must be one of: ${GROUP_BY_BY_SCOPE[scope].join(', ')}`)
+
+	const has_preset = flags.period != null && flags.period !== true
+	const has_from = flags.from != null && flags.from !== true
+	if (has_preset && has_from)
+		throw new UsageError('Use either --period or --from/--to, not both.')
+	if (!has_preset && !has_from)
+		throw new UsageError(`A time window is required: --period <${VALID_PRESETS.join('|')}> or --from <date>.`)
+
+	let period
+	if (has_preset) {
+		if (!VALID_PRESETS.includes(flags.period))
+			throw new UsageError(`--period must be one of: ${VALID_PRESETS.join(', ')}`)
+		period = { preset: flags.period }
+	} else {
+		period = { from: flags.from }
+		if (flags.to != null && flags.to !== true) period.to = flags.to
+	}
+
+	const body = { scope, metric, group_by, period }
+
+	// --skill narrows my_skills_reach to a single authored skill. The server
+	// resolves the owner/skill slug to its id against your owned set.
+	const has_skill = flags.skill != null && flags.skill !== true
+	if (has_skill) {
+		if (scope !== 'my_skills_reach')
+			throw new UsageError('--skill is only valid for --scope my_skills_reach.')
+		if (!flags.skill.includes('/'))
+			throw new UsageError('--skill must be in owner/skill form, e.g. acme/deploy-aws.')
+		body.repo_slug = flags.skill
+	}
+
+	return body
+}
+
+const render_human = (data, warnings) => {
+	const window = data.period && data.period.from
+		? `${String(data.period.from).slice(0, 10)} → ${String(data.period.to).slice(0, 10)}`
+		: ''
+	console.log(`\n${bold(`${data.scope} · ${data.metric}`)}${window ? dim(`   ${window}`) : ''}\n`)
+	print_label('  Total', cyan(String(data.total)))
+
+	if (Array.isArray(data.series) && data.series.length > 0) {
+		console.log('')
+		const rows = data.series.map(p => [String(p.key), String(p.value)])
+		print_table(['Bucket', 'Count'], rows)
+	} else if (data.total === 0) {
+		print_info('No events in this window.')
+	}
+
+	if (data.period && data.period.available_from) {
+		console.log(`\n${gray(`Data available from ${String(data.period.available_from).slice(0, 10)}.`)}`)
+	}
+	for (const w of (warnings || [])) print_warn(w)
+}
+
+const run = (args) => catch_errors('Stats failed', async () => {
+	if (args.flags._show_help) {
+		print_help(HELP_TEXT)
+		return process.exit(EXIT_CODES.SUCCESS)
+	}
+
+	const body = build_request(args.flags)
+
+	// Auth required — fail fast with the standard auth-required envelope
+	// (next_step → login) before any network call.
+	const [, token_data] = await token_store.load_token()
+	if (!token_data) throw new AuthError()
+
+	// unwrap:false → the API already emits the canonical six-key envelope; we
+	// pass its data / warnings / next_step straight through.
+	const [errors, resp] = await client.post('/me/stats:query', body, { auth: true, unwrap: false })
+	if (errors) throw e('Stats request failed', errors)
+
+	const data = (resp && resp.data) || {}
+	const warnings = (resp && resp.warnings) || []
+	const next_step = (resp && resp.next_step) || {}
+
+	if (args.flags.json) {
+		print_json({ data, warnings, next_step })
+		return
+	}
+
+	render_human(data, warnings)
+}).then(([errors]) => { if (errors) { exit_with_error(errors); return } })
+
+const schema = {
+	name:     'stats',
+	audience: 'consumer',
+	purpose:  'Retrieve your own consumption stats (my_activity) or aggregate reach of skills you authored (my_skills_reach) over a bounded window. Authenticated, read-only; never identifies who consumed your skills.',
+	mutation: false,
+	interactive_in_text_mode: false,
+	input: {
+		positional: [],
+		flags: [
+			{ name: 'scope',    type: 'string', required: true,  description: 'my_activity | my_skills_reach' },
+			{ name: 'metric',   type: 'string', required: true,  description: 'my_activity: installs|updates|searches|uninstalls; my_skills_reach: installs_by_others|distinct_installers' },
+			{ name: 'period',   type: 'string', default: undefined, description: 'Window preset: 7d|30d|90d|6mo|12mo (use instead of --from/--to)' },
+			{ name: 'from',     type: 'string', default: undefined, description: 'Explicit window start (ISO date)' },
+			{ name: 'to',       type: 'string', default: undefined, description: 'Explicit window end (ISO date, default now)' },
+			{ name: 'group-by', type: 'string', default: 'none', description: 'my_activity: none|day|week|month|surface; my_skills_reach: none|day|week|month|skill' },
+			{ name: 'skill',    type: 'string', default: undefined, description: 'my_skills_reach only: limit to one authored skill (owner/skill)' },
+			{ name: 'json',     type: 'boolean', default: false, description: 'Output as JSON' },
+		],
+	},
+	output: {
+		data_shape: {
+			scope:    'string',
+			metric:   'string',
+			group_by: 'string',
+			period:   '{ from: string, to: string, available_from: string|null }',
+			total:    'number',
+			series:   'array<{ key: string, value: number }>',
+		},
+	},
+	errors: [
+		{ code: 'USAGE_ERROR',   next_step: { kind: 'routing',  action: 'discover_schema' } },
+		{ code: 'AUTH_REQUIRED', next_step: { kind: 'recovery', action: 'login' } },
+		// Terminal errors the agent surfaces as-is — no recovery action.
+		{ code: 'INVALID_BODY' },
+		{ code: 'NOT_FOUND' },
+		{ code: 'NETWORK_ERROR', next_step: { kind: 'recovery', action: 'retry' } },
+	],
+	examples: [
+		'happyskills stats --scope my_activity --metric installs --period 30d',
+		'happyskills stats --scope my_skills_reach --metric distinct_installers --period 12mo --group-by skill',
+		'happyskills stats --scope my_skills_reach --metric installs_by_others --period 12mo --skill acme/deploy-aws',
+	],
+}
+
+module.exports = { run, build_request, schema }

package/src/commands/stats.test.js

@@ -0,0 +1,123 @@
+// Unit tests for `happyskills stats` (spec 260603-03). Two surfaces:
+//   1. build_request — flag → closed-grammar validation + body construction.
+//   2. run(--json) — the envelope passthrough: the API already emits the
+//      canonical six-key envelope; the command forwards data/warnings/next_step
+//      through the CLI's emit_envelope chokepoint unchanged.
+//
+// Covered by `npm test` (src/**/*.test.js).
+
+const { describe, it, mock } = require('node:test')
+const assert = require('node:assert/strict')
+const { build_request, run, schema } = require('./stats')
+const client = require('../api/client')
+const token_store = require('../auth/token_store')
+const state = require('../state')
+
+describe('build_request — closed grammar', () => {
+	it('builds a my_activity preset body', () => {
+		assert.deepEqual(build_request({ scope: 'my_activity', metric: 'installs', period: '30d' }), {
+			scope: 'my_activity', metric: 'installs', group_by: 'none', period: { preset: '30d' },
+		})
+	})
+
+	it('builds an explicit from/to body with a time grain', () => {
+		assert.deepEqual(build_request({ scope: 'my_activity', metric: 'searches', from: '2026-05-01', to: '2026-06-01', 'group-by': 'week' }), {
+			scope: 'my_activity', metric: 'searches', group_by: 'week', period: { from: '2026-05-01', to: '2026-06-01' },
+		})
+	})
+
+	it('rejects an out-of-enum scope', () => {
+		assert.throws(() => build_request({ scope: 'nope', metric: 'installs', period: '7d' }), /scope/)
+	})
+
+	it('rejects a metric not valid for the scope', () => {
+		assert.throws(() => build_request({ scope: 'my_skills_reach', metric: 'searches', period: '7d' }), /metric/)
+	})
+
+	it('rejects a group-by not valid for the scope (surface is my_activity-only)', () => {
+		assert.throws(() => build_request({ scope: 'my_skills_reach', metric: 'installs_by_others', period: '7d', 'group-by': 'surface' }), /group-by/)
+	})
+
+	it('requires exactly one time window', () => {
+		assert.throws(() => build_request({ scope: 'my_activity', metric: 'installs' }), /time window/)
+		assert.throws(() => build_request({ scope: 'my_activity', metric: 'installs', period: '7d', from: '2026-01-01' }), /not both/)
+	})
+
+	it('rejects an out-of-enum preset', () => {
+		assert.throws(() => build_request({ scope: 'my_activity', metric: 'installs', period: '13mo' }), /period/)
+	})
+
+	it('maps --skill to repo_slug for my_skills_reach', () => {
+		const body = build_request({ scope: 'my_skills_reach', metric: 'installs_by_others', period: '12mo', skill: 'acme/deploy-aws' })
+		assert.equal(body.repo_slug, 'acme/deploy-aws')
+	})
+
+	it('rejects --skill on my_activity', () => {
+		assert.throws(() => build_request({ scope: 'my_activity', metric: 'installs', period: '30d', skill: 'acme/x' }), /--skill is only valid/)
+	})
+
+	it('rejects a --skill without owner/skill form', () => {
+		assert.throws(() => build_request({ scope: 'my_skills_reach', metric: 'installs_by_others', period: '12mo', skill: 'deploy' }), /owner\/skill/)
+	})
+})
+
+describe('schema export', () => {
+	it('is non-mutating, consumer-audience, with scope+metric required', () => {
+		assert.equal(schema.name, 'stats')
+		assert.equal(schema.mutation, false)
+		assert.equal(schema.audience, 'consumer')
+		const required = schema.input.flags.filter(f => f.required).map(f => f.name).sort()
+		assert.deepEqual(required, ['metric', 'scope'])
+	})
+
+	it('declares the AUTH_REQUIRED → login recovery contract', () => {
+		const auth = schema.errors.find(e => e.code === 'AUTH_REQUIRED')
+		assert.ok(auth)
+		assert.equal(auth.next_step.action, 'login')
+	})
+})
+
+describe('run --json — envelope passthrough', () => {
+	it('forwards the API data + warnings through a six-key envelope on stdout', async (t) => {
+		state.set_json_mode()
+		t.mock.method(token_store, 'load_token', async () => [null, { id_token: 'tok' }])
+		t.mock.method(client, 'post', async () => [null, {
+			ok: true,
+			data: { scope: 'my_activity', metric: 'installs', group_by: 'none', period: { from: 'a', to: 'b', available_from: null }, total: 5, series: [] },
+			error: {},
+			next_step: {},
+			warnings: ['Data is only available from 2026-05-25; earlier dates in your range return no events.'],
+			meta: {},
+		}])
+
+		let printed = null
+		const log = mock.method(console, 'log', (s) => { printed = s })
+
+		await run({ flags: { scope: 'my_activity', metric: 'installs', period: '30d', json: true } })
+		log.mock.restore()
+
+		const env = JSON.parse(printed)
+		// Six-key envelope, data forwarded, warning preserved.
+		for (const k of ['ok', 'data', 'error', 'next_step', 'warnings', 'meta']) assert.ok(k in env, `missing ${k}`)
+		assert.equal(env.ok, true)
+		assert.equal(env.data.total, 5)
+		assert.equal(env.warnings.length, 1)
+	})
+
+	it('sends the request to POST /me/stats:query with the built body', async (t) => {
+		state.set_json_mode()
+		t.mock.method(token_store, 'load_token', async () => [null, { id_token: 'tok' }])
+		let captured = null
+		t.mock.method(client, 'post', async (path, body, opts) => {
+			captured = { path, body, opts }
+			return [null, { ok: true, data: {}, error: {}, next_step: {}, warnings: [], meta: {} }]
+		})
+		const log = mock.method(console, 'log', () => {})
+		await run({ flags: { scope: 'my_skills_reach', metric: 'distinct_installers', period: '12mo', 'group-by': 'skill', json: true } })
+		log.mock.restore()
+
+		assert.equal(captured.path, '/me/stats:query')
+		assert.equal(captured.opts.unwrap, false)
+		assert.deepEqual(captured.body, { scope: 'my_skills_reach', metric: 'distinct_installers', group_by: 'skill', period: { preset: '12mo' } })
+	})
+})

package/src/constants.js

@@ -82,6 +82,7 @@ const COMMANDS = [
 	'reconcile',
 	'release',
 	'feedback',
+	'stats',
 	'schema'
 ]
 

package/src/index.js

@@ -131,6 +131,7 @@ Commands:
   reconcile <owner/skill>  Diagnose and repair lock-vs-disk drift
   release <skill-name>     Atomic release: snapshot + validate + bump + publish
   feedback <category>      Lodge feedback (bug, wish, compliment, question, other)
+  stats                    Your usage + reach of skills you authored (requires login)
 
 Global flags:
   --help                   Show help for a command