happyskills 0.48.0 → 0.49.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/validation/file_size_rules.js

@@ -1,27 +1,34 @@
 const fs = require('fs')
 const path = require('path')
 const { error: { catch_errors } } = require('puffy-core')
+const { MAX_FILE_SIZE, MAX_TOTAL_SIZE } = require('../config/limits')
 
-const MAX_FILE_SIZE = 1 * 1024 * 1024 // 1MB
+const MAX_FILE_SIZE_MB = MAX_FILE_SIZE / (1024 * 1024)
+const MAX_TOTAL_SIZE_MB = MAX_TOTAL_SIZE / (1024 * 1024)
 
-const result = (file, actual_size) => ({
+const file_result = (file, actual_size) => ({
 	file,
 	field: null,
 	rule: 'max_file_size',
 	severity: 'error',
-	message: `File exceeds 1MB limit (${(actual_size / (1024 * 1024)).toFixed(2)}MB)`
+	message: `File exceeds ${MAX_FILE_SIZE_MB}MB limit (${(actual_size / (1024 * 1024)).toFixed(2)}MB)`
+})
+
+const total_result = (actual_size) => ({
+	file: null,
+	field: null,
+	rule: 'max_total_size',
+	severity: 'error',
+	message: `Skill bundle exceeds ${MAX_TOTAL_SIZE_MB}MB limit (${(actual_size / (1024 * 1024)).toFixed(2)}MB)`
 })
 
 /**
- * Scans all files in a skill directory and checks that none exceed the max file size.
- * Returns error results for each file that exceeds the limit.
+ * Scans all files in a skill directory and checks both per-file and total bundle size.
  * Skips dotfiles and common non-publishable directories (consistent with hash_directory exclusions).
- *
- * @param {string} skill_dir - Absolute path to the skill directory
- * @returns {[errors, results[]]} — results with severity 'error' for each oversized file
  */
 const validate_file_sizes = (skill_dir) => catch_errors('Failed to check file sizes', async () => {
 	const results = []
+	let total_size = 0
 	const walk = async (dir, prefix) => {
 		let items
 		try { items = await fs.promises.readdir(dir, { withFileTypes: true }) } catch { return }
@@ -36,12 +43,16 @@ const validate_file_sizes = (skill_dir) => catch_errors('Failed to check file si
 				let stat
 				try { stat = await fs.promises.stat(full) } catch { continue }
 				if (stat.size > MAX_FILE_SIZE) {
-					results.push(result(rel, stat.size))
+					results.push(file_result(rel, stat.size))
 				}
+				total_size += stat.size
 			}
 		}
 	}
 	await walk(skill_dir, '')
+	if (total_size > MAX_TOTAL_SIZE) {
+		results.push(total_result(total_size))
+	}
 	return results
 })
 

package/src/validation/file_size_rules.test.js

@@ -4,8 +4,7 @@ const fs = require('fs')
 const path = require('path')
 const os = require('os')
 const { validate_file_sizes } = require('./file_size_rules')
-
-const MAX_FILE_SIZE = 1 * 1024 * 1024 // 1MB
+const { MAX_FILE_SIZE, MAX_TOTAL_SIZE } = require('../config/limits')
 
 const make_temp_dir = () => fs.mkdtempSync(path.join(os.tmpdir(), 'file-size-test-'))
 const clean = (dir) => fs.rmSync(dir, { recursive: true, force: true })
@@ -16,41 +15,47 @@ describe('validate_file_sizes', () => {
 	beforeEach(() => { dir = make_temp_dir() })
 	afterEach(() => { clean(dir) })
 
-	it('returns empty for files under 1MB limit', async () => {
+	it('returns empty for files under the limit', async () => {
 		fs.writeFileSync(path.join(dir, 'small.txt'), 'hello world')
 		const [err, results] = await validate_file_sizes(dir)
 		assert.strictEqual(err, null)
 		assert.strictEqual(results.length, 0)
 	})
 
-	it('returns error for file exceeding 1MB', async () => {
+	it('returns max_file_size error for a single file exceeding MAX_FILE_SIZE', async () => {
 		fs.writeFileSync(path.join(dir, 'big.txt'), Buffer.alloc(MAX_FILE_SIZE + 1))
 		const [err, results] = await validate_file_sizes(dir)
 		assert.strictEqual(err, null)
-		assert.strictEqual(results.length, 1)
-		assert.strictEqual(results[0].severity, 'error')
-		assert.strictEqual(results[0].rule, 'max_file_size')
-		assert.strictEqual(results[0].file, 'big.txt')
+		const per_file = results.filter(r => r.rule === 'max_file_size')
+		assert.strictEqual(per_file.length, 1)
+		assert.strictEqual(per_file[0].severity, 'error')
+		assert.strictEqual(per_file[0].file, 'big.txt')
 	})
 
-	it('handles multiple oversized files', async () => {
-		fs.writeFileSync(path.join(dir, 'big1.txt'), Buffer.alloc(MAX_FILE_SIZE + 1))
-		fs.writeFileSync(path.join(dir, 'big2.txt'), Buffer.alloc(MAX_FILE_SIZE + 100))
+	it('returns max_total_size error when bundle exceeds MAX_TOTAL_SIZE', async () => {
+		// Split across two files so per-file check passes but total fails.
+		const half = Math.floor(MAX_FILE_SIZE / 2) + 1
+		const each = Math.min(half, MAX_FILE_SIZE)
+		const n = Math.ceil((MAX_TOTAL_SIZE + 1) / each)
+		for (let i = 0; i < n; i++) {
+			fs.writeFileSync(path.join(dir, `f${i}.bin`), Buffer.alloc(each))
+		}
 		const [err, results] = await validate_file_sizes(dir)
 		assert.strictEqual(err, null)
-		assert.strictEqual(results.length, 2)
-		assert.ok(results.every(r => r.severity === 'error'))
-		assert.ok(results.every(r => r.rule === 'max_file_size'))
+		const bundle = results.filter(r => r.rule === 'max_total_size')
+		assert.strictEqual(bundle.length, 1)
+		assert.strictEqual(bundle[0].severity, 'error')
 	})
 
-	it('reports correct relative path for nested files', async () => {
+	it('reports correct relative path for nested oversized files', async () => {
 		const sub = path.join(dir, 'sub')
 		fs.mkdirSync(sub)
 		fs.writeFileSync(path.join(sub, 'big.txt'), Buffer.alloc(MAX_FILE_SIZE + 1))
 		const [err, results] = await validate_file_sizes(dir)
 		assert.strictEqual(err, null)
-		assert.strictEqual(results.length, 1)
-		assert.strictEqual(results[0].file, 'sub/big.txt')
+		const per_file = results.filter(r => r.rule === 'max_file_size')
+		assert.strictEqual(per_file.length, 1)
+		assert.strictEqual(per_file[0].file, 'sub/big.txt')
 	})
 
 	it('skips dotfiles', async () => {
@@ -69,7 +74,7 @@ describe('validate_file_sizes', () => {
 		assert.strictEqual(results.length, 0)
 	})
 
-	it('passes for file exactly at 1MB limit', async () => {
+	it('passes for a file exactly at MAX_FILE_SIZE and bundle at MAX_TOTAL_SIZE', async () => {
 		fs.writeFileSync(path.join(dir, 'exact.txt'), Buffer.alloc(MAX_FILE_SIZE))
 		const [err, results] = await validate_file_sizes(dir)
 		assert.strictEqual(err, null)