wasm-rquickjs-cli 0.0.21

Tool for wrapping JavaScript modules as WebAssembly components using the QuickJS engine
# AGENTS.md - wasm-rquickjs Development Guide

## Project Overview

**wasm-rquickjs** is a command-line tool and library that wraps JavaScript code into WebAssembly Components using the QuickJS engine. The tool generates self-contained Rust crates that compile to WASM components.

## Project Structure

```
wasm-rquickjs/
├── crates/
│   ├── wasm-rquickjs/          # Main library crate
│   │   ├── skeleton/           # Embedded skeleton crate (separate project)
│   │   └── src/
│   └── wasi-logging/           # WASI logging support crate
├── examples/                   # Example projects
├── src/                        # CLI binary source (main.rs)
├── tests/                      # Integration tests
├── Cargo.toml                  # Workspace root
├── cleanup-skeleton.sh         # Script to clean skeleton build artifacts
└── README.md                   # Main documentation
```

## Important Notes About @crates/wasm-rquickjs/skeleton

The `skeleton` crate is a **separate project** that is embedded within the `wasm-rquickjs` crate. It is crucial to understand the following:

### Cargo.toml Naming Convention

**The skeleton's `Cargo.toml` MUST be renamed to `Cargo.toml_` in the repository.**

- The file is stored as `Cargo.toml_` to avoid conflicts with Rust packaging when embedded
- When working on the skeleton locally, rename it to `Cargo.toml` before building
- Before committing changes back, rename it back to `Cargo.toml_`
- The embedded file in the final package uses the renamed `Cargo.toml_`

### Building and Testing the Skeleton

The skeleton crate can be compiled separately from the main project:

```bash
cd crates/wasm-rquickjs/skeleton

# Rename Cargo.toml_ to Cargo.toml for local development
mv Cargo.toml_ Cargo.toml

# Build/test the skeleton
cargo build
cargo test

# Rename back before committing
mv Cargo.toml Cargo.toml_
```

### Runtime tests
To test the builtin module of the skeleton, first define an example in `examples`, consisting of a pair of a JS file and a WIT interface,
and then add one or more tests in `tests/runtime.rs` that use the example.

### Cleaning Skeleton Build Artifacts

After compiling the skeleton for testing, **always clean its build artifacts** before compiling the main `wasm-rquickjs` crate:

```bash
./cleanup-skeleton.sh
```

**Why?** The `include_dir!` macro embeds the entire skeleton directory into the main package during compilation. If the skeleton's `target/` directory is present, it will be embedded, causing:
- Dramatically slower compilation times
- Significantly larger resulting binaries

## Build Commands

### Build the CLI binary
```bash
cargo build --release
```

### Run tests
```bash
cargo test
```

### Build specific test harness
```bash
cargo test --test compilation
cargo test --test runtime
cargo test --test dts
cargo test --test errors
```

### Generate code for a JavaScript module
```bash
./target/release/wasm-rquickjs generate-wrapper-crate \
  --js <path/to/module.js> \
  --wit <path/to/wit/root> \
  --output <output/directory>
```

### Generate TypeScript definitions
```bash
./target/release/wasm-rquickjs generate-dts \
  --wit <path/to/wit/root> \
  --output <output/directory>
```

## Code Quality

### Formatting

The project uses `rustfmt` for code formatting. Before committing, ensure code is formatted:

```bash
cargo fmt
```

To check formatting without making changes:

```bash
cargo fmt -- --check
```

### Clippy Linting

The project uses Clippy with strict warnings enabled. All warnings must be fixed:

```bash
cargo clippy -- -Dwarnings
```

To fix common issues automatically:

```bash
cargo clippy --fix -- -Dwarnings
```

### Pre-commit Checks

Run all quality checks before committing:

```bash
cargo fmt
cargo clippy -- -Dwarnings
cargo test
```

## Workspace Configuration

The workspace is configured in the root `Cargo.toml` with the following members:
- `crates/wasi-logging` - WASI logging support
- `crates/wasm-rquickjs` - Main library crate

**Excluded from workspace:**
- `crates/wasm-rquickjs/skeleton` - Separate project, compiled independently
- `tmp/` - Temporary build artifacts

## Development Workflow

### When working on the skeleton (JavaScript APIs, core functionality):

1. Navigate to the skeleton directory
2. Rename `Cargo.toml_` to `Cargo.toml`
3. Make changes and test with `cargo build`/`cargo test`
4. When done, run from the repo root: `./cleanup-skeleton.sh`
5. Rename skeleton's `Cargo.toml` back to `Cargo.toml_`
6. Commit your changes

### When working on code generation:

1. Modify the main `crates/wasm-rquickjs` crate
2. Run tests with `cargo test`
3. Changes to the skeleton will be embedded via `include_dir!` at compile time

### When working on the CLI:

1. Modify `src/main.rs`
2. Build with `cargo build --release`
3. Test with `cargo test --test compilation` or `cargo test --test runtime`

## Key Files

- `src/main.rs` - CLI entry point
- `crates/wasm-rquickjs/src/` - Code generation logic
- `crates/wasm-rquickjs/skeleton/src/` - JavaScript runtime APIs
- `tests/` - Integration tests for compilation, runtime, DTS generation, and error handling

## Features

The generated crates support feature flags:
- `logging` - Enable `wasi:logging` for JavaScript console API
- `http` - Enable `wasi:http` for JavaScript fetch API

Both features are enabled by default in generated crates.

## Dependencies

Key external dependencies:
- `rquickjs` - QuickJS Rust bindings
- `wit-parser` / `wit-encoder` - WebAssembly Interface Type support
- `wasmtime` - WASM runtime for testing
- `cargo-component` - WASM component compilation (for end users)