promptex-js 1.0.0 → 1.1.0

package/dist/cli/main.js

@@ -62,13 +62,17 @@ import { homedir } from 'node:os';
 import { basename, dirname, isAbsolute, join, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
 // 診斷的人讀格式化以靜態 import 取得，不像本檔其餘 SDK 用法那樣延後到用時
-// 才 `await import`：`reportOpsError` 的呼叫點多在同步函式內（如 `invokeCore`
+// 才 `await import`：`failOps` 的呼叫點多在同步函式內（如 `invokeCore`
 // 的 catch），非同步載入會逼那條錯誤路徑跟著改成非同步。本檔的每個動詞本來
 // 就會載入 `dist/`，提前到模組載入時不多付一次成本。
 import { declaredSchema, formatDiagnostic, readConfig, REFUSAL_MESSAGES, RefusalError, setLocale, t, writeConfig } from '../index.js';
 import { collectSourceFiles, compile, describeLoadFailure, dumpHandoff, FRAMEWORK_VERSION, parseProvenanceEnv, SourceDirFailure } from './compile-engine.js';
 import { runInit as runInitViaCore } from './init.js';
 import { loadNativeCore as loadNative } from '../native.js';
+import { configureErrors, failWith, scanArgv } from './error-output.js';
+import { FORMAT_VERSION } from '../cli-contract.generated.js';
+import { firstRejectedOutside, firstViolatedRule, flagSpec, isStandaloneVerb, projectVerbs } from './flag-table.js';
+import { runVersion } from './version-command.js';
 import { scratchDir } from './scratch.js';
 import { writeStructuredLine } from './stdout.js';
 import { resolveWatchTarget, startWatchLoop } from './watch.js';
@@ -78,7 +82,7 @@ import { CLI_SHIM } from '../paths.js';
 // 是它的旗標；`manifest`（落點查詢）與 `init`（專案初始化）各為獨立指令，兩者
 // 呼叫的框架能力與建置的任一旗標組合互不重疊，故不構成別名（AC-132）。舊的
 // `install`／`plan`／`watch` 不再是指令名，一律當未知指令拒絕。
-const COMMANDS = ['build', 'manifest', 'init'];
+// 認得哪些指令由旗標定義表決定（見 `flag-table.ts` 的 `projectVerbs`），這裡不再另存一份清單。
 /**
  * 命令列的本次呼叫狀態：全部由 `main()` 依 argv 賦值，模組層只宣告。
  *
@@ -196,10 +200,10 @@ const configDeclareTargetMissing = () => t('cli.config.declare_target_missing');
  * 定義位置在 `config` 分派之前：那條路徑在動詞分派前提前結束行程（見
  * `dispatchConfig`），常數若留在原本的位置會落在暫時性死區。
  */
-const PLATFORM_UNUSED_KEYS = {
-    configMode: 'cli.platform_unused.units',
-    init: 'cli.platform_unused.init',
-    config: 'cli.platform_unused.config',
+const PLATFORM_UNUSED_CODES = {
+    configMode: 'USAGE_PLATFORM_UNUSED_IN_UNIT_MODE',
+    init: 'USAGE_PLATFORM_UNUSED_BY_INIT',
+    config: 'USAGE_PLATFORM_UNUSED_BY_CONFIG',
 };
 /** 尚未解析時的預設值：本檔被 import 而不呼叫 `main()` 時，`parsedArgs` 停在這裡。 */
 const EMPTY_ARGS = {
@@ -219,6 +223,31 @@ const EMPTY_ARGS = {
     ops: null,
     apply: false,
     locale: null,
+    given: new Set(),
+};
+/**
+ * 旗標的值寫進 `CliArgs` 的哪個欄位。旗標認不認得、帶不帶值由定義表決定
+ * （`flag-table.ts`），表不管欄位；表新增旗標時這裡也要補一筆，`tests/cli-flag-table.test.ts`
+ * 會核對每個旗標都有對應。
+ */
+export const VALUE_FIELDS = {
+    '--out': 'out',
+    '--platform': 'platform',
+    '--unit': 'unit',
+    '--lang': 'lang',
+    '--ops': 'ops',
+    '--locale': 'locale',
+    '--export': 'exportDir',
+};
+/** 不帶值的旗標寫進 `CliArgs` 的哪個布林欄位。 */
+export const SWITCH_FIELDS = {
+    '--yes': 'assumeYes',
+    '--json': 'json',
+    '--content': 'content',
+    '--install': 'install',
+    '--dry-run': 'dryRun',
+    '--watch': 'watch',
+    '--apply': 'apply',
 };
 /**
  * 解析 `<動詞> <目錄> [--out o] [--platform p] [--unit u] [--lang l] [--yes]`。
@@ -239,34 +268,30 @@ const EMPTY_ARGS = {
  * 會被監看的求值子行程 import 而不呼叫 `main()`。是否結束由呼叫端決定。
  */
 function parseCliArgs(argv) {
-    const args = { ...EMPTY_ARGS };
-    const VALUED = { '--out': 'out', '--platform': 'platform', '--unit': 'unit', '--lang': 'lang', '--ops': 'ops', '--locale': 'locale', '--export': 'exportDir' };
+    const given = new Set();
+    const args = { ...EMPTY_ARGS, given };
     let i = 0;
     while (i < argv.length) {
         const arg = argv[i];
         i += 1;
-        if (Object.hasOwn(VALUED, arg)) {
-            if (i >= argv.length)
-                return { args, error: t('cli.flag.missing_value', { flag: arg }) };
-            args[VALUED[arg]] = argv[i];
-            i += 1;
+        // 旗標一律先解析、不分動詞：對不適用的動詞靜默接受是 1.0.x 的行為，1.x 照舊，
+        // 只有定義表標了 `rejectOutside` 的旗標由 `settleBuildMode` 擋下。
+        // compat(remove-in=2.0): silent-inapplicable-flag
+        const spec = flagSpec(arg);
+        if (spec !== undefined) {
+            if (spec.takesValue) {
+                if (i >= argv.length)
+                    return { args, error: { code: 'USAGE_FLAG_MISSING_VALUE', details: { flag: arg } } };
+                args[VALUE_FIELDS[arg]] = argv[i];
+                i += 1;
+            }
+            else {
+                args[SWITCH_FIELDS[arg]] = true;
+            }
+            given.add(arg);
         }
-        else if (arg === '--yes')
-            args.assumeYes = true;
-        else if (arg === '--json')
-            args.json = true;
-        else if (arg === '--content')
-            args.content = true;
-        else if (arg === '--install')
-            args.install = true;
-        else if (arg === '--dry-run')
-            args.dryRun = true;
-        else if (arg === '--watch')
-            args.watch = true;
-        else if (arg === '--apply')
-            args.apply = true;
         else if (arg.startsWith('--'))
-            return { args, error: `${t('cli.flag.unknown', { flag: arg })}\n${usage()}` };
+            return { args, error: { code: 'USAGE_UNKNOWN_FLAG', details: { flag: arg } } };
         else if (args.positional === null)
             args.positional = arg;
         // 只有 `config declare` 收第二個位置參數（套件名）：它不是旗標，而是那個子動作的
@@ -275,7 +300,7 @@ function parseCliArgs(argv) {
         else if (configAction === 'declare' && args.declareTarget === null)
             args.declareTarget = arg;
         else
-            return { args, error: `${t('cli.positional.surplus', { arg })}\n${usage()}` };
+            return { args, error: { code: 'USAGE_SURPLUS_ARGUMENT', details: { arg } } };
     }
     return { args: settleDeclarePositionals(args), error: null };
 }
@@ -290,25 +315,15 @@ function parseCliArgs(argv) {
  * 只有一個落點；`--dry-run` 搭 `--watch` 阻斷：試跑的輸出在監看迴圈裡沒有讀者。
  */
 function settleBuildMode(commandName, args) {
-    if (commandName !== 'build') {
-        const given = [
-            [args.install, '--install'],
-            [args.dryRun, '--dry-run'],
-            [args.exportDir !== null, '--export'],
-            [args.watch, '--watch'],
-        ];
-        for (const [present, flag] of given) {
-            if (present)
-                return { mode: commandName, error: t('cli.flags.build_only', { flag }) };
-        }
+    // 哪些旗標只屬於 build、哪些規則成立，都由定義表回答（`flag-table.ts`）。
+    const rejected = firstRejectedOutside(args.given, commandName);
+    if (rejected !== null)
+        return { mode: commandName, error: { code: 'USAGE_FLAG_BUILD_ONLY', details: { flag: rejected } } };
+    if (commandName !== 'build')
         return { mode: commandName, error: null };
-    }
-    if (args.dryRun && !args.install)
-        return { mode: 'build', error: t('cli.flags.dry_run_requires_install') };
-    if (args.exportDir !== null && args.install)
-        return { mode: 'build', error: t('cli.flags.export_conflicts_install') };
-    if (args.dryRun && args.watch)
-        return { mode: 'build', error: t('cli.flags.dry_run_with_watch') };
+    const violated = firstViolatedRule(args.given, commandName);
+    if (violated !== null)
+        return { mode: 'build', error: { code: violated, details: {} } };
     const mode = args.exportDir !== null ? 'export' : args.install && args.dryRun ? 'dry-run' : args.install ? 'install' : 'build';
     return { mode, error: null };
 }
@@ -384,47 +399,31 @@ let platformSpecified = false;
  * dry-run／manifest 共用的求值前置對它全無意義。
  */
 function dispatchConfig() {
-    if (configAction === null) {
-        console.error(`${configActionMissing()}\n${usage()}`);
-        process.exit(1);
-    }
-    if (!CONFIG_ACTIONS.includes(configAction)) {
-        console.error(`${configActionUnknown(configAction)}\n${usage()}`);
-        process.exit(1);
-    }
-    if (parseError !== null) {
-        console.error(parseError);
-        process.exit(1);
-    }
+    if (configAction === null)
+        failWith('USAGE_CONFIG_ACTION_MISSING');
+    if (!CONFIG_ACTIONS.includes(configAction))
+        failWith('USAGE_CONFIG_ACTION_UNKNOWN', { action: configAction });
+    if (parseError !== null)
+        failWith(parseError.code, parseError.details);
     // 沒帶操作即報錯，不當成空操作：靜默跑完會與「改完了但沒有差異」無法分辨。
-    if (configAction === 'write' && parsedArgs.ops === null) {
-        console.error(`${configOpsMissing()}\n${usage()}`);
-        process.exit(1);
-    }
+    if (configAction === 'write' && parsedArgs.ops === null)
+        failWith('USAGE_CONFIG_OPS_MISSING');
     // 沒帶套件名即報錯，理由同上：`declaredSchema` 對空名字答 `{"schema": null}`
     // 並以結束碼 0 收場，那與「這個套件沒有宣告參數」的正常答案分不開。
-    if (configAction === 'declare' && parsedArgs.declareTarget === null) {
-        console.error(`${configDeclareTargetMissing()}\n${usage()}`);
-        process.exit(1);
-    }
+    if (configAction === 'declare' && parsedArgs.declareTarget === null)
+        failWith('USAGE_CONFIG_DECLARE_TARGET_MISSING');
     // `--platform` 對 config 沒有消費者：這條路徑不投影也不產出任何平台產物。
     // 順序比照 Rust 側（把關排在全部解析錯誤之後，見 `cli.rs` 的 `run`）。
-    if (platformSpecified) {
-        console.error(t(PLATFORM_UNUSED_KEYS.config));
-        process.exit(1);
-    }
+    if (platformSpecified)
+        failWith(PLATFORM_UNUSED_CODES.config);
     // `--content` 對 config 同樣沒有消費者，且這條路徑在此即結束行程，趕不上
     // `assertContentUsed`（那一支排在指令白名單檢查之後）。
-    if (parsedArgs.content) {
-        console.error(t('cli.content_unused.verb'));
-        process.exit(1);
-    }
+    if (parsedArgs.content)
+        failWith('USAGE_CONTENT_REQUIRES_DRY_RUN');
     // 寫入旗標同理：config 不走建置的寫入路徑。
     const settled = settleBuildMode('config', parsedArgs);
-    if (settled.error !== null) {
-        console.error(settled.error);
-        process.exit(1);
-    }
+    if (settled.error !== null)
+        failWith(settled.error.code, settled.error.details);
     process.exit(runConfig(configAction, realResolve(parsedArgs.positional ?? '.'), parsedArgs));
 }
 /**
@@ -445,6 +444,13 @@ function jsonTypeName(value) {
     const primitive = { string: 'string', number: 'number', boolean: 'boolean' };
     return primitive[typeof value] ?? 'object';
 }
+/**
+ * `config` 輸出在最前面加 `formatVersion`，值取自生成模組（來源是核心的常數，
+ * `gen-cli-contract.mjs --check` 擋下不一致），不經原生綁定。其餘欄位與形狀不變。
+ */
+function withFormatVersion(body) {
+    return { formatVersion: FORMAT_VERSION, ...body };
+}
 /**
  * 配置檔的程式化改寫（ADR-024）。
  *
@@ -456,14 +462,15 @@ function runConfig(action, projectRoot, args) {
     // 正是在「挑一個擴充、剛裝好、還沒寫進配置」那一刻問它。
     if (action === 'declare') {
         const schema = declaredSchema(projectRoot, args.declareTarget ?? '');
-        writeStructuredLine(JSON.stringify({ schema }, null, 2));
+        writeStructuredLine(JSON.stringify(withFormatVersion({ schema }), null, 2));
         return 0;
     }
     const configPath = join(projectRoot, 'promptex.config.ts');
     if (!existsSync(configPath)) {
-        console.error(`✗ ${REFUSAL_MESSAGES['no-config-file']}`);
-        console.error(t('cli.config.looked_at', { path: configPath }));
-        return 1;
+        failWith('RUN_CONFIG_FILE_NOT_FOUND', { path: configPath }, [
+            `✗ ${REFUSAL_MESSAGES['no-config-file']}`,
+            t('cli.config.looked_at', { path: configPath }),
+        ]);
     }
     const source = readFileSync(configPath, 'utf8');
     if (action === 'read') {
@@ -480,10 +487,15 @@ function runConfig(action, projectRoot, args) {
         catch (e) {
             if (!(e instanceof RefusalError))
                 throw e;
-            console.error(`✗ ${e.message}`);
-            return 1;
+            // 配置檔本身壞掉的拒絕理由各有代碼；沒有專屬代碼的理由歸 `RUN_INTERNAL`，把原文放 `detail`。
+            const human = `✗ ${e.message}`;
+            if (e.code === 'unbalanced')
+                failWith('RUN_CONFIG_UNBALANCED', {}, human);
+            if (e.code === 'no-unit-array')
+                failWith('RUN_CONFIG_NO_UNIT_ARRAY', {}, human);
+            failWith('RUN_INTERNAL', { detail: e.message }, human);
         }
-        writeStructuredLine(JSON.stringify(view, null, 2));
+        writeStructuredLine(JSON.stringify(withFormatVersion(view), null, 2));
         return 0;
     }
     // 呼叫端已擋下 `--ops` 缺席的情形（見 `dispatchConfig`），此處補一次收窄
@@ -494,27 +506,29 @@ function runConfig(action, projectRoot, args) {
         ops = JSON.parse(rawOps);
     }
     catch {
-        console.error(t('cli.config.ops_not_json', { raw: rawOps }));
-        return 1;
-    }
-    if (!Array.isArray(ops)) {
-        console.error(t('cli.config.ops_not_array', { got: jsonTypeName(ops) }));
-        return 1;
+        failWith('USAGE_CONFIG_OPS_NOT_JSON', { raw: rawOps });
     }
+    if (!Array.isArray(ops))
+        failWith('USAGE_CONFIG_OPS_NOT_ARRAY', { got: jsonTypeName(ops) });
     const outcome = writeConfig(source, ops);
     if (outcome.refusal !== null) {
         console.error(`✗ ${outcome.refusal.message}`);
         if (outcome.refusal.detail !== undefined)
             console.error(`    ${outcome.refusal.detail}`);
-        writeStructuredLine(JSON.stringify(outcome, null, 2));
+        writeStructuredLine(JSON.stringify(withFormatVersion(outcome), null, 2));
         return 1;
     }
     // 落檔在最後一步，且只在明說要落檔時發生：不帶旗標時磁碟上一個字都沒動。
     if (args.apply && outcome.after !== source) {
-        writeFileSync(configPath, outcome.after);
+        try {
+            writeFileSync(configPath, outcome.after);
+        }
+        catch {
+            failWith('RUN_CONFIG_WRITE_FAILED', { path: configPath });
+        }
         outcome.applied = true;
     }
-    writeStructuredLine(JSON.stringify(outcome, null, 2));
+    writeStructuredLine(JSON.stringify(withFormatVersion(outcome), null, 2));
     return 0;
 }
 let srcDir = '';
@@ -548,12 +562,11 @@ let unit = 'default';
 function assertPlatformUnused(situation) {
     if (!platformSpecified || command === 'manifest')
         return;
-    console.error(t(PLATFORM_UNUSED_KEYS[situation]));
-    process.exit(1);
+    failWith(PLATFORM_UNUSED_CODES[situation]);
 }
-const OUT_UNUSED_KEYS = {
-    configMode: 'cli.out_unused.units',
-    init: 'cli.out_unused.init',
+const OUT_UNUSED_CODES = {
+    configMode: 'USAGE_OUT_UNUSED_IN_UNIT_MODE',
+    init: 'USAGE_OUT_UNUSED_BY_INIT',
 };
 /**
  * `--out` 沒有消費者時一律報錯，不靜默忽略。
@@ -570,8 +583,7 @@ const OUT_UNUSED_KEYS = {
 function assertOutUnused(situation) {
     if (!outSpecified)
         return;
-    console.error(t(OUT_UNUSED_KEYS[situation]));
-    process.exit(1);
+    failWith(OUT_UNUSED_CODES[situation]);
 }
 /**
  * `--content` 沒有消費者時一律報錯，理由同 `--out` 與 `--platform`：靜默忽略的
@@ -585,14 +597,10 @@ function assertOutUnused(situation) {
 function assertContentUsed() {
     if (!CONTENT_REQUESTED)
         return;
-    if (MODE !== 'dry-run') {
-        console.error(t('cli.content_unused.verb'));
-        process.exit(1);
-    }
-    if (!STRUCTURED_OUTPUT) {
-        console.error(t('cli.content_unused.json'));
-        process.exit(1);
-    }
+    if (MODE !== 'dry-run')
+        failWith('USAGE_CONTENT_REQUIRES_DRY_RUN');
+    if (!STRUCTURED_OUTPUT)
+        failWith('USAGE_CONTENT_REQUIRES_JSON');
 }
 // init 不進入下方的求值／投影／安裝流程（它本身就是要產出待求值的源碼，
 // 此刻目標目錄還沒有可求值的內容），在這裡提前分派並結束行程。把關要先於
@@ -605,14 +613,17 @@ function loadNativeCore() {
         return loadNative();
     }
     catch (e) {
-        console.error(e instanceof Error ? e.message : String(e));
-        process.exit(1);
+        const message = e instanceof Error ? e.message : String(e);
+        failWith('RUN_BINDING_NOT_FOUND', { platform: `${process.platform}-${process.arch}` }, message);
     }
 }
 /**
  * 專案初始化（新增動詞，非四個既有日常動作之一）：在目標目錄產出配置檔、
  * 源碼目錄與可獨立編譯的範例資源（AC-126 至 AC-130）。
  *
+ * compat(remove-in=2.0): cli-init-verb（1.1 棄用、2.0 移除，改用各語言的 create；
+ * 行為凍結，不再加功能）
+ *
  * 骨架內容、語言別名的收斂、衝突判定與「全有全無」的處置全住核心
  * （`promptex_core::init`），版面同樣住核心（`present` 的 `init` 請求）：
  * 三個生態的 `init` 因此既產出同一份位元組、也印出同一份版面。本層只做
@@ -631,9 +642,11 @@ async function runInit() {
         outcome = runInitViaCore(targetDir, parsedArgs.lang ?? 'ts', parsedArgs.assumeYes, LOCALE);
     }
     catch (e) {
-        console.error(`✗ ${opsErrorText(e instanceof Error ? e.message : String(e))}`);
-        process.exit(1);
+        failOps(e instanceof Error ? e.message : String(e), '✗ ');
     }
+    // 帶 `--json` 且中止時，stdout 輸出錯誤 JSON，不再印人讀版面（stderr 只留一行 `message`）。
+    if (outcome.aborted && STRUCTURED_OUTPUT)
+        failWith('RUN_INIT_ABORTED', { files: outcome.conflicts });
     present({ kind: 'init', outcome });
     if (outcome.aborted)
         process.exit(1);
@@ -679,33 +692,42 @@ function opsErrorText(message) {
     return lines.map((line) => line.text).join('\n');
 }
 /**
- * 把綁定回傳的失敗印到 stderr。
- *
- * 診斷逐筆走 `formatDiagnostic`，與求值期失敗（`cli/compile-engine.ts`）及
- * 另兩個生態的同一路徑逐行同構：此前這裡只印代碼與訊息，位置與提示在
- * TypeScript 的命令列輸出中看不到，同一份宣告在求值期失敗與投影期失敗時
- * 作者看到的詳略不同。收尾那一行取核心的版面（`present` 的 `diagnosticAbort`
- * 請求）：逐筆格式化刻意保留三份（求值期不得依賴原生綁定），收尾句不受那個
- * 限制，宿主各寫一份只是純字面重複。
- *
- * 其餘種類整批交給核心的 `present`：措辭與該印到哪個流都由核心決定，本檔不
- * 依 `kind` 分支。分支就是重組文字的入口，而重組出來的那份與核心是否同文
- * 沒有任何測試在比對。
+ * 把綁定回傳的失敗輸出並結束行程。
+ *
+ * 錯誤代碼與 `details` 由核心決定（失敗 payload 的 `code`、`details`，見核心的
+ * `OpsError::code_and_details`），這裡原樣交給 `failWith`，不依 `kind` 自己分類。
+ *
+ * 不帶 `--json` 時的人讀輸出：診斷逐筆走 `formatDiagnostic`，與求值期失敗（`cli/compile-engine.ts`）
+ * 及另兩個生態的同一路徑逐行同構：此前這裡只印代碼與訊息，位置與提示在
+ * TypeScript 的命令列輸出中看不到，同一份宣告在求值期失敗與投影期失敗時作者看到的
+ * 詳略不同。收尾那一行取核心的版面（`present` 的 `diagnosticAbort` 請求）：逐筆格式化刻意
+ * 保留三份（求值期不得依賴原生綁定），收尾句不受那個限制，宿主各寫一份只是純字面重複。
+ * 其餘種類整批交給核心的 `present`：措辭與該印到哪個流都由核心決定，本檔不依 `kind` 分支。
+ * 分支就是重組文字的入口，而重組出來的那份與核心是否同文沒有任何測試在比對。
+ *
+ * `prefix` 讓呼叫端在人讀文字前加記號（如 `init` 的 `✗ `），改走 `opsErrorText` 取文字，只作用在非診斷的種類。
  */
-function reportOpsError(message) {
+function failOps(message, prefix = '') {
     const payload = parseOpsFailure(message);
-    if (payload === null) {
-        console.error(message);
-        return;
-    }
-    if (payload.kind === 'diagnostics') {
-        for (const d of payload.diagnostics)
-            for (const line of formatDiagnostic(d))
-                console.error(line);
-        present({ kind: 'diagnosticAbort' });
-        return;
-    }
-    present({ kind: 'failure', failure: payload });
+    if (payload === null)
+        failWith('RUN_INTERNAL', { detail: message }, message);
+    const code = typeof payload.code === 'string' ? payload.code : 'RUN_INTERNAL';
+    const details = (payload.details ?? { detail: message });
+    const human = () => {
+        if (payload.kind === 'diagnostics') {
+            for (const d of payload.diagnostics)
+                for (const line of formatDiagnostic(d))
+                    console.error(line);
+            present({ kind: 'diagnosticAbort' });
+        }
+        else if (prefix === '') {
+            present({ kind: 'failure', failure: payload });
+        }
+        else {
+            console.error(`${prefix}${opsErrorText(message)}`);
+        }
+    };
+    failWith(code, details, human, { projectRoot: evaluationProjectRoot || undefined });
 }
 /**
  * 依核心給的版面印出：核心說要印什麼、印到哪個流（見核心的 `present` 模組），
@@ -749,7 +771,7 @@ function present(request) {
  */
 function printManifestQuery({ platform, unit, installRoot, supported, nodes = [], files = [], }) {
     const native = loadNativeCore();
-    const query = native.manifestQuery(JSON.stringify({ platform, engineVersion: ENGINE_VERSION, unit, installRoot, supported, nodes, files }), LOCALE);
+    const query = native.manifestQuery(JSON.stringify({ platform, engineVersion: engineVersion(), unit, installRoot, supported, nodes, files }), LOCALE);
     // 取結構化輸出時這一份改走錯誤通道：它本來就是給另一個專案解析的 JSON，
     // 但標準輸出此刻由 `emitStructured` 的單一 JSON 文件佔用，兩份都印會讓
     // 整體不再是一個 JSON 值，AC-507 的「可被結構化解析」隨之落空。
@@ -818,7 +840,7 @@ function emitStructured(out, targetPlatform, queryMeta, contents) {
     // 信封交給核心組（`orchestrate::structured_envelope_json`）：欄位集合、順序、
     // 分隔符與診斷位置的相對化都是跨生態契約，三側各寫一份只靠註解互相指認，攔不住
     // 任何漏欄；`diagnostics` 就是這樣一度只加在本檔的。
-    const { structuredEnvelope } = loadNative();
+    const { structuredEnvelope } = loadNativeCore();
     writeStructuredLine(structuredEnvelope(JSON.stringify({
         // 動詞取自命令列而非 `outcome`：後者不承載自己是哪個動詞的結果
         // （build 的 outcome 是 written／report／degraded／unsupported／
@@ -870,8 +892,7 @@ function readNativeInputs(irPath, settingsPath, externalsPath) {
 function invokeCore({ irPath, settingsPath, externalsPath, root, platform, sourceRoot, unitName, mode = MODE, scope = 'project', queryMeta }) {
     const result = coreOutcome({ irPath, settingsPath, externalsPath, root, platform, sourceRoot, unitName, mode, scope });
     if (!result.ok) {
-        reportOpsError(result.message);
-        return 1;
+        failOps(result.message);
     }
     // 沒有擴充的目標，核心的投影樹即最終落地的那一棵，取它就是安裝結果本身。
     let contents;
@@ -881,8 +902,7 @@ function invokeCore({ irPath, settingsPath, externalsPath, root, platform, sourc
             contents = JSON.parse(loadNativeCore().projectionTree(mode, root, irJson, platform, sourceRoot ?? '', settingsJson, externalsJson, unitName, LOCALE, scope));
         }
         catch (e) {
-            reportOpsError(e instanceof Error ? e.message : String(e));
-            return 1;
+            failOps(e instanceof Error ? e.message : String(e));
         }
     }
     printCoreOutcome(result.outcome, platform, queryMeta, contents);
@@ -940,7 +960,7 @@ function coreOutcome({ irPath, settingsPath, externalsPath, root, platform, sour
  *
  * 階梯方向不成立時核心以診斷回傳、一個檔案都不寫出（它排在核心內任何寫入之
  * 前），與內建平台在投影期被攔下同樣是全有全無；本檔把那批診斷走既有的
- * `reportOpsError` 路徑印出。
+ * `failOps` 路徑印出。
  *
  * 報告只在 `build`／`install` 印出：`plan` 與 `manifest` 是零副作用動詞，兩者的
  * 結果本來就沒有 `report` 欄位，內建平台在這兩個動詞下同樣不印報告，查詢指令的
@@ -968,8 +988,7 @@ async function runThirdPartyEmit(target, mode, irPath, unitOutDir, unitName, que
     catch (e) {
         // 階梯方向不成立與落地失敗都走既有的診斷輸出路徑，與內建平台的求值期診斷
         // 同一形態；不讓綁定的 JSON 錯誤物件原樣冒到頂層變成堆疊追蹤。
-        reportOpsError(e instanceof Error ? e.message : String(e));
-        process.exit(1);
+        failOps(e instanceof Error ? e.message : String(e));
     }
     // 放行的逃逸路徑警告走本檔的診斷格式化（那一段刻意保留三份，見核心的
     // `present` 模組文件），印完才接核心給的逐行輸出。
@@ -1038,8 +1057,7 @@ function thirdPartyFilesJson(files) {
             text[rel] = decoder.decode(content);
         }
         catch {
-            console.error(t('cli.third_party_not_utf8', { path: rel }));
-            process.exit(1);
+            failWith('RUN_THIRD_PARTY_NOT_UTF8', { path: rel });
         }
     }
     return JSON.stringify(text);
@@ -1097,8 +1115,7 @@ async function runExtendedTarget(target, mode, coreArgs, unitOutDir, unitName, q
     const native = loadNativeCore();
     const base = coreOutcome({ ...coreArgs, root: unitOutDir, mode });
     if (!base.ok) {
-        reportOpsError(base.message);
-        return 1;
+        failOps(base.message);
     }
     // 兩支綁定共用的三個引數先接成綁定那側的參數名（`root`／`unit`／`sourceRoot`）
     // 再傳：位置引數排錯順序在無型別的 .mjs 沒有任何訊號，同名接一次讓它落在靜態
@@ -1112,8 +1129,7 @@ async function runExtendedTarget(target, mode, coreArgs, unitOutDir, unitName, q
         beforeJson = native.projectionTree(mode, root, irJson, target.platform, sourceRoot ?? '', settingsJson, externalsJson, unit, LOCALE, coreArgs.scope ?? 'project');
     }
     catch (e) {
-        reportOpsError(e instanceof Error ? e.message : String(e));
-        return 1;
+        failOps(e instanceof Error ? e.message : String(e));
     }
     const files = decodeTree(beforeJson);
     const ctx = createAdapterContext(target.platform, select);
@@ -1126,8 +1142,7 @@ async function runExtendedTarget(target, mode, coreArgs, unitOutDir, unitName, q
         reportText = ctx.hasNotes() ? formatReport(ctx.report(target.platform, [...files.keys()].sort())) : null;
     }
     catch (e) {
-        reportOpsError(e instanceof Error ? e.message : String(e));
-        return 1;
+        failOps(e instanceof Error ? e.message : String(e));
     }
     const afterJson = encodeTree(files);
     const baselineJson = JSON.stringify(base.outcome);
@@ -1136,8 +1151,7 @@ async function runExtendedTarget(target, mode, coreArgs, unitOutDir, unitName, q
         landed = JSON.parse(native.extensionApply(mode, root, unit, target.platform, beforeJson, afterJson, baselineJson, LOCALE));
     }
     catch (e) {
-        reportOpsError(e instanceof Error ? e.message : String(e));
-        return 1;
+        failOps(e instanceof Error ? e.message : String(e));
     }
     // 逐檔加工的訊息只在 build／install 印出：dry-run／manifest 的輸出是整份「會變成
     // 什麼」的預覽清單，再疊一批逐檔訊息等於同一件事說兩次，且該清單本身已把擴充
@@ -1190,25 +1204,32 @@ function homeBasis() {
  * 出處可由環境注入（見 cli/compile-engine.ts 的 `parseProvenanceEnv`）：三個欄位
  * 都隨環境變動。
  *
- * 解析失敗在此收成人讀訊息再結束行程，不讓例外冒到頂層：這一行在模組載入時
- * 執行，未接住的例外印出的是 Node 的堆疊，而作者要的資訊只有「哪個環境變數
- * 的值不合法」。
+ * 延後到第一次用到才解析，而且 `main()` 在參數驗證通過、進入建置與查詢流程之前先呼叫
+ * 一次：解析要排在 `--json` 掃描之後，不合法時才能輸出 `USAGE_PROVENANCE_INVALID` 的錯誤 JSON；
+ * `version`、`init` 與 `config` 不用出處，不受這個環境變數影響。此前它在模組載入時解析，
+ * 比任何掃描都早，連 `version` 都被擋住。
+ *
+ * 解析失敗收成錯誤輸出再結束行程，不讓例外冒到頂層：未接住的例外印出的是 Node 的堆疊，
+ * 而作者要的資訊只有「哪個環境變數的值不合法」。
  */
-const PROVENANCE = (() => {
+let provenanceCache = null;
+function provenance() {
+    if (provenanceCache !== null)
+        return provenanceCache.value;
     try {
-        return parseProvenanceEnv(process.env.PROMPTEX_PROVENANCE);
+        provenanceCache = { value: parseProvenanceEnv(process.env.PROMPTEX_PROVENANCE) };
     }
     catch (e) {
-        console.error(e instanceof Error ? e.message : String(e));
-        process.exit(1);
+        failWith('USAGE_PROVENANCE_INVALID', {}, e instanceof Error ? e.message : String(e));
     }
-})();
+    return provenanceCache.value;
+}
 /**
  * 查詢輸出與落點條目回報的引擎版本。取已安裝的框架版本，但出處注入時以注入
  * 值為準：這個值會進旁置落點表與查詢輸出，逐字比對產物的呼叫端（情境回歸、
  * CI）需要它固定，否則每次升版都讓一批與版本無關的比對失敗。
  */
-const ENGINE_VERSION = PROVENANCE?.engineVersion ?? FRAMEWORK_VERSION;
+const engineVersion = () => provenance()?.engineVersion ?? FRAMEWORK_VERSION;
 /**
  * 求值宿主原語（ADR-008 界線二）：載入核心指名的那個單元的源碼、產出中介
  * 表示。這是核心做不到的兩件事之一，因此留在宿主側；本函式不做任何判斷，
@@ -1264,7 +1285,7 @@ async function runEvaluatePrimitive(primitive, unitDef, projectRoot) {
             kind: 'evaluate',
             id: primitive.id,
             ok: true,
-            ir: JSON.stringify(engine.toIR(PROVENANCE, unitDef.select)),
+            ir: JSON.stringify(engine.toIR(provenance(), unitDef.select)),
         };
     }
     catch (e) {
@@ -1380,8 +1401,7 @@ async function orchestrate({ verb, configDir, configPath, units, unitFilter, })
         }), LOCALE));
     }
     catch (e) {
-        reportOpsError(e instanceof Error ? e.message : String(e));
-        process.exit(1);
+        failOps(e instanceof Error ? e.message : String(e));
     }
     // `configDir` 即專案根：配置單元模式為配置檔所在目錄（PDR-003），單一目錄
     // 模式由 `runSingleDir` 傳入該模式的第一個位置參數，兩者都是本次求值的
@@ -1397,8 +1417,7 @@ async function orchestrate({ verb, configDir, configPath, units, unitFilter, })
         return { ...resolution, config };
     }
     catch (e) {
-        reportOpsError(e instanceof Error ? e.message : String(e));
-        process.exit(1);
+        failOps(e instanceof Error ? e.message : String(e));
     }
 }
 /**
@@ -1549,6 +1568,11 @@ export async function distributeTarget({ mode, scope = 'project', target, target
     }
     return invokeCore({ ...coreArgs, root: unitOutDir, mode, queryMeta });
 }
+/** 配置檔載入失敗：人讀輸出是框架層的診斷行，錯誤 JSON 的 `detail` 放原始例外訊息。 */
+function failConfigLoad(configPath, error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    failWith('RUN_CONFIG_LOAD_FAILED', { path: configPath, detail }, describeLoadFailure(configPath, error));
+}
 /**
  * 配置單元模式（PDR-005）：把求值後的配置交給核心算出編排計畫，執行計畫指名
  * 的原語（求值兄弟單元、查詢另一個專案），再依核心解析出的結果逐單元求值自己
@@ -1574,17 +1598,13 @@ async function runConfigUnits(configPath) {
         mod = (await import(pathToFileURL(configPath).href));
     }
     catch (e) {
-        for (const line of describeLoadFailure(configPath, e))
-            console.error(line);
-        process.exit(1);
+        failConfigLoad(configPath, e);
     }
     // 先以 `unknown` 收再驗、驗過才具名：`Array.isArray` 對唯讀陣列的收窄會把
     // 型別退成 `any[]`，直接對已具名的值做這個檢查等於把整條下游的型別關掉。
     const defaultExport = mod.default;
-    if (!Array.isArray(defaultExport)) {
-        console.error(t('cli.config.default_export_invalid', { path: configPath }));
-        process.exit(1);
-    }
+    if (!Array.isArray(defaultExport))
+        failWith('RUN_CONFIG_EXPORT_INVALID', { path: configPath });
     const units = defaultExport;
     const resolution = await orchestrate({
         verb: command,
@@ -1620,11 +1640,12 @@ async function runConfigUnits(configPath) {
                 // 結構版本問核心（`graphVersion()`），不寫死字面：版本正是消費端用來分辨
                 // 新舊結構的那個欄位，核心改版而這裡的字面停在舊值時沒有任何訊號，症狀是
                 // 同一份專案從 Rust 與從 TypeScript 問到兩種版本。
+                // compat(remove-in=2.0): legacy-version-field（graph.version）
                 const empty = {
                     files: [],
                     nodes: [],
                     metadata: [],
-                    graph: { version: native.graphVersion(), nodes: [], edges: [] },
+                    graph: { formatVersion: FORMAT_VERSION, version: native.graphVersion(), nodes: [], edges: [] },
                 };
                 emitStructured(empty, platform, { unit: unitName, installRoot: resolved.installRoot });
             }
@@ -1713,6 +1734,13 @@ async function runConfigUnits(configPath) {
 export async function main(argv) {
     command = argv[2] ?? '';
     rest = argv.slice(3);
+    // 解析參數之前先掃一次有沒有 `--json`：用法錯誤也要輸出錯誤 JSON。`config` 不帶 `--json`
+    // 也輸出 JSON，所以它的失敗一律輸出錯誤 JSON。
+    const scanned = scanArgv(rest);
+    configureErrors({ verb: command, explicitJson: scanned.json, stdoutJson: scanned.json || command === 'config', localeFlag: scanned.locale });
+    // 獨立動詞（`version`）不載入專案、不需要原生綁定，在任何解析與載入之前就結束。
+    if (isStandaloneVerb(command))
+        process.exit(runVersion(rest));
     isConfig = command === 'config';
     configAction = isConfig ? (rest[0] ?? null) : null;
     configArgv = isConfig ? rest.slice(1) : rest;
@@ -1720,15 +1748,13 @@ export async function main(argv) {
     platformSpecified = rest.includes('--platform');
     if (isConfig)
         dispatchConfig();
-    if ((!COMMANDS.includes(command) || parseError !== null)) {
-        console.error(COMMANDS.includes(command) ? parseError : usage());
-        process.exit(1);
-    }
+    if (!projectVerbs().includes(command))
+        failWith('USAGE_UNKNOWN_VERB', { verb: command });
+    if (parseError !== null)
+        failWith(parseError.code, parseError.details);
     const settled = settleBuildMode(command, parsedArgs);
-    if (settled.error !== null) {
-        console.error(settled.error);
-        process.exit(1);
-    }
+    if (settled.error !== null)
+        failWith(settled.error.code, settled.error.details);
     MODE = settled.mode;
     WATCH = parsedArgs.watch;
     // 匯出目錄以呼叫當下的工作目錄為基準轉成絕對路徑：核心收到的是每個單元的
@@ -1756,17 +1782,23 @@ export async function main(argv) {
     // 原生綁定」。代價是 config 那條路徑的訊息一律走預設語系而不理會 `--locale`
     // ——Python 側沒有這個落差（`cli.py` 的設定點在 config 分派之前），要補齊得先
     // 讓語系在不載入綁定的前提下解得出來，不是把這一行往前搬。
-    LOCALE = loadNative().resolveLocale(parsedArgs.locale, JSON.stringify(process.env), Intl.DateTimeFormat().resolvedOptions().locale ?? null);
+    LOCALE = loadNativeCore().resolveLocale(parsedArgs.locale, JSON.stringify(process.env), Intl.DateTimeFormat().resolvedOptions().locale ?? null);
     setLocale(LOCALE);
+    configureErrors({ locale: LOCALE });
     assertContentUsed();
     unitSpecified = parsedArgs.unit !== null;
     unit = parsedArgs.unit ?? 'default';
     if (command === 'init') {
+        // compat(remove-in=2.0): cli-init-verb（1.1 棄用、2.0 移除，改用各語言的 create）
+        // 棄用提示只寫 stderr，stdout 與結束碼和棄用前相同，`--json` 的輸出也不受影響。
+        process.stderr.write(`${t('cli.init.deprecated')}\n`);
         assertOutUnused('init');
         assertPlatformUnused('init');
         await runInit();
         process.exit(0);
     }
+    // 出處由環境注入，建置與查詢都要用它。解析排在 `--json` 掃描與參數驗證之後，不合法時輸出用法錯誤。
+    provenance();
     const configPath = join(srcDir, 'promptex.config.ts');
     if (WATCH) {
         // 監看的對象是「一個來源目錄產出到一個落點」這件事。無配置檔時那就是
@@ -1805,9 +1837,7 @@ export async function main(argv) {
                 units = (await import(pathToFileURL(configPath).href)).default ?? [];
             }
             catch (e) {
-                for (const line of describeLoadFailure(configPath, e))
-                    console.error(line);
-                process.exit(1);
+                failConfigLoad(configPath, e);
             }
             // 外部落點條目在進入迴圈前解一次：監看的是本專案的源碼（ADR-010「重新
             // 求值：全量」指的是本單元的聚合檔），別的專案改了什麼不在監看範圍內，
@@ -1824,8 +1854,7 @@ export async function main(argv) {
             if (target === null) {
                 // 判定不成立要印什麼與判定本身同住核心：判定收斂了而訊息留在外面，
                 // 三個宿主仍各持一份逐字相同的字串，改一處漏兩處的形態原封不動。
-                present({ kind: 'watch', event: 'targetRejected' });
-                process.exit(1);
+                failWith('RUN_WATCH_TARGET_REJECTED', {}, () => present({ kind: 'watch', event: 'targetRejected' }));
             }
             ;
             ({ promptDir: watchPromptDir, root: watchRoot, platform: watchPlatform, unitName: watchUnit,