feat: add Java integration via Chicory WebAssembly runtime

.github/workflows/test-java.yml

@@ -0,0 +1,33 @@
+name: test-java
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  MISE_EXPERIMENTAL: 1
+
+jobs:
+  test-java:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        with:
+          submodules: recursive
+      - uses: Swatinem/rust-cache@779680da715d629ac1d338a641029a2f4372abb5 # v2
+        with:
+          shared-key: wasm
+      - uses: jdx/mise-action@e79ddf65a11cec7b0e882bedced08d6e976efb2d # v3
+      - uses: actions/setup-java@c5195efecf7bdfc987ee8bae7a71cb8b11521c00 # v4
+        with:
+          distribution: temurin
+          java-version: 21
+      - run: rustup target add wasm32-wasip1
+      - run: mise run wasm:build
+      - run: cd integrations/java && mvn clean install
+      - uses: jbangdev/setup-jbang@2b1b465a7b75f4222b81426f23a01e013aa7b95c # v0.1.1
+      - run: cd integrations/java && jbang example/Main.java

.gitignore

@@ -10,3 +10,6 @@
 #/target
 megalinter-reports/
 tasks/fig/build
+
+cli/wasi-sdk/
+integrations/java/target/

Cargo.toml

@@ -20,3 +20,8 @@ usage-lib = { path = "./lib", version = "3.2.0", features = ["clap"] }
 
 [workspace.metadata.release]
 allow-branch = ["main"]
+
+[profile.wasm]
+inherits = "release"
+opt-level = "z"
+strip = "symbols"

cli/Cargo.toml

@@ -40,6 +40,7 @@ serde_with = "3"
 tera = "1"
 thiserror = "2"
 usage-lib = { workspace = true, features = ["clap", "docs", "unstable_choices_env"] }
+[target.'cfg(not(target_arch = "wasm32"))'.dependencies]
 xx = "2"
 
 [target.'cfg(unix)'.dependencies]

cli/src/cli/complete_word.rs

@@ -2,15 +2,15 @@ use std::collections::BTreeMap;
 use std::env;
 use std::fmt::Debug;
 use std::path::{Path, PathBuf};
+#[cfg(not(target_arch = "wasm32"))]
 use std::process::Command;
 use std::sync::Arc;
 
 use clap::Args;
 use itertools::Itertools;
 use miette::IntoDiagnostic;
+use regex::Regex;
 use std::sync::LazyLock;
-use xx::process::check_status;
-use xx::{regex, XXError, XXResult};
 
 use usage::{Spec, SpecArg, SpecCommand, SpecComplete, SpecFlag};
 
@@ -283,7 +283,8 @@ impl CompleteWord {
             trace!("run: {run}");
             let stdout = sh(&run)?;
             // trace!("stdout: {stdout}");
-            let re = regex!(r"[^\\]:");
+            static COLON_RE: LazyLock<Regex> = LazyLock::new(|| Regex::new(r"[^\\]:").unwrap());
+            let re = &*COLON_RE;
             return Ok(stdout
                 .lines()
                 .map(|l| {
@@ -372,7 +373,10 @@ fn zsh_escape(s: &str) -> String {
         .replace(']', "\\]")
 }
 
-fn sh(script: &str) -> XXResult<String> {
+#[cfg(not(target_arch = "wasm32"))]
+fn sh(script: &str) -> xx::XXResult<String> {
+    use xx::process::check_status;
+    use xx::XXError;
     let output = Command::new("sh")
         .arg("-c")
         .arg(script)
@@ -387,3 +391,8 @@ fn sh(script: &str) -> XXResult<String> {
     let stdout = String::from_utf8(output.stdout).expect("stdout is not utf-8");
     Ok(stdout)
 }
+
+#[cfg(target_arch = "wasm32")]
+fn sh(_script: &str) -> miette::Result<String> {
+    Err(miette::miette!("shell execution is not supported on wasm"))
+}

cli/src/cli/generate/fig.rs

@@ -7,6 +7,7 @@ use itertools::Itertools;
 use usage::{SpecArg, SpecCommand, SpecComplete, SpecFlag};
 
 use crate::cli::generate;
+use miette::IntoDiagnostic;
 use serde::{Deserialize, Serialize, Serializer};
 use serde_with::{serde_as, OneOrMany};
 
@@ -356,7 +357,10 @@ impl Fig {
     pub fn run(&self) -> miette::Result<()> {
         let write = |path: &PathBuf, md: &str| -> miette::Result<()> {
             println!("writing to {}", path.display());
-            xx::file::write(path, format!("{}\n", md.trim()))?;
+            if let Some(parent) = path.parent() {
+                std::fs::create_dir_all(parent).into_diagnostic()?;
+            }
+            std::fs::write(path, format!("{}\n", md.trim())).into_diagnostic()?;
             Ok(())
         };
         let spec = generate::file_or_spec(&self.file, &self.spec)?;

cli/src/cli/generate/manpage.rs

@@ -2,6 +2,7 @@ use std::path::PathBuf;
 
 use super::parse_file_or_stdin;
 use clap::Args;
+use miette::IntoDiagnostic;
 use usage::docs::manpage::ManpageRenderer;
 
 #[derive(Args)]
@@ -34,7 +35,10 @@ impl Manpage {
 
         if let Some(out_file) = &self.out_file {
             println!("writing to {}", out_file.display());
-            xx::file::write(out_file, &manpage)?;
+            if let Some(parent) = out_file.parent() {
+                std::fs::create_dir_all(parent).into_diagnostic()?;
+            }
+            std::fs::write(out_file, &manpage).into_diagnostic()?;
         } else {
             print!("{}", manpage);
         }

cli/src/cli/generate/markdown.rs

@@ -2,6 +2,7 @@ use std::path::PathBuf;
 
 use super::parse_file_or_stdin;
 use clap::Args;
+use miette::IntoDiagnostic;
 use usage::docs::markdown::MarkdownRenderer;
 
 /// Generate markdown documentation from usage specs
@@ -43,13 +44,17 @@ impl Markdown {
     pub fn run(&self) -> miette::Result<()> {
         let write = |path: &PathBuf, md: &str| -> miette::Result<()> {
             println!("writing to {}", path.display());
-            xx::file::write(
+            if let Some(parent) = path.parent() {
+                std::fs::create_dir_all(parent).into_diagnostic()?;
+            }
+            std::fs::write(
                 path,
                 format!(
                     "<!-- @generated by usage-cli from usage spec -->\n{}\n",
                     md.trim()
                 ),
-            )?;
+            )
+            .into_diagnostic()?;
             Ok(())
         };
         let spec = parse_file_or_stdin(&self.file)?;

cli/src/lib.rs

@@ -1,6 +1,7 @@
 #[macro_use]
 extern crate log;
 extern crate miette;
+#[cfg(not(target_arch = "wasm32"))]
 extern crate xx;
 
 use miette::Result;

integrations/java/README.md

@@ -0,0 +1,108 @@
+# usage-java
+
+Run the [usage](https://usage.jdx.dev) CLI from Java via [Chicory](https://github.com/dylibso/chicory), a pure-Java WebAssembly runtime.
+
+The `usage` CLI is compiled to WebAssembly (WASI) and executed at runtime through Chicory with build-time AOT compilation for fast execution.
+
+## Prerequisites
+
+Build the WASM binary (requires wasi-sdk):
+
+```bash
+mise run wasm:build
+```
+
+## Build
+
+```bash
+cd integrations/java
+mvn compile
+```
+
+## Quick Start
+
+```java
+import dev.jdx.usage.Usage;
+import dev.jdx.usage.UsageResult;
+
+String spec =
+    "name \"mycli\"\n"
+    + "bin \"mycli\"\n"
+    + "version \"1.0.0\"\n"
+    + "flag \"-v --verbose\" help=\"Verbose output\"\n"
+    + "cmd \"run\" help=\"Run the thing\" {\n"
+    + "    arg <target>\n"
+    + "}\n";
+
+// Generate bash completions
+UsageResult result = Usage.builder()
+    .withStdin(spec)
+    .withArgs("generate", "completion", "bash", "mycli", "-f", "-")
+    .run();
+
+System.out.println(result.stdoutAsString());
+```
+
+## API
+
+### `Usage.builder()`
+
+Creates a builder for running usage CLI commands.
+
+| Method                 | Description                                                               |
+| ---------------------- | ------------------------------------------------------------------------- |
+| `.withStdin(String)`   | Pipe a string to stdin (typically a usage spec)                           |
+| `.withStdin(byte[])`   | Pipe bytes to stdin                                                       |
+| `.withArgs(String...)` | Append CLI arguments (the `usage` program name is added automatically)    |
+| `.withDirectory(Path)` | Pre-open a directory for WASI filesystem access (needed for `--out-file`) |
+| `.run()`               | Execute and return a `UsageResult`                                        |
+
+### `UsageResult`
+
+| Method              | Description              |
+| ------------------- | ------------------------ |
+| `.stdout()`         | Raw stdout bytes         |
+| `.stderr()`         | Raw stderr bytes         |
+| `.stdoutAsString()` | Stdout as UTF-8 string   |
+| `.stderrAsString()` | Stderr as UTF-8 string   |
+| `.exitCode()`       | Process exit code        |
+| `.success()`        | `true` if exit code is 0 |
+
+## Common Commands
+
+```java
+// Generate shell completions
+Usage.builder().withStdin(spec).withArgs("generate", "completion", "bash", "mybinary", "-f", "-").run();
+Usage.builder().withStdin(spec).withArgs("generate", "completion", "zsh", "mybinary", "-f", "-").run();
+Usage.builder().withStdin(spec).withArgs("generate", "completion", "fish", "mybinary", "-f", "-").run();
+
+// Generate man page
+Usage.builder().withStdin(spec).withArgs("generate", "manpage", "-f", "-").run();
+
+// Generate JSON spec
+Usage.builder().withStdin(spec).withArgs("generate", "json", "-f", "-").run();
+
+// Generate markdown (requires a directory for --out-file, use ZeroFs for in-memory)
+FileSystem fs = ZeroFs.newFileSystem(Configuration.unix().toBuilder().setAttributeViews("unix").build());
+Path outDir = fs.getPath("out");
+Files.createDirectory(outDir);
+Usage.builder()
+    .withStdin(spec)
+    .withArgs("generate", "markdown", "-f", "-", "--out-file", outDir.resolve("docs.md").toString())
+    .withDirectory(outDir)
+    .run();
+String markdown = new String(Files.readAllBytes(outDir.resolve("docs.md")));
+```
+
+## Example
+
+See [`example/Main.java`](example/Main.java) for a complete example mirroring the [cobra integration example](../cobra/example/main.go).
+
+Run it with [jbang](https://www.jbang.dev/):
+
+```bash
+mise run wasm:build
+cd integrations/java
+mvn install
+jbang example/Main.java
+```