happyskills 0.48.0 → 0.50.0

package/src/snapshot/storage.js

@@ -0,0 +1,237 @@
+const fs = require('fs')
+const path = require('path')
+const crypto = require('crypto')
+const { error: { catch_errors, wrap_errors: e } } = require('puffy-core')
+const { ensure_dir, read_json, file_exists } = require('../utils/fs')
+const { hash_directory } = require('../lock/integrity')
+const {
+	skill_snapshots_dir,
+	snapshot_dir,
+	snapshot_manifest_path,
+	snapshot_content_dir
+} = require('./paths')
+
+const DEFAULT_RETENTION = 10
+
+// Combine the directory hash with a deterministic lock-entry serialization so
+// the snapshot_state_hash uniquely identifies the full state being preserved.
+// If two snapshots share the same hash, restoring either produces the same
+// outcome — useful for list/dedup ergonomics.
+const compute_skill_state_hash = (dir_integrity, lock_entry) => {
+	const lock_serialized = JSON.stringify(lock_entry || null, Object.keys(lock_entry || {}).sort())
+	const h = crypto.createHash('sha256')
+	h.update(dir_integrity || '')
+	h.update('|')
+	h.update(lock_serialized)
+	return `sha256-${h.digest('hex')}`
+}
+
+const make_snapshot_id = (state_hash) => {
+	const ts = new Date().toISOString().replace(/[:.]/g, '').replace('Z', 'Z')
+	const short = state_hash.replace(/^sha256-/, '').slice(0, 12)
+	return `snap_${ts}_${short}`
+}
+
+// Atomic recursive copy: copy into a sibling .tmp then rename into place.
+// rename() is atomic on the same filesystem, so the snapshot is either fully
+// present or absent — no half-copied states.
+const copy_dir = async (src, dst) => {
+	await fs.promises.cp(src, dst, { recursive: true, force: true, errorOnExist: false })
+}
+
+const create = (options) => catch_errors('Failed to create snapshot', async () => {
+	const { skill_dir, workspace, skill, lock_entry, note, is_global, project_root, retention } = options
+	if (!workspace || !skill) throw new Error('workspace and skill are required')
+	if (!skill_dir) throw new Error('skill_dir is required')
+
+	const [, dir_present] = await file_exists(skill_dir)
+	if (!dir_present) throw new Error(`Cannot snapshot — skill directory does not exist: ${skill_dir}`)
+
+	const [hash_err, dir_integrity] = await hash_directory(skill_dir)
+	if (hash_err) throw e('Failed to hash skill directory', hash_err)
+
+	const state_hash = compute_skill_state_hash(dir_integrity, lock_entry)
+	const snapshot_id = make_snapshot_id(state_hash)
+	const dest = snapshot_dir(is_global, project_root, workspace, skill, snapshot_id)
+	const content_dest = snapshot_content_dir(dest)
+
+	const [parent_err] = await ensure_dir(path.dirname(dest))
+	if (parent_err) throw e('Failed to ensure snapshots parent dir', parent_err)
+
+	const tmp_dest = `${dest}.tmp-${process.pid}-${Date.now()}`
+	const tmp_content = path.join(tmp_dest, 'content')
+	await fs.promises.mkdir(tmp_dest, { recursive: true })
+	await copy_dir(skill_dir, tmp_content)
+
+	const manifest = {
+		snapshot_id,
+		timestamp: new Date().toISOString(),
+		skill_state_hash: state_hash,
+		workspace,
+		skill,
+		dir_integrity,
+		note: note || null,
+		lock_entry: lock_entry || null
+	}
+	await fs.promises.writeFile(
+		path.join(tmp_dest, 'manifest.json'),
+		JSON.stringify(manifest, null, '\t') + '\n',
+		'utf-8'
+	)
+
+	await fs.promises.rename(tmp_dest, dest)
+
+	const keep = typeof retention === 'number' ? retention : DEFAULT_RETENTION
+	const [, prune_result] = await prune({ workspace, skill, is_global, project_root, keep })
+
+	return {
+		snapshot_id,
+		path: dest,
+		timestamp: manifest.timestamp,
+		skill_state_hash: state_hash,
+		note: manifest.note,
+		pruned: prune_result?.deleted_ids || []
+	}
+})
+
+const list = (options) => catch_errors('Failed to list snapshots', async () => {
+	const { workspace, skill, is_global, project_root } = options
+	const skill_dir = skill_snapshots_dir(is_global, project_root, workspace, skill)
+	const [, present] = await file_exists(skill_dir)
+	if (!present) return { snapshots: [] }
+	const entries = await fs.promises.readdir(skill_dir, { withFileTypes: true })
+	const snapshots = []
+	for (const entry of entries) {
+		if (!entry.isDirectory()) continue
+		if (!entry.name.startsWith('snap_')) continue
+		const dest = path.join(skill_dir, entry.name)
+		const [, manifest] = await read_json(snapshot_manifest_path(dest))
+		if (!manifest) continue
+		snapshots.push({
+			snapshot_id: manifest.snapshot_id,
+			timestamp: manifest.timestamp,
+			skill_state_hash: manifest.skill_state_hash,
+			note: manifest.note,
+			path: dest
+		})
+	}
+	snapshots.sort((a, b) => (a.timestamp < b.timestamp ? 1 : -1))
+	return { snapshots }
+})
+
+const find_snapshot = (snapshot_id, options) => catch_errors('Failed to find snapshot', async () => {
+	const { is_global, project_root } = options
+	const { snapshots_root } = require('./paths')
+	const root = snapshots_root(is_global, project_root)
+	const [, root_present] = await file_exists(root)
+	if (!root_present) return null
+	const workspaces = await fs.promises.readdir(root, { withFileTypes: true })
+	for (const ws of workspaces) {
+		if (!ws.isDirectory()) continue
+		const ws_dir = path.join(root, ws.name)
+		const skills = await fs.promises.readdir(ws_dir, { withFileTypes: true })
+		for (const sk of skills) {
+			if (!sk.isDirectory()) continue
+			const candidate = path.join(ws_dir, sk.name, snapshot_id)
+			const [, present] = await file_exists(candidate)
+			if (present) {
+				const [, manifest] = await read_json(snapshot_manifest_path(candidate))
+				if (manifest) return { manifest, path: candidate, workspace: ws.name, skill: sk.name }
+			}
+		}
+	}
+	return null
+})
+
+// Restore atomically: copy snapshot/content into a sibling .restore-tmp, then
+// swap it with the live skill directory. The previous live directory is moved
+// to a .pre-restore-* path next to it so the operation is fully reversible.
+const restore = (snapshot_id, options) => catch_errors('Failed to restore snapshot', async () => {
+	const { skill_dir, is_global, project_root, verify_hash } = options
+	if (!skill_dir) throw new Error('skill_dir is required for restore')
+
+	const [find_err, found] = await find_snapshot(snapshot_id, { is_global, project_root })
+	if (find_err) throw e('Failed to look up snapshot', find_err)
+	if (!found) throw new Error(`Snapshot not found: ${snapshot_id}`)
+
+	const content_src = snapshot_content_dir(found.path)
+	const [, content_present] = await file_exists(content_src)
+	if (!content_present) throw new Error(`Snapshot content missing: ${content_src}`)
+
+	if (verify_hash !== false && found.manifest.dir_integrity) {
+		const [hash_err, current_snap_hash] = await hash_directory(content_src)
+		if (!hash_err && current_snap_hash !== found.manifest.dir_integrity) {
+			throw new Error(`SNAPSHOT_CORRUPTED: ${snapshot_id} content hash does not match manifest`)
+		}
+	}
+
+	const parent = path.dirname(skill_dir)
+	await ensure_dir(parent)
+	const restore_tmp = `${skill_dir}.restore-tmp-${process.pid}-${Date.now()}`
+	await copy_dir(content_src, restore_tmp)
+
+	const [, live_present] = await file_exists(skill_dir)
+	const trash = `${skill_dir}.pre-restore-${process.pid}-${Date.now()}`
+	if (live_present) {
+		await fs.promises.rename(skill_dir, trash)
+	}
+	try {
+		await fs.promises.rename(restore_tmp, skill_dir)
+	} catch (err) {
+		// Best-effort rollback if rename of restored content fails.
+		if (live_present) {
+			await fs.promises.rename(trash, skill_dir).catch(() => {})
+		}
+		throw e('Failed to swap restored content into place', err)
+	}
+	if (live_present) {
+		await fs.promises.rm(trash, { recursive: true, force: true }).catch(() => {})
+	}
+
+	return {
+		restored: true,
+		snapshot_id,
+		workspace: found.workspace,
+		skill: found.skill,
+		path: found.path,
+		version: found.manifest.lock_entry?.version || null
+	}
+})
+
+const remove = (snapshot_id, options) => catch_errors('Failed to delete snapshot', async () => {
+	const { is_global, project_root } = options
+	const [, found] = await find_snapshot(snapshot_id, { is_global, project_root })
+	if (!found) return { deleted: false, snapshot_id, reason: 'not_found' }
+	await fs.promises.rm(found.path, { recursive: true, force: true })
+	return { deleted: true, snapshot_id }
+})
+
+const prune = (options) => catch_errors('Failed to prune snapshots', async () => {
+	const { workspace, skill, is_global, project_root, keep } = options
+	const k = typeof keep === 'number' && keep >= 0 ? keep : DEFAULT_RETENTION
+	const [, listing] = await list({ workspace, skill, is_global, project_root })
+	if (!listing || !listing.snapshots) return { kept: 0, deleted: 0, deleted_ids: [] }
+	const sorted = listing.snapshots
+	const to_keep = sorted.slice(0, k)
+	const to_delete = sorted.slice(k)
+	for (const snap of to_delete) {
+		await fs.promises.rm(snap.path, { recursive: true, force: true })
+	}
+	return {
+		kept: to_keep.length,
+		deleted: to_delete.length,
+		deleted_ids: to_delete.map(s => s.snapshot_id)
+	}
+})
+
+module.exports = {
+	create,
+	list,
+	restore,
+	remove,
+	prune,
+	find_snapshot,
+	compute_skill_state_hash,
+	make_snapshot_id,
+	DEFAULT_RETENTION
+}

package/src/snapshot/storage.test.js

@@ -0,0 +1,298 @@
+'use strict'
+const { describe, it } = require('node:test')
+const assert = require('node:assert/strict')
+const fs = require('fs')
+const path = require('path')
+const os = require('os')
+
+const storage = require('./storage')
+const { clear_integrity_cache } = require('../lock/integrity')
+
+const make_tmp = () => fs.mkdtempSync(path.join(os.tmpdir(), 'hs-snapshot-test-'))
+const cleanup = (dir) => fs.rmSync(dir, { recursive: true, force: true })
+
+const write_skill = (skill_dir, files) => {
+	fs.mkdirSync(skill_dir, { recursive: true })
+	for (const [rel, content] of Object.entries(files)) {
+		const full = path.join(skill_dir, rel)
+		fs.mkdirSync(path.dirname(full), { recursive: true })
+		fs.writeFileSync(full, content)
+	}
+}
+
+describe('snapshot.compute_skill_state_hash', () => {
+	it('is deterministic for identical inputs', () => {
+		const a = storage.compute_skill_state_hash('sha256-abc', { version: '1.0.0', commit: 'x' })
+		const b = storage.compute_skill_state_hash('sha256-abc', { version: '1.0.0', commit: 'x' })
+		assert.strictEqual(a, b)
+		assert.match(a, /^sha256-[0-9a-f]{64}$/)
+	})
+
+	it('differs when content hash changes', () => {
+		const a = storage.compute_skill_state_hash('sha256-abc', { version: '1.0.0' })
+		const b = storage.compute_skill_state_hash('sha256-def', { version: '1.0.0' })
+		assert.notStrictEqual(a, b)
+	})
+
+	it('differs when lock entry changes', () => {
+		const a = storage.compute_skill_state_hash('sha256-abc', { version: '1.0.0' })
+		const b = storage.compute_skill_state_hash('sha256-abc', { version: '1.0.1' })
+		assert.notStrictEqual(a, b)
+	})
+
+	it('order of lock-entry keys does not affect the hash', () => {
+		const a = storage.compute_skill_state_hash('sha256-abc', { version: '1.0.0', commit: 'x', integrity: 'y' })
+		const b = storage.compute_skill_state_hash('sha256-abc', { integrity: 'y', commit: 'x', version: '1.0.0' })
+		assert.strictEqual(a, b)
+	})
+})
+
+describe('snapshot.create', () => {
+	it('captures skill directory contents and manifest', async () => {
+		const root = make_tmp()
+		clear_integrity_cache()
+		try {
+			const skill_dir = path.join(root, '.agents', 'skills', 'my-skill')
+			write_skill(skill_dir, {
+				'skill.json': JSON.stringify({ name: 'my-skill', version: '1.0.0' }),
+				'SKILL.md': '---\nname: my-skill\ndescription: test\n---\nbody\n'
+			})
+			const lock_entry = { version: '1.0.0', commit: 'abc', integrity: 'sha256-x' }
+			const [err, result] = await storage.create({
+				skill_dir, workspace: 'acme', skill: 'my-skill', lock_entry,
+				is_global: false, project_root: root, note: 'pre-test'
+			})
+			assert.strictEqual(err, null)
+			assert.match(result.snapshot_id, /^snap_/)
+			assert.match(result.skill_state_hash, /^sha256-/)
+			assert.strictEqual(result.note, 'pre-test')
+			assert.ok(fs.existsSync(result.path), 'snapshot dir must exist')
+			assert.ok(fs.existsSync(path.join(result.path, 'manifest.json')), 'manifest must exist')
+			assert.ok(fs.existsSync(path.join(result.path, 'content', 'skill.json')), 'content/skill.json must exist')
+			assert.ok(fs.existsSync(path.join(result.path, 'content', 'SKILL.md')), 'content/SKILL.md must exist')
+			const manifest = JSON.parse(fs.readFileSync(path.join(result.path, 'manifest.json'), 'utf-8'))
+			assert.strictEqual(manifest.workspace, 'acme')
+			assert.strictEqual(manifest.skill, 'my-skill')
+			assert.deepEqual(manifest.lock_entry, lock_entry)
+		} finally { cleanup(root); clear_integrity_cache() }
+	})
+
+	it('fails when the skill directory does not exist', async () => {
+		const root = make_tmp()
+		clear_integrity_cache()
+		try {
+			const skill_dir = path.join(root, '.agents', 'skills', 'ghost')
+			const [err] = await storage.create({
+				skill_dir, workspace: 'acme', skill: 'ghost',
+				is_global: false, project_root: root
+			})
+			assert.notStrictEqual(err, null)
+		} finally { cleanup(root); clear_integrity_cache() }
+	})
+})
+
+describe('snapshot.list', () => {
+	it('returns empty list when no snapshots exist', async () => {
+		const root = make_tmp()
+		try {
+			const [err, result] = await storage.list({
+				workspace: 'acme', skill: 'no-such', is_global: false, project_root: root
+			})
+			assert.strictEqual(err, null)
+			assert.deepEqual(result.snapshots, [])
+		} finally { cleanup(root) }
+	})
+
+	it('lists created snapshots newest-first', async () => {
+		const root = make_tmp()
+		clear_integrity_cache()
+		try {
+			const skill_dir = path.join(root, '.agents', 'skills', 'multi')
+			write_skill(skill_dir, { 'skill.json': '{"name":"multi","version":"1.0.0"}' })
+			const [, first] = await storage.create({
+				skill_dir, workspace: 'acme', skill: 'multi', lock_entry: { version: '1.0.0' },
+				is_global: false, project_root: root, note: 'first'
+			})
+			// Force the integrity cache to recompute so the second snapshot has a
+			// distinct content hash and thus a distinct snapshot_id.
+			clear_integrity_cache()
+			fs.writeFileSync(path.join(skill_dir, 'skill.json'), '{"name":"multi","version":"1.0.1"}')
+			// Sleep 10ms to guarantee a different timestamp in the id.
+			await new Promise(r => setTimeout(r, 10))
+			const [, second] = await storage.create({
+				skill_dir, workspace: 'acme', skill: 'multi', lock_entry: { version: '1.0.1' },
+				is_global: false, project_root: root, note: 'second'
+			})
+			const [, listing] = await storage.list({
+				workspace: 'acme', skill: 'multi', is_global: false, project_root: root
+			})
+			assert.strictEqual(listing.snapshots.length, 2)
+			assert.strictEqual(listing.snapshots[0].snapshot_id, second.snapshot_id, 'newest is first')
+			assert.strictEqual(listing.snapshots[1].snapshot_id, first.snapshot_id)
+		} finally { cleanup(root); clear_integrity_cache() }
+	})
+})
+
+describe('snapshot.restore', () => {
+	it('restores a captured directory bit-for-bit', async () => {
+		const root = make_tmp()
+		clear_integrity_cache()
+		try {
+			const skill_dir = path.join(root, '.agents', 'skills', 'restorable')
+			write_skill(skill_dir, {
+				'skill.json': '{"name":"restorable","version":"1.0.0"}',
+				'SKILL.md': 'original body\n',
+				'references/foo.md': 'original reference\n'
+			})
+			const [, snap] = await storage.create({
+				skill_dir, workspace: 'acme', skill: 'restorable',
+				lock_entry: { version: '1.0.0' },
+				is_global: false, project_root: root
+			})
+
+			// Mutate the live directory after snapshot.
+			fs.writeFileSync(path.join(skill_dir, 'SKILL.md'), 'mutated body\n')
+			fs.writeFileSync(path.join(skill_dir, 'skill.json'), '{"name":"restorable","version":"9.9.9"}')
+			fs.rmSync(path.join(skill_dir, 'references'), { recursive: true })
+
+			const [err, result] = await storage.restore(snap.snapshot_id, {
+				skill_dir, is_global: false, project_root: root
+			})
+			assert.strictEqual(err, null)
+			assert.strictEqual(result.restored, true)
+			assert.strictEqual(
+				fs.readFileSync(path.join(skill_dir, 'SKILL.md'), 'utf-8'),
+				'original body\n'
+			)
+			assert.strictEqual(
+				fs.readFileSync(path.join(skill_dir, 'skill.json'), 'utf-8'),
+				'{"name":"restorable","version":"1.0.0"}'
+			)
+			assert.strictEqual(
+				fs.readFileSync(path.join(skill_dir, 'references', 'foo.md'), 'utf-8'),
+				'original reference\n'
+			)
+		} finally { cleanup(root); clear_integrity_cache() }
+	})
+
+	it('refuses corrupted snapshots', async () => {
+		const root = make_tmp()
+		clear_integrity_cache()
+		try {
+			const skill_dir = path.join(root, '.agents', 'skills', 'corrupt-snap')
+			write_skill(skill_dir, { 'skill.json': '{"name":"corrupt-snap","version":"1.0.0"}' })
+			const [, snap] = await storage.create({
+				skill_dir, workspace: 'acme', skill: 'corrupt-snap',
+				lock_entry: { version: '1.0.0' },
+				is_global: false, project_root: root
+			})
+			// Tamper with snapshot content but leave manifest's expected hash in place.
+			fs.writeFileSync(path.join(snap.path, 'content', 'skill.json'), '{"name":"tampered","version":"9.9.9"}')
+
+			const [err] = await storage.restore(snap.snapshot_id, {
+				skill_dir, is_global: false, project_root: root
+			})
+			assert.notStrictEqual(err, null)
+			const messages = err.map(x => x?.message || '').join('|')
+			assert.match(messages, /SNAPSHOT_CORRUPTED/)
+		} finally { cleanup(root); clear_integrity_cache() }
+	})
+
+	it('throws when the snapshot id is unknown', async () => {
+		const root = make_tmp()
+		try {
+			const skill_dir = path.join(root, '.agents', 'skills', 'whatever')
+			const [err] = await storage.restore('snap_doesnotexist_000000000000', {
+				skill_dir, is_global: false, project_root: root
+			})
+			assert.notStrictEqual(err, null)
+		} finally { cleanup(root) }
+	})
+})
+
+describe('snapshot.remove', () => {
+	it('removes a snapshot directory', async () => {
+		const root = make_tmp()
+		clear_integrity_cache()
+		try {
+			const skill_dir = path.join(root, '.agents', 'skills', 'rmable')
+			write_skill(skill_dir, { 'skill.json': '{"name":"rmable","version":"1.0.0"}' })
+			const [, snap] = await storage.create({
+				skill_dir, workspace: 'acme', skill: 'rmable', lock_entry: { version: '1.0.0' },
+				is_global: false, project_root: root
+			})
+			const [err, result] = await storage.remove(snap.snapshot_id, { is_global: false, project_root: root })
+			assert.strictEqual(err, null)
+			assert.strictEqual(result.deleted, true)
+			assert.ok(!fs.existsSync(snap.path), 'snapshot dir should be gone')
+		} finally { cleanup(root); clear_integrity_cache() }
+	})
+
+	it('reports not_found for unknown ids', async () => {
+		const root = make_tmp()
+		try {
+			const [err, result] = await storage.remove('snap_nope_xxx', { is_global: false, project_root: root })
+			assert.strictEqual(err, null)
+			assert.strictEqual(result.deleted, false)
+			assert.strictEqual(result.reason, 'not_found')
+		} finally { cleanup(root) }
+	})
+})
+
+describe('snapshot.prune', () => {
+	it('keeps the N most recent and deletes the rest', async () => {
+		const root = make_tmp()
+		clear_integrity_cache()
+		try {
+			const skill_dir = path.join(root, '.agents', 'skills', 'prune-me')
+			// Make 5 snapshots, vary content so each gets a distinct id.
+			const created_ids = []
+			for (let i = 0; i < 5; i++) {
+				clear_integrity_cache()
+				write_skill(skill_dir, { 'skill.json': `{"name":"prune-me","version":"1.0.${i}"}` })
+				await new Promise(r => setTimeout(r, 5))
+				const [, snap] = await storage.create({
+					skill_dir, workspace: 'acme', skill: 'prune-me', lock_entry: { version: `1.0.${i}` },
+					is_global: false, project_root: root, retention: 100
+				})
+				created_ids.push(snap.snapshot_id)
+			}
+			const [err, result] = await storage.prune({
+				workspace: 'acme', skill: 'prune-me', is_global: false, project_root: root, keep: 2
+			})
+			assert.strictEqual(err, null)
+			assert.strictEqual(result.kept, 2)
+			assert.strictEqual(result.deleted, 3)
+			assert.strictEqual(result.deleted_ids.length, 3)
+			// The 3 oldest should be deleted (created_ids[0..2]).
+			for (const old of created_ids.slice(0, 3)) {
+				assert.ok(result.deleted_ids.includes(old), `oldest ${old} should be deleted`)
+			}
+		} finally { cleanup(root); clear_integrity_cache() }
+	})
+
+	it('auto-prunes on create when default retention is hit', async () => {
+		const root = make_tmp()
+		clear_integrity_cache()
+		try {
+			const skill_dir = path.join(root, '.agents', 'skills', 'auto-prune')
+			let last
+			for (let i = 0; i < 12; i++) {
+				clear_integrity_cache()
+				write_skill(skill_dir, { 'skill.json': `{"name":"auto-prune","version":"1.0.${i}"}` })
+				await new Promise(r => setTimeout(r, 5))
+				const [, snap] = await storage.create({
+					skill_dir, workspace: 'acme', skill: 'auto-prune', lock_entry: { version: `1.0.${i}` },
+					is_global: false, project_root: root
+					// no retention override — uses DEFAULT_RETENTION=10
+				})
+				last = snap
+			}
+			const [, listing] = await storage.list({
+				workspace: 'acme', skill: 'auto-prune', is_global: false, project_root: root
+			})
+			assert.strictEqual(listing.snapshots.length, 10, 'should keep exactly 10 (DEFAULT_RETENTION)')
+			assert.strictEqual(listing.snapshots[0].snapshot_id, last.snapshot_id, 'newest must survive')
+		} finally { cleanup(root); clear_integrity_cache() }
+	})
+})

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 }