@stalfh233/omc-cli 0.4.13 → 0.4.15

package/README.md

@@ -246,12 +246,12 @@ src/        args/support/plan/read/write/package/context（治理管道）
 
 ## npm 分发
 
-本包（`@stalfh233/omc-cli`，可执行命令仍是 `omc`）通过公共 npm registry 分发。`omc-core` 是 `omc-cli` 的内部依赖，发布时先发 `omc-core`，再发 `omc-cli`；两者版本保持一致。当前版本为 `0.4.13`，尚未宣称 `1.0.0` 稳定契约。
+本包（`@stalfh233/omc-cli`，可执行命令仍是 `omc`）通过公共 npm registry 分发。`omc-core` 是 `omc-cli` 的内部依赖，发布时先发 `omc-core`，再发 `omc-cli`；两者版本保持一致。当前版本为 `0.4.15`，尚未宣称 `1.0.0` 稳定契约。
 
 ### 使用已发布包
 
 ```bash
-npm install -g @stalfh233/omc-cli@0.4.13
+npm install -g @stalfh233/omc-cli@0.4.15
 omc setup
 omc doctor
 omc help omc-write-hazards
@@ -272,7 +272,7 @@ npm publish --workspace packages/omc-cli
 
 ### 输出编码
 
-stdout 是机器解析的 JSON：Windows 上默认把非 ASCII 转义成 `\uXXXX`（纯 ASCII，在 GBK 控制台也不会乱码，等价于 Python `json.dumps(ensure_ascii=True)`），Linux/macOS 保持原始 UTF-8。UTF-8 终端想要可读中文时设 `OMC_ASCII_STDOUT=0`。`--out` 文件、artifact、stderr、CloudPivot 请求体始终是原始 UTF-8。
+stdout 是机器解析的 JSON，编码按消费方选择：**终端**（`isTTY`）写原始 UTF-8（Windows 上 Node 走 `WriteConsoleW`，中文正常显示）；**管道/重定向/捕获**写 ASCII 安全 JSON（非 ASCII 转义成 `\uXXXX`，任何代码页都能正确解析，等价于 Python `json.dumps(ensure_ascii=True)`）。Linux/macOS 始终原始 UTF-8；`--out` 文件、artifact、stderr、CloudPivot 请求体始终原始 UTF-8。强制用 `OMC_ASCII_STDOUT=1|0`。
 
 ### 版本策略
 

package/dist/cli-contract.js

@@ -13,21 +13,24 @@ export function envelope(status, result, requestId, error = null) {
 /**
  * The single stdout serialization for every envelope.
  *
- * stdout is machine-parsed JSON, so it must decode identically for ANY consumer
- * regardless of the ambient console code page. On zh-CN Windows the console is
- * GBK (cp936), and a native process's bytes are decoded with that code page — by
- * the terminal for direct output, and by PowerShell's `[Console]::OutputEncoding`
- * for `$x = omc …` / `omc … > f` / `omc … | …`. Raw UTF-8 Chinese is mangled
- * there (verified on Windows PowerShell 5.1 AND PowerShell 7.6). Escaping every
- * non-ASCII code unit to `\uXXXX` makes stdout pure ASCII, so it survives any
- * code page and still `JSON.parse`s back to the original string. This is the
- * same conservative default as Python's `json.dumps(ensure_ascii=True)`.
+ * Encoding is chosen by the CONSUMER, because "correct" differs by context:
  *
- * Escaping is ON by default only on win32; POSIX keeps its smaller raw UTF-8
- * bytes. Override with `OMC_ASCII_STDOUT=1|0` (set `0` on a UTF-8 terminal to
- * get readable Chinese). `--out` files, artifacts, stderr, and the CloudPivot
- * wire stay raw UTF-8 — they are not a code-page-bound console stream. See
- * `CONTEXT.md` → Agent-facing CLI.
+ * - A real terminal (stdout.isTTY) renders UTF-8 correctly on Windows: Node
+ *   writes UTF-16 through the console API (WriteConsoleW), which bypasses the
+ *   console code page entirely. So there we emit raw UTF-8 and a human sees
+ *   readable Chinese.
+ * - A PIPE / redirect / capture (not a TTY) is decoded by the consumer with its
+ *   own ambient code page. On zh-CN Windows that is GBK (cp936) and raw UTF-8 is
+ *   mangled by the terminal AND by PowerShell's `[Console]::OutputEncoding`
+ *   (verified on Windows PowerShell 5.1 and PowerShell 7.6) for `$x = omc …`,
+ *   `omc … > f`, and the `.ps1` shim pipe. There we escape every non-ASCII code
+ *   unit to `\uXXXX`: stdout stays pure ASCII, survives any code page, and
+ *   still `JSON.parse`s back to the original string — the same conservative
+ *   default as Python's `json.dumps(ensure_ascii=True)`.
+ *
+ * POSIX always keeps raw UTF-8. `OMC_ASCII_STDOUT=1|0` forces either mode. `--out`
+ * files, artifacts, stderr, and the CloudPivot wire stay raw UTF-8 — they are
+ * not a code-page-bound console stream. See `CONTEXT.md` → Agent-facing CLI.
  */
 export function asciiStdout() {
     const override = process.env.OMC_ASCII_STDOUT;
@@ -35,7 +38,9 @@ export function asciiStdout() {
         return true;
     if (override === "0")
         return false;
-    return process.platform === "win32";
+    if (process.platform !== "win32")
+        return false;
+    return process.stdout.isTTY !== true;
 }
 export function serializeEnvelope(value) {
     const json = JSON.stringify(value);

package/dist/cli.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { createInterface } from "node:readline/promises";
 import { stdin, argv } from "node:process";
+import { createRequire } from "node:module";
 import { Command, CommanderError } from "commander";
 import { ConfigStore, defaultPaths, removedProfileKeys } from "./config-store.js";
 import { loadCoverageManifest, versionFamilyNotice } from "./coverage.js";
@@ -1309,6 +1310,15 @@ async function main() {
     let commandExitCode = 0;
     beginUsage(argv);
     const command = new Command();
+    const ownPackageVersion = () => {
+        try {
+            // ESM 下读自身包根的 package.json（安装形态与源码形态都成立）
+            return String(createRequire(import.meta.url)("../package.json").version);
+        }
+        catch {
+            return "unknown";
+        }
+    };
     try {
         configureOutput(argv);
     }
@@ -1320,6 +1330,13 @@ async function main() {
     command.exitOverride();
     command.configureOutput({ writeOut: (text) => process.stderr.write(text), writeErr: (text) => process.stderr.write(text) });
     command.name("omc").showHelpAfterError().showSuggestionAfterError(true);
+    // --version 短路：commander 的 version 走 process.exit，会被 exitOverride 包成
+    // invalid-input 信封（exit 10）；cpdocs --omc-global 的探测要干净的 exit 0。
+    const bare = argv.slice(2).filter((a) => a !== "--");
+    if (bare.includes("--version") || bare.includes("-V")) {
+        process.stdout.write(`${ownPackageVersion()}\n`);
+        return 0;
+    }
     command.addHelpText("after", `\n${onboardingHelp()}\n`);
     // No command at all: guide the agent (help text + onboarding), exit 0. This
     // is a benign "show me the surface" invocation, not a failure.
@@ -1388,7 +1405,9 @@ function finish(code) {
 }
 const request = requestId();
 main().then((code) => {
-    if (argv[2] === "call" || argv[2] === "artifact" || argv[2] === "commands" || argv[2] === "describe" || argv[2] === "contract" || argv[2] === "capabilities" || argv[2] === "capability" || argv[2] === "next" || argv[2] === "usage" || argv[2] === "intent" || argv[2] === "help") {
+    // Commands that own their stdout never grow a trailing envelope. `--version`/
+    // `-V` are here because their short-circuit already wrote the bare version.
+    if (argv[2] === "call" || argv[2] === "artifact" || argv[2] === "commands" || argv[2] === "describe" || argv[2] === "contract" || argv[2] === "capabilities" || argv[2] === "capability" || argv[2] === "next" || argv[2] === "usage" || argv[2] === "intent" || argv[2] === "help" || argv[2] === "--version" || argv[2] === "-V") {
         completeUsage(code);
         finish(code);
         return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stalfh233/omc-cli",
-  "version": "0.4.13",
+  "version": "0.4.15",
   "description": "CloudPivot 8.6 configuration capability CLI — governed, fail-closed, coverage-manifest bounded.",
   "type": "module",
   "bin": {
@@ -51,7 +51,7 @@
   },
   "dependencies": {
     "commander": "14.0.3",
-    "omc-core": "0.4.13",
+    "omc-core": "0.4.15",
     "proper-lockfile": "4.1.2",
     "write-file-atomic": "6.0.0",
     "zod": "^3.23.8",