happyskills 0.29.0 → 0.30.1

package/CHANGELOG.md

@@ -7,6 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.30.1] - 2026-04-05
+
+### Fixed
+- Fix frequent unnecessary re-login caused by transient refresh failures (network errors, Lambda/NeonDB cold starts) destroying the credentials file — now only clears credentials on permanent failures (Cognito token rejection), preserves the refresh token for transient errors so the next CLI invocation can retry
+- Add diagnostic logging to token refresh failures (`print_warn` to stderr) with actual error reason, replacing silent failure that made auth issues impossible to diagnose
+- Add single retry on transient refresh failure within the same CLI invocation
+
+## [0.30.0] - 2026-04-03
+
+### Added
+- Add archive-based install for large skills — installer tries `?format=archive` clone first (single `.tar.gz` download via presigned URL), falls back to JSON clone transparently
+- Add 1MB per-file size validation rule — enforced in `validate` and `publish` commands, blocks oversized files before upload
+
 ## [0.29.0] - 2026-04-02
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "happyskills",
-	"version": "0.29.0",
+	"version": "0.30.1",
 	"description": "Package manager for AI agent skills",
 	"license": "SEE LICENSE IN LICENSE",
 	"author": "Nicolas Dao <nic@cloudlesslabs.com> (https://cloudlesslabs.com)",
@@ -45,7 +45,8 @@
 	"dependencies": {
 		"node-diff3": "^3.2.0",
 		"puffy-core": "^1.3.1",
-		"semver": "^7.6.0"
+		"semver": "^7.6.0",
+		"tar-stream": "^3.1.8"
 	},
 	"devDependencies": {
 		"dotenv": "^17.2.4"

package/src/api/repos.js

@@ -26,6 +26,7 @@ const clone = (owner, repo, ref, options = {}) => catch_errors(`Clone ${owner}/$
 	const params = new URLSearchParams()
 	if (options.commit) params.set('commit', options.commit)
 	else if (ref) params.set('ref', ref)
+	if (options.format) params.set('format', options.format)
 	const qs = params.toString() ? `?${params}` : ''
 	const [errors, data] = await client.get(`/repos/${owner}/${repo}/clone${qs}`)
 	if (errors) throw errors[errors.length - 1]

package/src/auth/token_store.js

@@ -3,18 +3,43 @@ const path = require('path')
 const { error: { catch_errors } } = require('puffy-core')
 const { credentials_path, config_dir } = require('../config/paths')
 
+const _is_permanent_failure = (errors) => {
+	if (!errors) return false
+	const { AuthError } = require('../utils/errors')
+	return errors.some(e => e instanceof AuthError)
+}
+
 const _try_refresh = async (refresh_token) => {
-	try {
-		const { refresh } = require('../api/auth')
-		const [errors, data] = await refresh(refresh_token)
-		if (errors || !data) return null
-		const merged = { ...data, refresh_token }
-		const [save_err] = await save_token(merged)
-		if (save_err) return null
-		return { ...merged, stored_at: new Date().toISOString() }
-	} catch {
-		return null
+	const max_attempts = 2
+	let permanent = false
+	for (let attempt = 1; attempt <= max_attempts; attempt++) {
+		try {
+			const { refresh } = require('../api/auth')
+			const [errors, data] = await refresh(refresh_token)
+			if (errors || !data) {
+				const reason = errors
+					? errors.map(e => e.message || String(e)).join('; ')
+					: 'empty response from server'
+				const { print_warn } = require('../ui/output')
+				print_warn(`Token refresh failed (attempt ${attempt}/${max_attempts}): ${reason}`)
+				permanent = _is_permanent_failure(errors)
+				if (permanent || attempt >= max_attempts) return { ok: false, permanent }
+				continue
+			}
+			const merged = { ...data, refresh_token }
+			const [save_err] = await save_token(merged)
+			if (save_err) return { ok: false, permanent: false }
+			return { ok: true, data: { ...merged, stored_at: new Date().toISOString() } }
+		} catch (err) {
+			const { print_warn } = require('../ui/output')
+			print_warn(`Token refresh exception (attempt ${attempt}/${max_attempts}): ${err.message || String(err)}`)
+			const { AuthError } = require('../utils/errors')
+			permanent = err instanceof AuthError
+			if (permanent || attempt >= max_attempts) return { ok: false, permanent }
+			continue
+		}
 	}
+	return { ok: false, permanent: false }
 }
 
 const save_token = (token_data) => catch_errors('Failed to save token', async () => {
@@ -55,10 +80,16 @@ const load_token = () => catch_errors('Failed to load token', async () => {
 		const elapsed_sec = (now - stored) / 1000
 		if (elapsed_sec >= data.expires_in) {
 			if (data.refresh_token) {
-				const refreshed = await _try_refresh(data.refresh_token)
-				if (refreshed) return refreshed
+				const result = await _try_refresh(data.refresh_token)
+				if (result.ok) return result.data
+				// Permanent failure (Cognito rejected the token) → clear the file.
+				// Transient failure (network, cold start) → preserve the file so
+				// the next invocation can retry with the still-valid refresh token.
+				if (result.permanent) await clear_token()
+			} else {
+				// No refresh token — nothing to preserve, clean up the expired file.
+				await clear_token()
 			}
-			await clear_token()
 			return null
 		}
 	}

package/src/auth/token_store.test.js

@@ -12,7 +12,7 @@ const fs = require('fs')
 // ─────────────────────────────────────────────────────────────────────────────
 
 const { save_token, load_token, clear_token, require_token } = require('./token_store')
-const { AuthError } = require('../utils/errors')
+const { AuthError, NetworkError } = require('../utils/errors')
 
 // ─── helpers ──────────────────────────────────────────────────────────────────
 
@@ -200,3 +200,199 @@ describe('require_token', () => {
 		})
 	})
 })
+
+// ─── token refresh behavior ─────────────────────────────────────────────────
+//
+// _try_refresh is internal, but its behavior is observable through load_token:
+// when the id_token is expired and a refresh_token exists, load_token calls
+// _try_refresh which calls require('../api/auth').refresh(). We mock that
+// module in require.cache to control the refresh outcome.
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe('load_token — refresh behavior', () => {
+	const auth_path = require.resolve('../api/auth')
+	let orig_auth_cache
+
+	const mock_refresh = (fn) => {
+		orig_auth_cache = require.cache[auth_path]
+		require.cache[auth_path] = {
+			id: auth_path,
+			filename: auth_path,
+			loaded: true,
+			exports: { refresh: fn }
+		}
+	}
+
+	const restore_refresh = () => {
+		if (orig_auth_cache) require.cache[auth_path] = orig_auth_cache
+		else delete require.cache[auth_path]
+	}
+
+	const write_expired_token = (dir, overrides = {}) => {
+		const token = {
+			id_token: 'expired-id-token',
+			access_token: 'expired-access-token',
+			refresh_token: 'valid-refresh-token',
+			expires_in: 1,
+			stored_at: new Date(Date.now() - 5000).toISOString(),
+			...overrides
+		}
+		fs.mkdirSync(path.join(dir, 'happyskills'), { recursive: true })
+		fs.writeFileSync(creds_file(dir), JSON.stringify(token), { mode: 0o600 })
+		return token
+	}
+
+	it('returns refreshed token when refresh succeeds', async () => {
+		await with_tmp(async (dir) => {
+			write_expired_token(dir)
+			mock_refresh(async () => [null, {
+				id_token: 'new-id-token',
+				access_token: 'new-access-token',
+				expires_in: 3600
+			}])
+			try {
+				const [err, loaded] = await load_token()
+				assert.strictEqual(err, null)
+				assert.ok(loaded, 'should return refreshed token')
+				assert.strictEqual(loaded.id_token, 'new-id-token')
+				assert.strictEqual(loaded.access_token, 'new-access-token')
+				assert.strictEqual(loaded.refresh_token, 'valid-refresh-token', 'original refresh_token preserved')
+				assert.ok(loaded.stored_at, 'stored_at should be set')
+			} finally {
+				restore_refresh()
+			}
+		})
+	})
+
+	it('saves refreshed tokens to disk after successful refresh', async () => {
+		await with_tmp(async (dir) => {
+			write_expired_token(dir)
+			mock_refresh(async () => [null, {
+				id_token: 'refreshed-on-disk',
+				access_token: 'new-access',
+				expires_in: 7200
+			}])
+			try {
+				await load_token()
+				const on_disk = JSON.parse(fs.readFileSync(creds_file(dir), 'utf-8'))
+				assert.strictEqual(on_disk.id_token, 'refreshed-on-disk')
+				assert.strictEqual(on_disk.refresh_token, 'valid-refresh-token', 'refresh_token preserved on disk')
+				assert.strictEqual(on_disk.expires_in, 7200)
+				assert.ok(on_disk.stored_at, 'stored_at should be updated on disk')
+			} finally {
+				restore_refresh()
+			}
+		})
+	})
+
+	it('preserves credentials file on transient refresh failure (NetworkError)', async () => {
+		await with_tmp(async (dir) => {
+			write_expired_token(dir)
+			mock_refresh(async () => [[new NetworkError('connection failed')], null])
+			try {
+				const [err, loaded] = await load_token()
+				assert.strictEqual(err, null)
+				assert.strictEqual(loaded, null, 'should return null on failed refresh')
+				assert.ok(fs.existsSync(creds_file(dir)), 'credentials file should be preserved for retry')
+				// Verify the refresh_token is still intact on disk
+				const on_disk = JSON.parse(fs.readFileSync(creds_file(dir), 'utf-8'))
+				assert.strictEqual(on_disk.refresh_token, 'valid-refresh-token')
+			} finally {
+				restore_refresh()
+			}
+		})
+	})
+
+	it('preserves credentials file on server error (ApiError)', async () => {
+		await with_tmp(async (dir) => {
+			write_expired_token(dir)
+			const { ApiError } = require('../utils/errors')
+			mock_refresh(async () => [[new ApiError('Internal server error', 500, 'INTERNAL_ERROR')], null])
+			try {
+				const [err, loaded] = await load_token()
+				assert.strictEqual(err, null)
+				assert.strictEqual(loaded, null)
+				assert.ok(fs.existsSync(creds_file(dir)), 'credentials file should be preserved on server error')
+			} finally {
+				restore_refresh()
+			}
+		})
+	})
+
+	it('deletes credentials file on permanent refresh failure (AuthError)', async () => {
+		await with_tmp(async (dir) => {
+			write_expired_token(dir)
+			mock_refresh(async () => [[new AuthError('token revoked')], null])
+			try {
+				const [err, loaded] = await load_token()
+				assert.strictEqual(err, null)
+				assert.strictEqual(loaded, null)
+				assert.ok(!fs.existsSync(creds_file(dir)), 'credentials file should be deleted on permanent failure')
+			} finally {
+				restore_refresh()
+			}
+		})
+	})
+
+	it('does not retry on permanent failure', async () => {
+		await with_tmp(async (dir) => {
+			write_expired_token(dir)
+			let call_count = 0
+			mock_refresh(async () => {
+				call_count++
+				return [[new AuthError('token expired')], null]
+			})
+			try {
+				await load_token()
+				assert.strictEqual(call_count, 1, 'should not retry on permanent failure')
+			} finally {
+				restore_refresh()
+			}
+		})
+	})
+
+	it('retries once on transient failure then succeeds', async () => {
+		await with_tmp(async (dir) => {
+			write_expired_token(dir)
+			let call_count = 0
+			mock_refresh(async () => {
+				call_count++
+				if (call_count === 1) return [[new NetworkError('cold start')], null]
+				return [null, {
+					id_token: 'retried-id-token',
+					access_token: 'retried-access-token',
+					expires_in: 3600
+				}]
+			})
+			try {
+				const [err, loaded] = await load_token()
+				assert.strictEqual(err, null)
+				assert.ok(loaded, 'should return refreshed token after retry')
+				assert.strictEqual(loaded.id_token, 'retried-id-token')
+				assert.strictEqual(call_count, 2, 'refresh should have been called twice')
+			} finally {
+				restore_refresh()
+			}
+		})
+	})
+
+	it('retries once on transient failure then gives up', async () => {
+		await with_tmp(async (dir) => {
+			write_expired_token(dir)
+			let call_count = 0
+			mock_refresh(async () => {
+				call_count++
+				return [[new NetworkError('still failing')], null]
+			})
+			try {
+				const [err, loaded] = await load_token()
+				assert.strictEqual(err, null)
+				assert.strictEqual(loaded, null)
+				assert.strictEqual(call_count, 2, 'should have retried once')
+				assert.ok(fs.existsSync(creds_file(dir)), 'credentials file preserved after exhausting retries')
+			} finally {
+				restore_refresh()
+			}
+		})
+	})
+})

package/src/commands/publish.js

@@ -17,6 +17,7 @@ const { validate_skill_md } = require('../validation/skill_md_rules')
 const { validate_skill_json } = require('../validation/skill_json_rules')
 const { validate_cross } = require('../validation/cross_rules')
 const { validate_no_conflict_markers } = require('../validation/conflict_marker_rules')
+const { validate_file_sizes } = require('../validation/file_size_rules')
 const { create_spinner } = require('../ui/spinner')
 const { print_help, print_success, print_error, print_warn, print_hint, print_json, code, summarize_warnings } = require('../ui/output')
 const { exit_with_error, UsageError, CliError } = require('../utils/errors')
@@ -103,8 +104,10 @@ const run = (args) => catch_errors('Publish failed', async () => {
 	if (cross_err) throw cross_err
 	const [marker_err, marker_results] = await validate_no_conflict_markers(dir)
 	if (marker_err) throw marker_err
+	const [size_err, size_results] = await validate_file_sizes(dir)
+	if (size_err) throw size_err
 
-	const all_results = [...md_data.results, ...json_data.results, ...cross_results, ...marker_results]
+	const all_results = [...md_data.results, ...json_data.results, ...cross_results, ...marker_results, ...size_results]
 	const validation_errors = all_results.filter(r => r.severity === 'error')
 	const validation_warnings = all_results.filter(r => r.severity === 'warning')
 

package/src/commands/validate.js

@@ -4,6 +4,7 @@ const { validate_skill_md } = require('../validation/skill_md_rules')
 const { validate_skill_json } = require('../validation/skill_json_rules')
 const { validate_cross } = require('../validation/cross_rules')
 const { validate_no_conflict_markers } = require('../validation/conflict_marker_rules')
+const { validate_file_sizes } = require('../validation/file_size_rules')
 const { file_exists, read_json } = require('../utils/fs')
 const { skills_dir, find_project_root } = require('../config/paths')
 const { print_help, print_json } = require('../ui/output')
@@ -147,8 +148,10 @@ const run = (args) => catch_errors('Validate failed', async () => {
 	if (cross_err) throw cross_err
 	const [marker_err, marker_results] = await validate_no_conflict_markers(skill_dir)
 	if (marker_err) throw marker_err
+	const [size_err, size_results] = await validate_file_sizes(skill_dir)
+	if (size_err) throw size_err
 
-	const all_results = [...md_data.results, ...json_data.results, ...cross_results, ...marker_results]
+	const all_results = [...md_data.results, ...json_data.results, ...cross_results, ...marker_results, ...size_results]
 	const type_label = is_kit ? ' [kit]' : ''
 
 	if (args.flags.json) {

package/src/engine/archive_installer.js

@@ -0,0 +1,87 @@
+const fs = require('fs')
+const path = require('path')
+const zlib = require('zlib')
+const { Readable } = require('stream')
+const tar = require('tar-stream')
+const { error: { catch_errors } } = require('puffy-core')
+const repos_api = require('../api/repos')
+
+/**
+ * Attempts an archive-based clone. Returns the extracted files or null if no archive is available.
+ *
+ * @param {string} owner - Workspace slug
+ * @param {string} name - Repo name
+ * @param {string} ref - Git ref (e.g., refs/tags/v1.0.0)
+ * @param {string} dest_dir - Directory to extract files into
+ * @returns {[errors, {ref, commit}|null]} — null if no archive available (caller should fall back to JSON clone)
+ */
+const install_from_archive = (owner, name, ref, dest_dir) => catch_errors('Archive install failed', async () => {
+	// Request archive format
+	const [clone_err, clone_data] = await repos_api.clone(owner, name, ref, { format: 'archive' })
+	if (clone_err) return null
+	if (!clone_data || clone_data.format !== 'archive' || !clone_data.url) return null
+
+	// Download archive from presigned URL
+	const resp = await fetch(clone_data.url)
+	if (!resp.ok) throw new Error(`Archive download failed: ${resp.status}`)
+
+	const archive_buffer = Buffer.from(await resp.arrayBuffer())
+
+	// Extract tar.gz to dest_dir
+	await extract_tar_gz(archive_buffer, dest_dir)
+
+	return { ref: clone_data.ref, commit: clone_data.commit }
+})
+
+/**
+ * Extracts a .tar.gz buffer into a directory.
+ */
+const extract_tar_gz = (buffer, dest_dir) => new Promise((resolve, reject) => {
+	const extract = tar.extract()
+
+	extract.on('entry', (header, stream, next) => {
+		if (header.type !== 'file') {
+			stream.resume()
+			return next()
+		}
+
+		// Normalize path: strip leading ./
+		const file_path = header.name.replace(/^\.\//, '')
+
+		// Skip macOS metadata
+		const basename = file_path.split('/').pop()
+		if (basename.startsWith('._') || basename === '.DS_Store') {
+			stream.resume()
+			return next()
+		}
+
+		// Path safety check
+		const resolved = path.resolve(dest_dir, file_path)
+		if (!resolved.startsWith(path.resolve(dest_dir) + path.sep) && resolved !== path.resolve(dest_dir)) {
+			stream.resume()
+			return next()
+		}
+
+		const chunks = []
+		stream.on('data', chunk => chunks.push(chunk))
+		stream.on('end', async () => {
+			try {
+				const dir = path.dirname(resolved)
+				await fs.promises.mkdir(dir, { recursive: true })
+				await fs.promises.writeFile(resolved, Buffer.concat(chunks))
+				next()
+			} catch (err) {
+				reject(err)
+			}
+		})
+		stream.on('error', reject)
+	})
+
+	extract.on('finish', resolve)
+	extract.on('error', reject)
+
+	const gunzip = zlib.createGunzip()
+	Readable.from(buffer).pipe(gunzip).pipe(extract)
+})
+
+module.exports = { install_from_archive, extract_tar_gz }

package/src/engine/archive_installer.test.js

@@ -0,0 +1,121 @@
+const { describe, it, beforeEach, afterEach } = require('node:test')
+const assert = require('node:assert/strict')
+const fs = require('fs')
+const path = require('path')
+const os = require('os')
+const zlib = require('zlib')
+const tar = require('tar-stream')
+const { extract_tar_gz } = require('./archive_installer')
+
+const create_tar_gz = (files) => new Promise((resolve, reject) => {
+	const pack = tar.pack()
+	for (const { name, content, type } of files) {
+		if (type) {
+			pack.entry({ name, type })
+		} else {
+			pack.entry({ name }, content)
+		}
+	}
+	pack.finalize()
+	const chunks = []
+	const gz = zlib.createGzip()
+	pack.pipe(gz)
+	gz.on('data', chunk => chunks.push(chunk))
+	gz.on('end', () => resolve(Buffer.concat(chunks)))
+	gz.on('error', reject)
+})
+
+describe('extract_tar_gz', () => {
+	let tmp_dir
+
+	beforeEach(async () => {
+		tmp_dir = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'archive-test-'))
+	})
+
+	afterEach(async () => {
+		await fs.promises.rm(tmp_dir, { recursive: true, force: true })
+	})
+
+	it('extracts files to destination directory', async () => {
+		const buffer = await create_tar_gz([
+			{ name: 'hello.txt', content: 'Hello world' },
+			{ name: 'data.json', content: '{"ok":true}' }
+		])
+
+		await extract_tar_gz(buffer, tmp_dir)
+
+		const hello = await fs.promises.readFile(path.join(tmp_dir, 'hello.txt'), 'utf8')
+		const data = await fs.promises.readFile(path.join(tmp_dir, 'data.json'), 'utf8')
+		assert.equal(hello, 'Hello world')
+		assert.equal(data, '{"ok":true}')
+	})
+
+	it('creates nested directories', async () => {
+		const buffer = await create_tar_gz([
+			{ name: 'sub/file.txt', content: 'nested content' }
+		])
+
+		await extract_tar_gz(buffer, tmp_dir)
+
+		const content = await fs.promises.readFile(path.join(tmp_dir, 'sub', 'file.txt'), 'utf8')
+		assert.equal(content, 'nested content')
+
+		const stat = await fs.promises.stat(path.join(tmp_dir, 'sub'))
+		assert.ok(stat.isDirectory())
+	})
+
+	it('skips macOS metadata files', async () => {
+		const buffer = await create_tar_gz([
+			{ name: '._hidden', content: 'mac metadata' },
+			{ name: '.DS_Store', content: 'store data' },
+			{ name: 'sub/._resource', content: 'nested mac metadata' },
+			{ name: 'real.txt', content: 'keep me' }
+		])
+
+		await extract_tar_gz(buffer, tmp_dir)
+
+		assert.equal(fs.existsSync(path.join(tmp_dir, '._hidden')), false)
+		assert.equal(fs.existsSync(path.join(tmp_dir, '.DS_Store')), false)
+		assert.equal(fs.existsSync(path.join(tmp_dir, 'sub', '._resource')), false)
+
+		const content = await fs.promises.readFile(path.join(tmp_dir, 'real.txt'), 'utf8')
+		assert.equal(content, 'keep me')
+	})
+
+	it('skips non-file entries', async () => {
+		const buffer = await create_tar_gz([
+			{ name: 'somedir/', type: 'directory' },
+			{ name: 'actual.txt', content: 'file content' }
+		])
+
+		await extract_tar_gz(buffer, tmp_dir)
+
+		const content = await fs.promises.readFile(path.join(tmp_dir, 'actual.txt'), 'utf8')
+		assert.equal(content, 'file content')
+	})
+
+	it('rejects path traversal', async () => {
+		const buffer = await create_tar_gz([
+			{ name: '../evil.txt', content: 'malicious' },
+			{ name: 'safe.txt', content: 'safe content' }
+		])
+
+		await extract_tar_gz(buffer, tmp_dir)
+
+		assert.equal(fs.existsSync(path.join(tmp_dir, '..', 'evil.txt')), false)
+
+		const content = await fs.promises.readFile(path.join(tmp_dir, 'safe.txt'), 'utf8')
+		assert.equal(content, 'safe content')
+	})
+
+	it('strips leading ./ from paths', async () => {
+		const buffer = await create_tar_gz([
+			{ name: './file.txt', content: 'dot-slash content' }
+		])
+
+		await extract_tar_gz(buffer, tmp_dir)
+
+		const content = await fs.promises.readFile(path.join(tmp_dir, 'file.txt'), 'utf8')
+		assert.equal(content, 'dot-slash content')
+	})
+})

package/src/engine/installer.js

@@ -108,11 +108,24 @@ const install = (skill, options = {}) => catch_errors('Install failed', async ()
 			const pkg_tmp = path.join(temp_dir, name)
 
 			spinner.update(`Downloading ${pkg.skill}@${pkg.version}...`)
-			const [dl_errors, clone_data] = await download(owner, name, pkg.ref)
-			if (dl_errors) { spinner.fail(`Download failed: ${pkg.skill}`); throw e(`Download ${pkg.skill} failed`, dl_errors) }
 
-			const [ext_errors] = await extract(clone_data, pkg_tmp)
-			if (ext_errors) { spinner.fail(`Extract failed: ${pkg.skill}`); throw e(`Extract ${pkg.skill} failed`, ext_errors) }
+			// Try archive-based install first (fast single download), fall back to JSON clone
+			const { install_from_archive } = require('./archive_installer')
+			const [arch_err, arch_result] = await install_from_archive(owner, name, pkg.ref, pkg_tmp)
+			let clone_ref, clone_commit
+
+			if (!arch_err && arch_result) {
+				// Archive install succeeded
+				clone_ref = arch_result.ref
+				clone_commit = arch_result.commit
+			} else {
+				// Fall back to JSON clone
+				const [dl_errors, clone_data] = await download(owner, name, pkg.ref)
+				if (dl_errors) { spinner.fail(`Download failed: ${pkg.skill}`); throw e(`Download ${pkg.skill} failed`, dl_errors) }
+
+				const [ext_errors] = await extract(clone_data, pkg_tmp)
+				if (ext_errors) { spinner.fail(`Extract failed: ${pkg.skill}`); throw e(`Extract ${pkg.skill} failed`, ext_errors) }
+			}
 
 			if (pkg.integrity) {
 				const [, valid] = await verify_integrity(pkg_tmp, pkg.integrity)

package/src/validation/file_size_rules.js

@@ -0,0 +1,48 @@
+const fs = require('fs')
+const path = require('path')
+const { error: { catch_errors } } = require('puffy-core')
+
+const MAX_FILE_SIZE = 1 * 1024 * 1024 // 1MB
+
+const 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)`
+})
+
+/**
+ * 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.
+ * 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 = []
+	const walk = async (dir, prefix) => {
+		let items
+		try { items = await fs.promises.readdir(dir, { withFileTypes: true }) } catch { return }
+		for (const item of items) {
+			if (item.name.startsWith('.')) continue
+			if (item.name === 'node_modules') continue
+			const rel = prefix ? `${prefix}/${item.name}` : item.name
+			const full = path.join(dir, item.name)
+			if (item.isDirectory()) {
+				await walk(full, rel)
+			} else {
+				let stat
+				try { stat = await fs.promises.stat(full) } catch { continue }
+				if (stat.size > MAX_FILE_SIZE) {
+					results.push(result(rel, stat.size))
+				}
+			}
+		}
+	}
+	await walk(skill_dir, '')
+	return results
+})
+
+module.exports = { validate_file_sizes }

package/src/validation/file_size_rules.test.js

@@ -0,0 +1,84 @@
+const { describe, it, beforeEach, afterEach } = require('node:test')
+const assert = require('node:assert/strict')
+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 make_temp_dir = () => fs.mkdtempSync(path.join(os.tmpdir(), 'file-size-test-'))
+const clean = (dir) => fs.rmSync(dir, { recursive: true, force: true })
+
+describe('validate_file_sizes', () => {
+	let dir
+
+	beforeEach(() => { dir = make_temp_dir() })
+	afterEach(() => { clean(dir) })
+
+	it('returns empty for files under 1MB 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 () => {
+		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')
+	})
+
+	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))
+		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'))
+	})
+
+	it('reports correct relative path for nested 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')
+	})
+
+	it('skips dotfiles', async () => {
+		fs.writeFileSync(path.join(dir, '.hidden'), Buffer.alloc(MAX_FILE_SIZE + 1))
+		const [err, results] = await validate_file_sizes(dir)
+		assert.strictEqual(err, null)
+		assert.strictEqual(results.length, 0)
+	})
+
+	it('skips node_modules', async () => {
+		const nm = path.join(dir, 'node_modules')
+		fs.mkdirSync(nm)
+		fs.writeFileSync(path.join(nm, 'big.txt'), Buffer.alloc(MAX_FILE_SIZE + 1))
+		const [err, results] = await validate_file_sizes(dir)
+		assert.strictEqual(err, null)
+		assert.strictEqual(results.length, 0)
+	})
+
+	it('passes for file exactly at 1MB limit', 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)
+		assert.strictEqual(results.length, 0)
+	})
+
+	it('handles empty directory', async () => {
+		const [err, results] = await validate_file_sizes(dir)
+		assert.strictEqual(err, null)
+		assert.strictEqual(results.length, 0)
+	})
+})