happyskills 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com),
+and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-02-28
+
+### Added
+- Initial release of the `happyskills` CLI
+- `install` command for downloading and resolving skill dependencies
+- `search` command for discovering skills from the registry
+- `info` command for viewing skill metadata
+- `init` command for scaffolding new skill projects
+- `publish` command for publishing skills to the registry
+- `login` / `logout` commands for authentication
+- Semantic version resolution with conflict detection
+- Lockfile support (`happyskills-lock.json`)

package/LICENSE

@@ -0,0 +1,116 @@
+HAPPYSKILLS PROPRIETARY LICENSE
+
+Copyright (c) 2026 Cloudless Consulting Pty Ltd (ABN 29 636 444 463)
+All rights reserved.
+
+https://cloudlesslabs.com
+
+TERMS AND CONDITIONS
+
+1. DEFINITIONS
+
+   "Software" refers to the HappySkills CLI tool, including all source code,
+   object code, documentation, and associated files distributed as the
+   "happyskills" package.
+
+   "Licensor" refers to Cloudless Consulting Pty Ltd.
+
+   "You" refers to any individual or entity that accesses, installs, or uses
+   the Software.
+
+2. GRANT OF LICENSE
+
+   Subject to the terms of this license, the Licensor grants You a limited,
+   non-exclusive, non-transferable, non-sublicensable, revocable license to:
+
+   (a) Install and use the Software solely for the purpose of interacting
+       with the HappySkills registry and platform services; and
+
+   (b) Use the Software in accordance with its intended purpose as a
+       command-line package manager for AI agent skills.
+
+3. RESTRICTIONS
+
+   You may NOT, without the prior written consent of the Licensor:
+
+   (a) Copy, modify, adapt, translate, or create derivative works based on
+       the Software or any part thereof;
+
+   (b) Reverse engineer, decompile, disassemble, or otherwise attempt to
+       derive the source code, algorithms, or data structures of the
+       Software, except to the extent that such activity is expressly
+       permitted by applicable law notwithstanding this limitation;
+
+   (c) Distribute, sublicense, lease, rent, sell, or otherwise transfer the
+       Software or any rights therein to any third party;
+
+   (d) Remove, alter, or obscure any proprietary notices, labels, or marks
+       on the Software;
+
+   (e) Use the Software to build a competing product or service;
+
+   (f) Use the Software in any manner that infringes the intellectual
+       property rights of the Licensor or any third party; or
+
+   (g) Use any portion of the Software's source code in any other software
+       or project, whether open source or proprietary.
+
+4. INTELLECTUAL PROPERTY
+
+   The Software and all copies thereof are proprietary to and the exclusive
+   property of the Licensor. The Software is protected by copyright laws,
+   international treaty provisions, and other intellectual property laws.
+   The Licensor retains all right, title, and interest in and to the
+   Software, including all intellectual property rights therein.
+
+   No title to or ownership of the Software or any intellectual property
+   rights therein is transferred to You by this license.
+
+5. NO WARRANTY
+
+   THE SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+   IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+   FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. IN NO EVENT SHALL
+   THE LICENSOR BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY,
+   WHETHER IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING FROM, OUT
+   OF, OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+   THE SOFTWARE.
+
+6. LIMITATION OF LIABILITY
+
+   TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, IN NO EVENT SHALL THE
+   LICENSOR BE LIABLE FOR ANY INDIRECT, INCIDENTAL, SPECIAL, CONSEQUENTIAL,
+   OR PUNITIVE DAMAGES, OR ANY LOSS OF PROFITS, REVENUE, DATA, OR USE,
+   ARISING OUT OF OR RELATED TO THE SOFTWARE, EVEN IF THE LICENSOR HAS BEEN
+   ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
+
+7. TERMINATION
+
+   This license is effective until terminated. It will terminate automatically
+   without notice if You fail to comply with any term of this license. Upon
+   termination, You must destroy all copies of the Software in Your
+   possession or control.
+
+   The Licensor may also terminate this license at any time for any reason
+   upon notice to You.
+
+8. GOVERNING LAW
+
+   This license shall be governed by and construed in accordance with the
+   laws of New South Wales, Australia, without regard to its conflict of law
+   provisions. Any disputes arising under this license shall be subject to
+   the exclusive jurisdiction of the courts of New South Wales, Australia.
+
+9. ENTIRE AGREEMENT
+
+   This license constitutes the entire agreement between You and the Licensor
+   regarding the Software and supersedes all prior agreements and
+   understandings, whether written or oral.
+
+10. CONTACT
+
+    For licensing inquiries, permissions, or questions:
+
+    Cloudless Consulting Pty Ltd
+    ABN 29 636 444 463
+    https://cloudlesslabs.com

package/README.md

@@ -0,0 +1,76 @@
+# HappySkills CLI
+
+Package manager for AI agent skills. Install, manage, version, and publish skills from your terminal — think npm for AI skills.
+
+## Installation
+
+```bash
+npm install -g happyskills
+```
+
+Requires Node.js 22 or later.
+
+## Quick Start
+
+```bash
+# Search the registry
+happyskills search deploy
+
+# Install a skill (with transitive dependencies)
+happyskills install acme/deploy-aws
+
+# Scaffold a new skill
+happyskills init my-skill
+
+# Publish to the registry
+happyskills login
+happyskills publish
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `init [name]` | Scaffold `SKILL.md` + `skill.json` in the current directory |
+| `install [owner/skill]` | Install a skill and its dependencies. Without arguments, installs from `skill.json` |
+| `uninstall <owner/skill>` | Remove a skill and prune orphaned dependencies |
+| `list` | List installed skills from the lock file |
+| `search <query>` | Search the skill registry |
+| `check [owner/skill]` | Check for available updates |
+| `update [owner/skill]` | Upgrade to latest compatible versions |
+| `publish` | Push the current skill to the registry |
+| `fork <owner/skill>` | Fork a skill to your workspace |
+| `login` | Authenticate with the registry |
+| `logout` | Clear stored credentials |
+| `whoami` | Show the currently authenticated user |
+
+## Command Aliases
+
+| Alias | Command |
+|-------|---------|
+| `i`, `add` | `install` |
+| `rm`, `remove` | `uninstall` |
+| `ls` | `list` |
+| `s` | `search` |
+| `up` | `update` |
+| `pub` | `publish` |
+
+## Global Flags
+
+| Flag | Description |
+|------|-------------|
+| `--help` | Show help for a command |
+| `--version` | Show CLI version |
+| `-g`, `--global` | Use global scope (`~/.claude/skills/`) |
+| `-y`, `--yes` | Skip confirmation prompts |
+| `--json` | Output as JSON (supported by `list`, `search`, `check`, `whoami`) |
+
+## License
+
+See [LICENSE](./LICENSE) for details.
+
+## Links
+
+- [Full documentation](https://github.com/cloudlesslabs/skillsbang/tree/master/cli)
+- [Report an issue](https://github.com/cloudlesslabs/skillsbang/issues)
+- [HappySkills website](https://happyskills.ai)

package/bin/happyskills.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+try { require('dotenv').config({ path: require('path').join(__dirname, '..', '.env') }) } catch {}
+const { run } = require('../src/index')
+run(process.argv.slice(2))

package/package.json

@@ -0,0 +1,37 @@
+{
+	"name": "happyskills",
+	"version": "0.1.0",
+	"description": "Package manager for AI agent skills",
+	"license": "SEE LICENSE IN LICENSE",
+	"author": "Nicolas Dao <nic@cloudlesslabs.com> (https://cloudlesslabs.com)",
+	"bin": {
+		"happyskills": "./bin/happyskills.js"
+	},
+	"main": "src/index.js",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/cloudlesslabs/skillsbang.git",
+		"directory": "cli"
+	},
+	"homepage": "https://happyskills.ai",
+	"bugs": {
+		"url": "https://github.com/cloudlesslabs/skillsbang/issues"
+	},
+	"keywords": ["cli", "skills", "package-manager", "ai", "claude", "agent", "dependency-resolution"],
+	"files": ["bin/", "src/", "LICENSE", "CHANGELOG.md"],
+	"scripts": {
+		"dev": "node bin/happyskills.js",
+		"test": "node --test src/**/*.test.js",
+		"release": "./scripts/release.sh"
+	},
+	"engines": {
+		"node": ">=22.0.0"
+	},
+	"dependencies": {
+		"puffy-core": "^1.3.1",
+		"semver": "^7.6.0"
+	},
+	"devDependencies": {
+		"dotenv": "^17.2.4"
+	}
+}

package/src/api/auth.js

@@ -0,0 +1,40 @@
+const { error: { catch_errors } } = require('puffy-core')
+const client = require('./client')
+
+const login = (email, password) => catch_errors('Login failed', async () => {
+	const [errors, data] = await client.post('/auth/login', { email, password }, { auth: false })
+	if (errors) throw errors[0]
+	return data
+})
+
+const signup = (email, password) => catch_errors('Signup failed', async () => {
+	const [errors, data] = await client.post('/auth/signup', { email, password }, { auth: false })
+	if (errors) throw errors[0]
+	return data
+})
+
+const confirm = (email, code) => catch_errors('Confirmation failed', async () => {
+	const [errors, data] = await client.post('/auth/confirm', { email, code }, { auth: false })
+	if (errors) throw errors[0]
+	return data
+})
+
+const resend_code = (email) => catch_errors('Resend code failed', async () => {
+	const [errors, data] = await client.post('/auth/resend-code', { email }, { auth: false })
+	if (errors) throw errors[0]
+	return data
+})
+
+const device_start = () => catch_errors('Device auth start failed', async () => {
+	const [errors, data] = await client.post('/auth/device/start', {}, { auth: false })
+	if (errors) throw errors[0]
+	return data
+})
+
+const device_token = (device_code) => catch_errors('Device auth token failed', async () => {
+	const [errors, data] = await client.post('/auth/device/token', { device_code }, { auth: false })
+	if (errors) throw errors[0]
+	return data
+})
+
+module.exports = { login, signup, confirm, resend_code, device_start, device_token }

package/src/api/client.js

@@ -0,0 +1,65 @@
+const { createHash } = require('crypto')
+const { error: { catch_errors, wrap_errors: e } } = require('puffy-core')
+const { API_URL } = require('../constants')
+const { ApiError, NetworkError, AuthError } = require('../utils/errors')
+const { load_token } = require('../auth/token_store')
+
+const get_base_url = () => process.env.HAPPYSKILLS_API_URL || API_URL
+
+const request = (method, path, options = {}) => catch_errors(`API ${method} ${path} failed`, async () => {
+	const { body, auth = true, raw_response = false, headers: extra_headers = {} } = options
+	const url = `${get_base_url()}${path}`
+	const headers = { ...extra_headers }
+
+	if (auth) {
+		const [, token_data] = await load_token()
+		if (token_data) {
+			headers['Authorization'] = `Bearer ${token_data.id_token}`
+		}
+	}
+
+	const body_str = body ? (typeof body === 'string' ? body : JSON.stringify(body)) : undefined
+
+	if (body && !raw_response) {
+		headers['Content-Type'] = 'application/json'
+	}
+
+	if (body_str) {
+		headers['x-amz-content-sha256'] = createHash('sha256').update(body_str).digest('hex')
+	}
+
+	let res
+	try {
+		res = await fetch(url, {
+			method,
+			headers,
+			body: body_str
+		})
+	} catch (err) {
+		throw new NetworkError(`Failed to connect to API: ${err.message}`)
+	}
+
+	if (raw_response) return res
+
+	const data = await res.json().catch(() => null)
+
+	if (!res.ok) {
+		const err_code = data?.error?.code || 'UNKNOWN'
+		const err_msg = data?.error?.message || `Request failed with status ${res.status}`
+
+		if (res.status === 401) {
+			throw new AuthError(err_msg)
+		}
+
+		throw new ApiError(err_msg, res.status, err_code)
+	}
+
+	return data?.data !== undefined ? data.data : data
+})
+
+const get = (path, options) => request('GET', path, options)
+const post = (path, body, options) => request('POST', path, { ...options, body })
+const put = (path, body, options) => request('PUT', path, { ...options, body })
+const del = (path, options) => request('DELETE', path, options)
+
+module.exports = { request, get, post, put, del, get_base_url }

package/src/api/repos.js

@@ -0,0 +1,44 @@
+const { error: { catch_errors } } = require('puffy-core')
+const client = require('./client')
+
+const search = (query, options = {}) => catch_errors('Search failed', async () => {
+	const params = new URLSearchParams({ q: query })
+	if (options.limit) params.set('limit', options.limit)
+	if (options.offset) params.set('offset', options.offset)
+	const [errors, data] = await client.get(`/repos/search?${params}`, { auth: false })
+	if (errors) throw errors[0]
+	return data
+})
+
+const resolve_dependencies = (skill, version, installed = {}) => catch_errors('Dependency resolution failed', async () => {
+	const [errors, data] = await client.post('/repos:resolve-dependencies', { skill, version, installed })
+	if (errors) throw errors[0]
+	return data
+})
+
+const clone = (owner, repo, ref) => catch_errors(`Clone ${owner}/${repo} failed`, async () => {
+	const params = ref ? `?ref=${encodeURIComponent(ref)}` : ''
+	const [errors, data] = await client.get(`/repos/${owner}/${repo}/clone${params}`)
+	if (errors) throw errors[0]
+	return data
+})
+
+const push = (owner, repo, body) => catch_errors(`Push to ${owner}/${repo} failed`, async () => {
+	const [errors, data] = await client.post(`/repos/${owner}/${repo}/push`, body)
+	if (errors) throw errors[0]
+	return data
+})
+
+const get_refs = (owner, repo) => catch_errors(`Get refs for ${owner}/${repo} failed`, async () => {
+	const [errors, data] = await client.get(`/repos/${owner}/${repo}/refs`)
+	if (errors) throw errors[0]
+	return data
+})
+
+const get_repo = (owner, repo) => catch_errors(`Get repo ${owner}/${repo} failed`, async () => {
+	const [errors, data] = await client.get(`/repos/${owner}/${repo}`, { auth: false })
+	if (errors) throw errors[0]
+	return data
+})
+
+module.exports = { search, resolve_dependencies, clone, push, get_refs, get_repo }

package/src/api/workspaces.js

@@ -0,0 +1,10 @@
+const { error: { catch_errors } } = require('puffy-core')
+const client = require('./client')
+
+const list_workspaces = () => catch_errors('List workspaces failed', async () => {
+	const [errors, data] = await client.get('/workspaces')
+	if (errors) throw errors[0]
+	return data
+})
+
+module.exports = { list_workspaces }

package/src/auth/token_store.js

@@ -0,0 +1,69 @@
+const fs = require('fs')
+const path = require('path')
+const { error: { catch_errors } } = require('puffy-core')
+const { credentials_path, config_dir } = require('../config/paths')
+
+const save_token = (token_data) => catch_errors('Failed to save token', async () => {
+	const creds_path = credentials_path()
+	const dir = config_dir()
+	await fs.promises.mkdir(dir, { recursive: true })
+	const data = {
+		...token_data,
+		stored_at: new Date().toISOString()
+	}
+	await fs.promises.writeFile(creds_path, JSON.stringify(data, null, '\t') + '\n', {
+		encoding: 'utf-8',
+		mode: 0o600
+	})
+})
+
+const load_token = () => catch_errors('Failed to load token', async () => {
+	const creds_path = credentials_path()
+	try {
+		await fs.promises.access(creds_path)
+	} catch {
+		return null
+	}
+
+	const stat = await fs.promises.stat(creds_path)
+	const mode = stat.mode & 0o777
+	if (mode !== 0o600) {
+		const { print_warn } = require('../ui/output')
+		print_warn(`Credentials file has permissive permissions (${mode.toString(8)}). Expected 600.`)
+	}
+
+	const content = await fs.promises.readFile(creds_path, 'utf-8')
+	const data = JSON.parse(content)
+
+	if (data.stored_at && data.expires_in) {
+		const stored = new Date(data.stored_at).getTime()
+		const now = Date.now()
+		const elapsed_sec = (now - stored) / 1000
+		if (elapsed_sec >= data.expires_in) {
+			await clear_token()
+			return null
+		}
+	}
+
+	return data
+})
+
+const clear_token = () => catch_errors('Failed to clear token', async () => {
+	const creds_path = credentials_path()
+	try {
+		await fs.promises.unlink(creds_path)
+	} catch {
+		// File may not exist
+	}
+})
+
+const require_token = async () => {
+	const [, data] = await load_token()
+	if (!data) {
+		const { AuthError } = require('../utils/errors')
+		throw new AuthError()
+	}
+	return data
+}
+
+module.exports = { save_token, load_token, clear_token, require_token }

package/src/commands/check.js

@@ -0,0 +1,108 @@
+const { error: { catch_errors, wrap_errors: e } } = require('puffy-core')
+const { read_lock, get_all_locked_skills } = require('../lock/reader')
+const repos_api = require('../api/repos')
+const { satisfies, gt } = require('../utils/semver')
+const { print_help, print_table, print_json, print_info, print_success } = require('../ui/output')
+const { green, yellow, red } = require('../ui/colors')
+const { exit_with_error } = require('../utils/errors')
+const { EXIT_CODES } = require('../constants')
+
+const HELP_TEXT = `Usage: happyskills check [owner/skill] [options]
+
+Check for available updates.
+
+Arguments:
+  owner/skill       Check specific skill (optional, checks all if omitted)
+
+Options:
+  --json            Output as JSON
+
+Examples:
+  happyskills check
+  happyskills check acme/deploy-aws
+  happyskills check --json`
+
+const run = (args) => catch_errors('Check failed', async () => {
+	if (args.flags._show_help) {
+		print_help(HELP_TEXT)
+		return process.exit(EXIT_CODES.SUCCESS)
+	}
+
+	const project_root = process.cwd()
+	const [, lock_data] = await read_lock(project_root)
+	const skills = get_all_locked_skills(lock_data)
+	const entries = Object.entries(skills)
+
+	if (entries.length === 0) {
+		print_info('No skills installed.')
+		return
+	}
+
+	const target_skill = args._[0]
+	const to_check = target_skill
+		? entries.filter(([name]) => name === target_skill)
+		: entries.filter(([, data]) => data.requested_by?.includes('__root__'))
+
+	if (to_check.length === 0) {
+		print_info(target_skill ? `${target_skill} is not installed.` : 'No directly installed skills found.')
+		return
+	}
+
+	const results = []
+	for (const [name, data] of to_check) {
+		const [owner, repo] = name.split('/')
+		const [errors, refs] = await repos_api.get_refs(owner, repo)
+		if (errors) {
+			results.push({ skill: name, installed: data.version, latest: 'error', status: 'error' })
+			continue
+		}
+
+		const versions = (refs || [])
+			.map(r => r.name?.replace('refs/tags/v', ''))
+			.filter(Boolean)
+
+		const latest = versions.sort((a, b) => gt(a, b) ? -1 : 1)[0]
+
+		if (!latest) {
+			results.push({ skill: name, installed: data.version, latest: '-', status: 'unknown' })
+		} else if (latest === data.version) {
+			results.push({ skill: name, installed: data.version, latest, status: 'up-to-date' })
+		} else if (gt(latest, data.version)) {
+			results.push({ skill: name, installed: data.version, latest, status: 'outdated' })
+		} else {
+			results.push({ skill: name, installed: data.version, latest, status: 'up-to-date' })
+		}
+	}
+
+	if (args.flags.json) {
+		print_json(results)
+		return
+	}
+
+	const status_colors = {
+		'up-to-date': green,
+		'outdated': yellow,
+		'error': red,
+		'unknown': (s) => s
+	}
+
+	const rows = results.map(r => [
+		r.skill,
+		r.installed,
+		r.latest,
+		(status_colors[r.status] || ((s) => s))(r.status)
+	])
+
+	print_table(['Skill', 'Installed', 'Latest', 'Status'], rows)
+
+	const outdated = results.filter(r => r.status === 'outdated')
+	if (outdated.length > 0) {
+		console.log()
+		print_info(`Run 'happyskills update' to upgrade ${outdated.length} skill(s).`)
+	} else if (results.every(r => r.status === 'up-to-date')) {
+		console.log()
+		print_success('All skills are up to date.')
+	}
+}).then(([errors]) => { if (errors) { exit_with_error(errors); return } })
+
+module.exports = { run }