happyskills 0.53.0 → 1.0.0

package/src/integration/api_envelope.test.js

@@ -0,0 +1,499 @@
+'use strict'
+/**
+ * End-to-end integration tests: CLI ↔ stubbed API speaking the new
+ * canonical six-key envelope (spec 260525-cli-default-json § 4).
+ *
+ * We spin up a tiny `http.createServer` per test that emits the EXACT
+ * envelope the production API now returns (post-Session 3), point the
+ * CLI binary at it via HAPPYSKILLS_API_URL, and assert that:
+ *   1. The CLI parses the response without losing fields (search.mode,
+ *      rerank context, feedback's next_step.context payload, the device
+ *      flow's AUTHORIZATION_PENDING polling loop).
+ *   2. The CLI's own --json output is itself a valid envelope.
+ *
+ * These tests catch the field-read drift between CLI command code and
+ * API envelope locations — the gap Session 3 introduced when /repos:search
+ * moved metadata into data, /feedback hoisted next_step to the root, and
+ * /auth/device/token started speaking the canonical shape on HTTP 202.
+ */
+const { describe, it, before, after } = require('node:test')
+const assert = require('node:assert/strict')
+const { spawn } = require('child_process')
+const http = require('http')
+const fs = require('fs')
+const os = require('os')
+const path = require('path')
+const {
+	parse_envelope,
+	assert_success_envelope,
+} = require('../schema/envelope_test_helpers')
+
+const CLI = path.resolve(__dirname, '../../bin/happyskills.js')
+const NODE = process.execPath
+
+// Minimal stub-server harness. Each test installs a route table that maps
+// `${METHOD} ${PATH}` → handler({ url, body }) returning { status, body }.
+// The body is always JSON-encoded with the new six-key envelope shape.
+//
+// IMPORTANT: every response carries `Connection: close`. Without this,
+// undici's connection pool keeps the socket warm and prevents the CLI
+// child process from exiting (the request-and-response cycle finishes but
+// the idle keep-alive socket keeps the event loop alive, so spawnSync
+// hangs until its timeout fires). Closing per response makes the child
+// exit naturally as soon as the run() promise resolves.
+const make_stub = () => {
+	const routes = new Map()
+	const server = http.createServer((req, res) => {
+		let body = ''
+		req.on('data', c => { body += c })
+		req.on('end', () => {
+			const key = `${req.method} ${req.url.split('?')[0]}`
+			const handler = routes.get(key)
+			const close_headers = { 'Content-Type': 'application/json', 'Connection': 'close' }
+			if (!handler) {
+				res.writeHead(404, close_headers)
+				res.end(JSON.stringify({
+					ok: false,
+					data: {},
+					error: { code: 'NOT_FOUND', message: `No stub for ${key}` },
+					next_step: {},
+					warnings: [],
+					meta: { command: key, exit_code: 1, envelope_schema_version: '1.0.0', api_version: 'stub' },
+				}))
+				return
+			}
+			let parsed_body = null
+			try { parsed_body = body ? JSON.parse(body) : null } catch (_) { /* leave null */ }
+			const out = handler({ url: req.url, body: parsed_body, headers: req.headers })
+			res.writeHead(out.status || 200, close_headers)
+			res.end(JSON.stringify(out.body))
+		})
+	})
+	// Disable keep-alive at the server level too — belt-and-braces against
+	// any client that ignores the Connection: close header.
+	server.keepAliveTimeout = 1
+	return {
+		server,
+		route: (key, handler) => { routes.set(key, handler) },
+		start: () => new Promise(resolve => server.listen(0, '127.0.0.1', () => resolve(server.address().port))),
+		close: () => new Promise(resolve => server.close(() => resolve())),
+	}
+}
+
+// Streaming spawn instead of spawnSync. The CLI's success path returns
+// without calling process.exit so the Node event loop holds the process
+// open until undici's keep-alive sockets idle out (~30s). spawnSync only
+// captures output AFTER the child exits, so it would hang. Streaming
+// captures stdout incrementally and we kill the child as soon as we've
+// seen a complete JSON envelope (or stderr indicates an error path).
+const run_cli = (args, env_override = {}) => new Promise((resolve) => {
+	const has_mode_flag = args.includes('--json') || args.includes('--text')
+	const final_args = has_mode_flag ? args : [...args, '--text']
+	const child = spawn(NODE, [CLI, ...final_args], {
+		env: { ...process.env, NO_COLOR: '1', CI: '', ...env_override },
+	})
+	let stdout = ''
+	let stderr = ''
+	let settled = false
+	const settle = (code) => {
+		if (settled) return
+		settled = true
+		try { child.kill('SIGTERM') } catch (_) { /* ignore */ }
+		resolve({ stdout, stderr, code })
+	}
+	child.stdout.on('data', (d) => {
+		stdout += d.toString()
+		// As soon as we've seen what looks like a complete JSON document on
+		// stdout, the command has emitted its envelope. Settle with code 0
+		// (the visible code; non-zero error paths exit explicitly and we
+		// catch those via the `exit` handler below).
+		if (stdout.trim().endsWith('}')) {
+			try {
+				JSON.parse(stdout)
+				settle(0)
+			} catch (_) { /* not yet a full envelope, keep buffering */ }
+		}
+	})
+	child.stderr.on('data', (d) => { stderr += d.toString() })
+	child.on('exit', (code) => settle(code))
+	// Hard ceiling — should never fire under normal conditions.
+	setTimeout(() => settle(null), 15000)
+})
+
+const make_tmp = () => fs.mkdtempSync(path.join(os.tmpdir(), 'hs-api-stub-'))
+
+// Build a canonical success envelope for the stub.
+const success_envelope = (data, opts = {}) => ({
+	ok: true,
+	data,
+	error: {},
+	next_step: opts.next_step || {},
+	warnings: opts.warnings || [],
+	meta: {
+		command: opts.command || 'stub',
+		exit_code: 0,
+		envelope_schema_version: '1.0.0',
+		api_version: 'stub-5.0.0',
+	},
+})
+
+// ─── search ────────────────────────────────────────────────────────────────
+
+describe('CLI ↔ API: /repos:search envelope (§ 15.3.1)', () => {
+	let stub, port
+
+	before(async () => {
+		stub = make_stub()
+		port = await stub.start()
+	})
+	after(async () => { await stub.close() })
+
+	it('renders results when the API places metadata inside data (post-§ 15.3.1)', async () => {
+		stub.route('POST /repos:search', () => ({
+			status: 200,
+			body: success_envelope({
+				query: 'deploy aws',
+				mode: 'semantic',
+				results: [{
+					name: 'deploy-aws',
+					workspace_slug: 'acme',
+					full_name: 'acme/deploy-aws',
+					description: 'Ship a service to AWS Lambda',
+					match_quality: 'strong',
+					quality_score: 80,
+					star_count: 12,
+				}],
+				count: 1,
+				match_notice: null,
+				workspace_match: null,
+				intent_id: 'int-abc-123',
+			}, { command: 'POST /repos:search' }),
+		}))
+		const { code, stdout } = await run_cli(
+			['search', 'deploy aws', '--json', '--limit', '10'],
+			{ HAPPYSKILLS_API_URL: `http://127.0.0.1:${port}` }
+		)
+		assert.strictEqual(code, 0, `expected exit 0, got ${code}; stdout:\n${stdout}`)
+		const env = parse_envelope(stdout, 'search semantic')
+		assert_success_envelope(env)
+		assert.strictEqual(env.data.mode, 'semantic')
+		assert.strictEqual(env.data.count, 1)
+		assert.strictEqual(env.data.results[0].name, 'deploy-aws')
+	})
+
+	it('forwards the rerank protocol through next_step.context.* (post-§ 15.3.1)', async () => {
+		stub.route('POST /repos:search', () => ({
+			status: 200,
+			body: success_envelope({
+				query: 'deploy aws',
+				mode: 'semantic',
+				results: [
+					{ name: 'deploy-aws', workspace_slug: 'acme', full_name: 'acme/deploy-aws', match_quality: 'good', quality_score: 70, star_count: 5 },
+					{ name: 'aws-lambda', workspace_slug: 'acme', full_name: 'acme/aws-lambda', match_quality: 'good', quality_score: 65, star_count: 3 },
+				],
+				count: 2,
+				match_notice: null,
+			}, {
+				command: 'POST /repos:search',
+				next_step: {
+					kind: 'continuation',
+					action: 'rank_digests_inline',
+					instructions: 'Rank these per the system prompt.',
+					context: {
+						rerank_digests: [
+							{ candidate_id: 1, digest: 'deploy aws lambda' },
+							{ candidate_id: 2, digest: 'aws lambda functions' },
+						],
+						rerank_system_prompt: 'You are a ranker.',
+						rerank_prompt_version: 'v3',
+						rerank_response_schema: { type: 'object', properties: { ranking: { type: 'array' } } },
+					},
+				},
+			}),
+		}))
+		const { code, stdout } = await run_cli(
+			['search', 'deploy aws', '--with-rerank', '--json', '--limit', '50'],
+			{ HAPPYSKILLS_API_URL: `http://127.0.0.1:${port}` }
+		)
+		assert.strictEqual(code, 0, `expected exit 0, got ${code}; stdout:\n${stdout}`)
+		const env = parse_envelope(stdout, 'search rerank')
+		assert_success_envelope(env)
+		// Rerank payload reached the CLI emit (the CLI flattens into data.rerank_*).
+		assert.ok(Array.isArray(env.data.rerank_digests))
+		assert.strictEqual(env.data.rerank_digests.length, 2)
+		assert.strictEqual(env.data.rerank_system_prompt, 'You are a ranker.')
+		assert.strictEqual(env.data.rerank_prompt_version, 'v3')
+		// CLI emits its own next_step pointing at rank_digests_inline.
+		assert.strictEqual(env.next_step.action, 'rank_digests_inline')
+		assert.strictEqual(env.next_step.kind, 'continuation')
+	})
+
+	it('surfaces match_notice into the emitted envelope', async () => {
+		stub.route('POST /repos:search', () => ({
+			status: 200,
+			body: success_envelope({
+				query: 'deploy',
+				mode: 'semantic',
+				results: [],
+				count: 0,
+				match_notice: 'Ambiguous — multiple meanings detected',
+			}, { command: 'POST /repos:search' }),
+		}))
+		const { code, stdout } = await run_cli(
+			['search', 'deploy', '--json', '--limit', '10'],
+			{ HAPPYSKILLS_API_URL: `http://127.0.0.1:${port}` }
+		)
+		assert.strictEqual(code, 0)
+		const env = parse_envelope(stdout, 'search match_notice')
+		assert_success_envelope(env)
+		assert.match(env.data.match_notice, /ambiguous/i)
+	})
+})
+
+// ─── feedback ──────────────────────────────────────────────────────────────
+
+describe('CLI ↔ API: POST /feedback envelope (§ 15.3.4)', () => {
+	let stub, port, tmp_xdg
+
+	before(async () => {
+		stub = make_stub()
+		port = await stub.start()
+		tmp_xdg = make_tmp()
+		// Stub credentials so the CLI sends auth.
+		const creds_dir = path.join(tmp_xdg, 'happyskills')
+		fs.mkdirSync(creds_dir, { recursive: true })
+		const payload = { email: 'test@example.com', 'cognito:username': 'testuser', sub: 'test-sub-123' }
+		const fake_jwt = `eyJhbGciOiJSUzI1NiJ9.${Buffer.from(JSON.stringify(payload)).toString('base64url')}.fakesig`
+		fs.writeFileSync(path.join(creds_dir, 'credentials.json'), JSON.stringify({
+			id_token: fake_jwt,
+			access_token: 'fake-access',
+			refresh_token: 'fake-refresh',
+			expires_in: 3600,
+			stored_at: new Date().toISOString(),
+		}, null, '\t'))
+	})
+	after(async () => {
+		await stub.close()
+		fs.rmSync(tmp_xdg, { recursive: true, force: true })
+	})
+
+	it('reads next_step.context.{feedback_id, attachments_supported, max_attachments} from the hoisted envelope', async () => {
+		stub.route('POST /feedback', ({ body }) => ({
+			status: 201,
+			body: {
+				ok: true,
+				data: {
+					feedback: {
+						id: 'fb-001',
+						subject: body?.subject || 'A bug',
+						body: body?.body || 'It broke.',
+						category: body?.category || 'bug',
+						created_at: '2026-05-28T00:00:00Z',
+					},
+				},
+				error: {},
+				next_step: {
+					kind: 'continuation',
+					action: 'attach_screenshot',
+					instructions: 'Thanks — feedback recorded. The principal may optionally attach a screenshot.',
+					context: {
+						feedback_id: 'fb-001',
+						attachments_supported: true,
+						max_attachments: 5,
+						message: 'Want to attach a screenshot?',
+					},
+				},
+				warnings: [],
+				meta: { command: 'POST /feedback', exit_code: 0, envelope_schema_version: '1.0.0', api_version: 'stub-5.0.0' },
+			},
+		}))
+		const { code, stdout } = await run_cli(
+			['feedback', 'bug', 'It broke.', '--subject', 'A bug', '--json'],
+			{ HAPPYSKILLS_API_URL: `http://127.0.0.1:${port}`, XDG_CONFIG_HOME: tmp_xdg }
+		)
+		assert.strictEqual(code, 0, `expected exit 0, got ${code}; stdout:\n${stdout}`)
+		const env = parse_envelope(stdout, 'feedback create')
+		assert_success_envelope(env)
+		assert.strictEqual(env.data.feedback.id, 'fb-001')
+		// The CLI's emitted next_step must carry the attach_screenshot action.
+		assert.strictEqual(env.next_step.action, 'attach_screenshot')
+		assert.strictEqual(env.next_step.context.feedback_id, 'fb-001')
+		assert.strictEqual(env.next_step.context.attachments_supported, true)
+		assert.strictEqual(env.next_step.context.max_attachments, 5)
+	})
+})
+
+// ─── device flow polling ───────────────────────────────────────────────────
+
+describe('CLI ↔ API: /auth/device/token envelope (§ 15.3.2)', () => {
+	let stub, port, tmp_xdg
+
+	before(async () => {
+		stub = make_stub()
+		port = await stub.start()
+		tmp_xdg = make_tmp()
+	})
+	after(async () => {
+		await stub.close()
+		fs.rmSync(tmp_xdg, { recursive: true, force: true })
+	})
+
+	it('completes a login that AUTHORIZATION_PENDING-polls once then succeeds', () => {
+		// First a /device/start, then /device/token returns PENDING once,
+		// then succeeds with a token. The login command opens a browser by
+		// default; we use --device flag... actually login doesn't have a
+		// browser-skip flag for tests. Instead we exercise the polling
+		// envelope directly by spawning the binary with the device URL set
+		// and a special flag combination. For this test we verify just the
+		// envelope-parsing piece — that the new shape works when the API
+		// emits AUTHORIZATION_PENDING via the canonical envelope.
+		//
+		// We test the device_token client module in isolation to keep this
+		// test deterministic (the full browser flow spawns `open`).
+		const { device_token } = require('../api/auth')
+		let call_count = 0
+		stub.route('POST /auth/device/token', () => {
+			call_count += 1
+			if (call_count === 1) {
+				return {
+					status: 202,
+					body: {
+						ok: false,
+						data: {},
+						error: { code: 'AUTHORIZATION_PENDING', message: 'Waiting for user authorization' },
+						next_step: {
+							kind: 'recovery',
+							action: 'retry',
+							instructions: 'Authorization is still pending. Poll again after the suggested interval.',
+							context: { retry_after_seconds: 2 },
+						},
+						warnings: [],
+						meta: { command: 'POST /auth/device/token', exit_code: 0, envelope_schema_version: '1.0.0', api_version: 'stub-5.0.0' },
+					},
+				}
+			}
+			return {
+				status: 200,
+				body: {
+					ok: true,
+					data: {
+						id_token: 'eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJhYmMifQ.sig',
+						access_token: 'access-xyz',
+						refresh_token: 'refresh-xyz',
+						expires_in: 3600,
+					},
+					error: {},
+					next_step: {},
+					warnings: [],
+					meta: { command: 'POST /auth/device/token', exit_code: 0, envelope_schema_version: '1.0.0', api_version: 'stub-5.0.0' },
+				},
+			}
+		})
+		// Set the API URL so the auth client targets the stub.
+		const prev = process.env.HAPPYSKILLS_API_URL
+		process.env.HAPPYSKILLS_API_URL = `http://127.0.0.1:${port}`
+		// Re-require the client module since it caches API_URL via constants.
+		// In practice this only matters if the test runs in a worker that has
+		// already cached the client — we accept that and use the env var
+		// directly via the request.
+		return (async () => {
+			try {
+				const [pending_err, pending] = await device_token('test-device-code')
+				assert.equal(pending_err, null, `unexpected error on pending poll: ${pending_err && pending_err.map(e => e.message).join(', ')}`)
+				assert.ok(pending && pending.error && pending.error.code === 'AUTHORIZATION_PENDING',
+					`expected AUTHORIZATION_PENDING surface, got ${JSON.stringify(pending)}`)
+				const [success_err, success] = await device_token('test-device-code')
+				assert.equal(success_err, null, `unexpected error on success poll: ${success_err && success_err.map(e => e.message).join(', ')}`)
+				assert.ok(success.id_token, 'expected id_token in success response')
+				assert.strictEqual(success.access_token, 'access-xyz')
+				assert.strictEqual(success.refresh_token, 'refresh-xyz')
+			} finally {
+				if (prev === undefined) delete process.env.HAPPYSKILLS_API_URL
+				else process.env.HAPPYSKILLS_API_URL = prev
+			}
+		})()
+	})
+})
+
+// ─── array-returning endpoints — sole-results unwrap ───────────────────────
+//
+// Spec § 4.3 mandates `data` is always an object — arrays are wrapped as
+// `{ results: [...] }`. The CLI API client strips that wrapper when it's
+// the sole payload (see cli/src/api/client.js) so legacy CLI consumers
+// (`people list`, `groups list`, `access list`, etc.) keep seeing the
+// bare array they always did. This test exercises the round-trip for the
+// `people search` command which iterates the returned array directly.
+
+describe('CLI ↔ API: array-returning endpoints unwrap sole `results`', () => {
+	let stub, port, tmp_xdg
+
+	before(async () => {
+		stub = make_stub()
+		port = await stub.start()
+		tmp_xdg = make_tmp()
+		const creds_dir = path.join(tmp_xdg, 'happyskills')
+		fs.mkdirSync(creds_dir, { recursive: true })
+		const payload = { email: 'test@example.com', 'cognito:username': 'testuser', sub: 'test-sub-123' }
+		const fake_jwt = `eyJhbGciOiJSUzI1NiJ9.${Buffer.from(JSON.stringify(payload)).toString('base64url')}.fakesig`
+		fs.writeFileSync(path.join(creds_dir, 'credentials.json'), JSON.stringify({
+			id_token: fake_jwt,
+			access_token: 'fake-access',
+			refresh_token: 'fake-refresh',
+			expires_in: 3600,
+			stored_at: new Date().toISOString(),
+		}, null, '\t'))
+	})
+	after(async () => {
+		await stub.close()
+		fs.rmSync(tmp_xdg, { recursive: true, force: true })
+	})
+
+	it('iterates `/users/search` rows that arrive wrapped as data.results', async () => {
+		stub.route('GET /users/search', () => ({
+			status: 200,
+			body: success_envelope({
+				results: [
+					{ username: 'alice', email: 'a@x.com', display_name: 'Alice' },
+					{ username: 'bob',   email: 'b@x.com', display_name: 'Bob' },
+				],
+			}, { command: 'GET /users/search' }),
+		}))
+		const { code, stdout } = await run_cli(
+			['people', 'search', 'al', '--json'],
+			{ HAPPYSKILLS_API_URL: `http://127.0.0.1:${port}`, XDG_CONFIG_HOME: tmp_xdg }
+		)
+		assert.strictEqual(code, 0, `expected exit 0, got ${code}; stdout:\n${stdout}`)
+		const env = parse_envelope(stdout, 'people search')
+		assert_success_envelope(env)
+		// The CLI re-emits the rows under data.results (canonical array key).
+		const rows = Array.isArray(env.data) ? env.data : env.data.results
+		assert.ok(Array.isArray(rows), `expected an array of users; got ${JSON.stringify(env.data)}`)
+		assert.strictEqual(rows.length, 2)
+		assert.strictEqual(rows[0].username, 'alice')
+	})
+
+	it('text mode renders the rows without crashing on .map/.length', async () => {
+		// Pre-fix: client returned `{ results: [...] }`, so `users.map` was
+		// undefined and the text path threw TypeError. This test pins down
+		// the regression by spawning the command WITHOUT --json (so the
+		// run_cli helper appends --text per its default), and asserting
+		// the process exits 0 with both usernames visible on stdout.
+		stub.route('GET /users/search', () => ({
+			status: 200,
+			body: success_envelope({
+				results: [
+					{ username: 'alice', email: 'a@x.com', display_name: 'Alice' },
+					{ username: 'bob',   email: 'b@x.com', display_name: 'Bob' },
+				],
+			}, { command: 'GET /users/search' }),
+		}))
+		const { code, stdout, stderr } = await run_cli(
+			['people', 'search', 'al'],
+			{ HAPPYSKILLS_API_URL: `http://127.0.0.1:${port}`, XDG_CONFIG_HOME: tmp_xdg }
+		)
+		assert.strictEqual(code, 0, `expected exit 0; stderr:\n${stderr}\nstdout:\n${stdout}`)
+		assert.doesNotMatch(stderr, /TypeError|is not a function|Cannot read/i, `text mode threw:\n${stderr}`)
+		assert.match(stdout, /alice/)
+		assert.match(stdout, /bob/)
+	})
+})

package/src/integration/bump.test.js

@@ -15,17 +15,24 @@ const { spawnSync } = require('child_process')
 const fs = require('fs')
 const os = require('os')
 const path = require('path')
+const {
+	parse_envelope,
+	assert_success_envelope,
+} = require('../schema/envelope_test_helpers')
 
 const CLI = path.resolve(__dirname, '../../bin/happyskills.js')
 const NODE = process.execPath
 
 const make_tmp = () => fs.mkdtempSync(path.join(os.tmpdir(), 'hs-bump-test-'))
 const run = (args, opts) => {
-	const result = spawnSync(NODE, [CLI, ...args], {
+	const has_mode_flag = args.includes('--json') || args.includes('--text')
+	const final_args = has_mode_flag ? args : [...args, '--text']
+	const result = spawnSync(NODE, [CLI, ...final_args], {
 		env: {
 			...process.env,
-			NO_COLOR: '1',
+			NO_COLOR: '1', HAPPYSKILLS_ENVELOPE_STRICT: '1',
 			HAPPYSKILLS_API_URL: 'http://localhost:0',
+			CI: '',
 			...(opts?.env || {})
 		},
 		encoding: 'utf-8',
@@ -34,9 +41,11 @@ const run = (args, opts) => {
 	})
 	return { stdout: result.stdout || '', stderr: result.stderr || '', code: result.status }
 }
+// Parse + envelope-validate. Bump/list emit success envelopes here.
 const parse_json = (stdout, label) => {
-	try { return JSON.parse(stdout) }
-	catch { assert.fail(`${label}: stdout is not valid JSON:\n${stdout}`) }
+	const env = parse_envelope(stdout, label)
+	assert_success_envelope(env, label)
+	return env
 }
 
 // Scaffold a project with one locked-and-installed skill.