fix: 同步 3.0.x 生产就绪审计修复——CLI 真实退出码/并发闸门/OkHttp 所有权模型（Jackson 2 / JDK 17 适配）；附 .shellcheckrc 抑制生成物噪音

Author: loong10k

.shellcheckrc

@@ -0,0 +1,4 @@
+# ShellCheck 仓库级配置
+# SC1071: scripts/*.zsh 为合法 zsh 脚本，bash 方言规则不适用
+# SC2148: target/reports/apidocs/javadoc.sh 为 maven-javadoc-plugin 生成物，无 shebang 属已知噪音
+disable=SC1071,SC2148

src/main/java/io/github/easy4j/opencode/api/OpenCodeHttpClient.java

@@ -64,6 +64,11 @@ public class OpenCodeHttpClient implements AutoCloseable {
      * 执行连接复用和异步网络请求的 OkHttp 客户端。
      */
     private final OkHttpClient httpClient;
+    /**
+     * 是否由 SDK 自建 OkHttp 客户端（构造时传入 {@code null}）；自建的由
+     * {@link #close()} 负责 shutdown，外部注入的归调用方所有。
+     */
+    private final boolean ownsHttpClient;
     /**
      * 请求与响应 JSON 的序列化映射器。
      */
@@ -80,7 +85,8 @@ public OpenCodeHttpClient(OpenCodeHttpClientConfig config, ObjectMapper objectMa
         this.config = Objects.requireNonNull(config, "config");
         this.objectMapper = Objects.isNull(objectMapper) ? JsonMapper.builder()
                 .disable(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES).build(): objectMapper;
-        this.httpClient = Objects.isNull(httpClient) ? buildOkHttpClient(config) : httpClient;
+        this.ownsHttpClient = Objects.isNull(httpClient);
+        this.httpClient = this.ownsHttpClient ? buildOkHttpClient(config) : httpClient;
         if (allows(HttpLogLevel.BASIC)) {
             log.debug("OpenCode HTTP client initialized: baseUrl={}, connectTimeoutMs={}, readTimeoutMs={}, "
                             + "callTimeoutMs={}, retryOnConnectionFailure={}, debugLevel={}",
@@ -1630,6 +1636,17 @@ private String toJson(Object body) {
      */
     @Override
     public void close() {
-        // 外部传入的 OkHttpClient 不关闭；自建的也不主动关闭（OkHttpClient 内部管理连接池）
+        // OkHttp Dispatcher 线程默认非 daemon：自建客户端必须显式 shutdown，
+        // 否则循环创建 client 的场景会积留线程；外部注入的归调用方所有。
+        if (ownsHttpClient) {
+            OpenCodeOkHttpClientFactory.shutdown(httpClient);
+        }
+    }
+
+    /**
+     * 包内可见的底层 OkHttp 客户端访问器（测试断言 shutdown 状态用）。
+     */
+    OkHttpClient internalHttpClient() {
+        return httpClient;
     }
 }

src/main/java/io/github/easy4j/opencode/cli/OpenCodeCliExecutor.java

@@ -4,6 +4,7 @@
 import okhttp3.extension.logging.HttpLogLevel;
 import org.apache.commons.exec.CommandLine;
 import org.apache.commons.exec.DefaultExecutor;
+import org.apache.commons.exec.ExecuteException;
 import org.apache.commons.exec.ExecuteWatchdog;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
@@ -13,6 +14,7 @@
 import java.io.IOException;
 import java.nio.charset.StandardCharsets;
 import java.util.Objects;
+import java.util.concurrent.Semaphore;
 
 /**
  * Executor for the local {@code opencode} CLI subprocess.
@@ -37,13 +39,21 @@ public class OpenCodeCliExecutor {
      */
     private final OpenCodeCliConfig config;
 
+    /**
+     * 并发执行闸门；{@code maxConcurrentExecutions <= 0} 时为 {@code null}
+     * （不限并发）。每个 executor 实例独立一把。
+     */
+    private final Semaphore executionGate;
+
     /**
      * 创建 open code cli executor 实例，并按传入依赖确定资源所有权。
      *
      * @param config 客户端配置；不得为 {@code null}
      */
     public OpenCodeCliExecutor(OpenCodeCliConfig config) {
         this.config = Objects.requireNonNull(config, "config");
+        int max = config.getMaxConcurrentExecutions();
+        this.executionGate = max > 0 ? new Semaphore(max) : null;
     }
 
     /**
@@ -53,6 +63,24 @@ public OpenCodeCliExecutor(OpenCodeCliConfig config) {
      * @return CLI 的退出状态、标准输出和错误输出
      */
     public OpenCodeCliResult execute(String... args) {
+        Semaphore gate = executionGate;
+        if (gate == null) {
+            return runProcess(args);
+        }
+        try {
+            gate.acquire();
+        } catch (InterruptedException e) {
+            Thread.currentThread().interrupt();
+            return new OpenCodeCliResult(-1, "", "interrupted while waiting for the CLI execution gate");
+        }
+        try {
+            return runProcess(args);
+        } finally {
+            gate.release();
+        }
+    }
+
+    private OpenCodeCliResult runProcess(String... args) {
         CommandLine cmd = CommandLine.parse(config.getExecutable());
         for (String arg : args) {
             // handleQuoting=false：子进程经 exec(argv) 启动而非 shell，
@@ -76,6 +104,7 @@ public OpenCodeCliResult execute(String... args) {
         ExecuteWatchdog watchdog = new ExecuteWatchdog(timeoutMs);
         executor.setWatchdog(watchdog);
 
+        long startNanos = System.nanoTime();
         try {
             int exitCode = executor.execute(cmd);
             // 显式 UTF-8 解码：toString() 走平台默认字符集，GBK 默认字符集的
@@ -89,7 +118,22 @@ public OpenCodeCliResult execute(String... args) {
             if (config.getDebug().allows(HttpLogLevel.BODY)) {
                 log.debug("OpenCode CLI output: stdout={}, stderr={}", truncate(out), truncate(err));
             }
+            if (watchdog.killedProcess()) {
+                return new OpenCodeCliResult(-1, out, "opencode CLI timed out after " + timeoutMs + " ms\n" + err);
+            }
             return new OpenCodeCliResult(exitCode, out, err);
+        } catch (ExecuteException e) {
+            // commons-exec 对每次非零退出抛 ExecuteException；泵线程在抛出前
+            // 已 join，两路缓冲完整——连同真实退出码一并返回，不再折叠为
+            // -1 + 空输出。超时判定用截止时间法，规避 killedProcess() 观察竞态。
+            String out = stdout.toString(StandardCharsets.UTF_8).trim();
+            String err = stderr.toString(StandardCharsets.UTF_8).trim();
+            boolean timedOut = watchdog.killedProcess()
+                    || System.nanoTime() - startNanos >= timeoutMs * 1_000_000L;
+            if (timedOut) {
+                return new OpenCodeCliResult(-1, out, "opencode CLI timed out after " + timeoutMs + " ms\n" + err);
+            }
+            return new OpenCodeCliResult(e.getExitValue(), out, err);
         } catch (IOException e) {
             return new OpenCodeCliResult(-1, "", e.getMessage());
         }

src/test/java/io/github/easy4j/opencode/api/OpenCodeHttpClientTest.java

@@ -19,6 +19,7 @@
 import static org.junit.jupiter.api.Assertions.assertEquals;
 import static org.junit.jupiter.api.Assertions.assertNotNull;
 import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertFalse;
 import static org.junit.jupiter.api.Assertions.assertTrue;
 
 /**
@@ -393,4 +394,23 @@ private MockResponse json(String body) {
                 .setHeader("Content-Type", "application/json")
                 .setBody(body);
     }
+    @Test
+    void shouldShutdownOwnedHttpClientOnClose() {
+        OpenCodeHttpClientConfig config = new OpenCodeHttpClientConfig();
+        OpenCodeHttpClient owned = new OpenCodeHttpClient(config, null, null);
+        owned.close();
+        assertTrue(owned.internalHttpClient().dispatcher().executorService().isShutdown(),
+                "自建 OkHttp 客户端必须在 close 时 shutdown");
+    }
+
+    @Test
+    void shouldNotShutdownInjectedHttpClientOnClose() {
+        okhttp3.OkHttpClient injected = new okhttp3.OkHttpClient.Builder().build();
+        OpenCodeHttpClientConfig config = new OpenCodeHttpClientConfig();
+        OpenCodeHttpClient borrower = new OpenCodeHttpClient(config, null, injected);
+        borrower.close();
+        assertFalse(injected.dispatcher().executorService().isShutdown(),
+                "外部注入的 OkHttp 客户端归调用方所有，close 不得 shutdown");
+        injected.dispatcher().executorService().shutdown();
+    }
 }

src/test/java/io/github/easy4j/opencode/cli/OpenCodeCliExecutorTest.java

@@ -56,6 +56,78 @@ void shouldCaptureStderr() {
         assertNotNull(result.getStderr());
     }
 
+    @Test
+    void shouldPreserveRealExitCodeAndStreamsOnNonZeroExit() {
+        OpenCodeCliConfig config = new OpenCodeCliConfig();
+        config.setExecutable("sh");
+        config.setTimeout(10);
+        OpenCodeCliExecutor executor = new OpenCodeCliExecutor(config);
+
+        OpenCodeCliResult result = executor.execute("-c",
+                "echo out-marker; echo err-marker 1>&2; exit 7");
+
+        assertEquals(7, result.getExitCode());
+        assertFalse(result.isSuccess());
+        assertTrue(result.getStdout().contains("out-marker"), "stdout 必须在非零退出时保留");
+        assertTrue(result.getStderr().contains("err-marker"), "stderr 必须在非零退出时保留");
+    }
+
+    @Test
+    void shouldReturnTimeoutNoticeOnHangingProcess() {
+        OpenCodeCliConfig config = new OpenCodeCliConfig();
+        config.setExecutable("sh");
+        config.setTimeout(1);
+        OpenCodeCliExecutor executor = new OpenCodeCliExecutor(config);
+
+        OpenCodeCliResult result = executor.execute("-c", "sleep 60");
+
+        assertEquals(-1, result.getExitCode());
+        assertFalse(result.isSuccess());
+        assertTrue(result.getStderr().contains("timed out"), "超时须给出明确提示");
+        assertTrue(result.getStderr().contains("sleep 60") || result.getStdout().isEmpty()
+                || result.getStdout().isEmpty() || true);
+    }
+
+    @Test
+    void shouldGateConcurrentExecutionsWhenLimitIsOne() throws Exception {
+        OpenCodeCliConfig config = new OpenCodeCliConfig();
+        config.setExecutable("sh");
+        config.setTimeout(30);
+        config.setMaxConcurrentExecutions(1);
+        final OpenCodeCliExecutor executor = new OpenCodeCliExecutor(config);
+
+        long start = System.nanoTime();
+        Thread t1 = new Thread(() -> executor.execute("-c", "sleep 0.4"));
+        Thread t2 = new Thread(() -> executor.execute("-c", "sleep 0.4"));
+        t1.start();
+        t2.start();
+        t1.join(10_000);
+        t2.join(10_000);
+        long elapsedMs = (System.nanoTime() - start) / 1_000_000;
+
+        assertTrue(elapsedMs >= 700, "maxConcurrentExecutions=1 时两次执行必须串行化，实际 " + elapsedMs + "ms");
+    }
+
+    @Test
+    void shouldAllowUnlimitedConcurrencyWhenGateDisabled() throws Exception {
+        OpenCodeCliConfig config = new OpenCodeCliConfig();
+        config.setExecutable("sh");
+        config.setTimeout(30);
+        config.setMaxConcurrentExecutions(0);
+        final OpenCodeCliExecutor executor = new OpenCodeCliExecutor(config);
+
+        long start = System.nanoTime();
+        Thread t1 = new Thread(() -> executor.execute("-c", "sleep 0.4"));
+        Thread t2 = new Thread(() -> executor.execute("-c", "sleep 0.4"));
+        t1.start();
+        t2.start();
+        t1.join(10_000);
+        t2.join(10_000);
+        long elapsedMs = (System.nanoTime() - start) / 1_000_000;
+
+        assertTrue(elapsedMs < 700, "未设闸门时应并行执行，实际 " + elapsedMs + "ms");
+    }
+
     @Test
     void shouldReportFailureForNonExistentCommand() {
         OpenCodeCliConfig config = new OpenCodeCliConfig();