happyskills 0.49.0 → 0.50.0

package/CHANGELOG.md

@@ -7,6 +7,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.50.0] - 2026-05-24
+
+### Added
+
+- **New `feedback` command** — `happyskills feedback <category> [body] [--subject "..."] [--attach a,b,c] [--json]`. Lodge a bug report, feature wish, compliment, question, or other feedback against the HappySkills platform from the terminal. Five categories: `bug | wish | compliment | question | other`. The body can be supplied inline or omitted to open `$EDITOR` (vim / nano fallback) — same UX as `git commit`. Optional `--subject` (≤ 200 chars) and `--attach` (comma-separated image paths, max 10, PNG/JPEG accepted on the CLI). Auto-captures `cli_version`, `node_version`, `os`, `arch`, `cwd_is_skill_dir`, and `current_skill` (read from a local `skill.json` if present) into the API's silent `client_context`, with secrets scrubbed before sending. `--json` emits the `{ data: { feedback, attachments }, error: null, next_step }` envelope at the response root — the `next_step` is what the `happyskills-help` skill reads to offer the post-creation attachment follow-up.
+- **Image attachments via cherry-picked jimp 1.x** — `cli/src/utils/image_compression.js` compresses each `--attach` file to ≤ 2000 px longest side / JPEG quality 80 / ≤ 1 MB before upload via the two-step pre-signed S3 flow. Uses `@jimp/core` + `@jimp/js-jpeg` + `@jimp/js-png` + `@jimp/plugin-resize` cherry-picked from the jimp 1.x family — NOT the `jimp` meta-package (which pulls in BMP, GIF, TIFF, blur, color, mask, threshold, dither, print, and a dozen other plugins we don't need). WebP is not supported on the CLI in this release (jimp 1.x ships no WebP codec); the web modal still accepts WebP via `browser-image-compression`. **Lazy-loaded**: jimp is only `require()`d when at least one `--attach` is provided, so every other CLI command (`install`, `search`, `publish`, etc.) pays zero require cost. An early-bail check after compression rejects images that still exceed 1 MB with a clean local error before any initiate round-trip.
+- **New `cli/src/api/feedback.js`** — API client for the new `/feedback` endpoints: `create_feedback`, `initiate_attachment_upload`, `put_attachment_to_s3`, `complete_attachment_upload`, `list_feedback`, `get_feedback`. Follows the existing per-resource module pattern (`api/repos.js`, `api/auth.js`, etc.).
+- **New `cli/src/utils/scrub_secrets.js`** — recursively scrubs OpenAI keys (`sk-…`), GitHub tokens (`ghp_…` / `gho_…`), Cognito JWT-shaped strings (`eyJ…`), and any value whose key matches `/(_TOKEN|_KEY|_SECRET|_PASSWORD|_API_KEY)$/i` before `client_context` leaves the CLI. Applied automatically by the feedback command; reusable from any future command that captures user environment data. Mirror of `web/src/lib/scrub-secrets.js` — the regexes must stay in sync.
+
+### Changed
+
+- **All API calls now send `User-Agent: happyskills-cli/<version>`** (`cli/src/api/client.js`). Required so the API can derive `feedback.source = 'cli'` server-side and never trust the source from the request body. No behaviour change for existing endpoints — none of them inspect User-Agent today; this is forward-compatible plumbing for any future endpoint that wants to know who's calling.
+- **Install size increased from 5.1 MB → ~15 MB** due to jimp 1.x's transitive deps (`zod` 5 MB for runtime type checks; `bare-fs`/`bare-os`/`bare-url` 3.6 MB combined for Bare-runtime polyfills). The cherry-pick keeps jimp itself to 1.4 MB on disk, but the dependency closure dominates. This violates the original spec § 8.3's 8 MB target — accepted as a deliberate trade-off because: (a) **cold-start cost is unaffected** (lazy require means non-feedback commands never load jimp); (b) `npm install -g happyskills` install cost is paid once per machine, not per invocation; (c) the mission-aligned goal of "friction is the enemy of getting feedback at all" outweighs install footprint. A follow-up could investigate shelling out to system `sips` / `magick` to shrink the install — flagged but not in this release.
+
+### Notes
+
+- New gotcha entries documenting browser-direct-to-S3 patterns (signed Content-Type on PUT, response-Content-Type override on GET, SDK v3.729+ checksum opt-out, bucket CORS as CSRF guard) were added to `docs/gotchas/aws-sdk.md` in the same monorepo change set. These pertain to the API and infra; mentioned here for context since the CLI's `--attach` flow is the other client of that pipeline.
+
 ## [0.49.0] - 2026-05-23
 
 This release combines two streams of work: **spec 260523-02 (Skill Update Determinism)** which introduces four new CLI primitives plus an `ahead` status to make skill update flows deterministic and safe-to-attempt, AND a **bundle-size enforcement** pass that adds a total-bundle cap to pre-publish validation.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "happyskills",
-	"version": "0.49.0",
+	"version": "0.50.0",
 	"description": "Package manager for AI agent skills",
 	"license": "SEE LICENSE IN LICENSE",
 	"author": "Nicolas Dao <nic@cloudlesslabs.com> (https://cloudlesslabs.com)",
@@ -43,6 +43,10 @@
 		"node": ">=22.0.0"
 	},
 	"dependencies": {
+		"@jimp/core": "^1.6.0",
+		"@jimp/js-jpeg": "^1.6.0",
+		"@jimp/js-png": "^1.6.0",
+		"@jimp/plugin-resize": "^1.6.0",
 		"node-diff3": "^3.2.0",
 		"puffy-core": "^1.3.1",
 		"semver": "^7.6.0",

package/src/api/client.js

@@ -1,15 +1,18 @@
 const { createHash } = require('crypto')
 const { error: { catch_errors, wrap_errors: e } } = require('puffy-core')
-const { API_URL } = require('../constants')
+const { API_URL, CLI_VERSION } = require('../constants')
 const { ApiError, NetworkError, AuthError } = require('../utils/errors')
 const { load_token } = require('../auth/token_store')
 
 const get_base_url = () => process.env.HAPPYSKILLS_API_URL || API_URL
+const USER_AGENT = `happyskills-cli/${CLI_VERSION}`
 
 const request = (method, path, options = {}) => catch_errors(`API ${method} ${path} failed`, async () => {
 	const { body, auth = true, raw_response = false, unwrap = true, headers: extra_headers = {} } = options
 	const url = `${get_base_url()}${path}`
-	const headers = { ...extra_headers }
+	// 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 }
 
 	if (auth) {
 		const [, token_data] = await load_token()

package/src/api/feedback.js

@@ -0,0 +1,71 @@
+// Spec 260524-01 — CLI client for the /feedback API.
+//
+// Returns the full response (envelope unwrapped to `data`) for `create` so the
+// caller can access the `next_step` envelope baked into the API response. The
+// attachment endpoints unwrap normally — callers only need the payload.
+
+const { error: { catch_errors, wrap_errors: e } } = require('puffy-core')
+const client = require('./client')
+
+// POST /feedback — does NOT unwrap, so the caller can read `next_step` which
+// the API places alongside `feedback` inside `data`. (Our envelope is
+// `{ data: { feedback, next_step } }`.)
+const create_feedback = (payload) => catch_errors('Create feedback failed', async () => {
+	const [errors, data] = await client.post('/feedback', payload)
+	if (errors) throw errors[errors.length - 1]
+	return data   // { feedback, next_step }
+})
+
+const initiate_attachment_upload = (feedback_id, payload) => catch_errors('Initiate attachment upload failed', async () => {
+	const [errors, data] = await client.post(`/feedback/${feedback_id}/attachments/initiate`, payload)
+	if (errors) throw errors[errors.length - 1]
+	return data   // { upload_id, storage_key, upload_url, expires_at, original_name }
+})
+
+const complete_attachment_upload = (feedback_id, payload) => catch_errors('Complete attachment upload failed', async () => {
+	const [errors, data] = await client.post(`/feedback/${feedback_id}/attachments/complete`, payload)
+	if (errors) throw errors[errors.length - 1]
+	return data   // { attachment }
+})
+
+const put_attachment_to_s3 = (presigned_url, buffer) => catch_errors('S3 attachment upload failed', async () => {
+	const res = await fetch(presigned_url, {
+		method: 'PUT',
+		body: buffer,
+		headers: {
+			'Content-Type': 'image/jpeg',
+			'Content-Length': buffer.length.toString()
+		}
+	})
+	if (!res.ok) {
+		const text = await res.text().catch(() => '')
+		throw new Error(`S3 PUT failed with status ${res.status}${text ? ': ' + text.slice(0, 200) : ''}`)
+	}
+})
+
+const list_feedback = (query = {}) => catch_errors('List feedback failed', async () => {
+	const params = new URLSearchParams()
+	if (query.limit != null) params.set('limit', String(query.limit))
+	if (query.offset != null) params.set('offset', String(query.offset))
+	if (query.category) params.set('category', query.category)
+	if (query.status) params.set('status', query.status)
+	const qs = params.toString()
+	const [errors, data] = await client.get(`/feedback${qs ? '?' + qs : ''}`)
+	if (errors) throw errors[errors.length - 1]
+	return data
+})
+
+const get_feedback = (feedback_id) => catch_errors('Get feedback failed', async () => {
+	const [errors, data] = await client.get(`/feedback/${feedback_id}`)
+	if (errors) throw errors[errors.length - 1]
+	return data
+})
+
+module.exports = {
+	create_feedback,
+	initiate_attachment_upload,
+	complete_attachment_upload,
+	put_attachment_to_s3,
+	list_feedback,
+	get_feedback
+}

package/src/commands/feedback.js

@@ -0,0 +1,260 @@
+// Spec 260524-01 — `happyskills feedback` command.
+//
+// Surfaces:
+//   happyskills feedback <category> [body] [--subject "..."] [--attach a,b,c] [--json]
+//
+// --json mode emits the API's response wrapped in the universal CLI envelope:
+//   { data: { feedback, next_step, attachments? }, error: null }
+// The `next_step` envelope is what the `happyskills-help` skill reads to
+// route the post-creation conversation (offer attachment, etc.) — see spec
+// § 6.2 + § 11.
+//
+// LAZY-LOAD: jimp / image_compression is only require()d when --attach is
+// present, so the 99% of CLI invocations that don't lodge feedback pay zero
+// startup cost (D8).
+
+const fs = require('fs')
+const os = require('os')
+const path = require('path')
+const { spawnSync } = require('child_process')
+const { error: { catch_errors, wrap_errors: e } } = require('puffy-core')
+const { require_token } = require('../auth/token_store')
+const feedback_api = require('../api/feedback')
+const { scrub } = require('../utils/scrub_secrets')
+const { print_help, print_json, print_success, print_info, print_hint } = require('../ui/output')
+const { exit_with_error, UsageError } = require('../utils/errors')
+const { EXIT_CODES, CLI_VERSION } = require('../constants')
+
+const HELP_TEXT = `Usage: happyskills feedback <category> [body] [options]
+
+Lodge feedback with HappySkills — bug reports, feature wishes, compliments,
+questions. Auto-captures CLI version / OS / current skill context silently
+(secrets are scrubbed before sending).
+
+Arguments:
+  category            One of: bug | wish | compliment | question | other
+  body                Your feedback. Omit to open $EDITOR (vim / nano fallback).
+
+Options:
+  --subject "..."     Short title (max 200 chars)
+  --attach <paths>    Comma-separated image paths (max 10, PNG/JPEG accepted).
+                      Each compressed to ≤2000px / quality 80 / JPEG before upload.
+                      Per-image cap after compression: 1 MB (server-enforced).
+  --json              Emit JSON envelope (intended for use inside an agentic
+                      session — see the happyskills-help skill).
+
+Examples:
+  happyskills feedback bug "search returns nothing for partial slugs"
+  happyskills feedback wish "I wish I could export my catalog to JSON"
+  happyskills feedback bug --attach screenshot.png --json
+  happyskills feedback compliment    # → opens $EDITOR for the body`
+
+const VALID_CATEGORIES = new Set(['bug', 'wish', 'compliment', 'question', 'other'])
+
+const try_editor_for_body = () => {
+	const editors = [
+		process.env.EDITOR,
+		process.env.VISUAL,
+		'vim',
+		'nano',
+	].filter(Boolean)
+
+	const tmp = path.join(os.tmpdir(), `happyskills-feedback-${process.pid}-${Date.now()}.txt`)
+	fs.writeFileSync(tmp, '# Write your feedback above this line. Lines starting with # are ignored.\n')
+
+	let succeeded = false
+	for (const editor of editors) {
+		try {
+			const r = spawnSync(editor, [tmp], { stdio: 'inherit' })
+			if (r.status === 0) { succeeded = true; break }
+		} catch (_) {
+			// try next
+		}
+	}
+	if (!succeeded) {
+		try { fs.unlinkSync(tmp) } catch (_) {}
+		throw new UsageError('Could not open an editor. Set $EDITOR, or pass the body as a positional argument.')
+	}
+
+	const raw = fs.readFileSync(tmp, 'utf-8')
+	try { fs.unlinkSync(tmp) } catch (_) {}
+	const body = raw
+		.split('\n')
+		.filter(line => !line.startsWith('#'))
+		.join('\n')
+		.trim()
+	return body
+}
+
+// Best-effort: read a local skill.json if the cwd looks like a skill directory.
+const read_current_skill = () => {
+	try {
+		const p = path.join(process.cwd(), 'skill.json')
+		if (!fs.existsSync(p)) return null
+		const raw = fs.readFileSync(p, 'utf-8')
+		const parsed = JSON.parse(raw)
+		const name = parsed.name || null
+		if (!name) return null
+		// name may be "ns/skill" or just "skill"
+		const slash = name.indexOf('/')
+		return {
+			namespace: slash > 0 ? name.slice(0, slash) : null,
+			name: slash > 0 ? name.slice(slash + 1) : name,
+			version: parsed.version || null
+		}
+	} catch (_) {
+		return null
+	}
+}
+
+const build_client_context = () => {
+	const current_skill = read_current_skill()
+	const ctx = {
+		source: 'cli',
+		cli_version: CLI_VERSION,
+		node_version: process.version,
+		os: process.platform,
+		arch: process.arch,
+		cwd_is_skill_dir: !!current_skill,
+	}
+	if (current_skill) ctx.current_skill = current_skill
+	return scrub(ctx)
+}
+
+const MAX_ATTACHMENTS = 10
+const MAX_ATTACHMENT_BYTES = 1 * 1000 * 1000   // 1 MB post-compression — matches API MAX_FEEDBACK_ATTACHMENT_BYTES
+
+const parse_attach_paths = (raw_value) => {
+	if (!raw_value) return []
+	const items = String(raw_value).split(',').map(s => s.trim()).filter(Boolean)
+	if (items.length > MAX_ATTACHMENTS) {
+		throw new UsageError(`At most ${MAX_ATTACHMENTS} attachments are allowed.`)
+	}
+	for (const p of items) {
+		if (!fs.existsSync(p)) {
+			throw new UsageError(`Attachment not found: ${p}`)
+		}
+	}
+	return items
+}
+
+const upload_attachments = (feedback_id, attach_paths, opts) => catch_errors('Failed to upload attachments', async () => {
+	const { print_progress } = opts
+	// Lazy import — keeps jimp out of the require graph for non-feedback commands.
+	const { compress_image } = require('../utils/image_compression')
+
+	const uploaded = []
+	for (let i = 0; i < attach_paths.length; i++) {
+		const src = attach_paths[i]
+		if (print_progress) print_progress(`Compressing ${path.basename(src)} (${i + 1}/${attach_paths.length})`)
+
+		const [c_err, compressed] = await compress_image(src)
+		if (c_err) throw e(`Failed to compress ${src}`, c_err)
+
+		// Early bail before paying for an initiate round-trip if the compressed
+		// image still exceeds the per-image cap. Server enforces the same limit;
+		// this is a clean local error rather than a 413 round trip away.
+		if (compressed.bytes > MAX_ATTACHMENT_BYTES) {
+			throw new UsageError(`Compressed "${path.basename(src)}" is ${compressed.bytes} bytes — exceeds the ${MAX_ATTACHMENT_BYTES}-byte (1 MB) per-image cap. Try cropping or sending a smaller region.`)
+		}
+
+		const [init_err, init] = await feedback_api.initiate_attachment_upload(feedback_id, {
+			bytes: compressed.bytes,
+			content_type: 'image/jpeg',
+			original_name: path.basename(src),
+		})
+		if (init_err) throw e(`Failed to initiate upload for ${src}`, init_err)
+
+		if (print_progress) print_progress(`Uploading ${path.basename(src)} (${i + 1}/${attach_paths.length})`)
+		const [put_err] = await feedback_api.put_attachment_to_s3(init.upload_url, compressed.buffer)
+		if (put_err) throw e(`S3 upload failed for ${src}`, put_err)
+
+		const [comp_err, comp] = await feedback_api.complete_attachment_upload(feedback_id, {
+			upload_id: init.upload_id,
+			bytes: compressed.bytes,
+			width: compressed.width,
+			height: compressed.height,
+			original_name: path.basename(src),
+		})
+		if (comp_err) throw e(`Failed to confirm upload for ${src}`, comp_err)
+
+		uploaded.push(comp.attachment)
+	}
+	return uploaded
+})
+
+const run = (args) => catch_errors('Feedback command failed', async () => {
+	if (args.flags._show_help) {
+		print_help(HELP_TEXT)
+		return process.exit(EXIT_CODES.SUCCESS)
+	}
+
+	const json_mode = !!args.flags.json
+	const category = args._[0]
+	const body_positional = args._.slice(1).join(' ').trim()
+
+	if (!category) {
+		throw new UsageError(`Category is required. One of: ${Array.from(VALID_CATEGORIES).join(' | ')}`)
+	}
+	if (!VALID_CATEGORIES.has(category)) {
+		throw new UsageError(`Invalid category "${category}". Must be one of: ${Array.from(VALID_CATEGORIES).join(' | ')}`)
+	}
+
+	let body = body_positional
+	if (!body) {
+		if (json_mode) {
+			// In agentic / scripted contexts we can't open an editor — fail fast.
+			throw new UsageError('In --json mode the feedback body must be passed as a positional argument; the editor fallback is interactive.')
+		}
+		body = try_editor_for_body()
+		if (!body) {
+			throw new UsageError('No feedback body was entered. Aborted.')
+		}
+	}
+
+	const subject = args.flags.subject && typeof args.flags.subject === 'string' ? args.flags.subject : null
+	const attach_paths = parse_attach_paths(args.flags.attach)
+
+	// Auth required — surfaces a clean AuthError exit code 3 on no/expired token.
+	await require_token()
+
+	const client_context = build_client_context()
+
+	const [create_err, create_result] = await feedback_api.create_feedback({
+		category,
+		subject,
+		body,
+		client_context,
+	})
+	if (create_err) throw e('Failed to create feedback', create_err)
+
+	const { feedback, next_step } = create_result
+
+	// Attachment phase
+	let attachments = []
+	if (attach_paths.length > 0) {
+		const print_progress = json_mode ? null : (msg) => print_info(msg)
+		const [upload_err, uploaded] = await upload_attachments(feedback.id, attach_paths, { print_progress })
+		if (upload_err) throw e('Attachment upload failed', upload_err)
+		attachments = uploaded
+	}
+
+	if (json_mode) {
+		// Universal CLI envelope shape. The skill's envelope-reader (per spec
+		// § 11) consumes `next_step` at the response root.
+		const data = { feedback, attachments }
+		print_json({ data, error: null, next_step })
+		return
+	}
+
+	// Human-readable
+	const short_id = String(feedback.id).slice(0, 8)
+	print_success(`Feedback recorded (#${short_id}).`)
+	if (attachments.length > 0) {
+		print_info(`Uploaded ${attachments.length} attachment${attachments.length === 1 ? '' : 's'}.`)
+	} else if (next_step && next_step.attachments_supported && attach_paths.length === 0) {
+		print_hint(`Pass --attach <path> to add a screenshot (max ${next_step.max_attachments}).`)
+	}
+}).then(([errors]) => { if (errors) { exit_with_error(errors); return } })
+
+module.exports = { run }

package/src/constants.js

@@ -77,7 +77,8 @@ const COMMANDS = [
 	'postlex',
 	'snapshot',
 	'reconcile',
-	'release'
+	'release',
+	'feedback'
 ]
 
 module.exports = {

package/src/index.js

@@ -116,6 +116,7 @@ Commands:
   snapshot <sub>           Capture and restore skill state (create, list, restore, delete, prune)
   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)
 
 Global flags:
   --help                   Show help for a command

package/src/utils/image_compression.js

@@ -0,0 +1,70 @@
+// Spec 260524-01 § 8.3 — CLI-side image compression for feedback attachments.
+//
+// FOOTPRINT DISCIPLINE (D8): this module cherry-picks @jimp/core +
+// @jimp/js-jpeg + @jimp/js-png + @jimp/plugin-resize from jimp 1.x. We
+// deliberately do NOT depend on the `jimp` meta-package — that pulls in
+// BMP, GIF, TIFF, blur, color, mask, threshold, dither, print, hash, blit,
+// circle, contain, cover, crop, displace, fisheye, flip, mask, quantize,
+// rotate, and a half-dozen more plugins we don't need.
+//
+// WEBP NOTE: jimp 1.x does NOT ship a WebP codec sub-package. CLI accepts
+// PNG and JPEG only; the web surface still accepts WebP via
+// `browser-image-compression`. Spec § 8.3's fallback explicitly anticipates
+// this drop ("drop @jimp/webp" — but in practice there's no such package).
+//
+// LAZY-LOAD: this module is dynamically imported only when the feedback
+// command actually has --attach arguments (see commands/feedback.js). Every
+// other CLI command — install, search, publish, etc. — pays zero require
+// cost for jimp.
+
+const { error: { catch_errors, wrap_errors: e } } = require('puffy-core')
+
+const MAX_DIMENSION = 2000
+const JPEG_QUALITY = 80
+
+const get_default = (m) => (m && m.default !== undefined) ? m.default : m
+
+let _Jimp = null
+
+const get_jimp = () => {
+	if (_Jimp) return _Jimp
+	const { createJimp } = require('@jimp/core')
+	const jpeg = get_default(require('@jimp/js-jpeg'))
+	const png = get_default(require('@jimp/js-png'))
+	const resize = get_default(require('@jimp/plugin-resize'))
+	_Jimp = createJimp({ formats: [jpeg, png], plugins: [resize] })
+	return _Jimp
+}
+
+// Returns { buffer, bytes, width, height } — JPEG-encoded, longest side
+// ≤ 2000 px, quality 80. Accepts PNG or JPEG input.
+const compress_image = (file_path) => catch_errors('Image compression failed', async () => {
+	const Jimp = get_jimp()
+	let img
+	try {
+		img = await Jimp.read(file_path)
+	} catch (err) {
+		throw e(`Could not read image at ${file_path} — only PNG and JPEG are supported on the CLI`, [err])
+	}
+
+	const { width, height } = img.bitmap
+	if (width > MAX_DIMENSION || height > MAX_DIMENSION) {
+		// scale proportionally so longest side = MAX_DIMENSION
+		if (width >= height) {
+			img.resize({ w: MAX_DIMENSION })
+		} else {
+			img.resize({ h: MAX_DIMENSION })
+		}
+	}
+
+	const buffer = await img.getBuffer('image/jpeg', { quality: JPEG_QUALITY })
+
+	return {
+		buffer,
+		bytes: buffer.length,
+		width: img.bitmap.width,
+		height: img.bitmap.height
+	}
+})
+
+module.exports = { compress_image, MAX_DIMENSION, JPEG_QUALITY }

package/src/utils/scrub_secrets.js

@@ -0,0 +1,49 @@
+// Spec 260524-01 § 12 — Secret scrubbing applied to feedback `client_context`
+// before it leaves the CLI. Must match the rules in web/src/lib/scrub-secrets.js.
+//
+// Rules:
+//   1. Strip OpenAI API keys (sk-...)
+//   2. Strip GitHub tokens (ghp_..., gho_...)
+//   3. Strip Cognito JWT-shaped tokens (eyJ...)
+//   4. Strip values for env-var keys ending in _TOKEN, _KEY, _SECRET, _PASSWORD
+//
+// The replacement is the literal string `<redacted>` so callers can see that
+// a value WAS present and got stripped — vs missing entirely.
+
+const REDACTED = '<redacted>'
+
+const PATTERNS = [
+	/sk-[A-Za-z0-9_-]{20,}/g,      // OpenAI keys
+	/ghp_[A-Za-z0-9]{30,}/g,       // GitHub personal access tokens
+	/gho_[A-Za-z0-9]{30,}/g,       // GitHub OAuth tokens
+	/eyJ[A-Za-z0-9_-]+\.eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+/g  // JWT shape
+]
+
+const SENSITIVE_KEY = /(_TOKEN|_KEY|_SECRET|_PASSWORD|_API_KEY)$/i
+
+const scrub_string = (value) => {
+	let out = value
+	for (const re of PATTERNS) out = out.replace(re, REDACTED)
+	return out
+}
+
+// Recursively walk an object, scrubbing string values and redacting values
+// whose key looks sensitive (e.g. `OPENAI_API_KEY`).
+const scrub = (value) => {
+	if (value == null) return value
+	if (typeof value === 'string') return scrub_string(value)
+	if (typeof value !== 'object') return value
+	if (Array.isArray(value)) return value.map(scrub)
+
+	const out = {}
+	for (const [key, v] of Object.entries(value)) {
+		if (typeof v === 'string' && SENSITIVE_KEY.test(key)) {
+			out[key] = REDACTED
+		} else {
+			out[key] = scrub(v)
+		}
+	}
+	return out
+}
+
+module.exports = { scrub, scrub_string, REDACTED }