fix(cli): 补齐显式机器输出边界

scripts/ssh-cli.ts

@@ -1,6 +1,6 @@
 import { readConfig } from "./src/config";
-import { isHelpToken, renderSshHelpText, sshHelpScope } from "./src/help";
-import { CliInputError, emitError, emitText } from "./src/output";
+import { isHelpToken, renderSshHelpText, sshHelp, sshHelpScope } from "./src/help";
+import { CliInputError, emitError, emitJson, emitText } from "./src/output";
 import { extractRemoteCliOptions } from "./src/remote-options";
 import { runRemoteSshCli } from "./src/remote-ssh";
 import { runSsh } from "./src/ssh";
@@ -25,8 +25,70 @@ function isGhContentRouteTarget(target: string | undefined): boolean {
   return typeof target === "string" && target.startsWith("gh:");
 }
 
+interface SshHelpRequest {
+  args: string[];
+  json: boolean;
+}
+
+function parseSshHelpRequest(normalizedArgs: string[]): SshHelpRequest | null {
+  const helpArgs = [normalizedArgs[0]];
+  let json = false;
+  let outputError: CliInputError | null = null;
+  for (let index = 1; index < normalizedArgs.length; index += 1) {
+    const arg = normalizedArgs[index];
+    if (arg === "--json") {
+      json = true;
+      continue;
+    }
+    if (arg === "-o") {
+      const format = normalizedArgs[index + 1];
+      if (format === undefined) {
+        outputError = new CliInputError("-o requires an output format", {
+          code: "missing-option-value",
+          argument: "-o",
+          usage: ["trans --help --json", "trans --help -o json"],
+        });
+      } else if (format !== "json") {
+        outputError = new CliInputError(`Unsupported trans help output format: ${format}`, {
+          code: "unsupported-output-format",
+          argument: format,
+          supported: ["json"],
+          usage: ["trans --help --json", "trans --help -o json"],
+        });
+      } else {
+        json = true;
+      }
+      index += format === undefined ? 0 : 1;
+      continue;
+    }
+    helpArgs.push(arg);
+  }
+
+  const [, sub, third] = helpArgs;
+  const helpFirst = isHelpToken(sub);
+  const routeFirst = helpArgs.length === 3 && isHelpToken(third);
+  if (!helpFirst && !routeFirst) return null;
+  if (outputError !== null) throw outputError;
+  return { args: helpArgs, json };
+}
+
+function emitSshHelp(request: SshHelpRequest): void {
+  const [, sub, third] = request.args;
+  const scope = isHelpToken(sub) ? sshHelpScope(request.args) : undefined;
+  if (isHelpToken(sub) && request.args.length > 2 && scope === undefined) {
+    throw new CliInputError(`Unknown trans help scope: ${third ?? "<missing>"}`, {
+      code: "unknown-help-scope",
+      argument: third ?? "",
+      usage: ["trans --help", "trans --help <operation>"],
+      hint: "Use trans --help to list the bounded operation groups before opening scoped help.",
+    });
+  }
+  if (request.json) emitJson(commandName, sshHelp(scope));
+  else emitText(renderSshHelpText(scope), commandName);
+}
+
 async function main(): Promise<void> {
-  const [top, sub, third] = args;
+  const [top, sub] = args;
   if (top !== "ssh") throw new Error(`ssh-cli supports only the ssh command, got: ${top || "<empty>"}`);
 
   if (sub === undefined) {
@@ -34,22 +96,9 @@ async function main(): Promise<void> {
     return;
   }
 
-  if (isHelpToken(sub)) {
-    const scope = sshHelpScope(args);
-    if (args.length > 2 && scope === undefined) {
-      throw new CliInputError(`Unknown trans help scope: ${third ?? "<missing>"}`, {
-        code: "unknown-help-scope",
-        argument: third ?? "",
-        usage: ["trans --help", "trans --help <operation>"],
-        hint: "Use trans --help to list the bounded operation groups before opening scoped help.",
-      });
-    }
-    emitText(renderSshHelpText(scope), commandName);
-    return;
-  }
-
-  if (isHelpToken(third) && args.length === 3) {
-    emitText(renderSshHelpText(), commandName);
+  const helpRequest = parseSshHelpRequest(args);
+  if (helpRequest !== null) {
+    emitSshHelp(helpRequest);
     return;
   }