wasmhub 0.3.2

# Contributing to WasmHub

Thank you for your interest in contributing! This project aims to be community-driven.

## 📁 Project Structure

```sh
wasmhub/
├── src/
│   ├── lib.rs                       # 📦 Library code
│   └── bin/
│       └── wasmhub.rs               # 🔧 CLI binary (feature-gated)
│
├── runtimes/                        # 📁 Runtime sources and manifests
│   └── go/
│       ├── main.go                  # Source file
│       ├── manifest.json            # Version metadata
│       └── *.wasm                   # Built binaries (gitignored)
│
├── scripts/                         # 🔧 Build scripts
│   ├── build-all.sh                 # Build all runtimes
│   ├── build-go.sh                  # Build Go runtime
│   ├── build-rust.sh                # Build Rust runtime
│   ├── generate-metadata.sh         # Generate manifest.json
│   └── verify-binary.sh             # Verify WASM binary
│
├── .github/workflows/
│   ├── ci.yml                       # ✅ CI pipeline (tests, lint, format)
│   ├── release.yml                  # 📦 Release workflow (builds WASM + CLI)
│   ├── build-runtimes.yml           # 🔨 Build runtimes on push
│   └── docs.yml                     # 📚 Build + deploy docs site to Pages
│
├── docs/                            # 📚 Eleventy docs site (GitHub Pages)
│   ├── content/                     # Markdown pages
│   ├── assets/theme.css             # Wasmhub theming
│   ├── .eleventy.js                 # Eleventy config
│   └── package.json                 # Site deps + build scripts
│
├── Cargo.toml                       # 📦 Package manifest
├── Dockerfile                       # 🐳 Build environment for WASM
├── justfile                         # 🛠️ Build commands
├── README.md                        # 📖 User-facing docs
├── CONTRIBUTING.md                  # 👥 This file
├── LICENSE                          # ⚖️ MIT License
└── .gitignore                       # 🚫 Git ignore rules
```

The project is a single Rust crate with:
- **Library API** (`src/lib.rs`) - Can be used programmatically
- **CLI tool** (`src/bin/wasmhub.rs`) - Enabled with `--features cli`

## 🚀 Ways to Contribute

1. **Report Bugs** - Open an issue with reproduction steps
2. **Request Features** - Suggest new runtimes or improvements
3. **Submit PRs** - Fix bugs, add runtimes, improve docs
4. **Improve Documentation** - Help others understand the project
5. **Share** - Star the repo, tell others about it

## 🔧 Development Setup

### Prerequisites

- Rust 1.85+ (`rustup install stable`)
- Git
- Just (optional, for convenient build commands: `cargo install just`)

### Clone & Build

```sh
# Clone repository
git clone https://github.com/anistark/wasmhub.git
cd wasmhub

# Build library only
cargo build

# Build library + CLI
cargo build --features cli

# Run tests
cargo test

# Run CLI locally
cargo run --features cli -- --help

# Install CLI globally
cargo install --path . --features cli
```

## 📝 Code Style

```sh
# Format code
just format

# Lint code
just lint

# Auto-fix linting issues
just lint-fix
```

All PRs must pass formatting and linting checks.

## 🧪 Testing

Write tests for all new features:

```rust
#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_language_from_str() {
        assert_eq!(Language::from_str("nodejs"), Some(Language::NodeJs));
        assert_eq!(Language::from_str("unknown"), None);
    }
}
```

Run tests:
```sh
cargo test
```

## 📦 Adding a New Runtime

WASM binaries are **not** committed to the repository. They are built by CI and published as GitHub Release assets.

### Steps to Add a New Runtime

1. **Create the source directory**: `runtimes/<language>/`
2. **Add the source file** (e.g., `main.go`, `lib.rs`)
3. **Create a build script**: `scripts/build-<language>.sh`
4. **Update `scripts/build-all.sh`** to include your language
5. **Add to `Language` enum** in `src/runtime.rs`
6. **Write tests**
7. **Update README.md** with the new runtime
8. **Submit PR**

Example for adding Java:
```sh
# Create runtime directory with source
mkdir -p runtimes/java
# Add source file (e.g., Main.java)

# Create build script
cat > scripts/build-java.sh << 'EOF'
#!/usr/bin/env bash
# Build Java to WASM using TeaVM or similar
EOF
chmod +x scripts/build-java.sh

# Update build-all.sh to include Java builds
# Update Language enum in src/runtime.rs
git commit -am "Add Java runtime support"
```

### Runtime Directory Structure

```sh
runtimes/
├── go/
│   ├── main.go           # Source file (committed)
│   ├── manifest.json     # Generated by build (committed)
│   └── go-1.23.wasm      # Built binary (gitignored, in releases)
└── rust/
    ├── Cargo.toml        # Source (committed)
    ├── src/lib.rs        # Source (committed)
    ├── manifest.json     # Generated by build (committed)
    └── rust-1.75.wasm    # Built binary (gitignored, in releases)
```

### Manifest Format

Each runtime has a `manifest.json` that describes available versions:

```json
{
    "language": "go",
    "latest": "1.23",
    "versions": {
        "1.23": {
            "file": "go-1.23.wasm",
            "size": 266712,
            "sha256": "efa1e13f39dfd3783d0eff5669088ab99a1ea1d38ac79f29b02e2ad8ddfea29d",
            "released": "2026-02-03T13:23:13Z",
            "wasi": "wasip1",
            "features": []
        }
    }
}
```

The manifest is auto-generated by `scripts/generate-metadata.sh` during the build process.

## 📚 Documentation Site

The docs site lives in `docs/` and is built with [Eleventy 3.x](https://www.11ty.dev/) using the [eleventy-libdoc](https://github.com/ita-design-system/eleventy-libdoc) starter. It's deployed to GitHub Pages at **https://anistark.github.io/wasmhub/** automatically when anything under `docs/**` lands on `main`.

### Run the docs locally

```sh
just docs-install      # first time only — installs pnpm deps
just docs              # → http://localhost:8080/
just docs-build        # production build → docs/_site/
just docs-clean        # remove _site/
```

Or directly with pnpm if you prefer:

```sh
cd docs
pnpm install
pnpm run serve
```

> **Use pnpm**, not npm. The lockfile and CI are pinned to pnpm.

### Add or edit a page

1. Create or edit a `.md` file under `docs/content/`
2. Add YAML frontmatter (title, navigation order — see existing pages for the libdoc convention)
3. Cross-link to other pages using the Eleventy `url` filter so the `/wasmhub/` path prefix works on GitHub Pages:
   ```liquid
   [CLI reference]({{ '/cli/' | url }})
   ```
4. Preview locally with `npm run serve`
5. Open a PR — once merged, the site rebuilds and deploys within ~2 minutes

### Theming

Wasmhub branding lives in `docs/assets/theme.css` and overrides libdoc's CSS custom properties. **Don't edit libdoc's vendored CSS directly** — it makes future libdoc upgrades painful. If you need to add styles libdoc doesn't expose as variables, add them to `theme.css`.

### Adding screenshots/images

Drop images into `docs/assets/` (or a subfolder). libdoc uses `@11ty/eleventy-img` + `sharp` for transcoding/responsive variants — reference images normally in Markdown and the build handles the rest.

### Build for production

```sh
cd docs
pnpm run build         # output in docs/_site/ (gitignored)
```

CI does this automatically — you don't need to commit build output.

---

## 🔄 CI/CD and Releases

### Continuous Integration

Every PR and push to `main` triggers CI checks:
- **Test**: Runs `cargo test` on Linux, macOS, and Windows
- **Format**: Checks code formatting with `cargo fmt`
- **Lint**: Runs `cargo clippy` for linting

### Release Process

When a GitHub Release is created:

1. **WASM runtimes are built** using the Docker build environment
2. **Manifests are generated** with checksums and metadata
3. **Binaries are uploaded** as release assets
4. **CLI binaries** are cross-compiled for all platforms

To create a release:
```sh
# Update version in Cargo.toml, then run:
just publish

# Or for GitHub release only (no crates.io):
just publish-github

# Or with explicit version:
just release 0.3.2
```

### Build Environment

WASM runtimes are built in a Docker container with:
- WASI SDK (for C/C++ compilation)
- TinyGo (for Go compilation)
- Rust with `wasm32-wasip1` target
- `wasm-opt` for binary optimization

To build locally:
```sh
# Using Docker (recommended)
just docker-build          # Build the Docker image
just docker-build-runtimes # Build all WASM runtimes

# Or install dependencies natively and run
./scripts/build-all.sh
```

---

## 🐛 Reporting Bugs

Open an issue with:
- **Description** - What went wrong?
- **Steps to reproduce**
- **Expected behavior**
- **Actual behavior**
- **Environment** - OS, Rust version, etc.

## 💡 Feature Requests

Open an issue with:
- **Use case** - Why is this needed?
- **Proposed solution**
- **Alternatives considered**

## 🔀 Pull Request Process

1. **Fork** the repository
2. **Create a branch** - `git checkout -b feature/my-feature`
3. **Make changes** - Follow code style
4. **Write tests** - Ensure coverage
5. **Update docs** - If needed
6. **Commit** - Use clear commit messages
7. **Push** - `git push origin feature/my-feature`
8. **Open PR** - Fill out the template

### PR Checklist

- [ ] Code follows Rust style guide (`cargo fmt`)
- [ ] No clippy warnings (`cargo clippy`)
- [ ] Tests added and passing (`cargo test`)
- [ ] Documentation updated
- [ ] CHANGELOG.md updated (if applicable)

## 📜 Commit Messages

Use conventional commits:

```
feat: add Java runtime support
fix: correct cache path on Windows
docs: update CLI usage examples
test: add integration tests for loader
chore: update dependencies
```

## 🏷️ Issue Labels

- `good-first-issue` - Great for newcomers
- `help-wanted` - Need community help
- `bug` - Something isn't working
- `enhancement` - New feature request
- `documentation` - Docs improvements

## ⚖️ Code of Conduct

Be respectful, inclusive, and collaborative. We're building this together.

## 📞 Questions?

- Open a [Discussion](https://github.com/anistark/wasmhub/discussions)
- Ask on Discord (coming soon)
- Email: ani@anistark.com

## 💡 Quick Reference

### Common Commands

Using justfile (recommended):

```sh
# Show all available commands
just --list

# Format code
just format

# Lint code
just lint

# Auto-fix lint issues
just lint-fix

# Check compilation
just check

# Build library
just build

# Build with all features
just build-all

# Run tests
just test

# Run all CI checks locally
just ci

# Install CLI globally
just install
```

Or using cargo directly:

```sh
# Build everything (library + CLI)
cargo build --all-features

# Run all tests
cargo test

# Format code
cargo fmt --all

# Lint code
cargo clippy --all-features

# Run CLI locally
cargo run --features cli -- list

# Check documentation
cargo doc --open

# Build release binary
cargo build --release --features cli
```

### Project Layout

- **src/lib.rs** - Public API for the library
- **src/bin/wasmhub.rs** - CLI application code
- **runtimes/** - Downloaded WASM runtime binaries
- **Cargo.toml** - Package manifest with `cli` feature flag

### Feature Flags

- **default** - Library only, no CLI
- **cli** - Includes CLI binary with `clap` argument parsing

Thank you for contributing! 🎉