happyskills 0.29.0 → 0.30.0

package/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [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.0",
 	"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/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)
+	})
+})