You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
> **Project status**: stable (1.0.x line). Not yet published to Maven Central; artifacts are distributed via the Aliyun Maven repository and GitHub Releases.
21
+
22
+
<aid="1-project-overview"></a>
23
+
## 1. Project Overview
24
+
25
+
### 1.1 What it is
26
+
27
+
**opencli-java-sdk** integrates Java applications with the [OpenCLI](https://github.com/partme-ai/opencli) multi-adapter CLI ecosystem. It executes `opencli <adapter> ...` subprocesses via Commons Exec, exposes typed results (`OpenCliResult` / `OpenCliTypedResult`), unified exception semantics, remote HTTP agent support (Unirest) and a center WebSocket reverse-agent client (Java-WebSocket). It compiles and runs on JDK 8.
28
+
29
+
### 1.2 What it is not
30
+
31
+
- Not OpenCLI itself and not a browser automation engine — it drives the `opencli` CLI.
32
+
- No Spring dependency; Spring Boot applications use the companion `opencli-spring-boot-starter`.
33
+
- Not an SDK generator for new adapters; adapter IDs are generated from the upstream `opencli/docs/adapters/index.md` manifest.
34
+
35
+
### 1.3 Typical scenarios
36
+
37
+
| Scenario | Recommended entry | Result |
38
+
|---|---|---|
39
+
| Run any adapter command |`cli.adapter("hackernews").invoke("top", "--limit", "5")`| Typed `OpenCliResult`|
40
+
| Typed wrapper for a known adapter |`cli.gemini().deepResearch(...)`, `cli.npm()`, `cli.codex()` ... | Strongly-typed options and results |
41
+
| Batch over all adapters |`OpenCliAdapterEnumerator` + `OpenCliAdapterIds.ALL`| Sequential adapter execution |
42
+
| Run commands through a remote agent |`executionTarget=REMOTE_AGENT_HTTP` + `remoteAgentBaseUrl`|`POST {base}/collect` execution |
43
+
| Join a center as an edge node |`OpenCliWsReverseAgentClient`| Register, receive `collect`, reply `result`|
44
+
45
+
<aid="2-features--status"></a>
46
+
## 2. Features & Status
47
+
48
+
| Capability | Status | Notes |
49
+
|---|:---:|---|
50
+
| Local subprocess execution | Available |`OpenCliExecutor` (Commons Exec), unified exceptions (`OpenCliNonZeroExitException`, `OpenCliTimeoutException`, ...) |
51
+
| Adapter channel | Available |`OpenCliAdapterChannel` (`invoke(List)` / varargs) |
52
+
| Adapter registry | Available |`OpenCliAdapterIds` + `OpenCliAdapterTaxonomy` — 173 adapter ids (163 browser + 10 desktop) generated from the upstream manifest |
**Expected result**: the first call spawns `opencli hackernews top --limit 5` locally and returns a typed `OpenCliResult`; the second invokes the Gemini adapter's deep-research command with typed options. When the `opencli` executable is missing, `OpenCliExecutor` surfaces the failure through the unified exception hierarchy (`OpenCliStartupException` / `OpenCliExecutableFailureException`).
-In remote mode the `stdout`is the JSON `items`the agent returned (parsed into line items per `format`), which may differ from local raw subprocess text; `leadingArguments` are local-only and are not injected on the remote path.
186
+
-`execution-target=REMOTE_AGENT_HTTP` makes the availability probe report `SKIPPED_REMOTE_MODE` (treated as startable).
Protocol: edge sends `register`; center replies `registered`; center sends `collect` (request_id, site, command, args, positional_args, format, mode); the SDK executes `opencli` locally (via `copyForLocalCliExecution()` to avoid loops) and replies `result`; plus `ping` / `pong`.
- Unit tests cover the adapter registry, core execution, browser/meta/remote paths and WS helpers (14 test sources under `src/test`).
229
+
- JaCoCo runs `prepare-agent`, `report` and `check` on the `verify` phase with a **90% line-coverage** rule (`haltOnFailure=false`).
230
+
-`scripts/generate_opencli_adapter_ids.py` regenerates `OpenCliAdapterIds` / `OpenCliAdapterTaxonomy` from the upstream `opencli/docs/adapters/index.md` + `cli-manifest.json` (set `OPENCLI_ROOT` to point at the upstream tree).
231
+
- Release packaging (`mvn -Prelease deploy`) attaches sources and javadoc jars, GPG-signs artifacts and is wired for Sonatype Central Publishing; plain `mvn deploy` routes SNAPSHOT/release artifacts to the Aliyun Maven repository per `distributionManagement`.
Branch POMs (JDK and dependency stack per line) are rendered by `scripts/render-branch-pom.py`.
159
243
160
-
## License
244
+
<aid="11-contributing--license"></a>
245
+
## 11. Contributing & License
161
246
162
-
Apache License 2.0
247
+
Contributions are welcome. Run `mvn clean verify` before opening a pull request and describe compatibility, testing and migration impact. This project is licensed under the [Apache License 2.0](LICENSE).
0 commit comments