promptex-js 1.0.0 → 1.1.0

package/README.md

@@ -15,6 +15,16 @@ the `promptex` command line tool.
 npm install promptex-js
 ```
 
+To start a new project, or to add promptex to an existing one, use
+[`create-promptex-js`](../create-promptex-js/README.md). It writes the config file
+and an example, and leaves your existing files alone:
+
+```console
+pnpm create promptex-js .
+pnpm add promptex-js
+pnpm exec promptex build --install
+```
+
 ## Minimal example
 
 Declarations live in a `prompts/` directory. Anything you `define*` at module
@@ -71,10 +81,46 @@ Switch `--platform codex` and the same declaration lands in Codex's layout inste
 | `promptex build --export <export-dir> <dir>` | Write the exact tree `--install` would write under `<export-dir>/<unit>/`, with no registry. The unit subtree is cleared first. |
 | `promptex build --watch <dir>` | Rerun the same flags (`build` alone, `--install` or `--export`) as sources change. |
 | `promptex manifest <dir>` | Answer registry queries from the current projection. |
-| `promptex init <dir>` | Scaffold a new project (`--lang ts`, `python` or `rust`). |
+| `promptex init <dir>` | Deprecated, removed in 2.0. Use `pnpm create promptex-js <dir>` instead. |
+| `promptex version` | Report the package version, the language and the flags each command supports (`--json` for the machine-readable form). |
 
 Common flags: `--out <install root>` (single-directory mode), `--platform <name>` (`manifest` only), `--unit <unit name>`, `--json`, `--locale <tag>`.
 
+## Machine-readable output
+
+`--json` makes a command print one JSON document on stdout. Every document, and every
+file the tool writes under `.promptex/`, carries `formatVersion` (currently `"1.1"`).
+Within 1.x the version only gains keys, so read the keys you know and ignore the rest.
+
+`promptex version --json` reports the package, the language and what this CLI
+supports, so a caller can check a feature before using it:
+
+```json
+{"formatVersion":"1.1","package":{"name":"promptex-js","version":"1.0.1"},"language":"ts",
+ "capabilities":{"verbs":{"build":{"flags":["--install","--dry-run","…"]},"version":{"flags":[]}},
+                 "globalFlags":["--json","--locale"]}}
+```
+
+A failing command with `--json` prints an error document on stdout and the same
+message on one line of stderr:
+
+```json
+{"formatVersion":"1.1","error":{"code":"USAGE_UNKNOWN_FLAG","message":"Unknown flag: --foo","details":{"flag":"--foo","usage":"…"}}}
+```
+
+- `code` is stable. A `USAGE_` code means the call was wrong. A `RUN_` code means the
+  call was fine and the work failed. Branch on `code`, never on `message`, which is
+  localized and may change.
+- `details` is always an object. Its keys are fixed per code and identical in all three
+  languages. Its values (paths, usage text) may differ.
+- Exit code is `1` for every failure of the existing commands, usage errors included,
+  as before. A usage error of `version` exits with `2`.
+- `config` always prints a JSON document, with or without `--json`. When it fails, that
+  document is the error document. A `config write` that is refused is a result, not an
+  error: the result document is printed and the exit code is `1`.
+- `build --watch` prints each failed round for a person to read and emits no error
+  document, because watching is a long-running loop.
+
 ## What you can declare
 
 `defineSkill`, `defineRule`, `defineAgent`, `defineInstruction`, `defineResource`,

package/dist/cli/compile-engine.js

@@ -13,6 +13,7 @@ import { register } from 'node:module';
 import { pathToFileURL } from 'node:url';
 import { currentLocale, t } from '../i18n.js';
 import { loadNativeCore } from '../native.js';
+import { failWith } from './error-output.js';
 import { PACKAGE_JSON, UNIT_SCOPE_LOADER } from '../paths.js';
 /**
  * `?u=` 的承襲鉤子只需註冊一次：它是無狀態的（承襲與否只看父模組 URL），
@@ -262,39 +263,42 @@ export async function compile(promptDir, workDir, { projectRoot, select, externa
     // 排在 `reset()` 之後、任何求值動作之前：`reset()` 一併清掉上一輪的專案根，
     // 反過來設定會被隨即清掉。
     setProjectRoot(projectRoot);
-    const fail = (message) => {
-        if (exitOnError) {
-            console.error(message);
-            process.exit(1);
-        }
-        throw new CompileFailure(message);
-    };
     /** 逐行印到 stderr；格式住 SDK 的 `formatDiagnostic` 一份，三個呼叫點不各拼一次。 */
     const printDiagnostics = (diags) => {
         for (const d of diags)
             for (const line of formatDiagnostic(d))
                 console.error(line);
     };
+    /**
+     * 一批阻斷級診斷擋下建置。`exitOnError` 為真時走統一的失敗輸出（帶 `--json` 時是錯誤 JSON，
+     * 否則逐行印診斷加收尾句）；為假時（監看的求值子行程）照舊印診斷、拋 `CompileFailure`。
+     */
+    const failDiagnostics = (diags) => {
+        if (exitOnError) {
+            failWith('RUN_DIAGNOSTICS_ABORT', { diagnostics: diags }, () => {
+                printDiagnostics(diags);
+                console.error(abortSummary());
+            }, { projectRoot });
+        }
+        printDiagnostics(diags);
+        throw new CompileFailure(abortSummary());
+    };
     // 版本相容檢查排在準備階段之前，即整個編譯流程最早的一步（ADR-005
     // 「版本範圍宣告與編譯期檢查」）：不相容時連 plugin 自己的準備階段都不
     // 執行，確保零副作用（不建立快取目錄、不發出任何 I/O），比「排在收集遍
     // 之前」更早地做到「編譯開始前即報錯」（AC-218）。
     if (plugins.length > 0) {
         const versionDiags = checkPluginVersions(plugins, FRAMEWORK_VERSION);
-        if (versionDiags.length > 0) {
-            printDiagnostics(versionDiags);
-            return fail(abortSummary());
-        }
+        if (versionDiags.length > 0)
+            return failDiagnostics(versionDiags);
     }
     // 準備階段排在收集遍之前：資料經 plugin 閉包傳給改寫遍，與源碼求值無關
     // （ADR-005「準備階段是唯一的非同步生命週期」）。任一 plugin 的準備階段
     // 失敗即中止，不進入收集遍、不留下部分結果。
     if (plugins.length > 0) {
         const prepareDiags = await engine.prepare(plugins, projectRoot);
-        if (prepareDiags.length > 0) {
-            printDiagnostics(prepareDiags);
-            return fail(abortSummary());
-        }
+        if (prepareDiags.length > 0)
+            return failDiagnostics(prepareDiags);
     }
     // 載入源碼目錄下的全部聚合檔。求值即執行作者的程式碼（PDR-002 不設沙盒）：
     // 撰寫者與執行者是同一人，信任邊界不存在。
@@ -309,8 +313,7 @@ export async function compile(promptDir, workDir, { projectRoot, select, externa
     catch (e) {
         if (!(e instanceof SourceDirFailure))
             throw e;
-        printDiagnostics(e.diagnostics);
-        return fail(abortSummary());
+        return failDiagnostics(e.diagnostics);
     }
     for (const file of sourceFiles) {
         const href = pathToFileURL(file).href;
@@ -318,9 +321,14 @@ export async function compile(promptDir, workDir, { projectRoot, select, externa
             await import(cacheBust ? `${href}?u=${encodeURIComponent(cacheBust)}` : href);
         }
         catch (e) {
-            for (const line of describeLoadFailure(file, e))
+            const lines = describeLoadFailure(file, e);
+            if (exitOnError) {
+                const detail = e instanceof Error ? e.message : String(e);
+                failWith('RUN_SOURCE_LOAD_FAILED', { path: file, detail }, [...lines, sourceLoadAbort()]);
+            }
+            for (const line of lines)
                 console.error(line);
-            return fail(sourceLoadAbort());
+            throw new CompileFailure(sourceLoadAbort());
         }
     }
     // 外部引用先登記再解析（AC-058）：讓引用它們的 useSkill／useRule 等不被
@@ -337,10 +345,9 @@ export async function compile(promptDir, workDir, { projectRoot, select, externa
     // 「衝突分級依操作型別」，AC-072、AC-075 同型延伸）。
     const diagnostics = engine.resolve(plugins);
     if (diagnostics.length > 0) {
+        if (hasErrors(diagnostics))
+            return failDiagnostics(diagnostics);
         printDiagnostics(diagnostics);
-        if (hasErrors(diagnostics)) {
-            return fail(abortSummary());
-        }
     }
     // 出處可由環境注入：三個欄位都隨環境變動，逐字比對產物時需要固定值
     // （情境回歸的 runner 即以此讓決定性可驗證）。未注入時取預設，注入了卻
@@ -350,7 +357,10 @@ export async function compile(promptDir, workDir, { projectRoot, select, externa
         provenance = parseProvenanceEnv(process.env.PROMPTEX_PROVENANCE);
     }
     catch (e) {
-        return fail(e instanceof Error ? e.message : String(e));
+        const message = e instanceof Error ? e.message : String(e);
+        if (exitOnError)
+            failWith('USAGE_PROVENANCE_INVALID', {}, message);
+        throw new CompileFailure(message);
     }
     const ir = engine.toIR(provenance, select);
     // 源碼層宣告核對（E203、E204、E206 至 E209）：接在中介表示產出之後、任何
@@ -369,10 +379,8 @@ export async function compile(promptDir, workDir, { projectRoot, select, externa
     // 排在寫出 ir.json 之前：核對不過即零產物寫入，與求值期診斷的全有全無同一
     // 條慣例。
     const sourceDiags = JSON.parse(loadNativeCore().checkSourceDeclarations(JSON.stringify(ir), currentLocale()));
-    if (sourceDiags.length > 0) {
-        printDiagnostics(sourceDiags);
-        return fail(abortSummary());
-    }
+    if (sourceDiags.length > 0)
+        return failDiagnostics(sourceDiags);
     // 交接字串只序列化一次：同一份文字既是交給核心讀的旁置檔、也是跨語言對拍面
     // （AC-084）。兩處各序列化一次的話，比對的是「測試自己序列化出來的東西」
     // 而不是實際交出去的那一份，同一份中介表示因此可能對拍通過卻與生產不符。

package/dist/cli/error-output.d.ts

@@ -0,0 +1,61 @@
+import type { ErrorCode } from '../cli-contract.generated.js';
+/** 錯誤 JSON 的 `details`：鍵照錯誤代碼表。 */
+export type ErrorDetails = Readonly<Record<string, unknown>>;
+/**
+ * 用法錯誤：代碼與 `details` 照錯誤表。人讀文字與 `details.usage` 由 `failWith` 依代碼補上，
+ * 解析器只回報「是哪一種錯」，不自己組文字。
+ */
+export interface UsageFailure {
+    code: ErrorCode;
+    details: Record<string, unknown>;
+}
+/** 不帶 `--json` 時 stderr 的內容：整段文字、逐行的陣列，或自己印的函式。 */
+export type HumanOutput = string | readonly string[] | (() => void);
+/** 本次呼叫的失敗輸出設定，由 `main()` 在解析參數前依 argv 掃描結果設定。 */
+interface ErrorContext {
+    /** 動詞，決定用法錯誤的結束碼。 */
+    verb: string;
+    /** 呼叫帶了 `--json`：stderr 只寫一行 `message`。 */
+    explicitJson: boolean;
+    /** stdout 輸出錯誤 JSON：帶 `--json`，或動詞是 `config`。 */
+    stdoutJson: boolean;
+    /** `--locale` 的值（掃描得到的，可能還沒驗證）。 */
+    localeFlag: string | null;
+    /** 已確定的語系。`null` 表示還沒確定，輸出時照當時已能解析的來源決定。 */
+    locale: string | null;
+}
+/** 更新失敗輸出設定。 */
+export declare function configureErrors(patch: Partial<ErrorContext>): void;
+/** 解析參數之前掃一次 argv：用法錯誤也要輸出錯誤 JSON，所以得先知道有沒有 `--json`。 */
+export declare function scanArgv(argv: readonly string[]): {
+    json: boolean;
+    locale: string | null;
+};
+/**
+ * 結束碼。錯誤表的 `exitCode` 是 2.0 的目標值，1.x 的實際值由這裡依動詞決定。
+ */
+export declare function exitCodeFor(code: ErrorCode): number;
+/**
+ * 綁定載不起來時的退路：與核心的 `error_envelope_json` 同形。只在 `RUN_BINDING_NOT_FOUND`
+ * 這種拿不到核心的情形用，其餘一律由核心組。
+ */
+export declare function fallbackErrorEnvelope(code: ErrorCode, details: Record<string, unknown>, locale: string): string;
+/** 組錯誤 JSON，回 `{ envelope, message }`。 */
+export declare function buildErrorEnvelope(code: ErrorCode, details?: ErrorDetails, options?: {
+    projectRoot?: string;
+    locale?: string;
+}): {
+    envelope: string;
+    message: string;
+};
+/**
+ * 輸出失敗並結束行程。
+ *
+ * - `details`：鍵照錯誤代碼表。`usage` 不用給，輸出時補。
+ * - `human`：不帶 `--json` 時 stderr 的內容，各結束點原本怎麼印就怎麼給。沒給時印該代碼的訊息。
+ * - `projectRoot`：給了就把 `details.diagnostics` 的位置換成相對專案根。
+ */
+export declare function failWith(code: ErrorCode, details?: ErrorDetails, human?: HumanOutput, options?: {
+    projectRoot?: string;
+}): never;
+export {};

package/dist/cli/error-output.js

@@ -0,0 +1,146 @@
+// 命令列失敗的輸出：所有結束點走同一個函式（`failWith`）。
+//
+// 帶 `--json` 失敗時，stdout 恰好一份錯誤 JSON，stderr 另寫一行和 `message` 同文的文字。
+// 錯誤 JSON 的外層與 `message` 由核心組（`errorEnvelope`），這裡只傳代碼與 `details`。
+// 不帶 `--json` 時 stderr 維持原本給人看的文字。`config` 不帶 `--json` 也輸出 JSON，
+// 所以它的失敗一律在 stdout 輸出錯誤 JSON。
+//
+// 本檔不在模組載入時碰原生綁定：`version` 與解析期的失敗都要在沒有綁定時走得完
+// （`tests/zero-install.test.ts`）。核心的函式在輸出當下才載入；綁定載不起來時（代碼
+// `RUN_BINDING_NOT_FOUND`）退回本檔的同形組裝，`tests/cli-error-json.test.ts` 核對兩者逐字相同。
+import { ERRORS, FORMAT_VERSION } from '../cli-contract.generated.js';
+import { currentLocale, t } from '../i18n.js';
+import { loadNativeCore } from '../native.js';
+import { isStandaloneVerb } from './flag-table.js';
+import { writeStructuredLine } from './stdout.js';
+const context = { verb: '', explicitJson: false, stdoutJson: false, localeFlag: null, locale: null };
+/** 更新失敗輸出設定。 */
+export function configureErrors(patch) {
+    Object.assign(context, patch);
+}
+/** 解析參數之前掃一次 argv：用法錯誤也要輸出錯誤 JSON，所以得先知道有沒有 `--json`。 */
+export function scanArgv(argv) {
+    const at = argv.lastIndexOf('--locale');
+    return { json: argv.includes('--json'), locale: at >= 0 && at + 1 < argv.length ? argv[at + 1] : null };
+}
+/**
+ * 結束碼。錯誤表的 `exitCode` 是 2.0 的目標值，1.x 的實際值由這裡依動詞決定。
+ */
+export function exitCodeFor(code) {
+    const target = ERRORS.find((error) => error.code === code)?.exitCode ?? 1;
+    // compat(remove-in=2.0): usage-exit-code
+    // 既有動詞（build、manifest、init、config）的用法錯誤在 1.x 維持結束碼 1，
+    // 新動詞 `version` 從一開始就用錯誤表的 2。2.0 刪掉這一段，一律用錯誤表的值。
+    if (target === 2 && !isStandaloneVerb(context.verb))
+        return 1;
+    return target;
+}
+/** 錯誤 JSON 的語系：已確定的優先，否則請核心照旗標、環境與作業系統偏好解析，解析不到用英文。 */
+function errorLocale() {
+    if (context.locale !== null)
+        return context.locale;
+    try {
+        return loadNativeCore().resolveLocale(context.localeFlag, JSON.stringify(process.env), Intl.DateTimeFormat().resolvedOptions().locale ?? null);
+    }
+    catch {
+        return context.localeFlag ?? currentLocale();
+    }
+}
+/** 補上用法文字：錯誤表的 `details` 含 `usage` 而呼叫端沒給時，取該語系的用法。 */
+function withUsage(code, details, locale) {
+    const spec = ERRORS.find((error) => error.code === code);
+    if (spec?.details.includes('usage') && !('usage' in details))
+        return { ...details, usage: t('cli.usage.js', undefined, locale) };
+    return { ...details };
+}
+/** 訊息範本的代入值：字串陣列用逗號接起來，其餘轉字串。 */
+function interpolate(value) {
+    if (Array.isArray(value))
+        return value.map(String).join(', ');
+    if (value === null || value === undefined)
+        return '';
+    return typeof value === 'object' ? JSON.stringify(value) : String(value);
+}
+/** 該代碼的完整人讀文字（用法文字另計）。 */
+function textFor(code, details, locale) {
+    const spec = ERRORS.find((error) => error.code === code);
+    if (spec === undefined)
+        return code;
+    const params = {};
+    for (const [key, value] of Object.entries(details))
+        params[key] = interpolate(value);
+    return t(spec.messageKey, params, locale);
+}
+/** 錯誤 JSON 的 `message`：完整文字的第一行，去掉行首的 `✗ ` 記號。 */
+function oneLine(text) {
+    const first = text.split('\n')[0] ?? '';
+    return (first.startsWith('✗ ') ? first.slice(2) : first).trim();
+}
+/**
+ * 綁定載不起來時的退路：與核心的 `error_envelope_json` 同形。只在 `RUN_BINDING_NOT_FOUND`
+ * 這種拿不到核心的情形用，其餘一律由核心組。
+ */
+export function fallbackErrorEnvelope(code, details, locale) {
+    const spec = ERRORS.find((error) => error.code === code);
+    const shaped = {};
+    for (const key of spec?.details ?? [])
+        shaped[key] = details[key] ?? null;
+    const message = oneLine(textFor(code, shaped, locale));
+    return JSON.stringify({ formatVersion: FORMAT_VERSION, error: { code, message, details: shaped } });
+}
+/** 組錯誤 JSON，回 `{ envelope, message }`。 */
+export function buildErrorEnvelope(code, details = {}, options = {}) {
+    const locale = options.locale ?? errorLocale();
+    const filled = withUsage(code, details, locale);
+    let envelope;
+    try {
+        envelope = loadNativeCore().errorEnvelope(JSON.stringify({ code, details: filled, projectRoot: options.projectRoot }), locale);
+    }
+    catch {
+        envelope = fallbackErrorEnvelope(code, filled, locale);
+    }
+    const message = JSON.parse(envelope).error.message;
+    return { envelope, message };
+}
+/** 印不帶 `--json` 時給人看的文字。 */
+function printHuman(code, details, human) {
+    if (typeof human === 'function')
+        human();
+    else if (typeof human === 'string')
+        console.error(human);
+    else if (human !== undefined)
+        for (const line of human)
+            console.error(line);
+    else {
+        // 沒指定就印該代碼的訊息，錯誤表的 `details` 含 `usage` 時接上用法文字。
+        const spec = ERRORS.find((error) => error.code === code);
+        const text = textFor(code, details);
+        if (spec?.details.includes('usage'))
+            console.error(code === 'USAGE_UNKNOWN_VERB' ? t('cli.usage.js') : `${text}\n${t('cli.usage.js')}`);
+        else
+            console.error(text);
+    }
+}
+/**
+ * 輸出失敗並結束行程。
+ *
+ * - `details`：鍵照錯誤代碼表。`usage` 不用給，輸出時補。
+ * - `human`：不帶 `--json` 時 stderr 的內容，各結束點原本怎麼印就怎麼給。沒給時印該代碼的訊息。
+ * - `projectRoot`：給了就把 `details.diagnostics` 的位置換成相對專案根。
+ */
+export function failWith(code, details = {}, human, options = {}) {
+    if (context.stdoutJson) {
+        // `message` 與 `details.usage` 用同一個語系。
+        const locale = errorLocale();
+        const { envelope, message } = buildErrorEnvelope(code, details, { projectRoot: options.projectRoot, locale });
+        writeStructuredLine(envelope);
+        if (context.explicitJson)
+            console.error(message);
+        else
+            printHuman(code, details, human);
+    }
+    else {
+        printHuman(code, details, human);
+    }
+    process.exit(exitCodeFor(code));
+}

package/dist/cli/flag-table.d.ts

@@ -0,0 +1,30 @@
+import type { Ecosystem, ErrorCode, FlagSpec } from '../cli-contract.generated.js';
+/** 本命令列所屬的生態。 */
+export declare const ECOSYSTEM: Ecosystem;
+/** 依名稱查本生態認得的旗標，認不得回 `undefined`。 */
+export declare function flagSpec(name: string): FlagSpec | undefined;
+/** 本生態的全部旗標名稱，依表內順序。 */
+export declare function ownFlagNames(): string[];
+/** 旗標對指定動詞是否有效。全域旗標對所有動詞有效。 */
+export declare function flagApplies(flag: FlagSpec, verb: string): boolean;
+/** 表裡的全部動詞名稱。 */
+export declare function verbNames(): string[];
+/** 是否為獨立動詞：不載入專案、不需要原生綁定（如 `version`）。 */
+export declare function isStandaloneVerb(name: string): boolean;
+/**
+ * 走完旗標解析後才交給「建置、查詢、初始化」流程的動詞：表裡一層、非獨立的動詞。
+ * `config` 有子動作、走另一條路徑，`version` 是獨立動詞，兩者都不在此列。
+ */
+export declare function projectVerbs(): string[];
+/**
+ * 給了不適用的動詞、而表標了 `rejectOutside` 的第一個旗標（依表內順序）。
+ *
+ * 沒標 `rejectOutside` 的旗標給了不適用的動詞時靜默接受，那是 1.0.x 的行為，1.x 照舊。
+ * compat(remove-in=2.0): silent-inapplicable-flag
+ */
+export declare function firstRejectedOutside(given: ReadonlySet<string>, verb: string): string | null;
+/**
+ * 第一條被違反的 requires 或 conflicts 規則（依錯誤表內順序）的錯誤代碼，沒有則回 `null`。
+ * 規則只對旗標有效的動詞檢查。
+ */
+export declare function firstViolatedRule(given: ReadonlySet<string>, verb: string): ErrorCode | null;

package/dist/cli/flag-table.js

@@ -0,0 +1,77 @@
+// 命令列解析器讀旗標定義表的薄層。
+//
+// 表住核心的 `crates/promptex-core/cli/flags.json`，生成物是 `../cli-contract.generated.ts`。
+// 解析器靠本檔回答「這個動詞認不認得」「這個旗標認不認得、帶不帶值」「旗標對哪個動詞有效」
+// 「哪條規則被違反」。旗標的值寫進 `CliArgs` 的哪個欄位仍由 `main.ts` 決定，表不管那一層。
+//
+// 本檔只 import 生成物，不載入原生綁定，零安裝（`tests/zero-install.test.ts`）因此成立。
+import { ERRORS, FLAGS, VERBS } from '../cli-contract.generated.js';
+/** 本命令列所屬的生態。 */
+export const ECOSYSTEM = 'js';
+/** 本生態認得的旗標。 */
+const OWN_FLAGS = FLAGS.filter((flag) => flag.ecosystems.includes(ECOSYSTEM));
+/** 依名稱查本生態認得的旗標，認不得回 `undefined`。 */
+export function flagSpec(name) {
+    return OWN_FLAGS.find((flag) => flag.name === name);
+}
+/** 本生態的全部旗標名稱，依表內順序。 */
+export function ownFlagNames() {
+    return OWN_FLAGS.map((flag) => flag.name);
+}
+/** 旗標對指定動詞是否有效。全域旗標對所有動詞有效。 */
+export function flagApplies(flag, verb) {
+    if (!flag.ecosystems.includes(ECOSYSTEM))
+        return false;
+    if (flag.global)
+        return true;
+    if (!flag.verbs.includes(verb))
+        return false;
+    return (flag.verbEcosystems[verb] ?? flag.ecosystems).includes(ECOSYSTEM);
+}
+/** 表裡的全部動詞名稱。 */
+export function verbNames() {
+    return VERBS.map((verb) => verb.name);
+}
+/** 是否為獨立動詞：不載入專案、不需要原生綁定（如 `version`）。 */
+export function isStandaloneVerb(name) {
+    return VERBS.some((verb) => verb.name === name && verb.standalone);
+}
+/**
+ * 走完旗標解析後才交給「建置、查詢、初始化」流程的動詞：表裡一層、非獨立的動詞。
+ * `config` 有子動作、走另一條路徑，`version` 是獨立動詞，兩者都不在此列。
+ */
+export function projectVerbs() {
+    return VERBS.filter((verb) => verb.actions.length === 0 && !verb.standalone).map((verb) => verb.name);
+}
+/**
+ * 給了不適用的動詞、而表標了 `rejectOutside` 的第一個旗標（依表內順序）。
+ *
+ * 沒標 `rejectOutside` 的旗標給了不適用的動詞時靜默接受，那是 1.0.x 的行為，1.x 照舊。
+ * compat(remove-in=2.0): silent-inapplicable-flag
+ */
+export function firstRejectedOutside(given, verb) {
+    for (const flag of OWN_FLAGS) {
+        if (flag.rejectOutside && given.has(flag.name) && !flagApplies(flag, verb))
+            return flag.name;
+    }
+    return null;
+}
+/**
+ * 第一條被違反的 requires 或 conflicts 規則（依錯誤表內順序）的錯誤代碼，沒有則回 `null`。
+ * 規則只對旗標有效的動詞檢查。
+ */
+export function firstViolatedRule(given, verb) {
+    for (const error of ERRORS) {
+        const rule = error.rule;
+        if (rule === null || !error.ecosystems.includes(ECOSYSTEM))
+            continue;
+        const flag = flagSpec(rule.flag);
+        if (flag === undefined || !flagApplies(flag, verb) || !given.has(rule.flag))
+            continue;
+        if (rule.requires !== undefined && !given.has(rule.requires))
+            return error.code;
+        if (rule.conflicts !== undefined && given.has(rule.conflicts))
+            return error.code;
+    }
+    return null;
+}

package/dist/cli/main.d.ts

@@ -35,7 +35,17 @@ export interface CliArgs {
     ops: string | null;
     apply: boolean;
     locale: string | null;
+    /** 本次呼叫實際給了哪些旗標（旗標全名）。旗標適用的動詞與規則檢查都以它為輸入。 */
+    given: ReadonlySet<string>;
 }
+/**
+ * 旗標的值寫進 `CliArgs` 的哪個欄位。旗標認不認得、帶不帶值由定義表決定
+ * （`flag-table.ts`），表不管欄位；表新增旗標時這裡也要補一筆，`tests/cli-flag-table.test.ts`
+ * 會核對每個旗標都有對應。
+ */
+export declare const VALUE_FIELDS: Readonly<Record<string, 'out' | 'platform' | 'unit' | 'lang' | 'ops' | 'locale' | 'exportDir'>>;
+/** 不帶值的旗標寫進 `CliArgs` 的哪個布林欄位。 */
+export declare const SWITCH_FIELDS: Readonly<Record<string, 'assumeYes' | 'json' | 'content' | 'install' | 'dryRun' | 'watch' | 'apply'>>;
 /**
  * 寫出本單元的旁置平台設定檔，回傳路徑（無宣告時回空字串、不寫檔）。
  *