@ykdz/template 0.0.42 → 0.1.0-experimental.0

package/node_modules/@ykdz/cli-contract/dist/contract-schema.d.ts

@@ -6,6 +6,10 @@ export type JsonValue = JsonPrimitive | readonly JsonValue[] | {
 export type JsonObject = {
     readonly [key: string]: JsonValue;
 };
+/**
+ * 同一模式负责运行时验证和 JSON Schema 投影。输入字段的必填、候选值及实际格式规则
+ * 以模式为准；不要为了简化投影而删掉仍会影响接受范围的校验。
+ */
 export interface ContractSchema<Input = unknown, Output = Input> {
     readonly "~standard": StandardSchemaV1.Props<Input, Output> & StandardJSONSchemaV1.Props<Input, Output>;
 }

package/node_modules/@ykdz/cli-contract/dist/field-identity.d.ts

@@ -0,0 +1,2 @@
+export declare const reservedFieldNames: readonly ["constructor", "hasOwnProperty", "isPrototypeOf", "propertyIsEnumerable", "toString", "valueOf", "toLocaleString"];
+export declare function invalidFieldIdentityReason(field: string): "lowerCamelCase" | "reservedName" | undefined;

package/node_modules/@ykdz/cli-contract/dist/field-identity.js

@@ -0,0 +1,16 @@
+export const reservedFieldNames = [
+    "constructor",
+    "hasOwnProperty",
+    "isPrototypeOf",
+    "propertyIsEnumerable",
+    "toString",
+    "valueOf",
+    "toLocaleString",
+];
+export function invalidFieldIdentityReason(field) {
+    if (!/^[a-z][A-Za-z0-9]*$/.test(field))
+        return "lowerCamelCase";
+    return reservedFieldNames.some((reserved) => reserved === field)
+        ? "reservedName"
+        : undefined;
+}

package/node_modules/@ykdz/cli-contract/dist/index.d.ts

@@ -1,8 +1,9 @@
-/** 完整示例：https://github.com/YKDZ/cli-contract/tree/v0.2.1/packages/example */
-export { defineCli, helpCapability, outputCapability, versionCapability, type CliContract, type CliContractDependencies, type CliContractRawInput, type CliContractResult, type CliContractRoot, type CliGrammar, type CliManifest, type CommandGrammar, type CommandGroupDefinition, type CommandGroupGrammar, type CommandGroupManifest, type CommandWireManifest, type CanonicalLongOption, type CompletionFact, type CompletionHandlerContext, type CompletionOutcome, type CompletionRootCliDefinition, type CompletionRootCommandDefinition, type ContractTypeError, type DataFact, type DataFactUnion, type DataHandlerContext, type DataOutcome, type DataRootCliDefinition, type DataRootCommandDefinition, type DataVariantDefinition, type DataVariantDefinitions, type StreamHandlerContext, type StreamOutcome, type StreamRecordDefinition, type StreamRecordDefinitions, type StreamRecordFact, type StreamRecordFactUnion, type StreamRootCliDefinition, type StreamRootCommandDefinition, type StreamSuccessFact, type DefineCli, type DefineCommand, type FailureFact, type FailureFactUnion, type FailureOutcome, type FailureVariantDefinition, type FailureVariantDefinitions, type FailureVariantManifest, type FieldDefinition, type FieldDefinitions, type FieldDefinitionsForInput, type FieldGrammar, type ForbiddenCombinationUsageConstraint, type ForbiddenCombinationValue, type FlagDefinition, type FlagGrammar, type HelpCapability, type HelpCapabilityDefinition, type HelpFactWording, type HelpHeadings, type HierarchyCliGrammar, type HierarchyCliManifest, type OutcomeFact, type OutputCapability, type OutputFormat, text, type SilentText, type TextLine, type TextLines, type PositionalDefinition, type PositionalGrammar, type RepeatableOptionDefinition, type RepeatableOptionGrammar, type RequiresUsageConstraint, type RawFieldInput, type RawValueOptionInput, type RawValueOptionInputForSchema, type RootCliDefinition, type RootGroupDefinition, type RootGroupGrammar, type RootCommandDefinition, type RootCommandGrammar, type RootCommandManifest, type ExecutableCommandDefinition, type ExecutableCommandGrammar, type ExecutableCommandManifest, type ShortOptionAlias, type SchemaManifest, type ValueOptionDefinition, type ValueOptionDefinitions, type ValueOptionDefinitionsForInput, type ValueOptionGrammar, type VersionCapability, type VersionCapabilityDefinition, type VariadicPositionalDefinition, type VariadicPositionalGrammar, type UsageConstraint, type UsageConstraintGrammar, type ExclusiveUsageConstraint, } from "#/cli-contract";
+/** 完整示例：https://github.com/YKDZ/cli-contract/tree/v0.3.0/packages/example */
+export { defineCli, helpCapability, outputCapability, versionCapability, type CliContract, type CliContractDependencies, type CliContractRawInput, type CliContractResult, type CliContractRoot, type CliGrammar, type CliManifest, type CommandCombination, type CommandCombinationBrand, type CommandGrammar, type CommandGroupDefinition, type CommandGroupGrammar, type CommandGroupManifest, type CommandWireManifest, type CountUsageConstraint, type CanonicalLongOption, type CompletionFact, type CompletionHandlerContext, type CompletionOutcome, type CompletionRootCliDefinition, type CompletionRootCommandDefinition, type ContractTypeError, type DataFact, type DataFactUnion, type DataHandlerContext, type DataOutcome, type DataRootCliDefinition, type DataRootCommandDefinition, type DataVariantDefinition, type DataVariantDefinitions, type StreamHandlerContext, type StreamOutcome, type StreamRecordDefinition, type StreamRecordDefinitions, type StreamRecordFact, type StreamRecordFactUnion, type StreamRootCliDefinition, type StreamRootCommandDefinition, type StreamSuccessFact, type DefineCli, type DefineCommand, type FailureFact, type FailureFactUnion, type FailureOutcome, type FailureVariantDefinition, type FailureVariantDefinitions, type FailureVariantManifest, type FieldDefinition, type FieldDefinitions, type FieldDefinitionsForInput, type FieldGrammar, type ForbiddenCombinationUsageConstraint, type FlagDefinition, type FlagGrammar, type HelpCapability, type HelpCapabilityDefinition, type HelpFactTemplateParameters, type HelpFactWording, type HelpHeadings, type HierarchyCliGrammar, type HierarchyCliManifest, type OutcomeFact, type OutputCapability, type OutputFormat, text, TextValueError, type SilentText, type TextLine, type TextLines, type TextValueErrorIssue, type PositionalDefinition, type PositionalGrammar, type RepeatableOptionDefinition, type RepeatableOptionGrammar, type PresentUsageFact, type EqualsUsageFact, type UsageFact, type UsageFactValue, type RawFieldInput, type RawValueOptionInput, type RawValueOptionInputForSchema, type RootCliDefinition, type RootGroupDefinition, type RootGroupGrammar, type RootCommandDefinition, type RootCommandGrammar, type RootCommandManifest, type ExecutableCommandDefinition, type ExecutableCommandGrammar, type ExecutableCommandManifest, type ShortOptionAlias, type SchemaManifest, type ValueOptionDefinition, type ValueOptionDefinitions, type ValueOptionDefinitionsForInput, type ValueOptionGrammar, type VersionCapability, type VersionCapabilityDefinition, type VariadicPositionalDefinition, type VariadicPositionalGrammar, type UsageConstraint, type UsageConstraintEffect, type UsageConstraintGrammar, type CountUsageConstraintGrammar, type WhenUsageConstraint, } from "#/cli-contract";
+export type { AtomicTextPresenter } from "#/outcome-fact";
 export { executeCli, type CliOutput, type CliOutputDestination, type CliTermination, type ExecuteCliOptions, type WriteCliOutput, } from "#/cli-execution";
 export { CliWriteError } from "#/cli-write-error";
-export { parseCliInvocation, type CliInvocation, type CommandUsage, type ConflictingFlagIssue, type ConflictingOutputFormatIssue, type ExclusiveUsageConstraintIssue, type ForbiddenUsageCombinationIssue, type HelpRequest, type InputRejectedIssue, type InvalidFieldChoiceIssue, type InvalidOutputFormatIssue, type MissingOptionValueIssue, type MissingRequiredFieldIssue, type NonEmptyUsageIssues, type OptionOccurrenceEvidence, type ParsedInvocation, type RepeatedOptionIssue, type RequiredByUsageConstraintIssue, type SchemaIssueEvidence, type UnexpectedPositionalIssue, type UnexpectedOptionValueIssue, type UnknownOptionIssue, type UnknownCommandIssue, type UsageIssue, type UsageFailure, type VersionRequest, } from "#/cli-invocation";
+export { parseCliInvocation, type CliInvocation, type CommandUsage, type ConflictingFlagIssue, type ConflictingOutputFormatIssue, type CountConstraintViolationIssue, type ConditionalConstraintViolationIssue, type EqualsUsageObservation, type ForbiddenCombinationViolationIssue, type HelpRequest, type InputRejectedIssue, type InvalidFieldChoiceIssue, type InvalidOutputFormatIssue, type MissingOptionValueIssue, type MissingRequiredFieldIssue, type NonEmptyCliUsageIssues, type NonEmptyUsageIssues, type OptionOccurrenceEvidence, type ParsedInvocation, type RepeatedOptionIssue, type PresentUsageObservation, type SchemaIssueEvidence, type UnexpectedPositionalIssue, type UnexpectedOptionValueIssue, type UnknownOptionIssue, type UnknownCommandIssue, type UsageIssue, type CliUsageIssue, type UsageConstraintObservation, type UsageFailure, type VersionRequest, } from "#/cli-invocation";
 export { ContractExecutionError, type ContractExecutionIssue, } from "#/contract-execution-error";
 export { ContractDefinitionError, type ContractDefinitionIssue, type SchemaDefinitionTarget, } from "#/contract-definition-error";
 export type { ContractSchema, ContractSchemaInput, ContractSchemaOutput, EmptyCliInput, JsonObject, JsonPrimitive, JsonValue, } from "#/contract-schema";

package/node_modules/@ykdz/cli-contract/dist/index.js

@@ -1,5 +1,5 @@
-/** 完整示例：https://github.com/YKDZ/cli-contract/tree/v0.2.1/packages/example */
-export { defineCli, helpCapability, outputCapability, versionCapability, text, } from "#/cli-contract";
+/** 完整示例：https://github.com/YKDZ/cli-contract/tree/v0.3.0/packages/example */
+export { defineCli, helpCapability, outputCapability, versionCapability, text, TextValueError, } from "#/cli-contract";
 export { executeCli, } from "#/cli-execution";
 export { CliWriteError } from "#/cli-write-error";
 export { parseCliInvocation, } from "#/cli-invocation";

package/node_modules/@ykdz/cli-contract/dist/node.d.ts

@@ -1,4 +1,4 @@
-/** 完整示例：https://github.com/YKDZ/cli-contract/tree/v0.2.1/packages/example */
+/** 完整示例：https://github.com/YKDZ/cli-contract/tree/v0.3.0/packages/example */
 /// <reference types="node" preserve="true" />
 import type { Writable } from "node:stream";
 import type { WriteCliOutput } from "#/cli-execution";

package/node_modules/@ykdz/cli-contract/dist/node.js

@@ -1,4 +1,4 @@
-/** 完整示例：https://github.com/YKDZ/cli-contract/tree/v0.2.1/packages/example */
+/** 完整示例：https://github.com/YKDZ/cli-contract/tree/v0.3.0/packages/example */
 /// <reference types="node" preserve="true" />
 /**
  * 将调用方提供的 Writable 接到核心输出端口，按核心选择的 stdout/stderr 路由写入。

package/node_modules/@ykdz/cli-contract/dist/outcome-fact.d.ts

@@ -27,30 +27,63 @@ export type AtomicTextPresenter<Payload> = {
 export type StreamTextPresenter<Payload> = {
     bivarianceHack(payload: Payload): TextLine | TextFragment;
 }["bivarianceHack"];
+export type TextValueErrorIssue = Readonly<{
+    readonly code: "invalidTextLine";
+    readonly reason: "empty" | "carriageReturn" | "lineFeed" | "nullCharacter";
+}> | Readonly<{
+    readonly code: "invalidTextLines";
+    readonly reason: "notArray" | "noLines" | "noNonEmptyLine";
+}> | Readonly<{
+    readonly code: "invalidTextLines";
+    readonly reason: "notString" | "carriageReturn" | "lineFeed" | "nullCharacter";
+    /** `text.lines` 中从 0 开始的非法成员位置。 */
+    readonly line: number;
+}> | Readonly<{
+    readonly code: "invalidTextFragment";
+    readonly reason: "empty";
+}> | Readonly<{
+    readonly code: "invalidTextFragment";
+    readonly reason: "nullCharacter";
+    /** 片段中从 0 开始、含 NUL 的行号，按 LF 计数。 */
+    readonly line: number;
+}>;
+/**
+ * 文本构造器发现动态值违反分帧规则时抛出的 TypeError。
+ * `message` 保留稳定 code；`issue` 给出闭合原因和适用的 0 基行位置，且不包含文本内容。
+ */
+export declare class TextValueError extends TypeError {
+    readonly issue: TextValueErrorIssue;
+    constructor(issue: TextValueErrorIssue);
+}
 declare function createTextLine(value: string): TextLine;
 declare function createTextLines(values: readonly [string, ...string[]]): TextLines;
 declare function createTextFragment(value: string): TextFragment;
-/** 在呈现器中显式构造文本投影；这里只验证文本值，实际通道路由与分帧由执行内核负责。 */
+/**
+ * 在呈现器中显式构造文本投影；这里只验证文本值，实际通道路由与分帧由执行内核负责。
+ * 动态值违反构造规则时抛出 {@link TextValueError}，其 message 是稳定 code，issue 不含原文。
+ */
 export declare const text: Readonly<{
     /**
      * 构造非空单行，拒绝 CR、LF、NUL；核心写出时追加恰好一个 LF。
-     * 适用于原子结果、流记录及流成功终态，呈现器应提供完整文本而不依赖核心补写文案。
+     * 适用于 completion、data、failure、stream success 终态和普通 stream record；
+     * 呈现器提供完整文本，核心不补写文案。非法值会说明具体拒绝原因。
      */
     line: typeof createTextLine;
     /**
-     * 构造有序行组，至少一行非空；每行拒绝 CR、LF、NUL，空成员显式保留空白行。
-     * 核心用 LF 连接并追加一个终止 LF。用于原子结果、失败、流成功终态或帮助补充，
-     * 不用于流记录；例如 text.lines(["处理完成", "", "详细说明"])。
+     * 构造非空元组行组（readonly [string, ...string[]]），至少一个成员非空；每行拒绝 CR、LF、NUL。
+     * 空成员可显式保留空白行。核心以 LF 连接并追加一个终止 LF；动态非法成员会报告其 0 基位置。
+     * 适用于 completion、data、failure、stream success 终态及帮助补充，不适用于 stream record。
+     * 例如 `text.lines(["处理完成", "", "详细说明"])`。
      */
     lines: typeof createTextLines;
     /**
-     * 仅用于流记录中需要连续拼接的增量文本；必须非空且不含 NUL，可以含换行。
-     * 核心原样写出，不追加 LF，因此不承诺一行对应一条记录。
+     * 仅用于 stream record 中需要连续拼接的增量文本；必须非空且不含 NUL，可以含 LF。
+     * 核心原样写出，不追加或转换字符，因此不承诺一行对应一条记录；NUL 的错误位置按 0 基行号给出。
      */
     fragment: typeof createTextFragment;
     /**
-     * completion 成功或流成功终态显式选择不写文本字节；仍须由呈现器返回此值。
-     * 省略呈现器不等于静默，data、failure 和流记录也不能用它代替输出。
+     * 仅供 completion 成功或 stream success 终态显式选择不写文本字节；仍须由呈现器返回此值。
+     * 省略呈现器不等于静默；data、failure 和 stream record 都必须产生文本。
      */
     silent: SilentText;
 }>;

package/node_modules/@ykdz/cli-contract/dist/outcome-fact.js

@@ -1,27 +1,84 @@
 const outcomeFactType = Symbol("OutcomeFact.type");
 const textProjectionType = Symbol("TextProjection.type");
 const issuedTextProjections = new WeakSet();
+/**
+ * 文本构造器发现动态值违反分帧规则时抛出的 TypeError。
+ * `message` 保留稳定 code；`issue` 给出闭合原因和适用的 0 基行位置，且不包含文本内容。
+ */
+export class TextValueError extends TypeError {
+    issue;
+    constructor(issue) {
+        super(issue.code);
+        this.name = "TextValueError";
+        this.issue = Object.freeze(issue);
+    }
+}
 /* oxlint-disable typescript/no-unsafe-type-assertion -- 文本投影仅由这些工厂签发，运行时身份由 WeakSet 核对。 */
 function createTextLine(value) {
-    if (value.length === 0 ||
-        value.includes("\r") ||
-        value.includes("\n") ||
-        value.includes("\0")) {
-        throw new TypeError("invalidTextLine");
+    if (value.length === 0) {
+        throw new TextValueError({ code: "invalidTextLine", reason: "empty" });
+    }
+    if (value.includes("\r")) {
+        throw new TextValueError({
+            code: "invalidTextLine",
+            reason: "carriageReturn",
+        });
+    }
+    if (value.includes("\n")) {
+        throw new TextValueError({ code: "invalidTextLine", reason: "lineFeed" });
+    }
+    if (value.includes("\0")) {
+        throw new TextValueError({
+            code: "invalidTextLine",
+            reason: "nullCharacter",
+        });
     }
     const projection = Object.freeze({ kind: "line", value });
     issuedTextProjections.add(projection);
     return projection;
 }
 function createTextLines(values) {
-    if (!Array.isArray(values) ||
-        values.length === 0 ||
-        values.some((value) => typeof value !== "string" ||
-            value.includes("\r") ||
-            value.includes("\n") ||
-            value.includes("\0")) ||
-        values.every((value) => value.length === 0)) {
-        throw new TypeError("invalidTextLines");
+    if (!Array.isArray(values)) {
+        throw new TextValueError({ code: "invalidTextLines", reason: "notArray" });
+    }
+    if (values.length === 0) {
+        throw new TextValueError({ code: "invalidTextLines", reason: "noLines" });
+    }
+    for (const [line, value] of values.entries()) {
+        if (typeof value !== "string") {
+            throw new TextValueError({
+                code: "invalidTextLines",
+                reason: "notString",
+                line,
+            });
+        }
+        if (value.includes("\r")) {
+            throw new TextValueError({
+                code: "invalidTextLines",
+                reason: "carriageReturn",
+                line,
+            });
+        }
+        if (value.includes("\n")) {
+            throw new TextValueError({
+                code: "invalidTextLines",
+                reason: "lineFeed",
+                line,
+            });
+        }
+        if (value.includes("\0")) {
+            throw new TextValueError({
+                code: "invalidTextLines",
+                reason: "nullCharacter",
+                line,
+            });
+        }
+    }
+    if (values.every((value) => value.length === 0)) {
+        throw new TextValueError({
+            code: "invalidTextLines",
+            reason: "noNonEmptyLine",
+        });
     }
     const projection = Object.freeze({
         kind: "lines",
@@ -34,35 +91,52 @@ const silentProjection = Object.freeze({ kind: "silent" });
 issuedTextProjections.add(silentProjection);
 const silentText = silentProjection;
 function createTextFragment(value) {
-    if (value.length === 0 || value.includes("\0")) {
-        throw new TypeError("invalidTextFragment");
+    if (value.length === 0) {
+        throw new TextValueError({
+            code: "invalidTextFragment",
+            reason: "empty",
+        });
+    }
+    const nullCharacter = value.indexOf("\0");
+    if (nullCharacter >= 0) {
+        const line = value.slice(0, nullCharacter).split("\n").length - 1;
+        throw new TextValueError({
+            code: "invalidTextFragment",
+            reason: "nullCharacter",
+            line,
+        });
     }
     const projection = Object.freeze({ kind: "fragment", value });
     issuedTextProjections.add(projection);
     return projection;
 }
 /* oxlint-enable typescript/no-unsafe-type-assertion */
-/** 在呈现器中显式构造文本投影；这里只验证文本值，实际通道路由与分帧由执行内核负责。 */
+/**
+ * 在呈现器中显式构造文本投影；这里只验证文本值，实际通道路由与分帧由执行内核负责。
+ * 动态值违反构造规则时抛出 {@link TextValueError}，其 message 是稳定 code，issue 不含原文。
+ */
 export const text = Object.freeze({
     /**
      * 构造非空单行，拒绝 CR、LF、NUL；核心写出时追加恰好一个 LF。
-     * 适用于原子结果、流记录及流成功终态，呈现器应提供完整文本而不依赖核心补写文案。
+     * 适用于 completion、data、failure、stream success 终态和普通 stream record；
+     * 呈现器提供完整文本，核心不补写文案。非法值会说明具体拒绝原因。
      */
     line: createTextLine,
     /**
-     * 构造有序行组，至少一行非空；每行拒绝 CR、LF、NUL，空成员显式保留空白行。
-     * 核心用 LF 连接并追加一个终止 LF。用于原子结果、失败、流成功终态或帮助补充，
-     * 不用于流记录；例如 text.lines(["处理完成", "", "详细说明"])。
+     * 构造非空元组行组（readonly [string, ...string[]]），至少一个成员非空；每行拒绝 CR、LF、NUL。
+     * 空成员可显式保留空白行。核心以 LF 连接并追加一个终止 LF；动态非法成员会报告其 0 基位置。
+     * 适用于 completion、data、failure、stream success 终态及帮助补充，不适用于 stream record。
+     * 例如 `text.lines(["处理完成", "", "详细说明"])`。
      */
     lines: createTextLines,
     /**
-     * 仅用于流记录中需要连续拼接的增量文本；必须非空且不含 NUL，可以含换行。
-     * 核心原样写出，不追加 LF，因此不承诺一行对应一条记录。
+     * 仅用于 stream record 中需要连续拼接的增量文本；必须非空且不含 NUL，可以含 LF。
+     * 核心原样写出，不追加或转换字符，因此不承诺一行对应一条记录；NUL 的错误位置按 0 基行号给出。
      */
     fragment: createTextFragment,
     /**
-     * completion 成功或流成功终态显式选择不写文本字节；仍须由呈现器返回此值。
-     * 省略呈现器不等于静默，data、failure 和流记录也不能用它代替输出。
+     * 仅供 completion 成功或 stream success 终态显式选择不写文本字节；仍须由呈现器返回此值。
+     * 省略呈现器不等于静默；data、failure 和 stream record 都必须产生文本。
      */
     silent: silentText,
 });

package/node_modules/@ykdz/cli-contract/dist/outcome-wire.d.ts

@@ -1,12 +1,12 @@
 import type { JsonObject } from "#/contract-schema";
 export declare function createCompletionEnvelope<Command extends string>(command: Command): Readonly<{
-    schemaVersion: "1";
+    schemaVersion: "2";
     command: Command;
     kind: "completion";
 }>;
 export declare function createCompletionWireSchema(command: string): JsonObject;
 export declare function createDataEnvelope<Command extends string, Variant extends string, Data>(command: Command, variant: Variant, data: Data): Readonly<{
-    schemaVersion: "1";
+    schemaVersion: "2";
     command: Command;
     kind: "data";
     variant: Variant;
@@ -14,7 +14,7 @@ export declare function createDataEnvelope<Command extends string, Variant exten
 }>;
 export declare function createDataWireSchema(command: string, variant: string, dataSchema: JsonObject): JsonObject;
 export declare function createFailureEnvelope<Command extends string, Variant extends string, Data>(command: Command, variant: Variant, data: Data): Readonly<{
-    schemaVersion: "1";
+    schemaVersion: "2";
     command: Command;
     kind: "failure";
     variant: Variant;
@@ -22,7 +22,7 @@ export declare function createFailureEnvelope<Command extends string, Variant ex
 }>;
 export declare function createFailureWireSchema(command: string, variant: string, dataSchema: JsonObject): JsonObject;
 export declare function createStreamHeaderEnvelope<Command extends string>(command: Command): Readonly<{
-    schemaVersion: "1";
+    schemaVersion: "2";
     command: Command;
     kind: "stream";
 }>;
@@ -43,7 +43,7 @@ export interface UsageFailureWireScope {
     readonly helpArgv: readonly string[];
 }
 export declare function createUsageFailureEnvelope<Command extends string>(command: Command, issues: unknown, usage: string, helpArgv: readonly string[]): Readonly<{
-    schemaVersion: "1";
+    schemaVersion: "2";
     command: Command;
     kind: "usageFailure";
     issues: unknown;

package/node_modules/@ykdz/cli-contract/dist/outcome-wire.js

@@ -1,4 +1,4 @@
-const schemaVersion = "1";
+const schemaVersion = "2";
 export function createCompletionEnvelope(command) {
     return Object.freeze({
         schemaVersion,
@@ -94,10 +94,41 @@ function usageIssueSchemas() {
             type: "array",
         },
     }, ["message"]);
-    const constraintValue = objectSchema({
-        field: string,
-        value: { oneOf: [{ type: "boolean" }, string] },
-    }, ["field", "value"]);
+    const usageFact = {
+        oneOf: [
+            objectSchema({ field: string, kind: { const: "present" } }, [
+                "kind",
+                "field",
+            ]),
+            objectSchema({
+                field: string,
+                kind: { const: "equals" },
+                value: { oneOf: [{ type: "boolean" }, string] },
+            }, ["kind", "field", "value"]),
+        ],
+    };
+    const usageObservation = {
+        oneOf: [
+            objectSchema({
+                field: string,
+                kind: { const: "present" },
+                present: { type: "boolean" },
+            }, ["kind", "field", "present"]),
+            objectSchema({
+                expected: { oneOf: [{ type: "boolean" }, string] },
+                field: string,
+                kind: { const: "equals" },
+                present: { const: false },
+            }, ["kind", "field", "expected", "present"]),
+            objectSchema({
+                actual: { oneOf: [{ type: "boolean" }, string] },
+                expected: { oneOf: [{ type: "boolean" }, string] },
+                field: string,
+                kind: { const: "equals" },
+                present: { const: true },
+            }, ["kind", "field", "expected", "present", "actual"]),
+        ],
+    };
     const outputOccurrence = objectSchema({
         format: { enum: ["structured", "text"] },
         option: string,
@@ -112,14 +143,47 @@ function usageIssueSchemas() {
         issueSchema("conflictingOutputFormat", {
             occurrences: { items: outputOccurrence, minItems: 2, type: "array" },
         }),
-        issueSchema("exclusiveUsageConstraint", {
-            fields: { items: string, minItems: 2, type: "array" },
-        }),
-        issueSchema("forbiddenUsageCombination", {
-            values: { items: constraintValue, minItems: 2, type: "array" },
+        {
+            ...issueSchema("countConstraintViolation", {
+                min: { minimum: 0, type: "integer" },
+                max: { minimum: 0, type: "integer" },
+                presentFields: { items: string, type: "array" },
+                absentFields: { items: string, type: "array" },
+            }),
+            anyOf: [
+                { properties: { presentFields: { minItems: 1 } } },
+                { properties: { absentFields: { minItems: 1 } } },
+            ],
+        },
+        issueSchema("forbiddenCombinationViolation", {
+            facts: { items: usageFact, minItems: 1, type: "array" },
         }),
+        {
+            ...issueSchema("conditionalConstraintViolation", {
+                branch: { enum: ["onMatch", "otherwise"] },
+                conditions: {
+                    items: usageObservation,
+                    minItems: 1,
+                    type: "array",
+                },
+                missingRequiredFields: { items: string, type: "array" },
+                presentForbiddenFields: { items: string, type: "array" },
+            }),
+            anyOf: [
+                {
+                    properties: {
+                        missingRequiredFields: { minItems: 1 },
+                    },
+                },
+                {
+                    properties: {
+                        presentForbiddenFields: { minItems: 1 },
+                    },
+                },
+            ],
+        },
         issueSchema("inputRejected", {
-            evidence: { items: evidence, minItems: 1, type: "array" },
+            evidence: { items: evidence, type: "array" },
         }),
         issueSchema("invalidFieldChoice", {
             choices: { items: string, minItems: 1, type: "array" },
@@ -142,10 +206,6 @@ function usageIssueSchemas() {
             field: string,
             occurrences: occurrences(2),
         }),
-        issueSchema("requiredByUsageConstraint", {
-            field: string,
-            requires: string,
-        }),
         issueSchema("unexpectedOptionValue", {
             field: string,
             option: string,

package/node_modules/@ykdz/cli-contract/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ykdz/cli-contract",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Framework-agnostic, executable CLI contracts for Node.js.",
   "keywords": [
     "cli",
@@ -42,17 +42,18 @@
   },
   "dependencies": {
     "@standard-schema/spec": "^1.1.0",
-    "@types/node": "^24.13.4"
+    "@types/node": "^24.19.0"
   },
   "devDependencies": {
     "@cli-contract/typescript-config": "0.1.0",
     "@valibot/to-json-schema": "^1.7.1",
-    "oxfmt": "^0.67.0",
+    "ajv": "^8.20.0",
+    "oxfmt": "^0.71.0",
     "oxlint": "^1.82.0",
-    "oxlint-tsgolint": "^7.0.2001",
+    "oxlint-tsgolint": "^7.0.2003",
     "typescript-7": "npm:typescript@^7.0.2",
     "valibot": "^1.5.0",
-    "zod": "^4.5.4"
+    "zod": "^4.6.5"
   },
   "engines": {
     "node": ">=24"

package/node_modules/@ykdz/preset-rust-bin/native/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@ykdz/preset-rust-bin",
+  "version": "0.0.0",
+  "private": true,
+  "files": [
+    "template-dist"
+  ],
+  "type": "module",
+  "exports": {
+    "./reference": "./package.json",
+    "./template": {
+      "source": "./template/definition.ts",
+      "types": "./template-dist/definition.d.ts",
+      "default": "./template-dist/definition.js"
+    }
+  },
+  "scripts": {
+    "check:author-planning-roles": "pnpm --workspace-root run author-planning-roles:workspace -- --owner-directory \"$PWD\"",
+    "build": "pnpm run build:template",
+    "build:template": "rm -rf template-dist && tsc -p tsconfig.template.json --pretty false",
+    "format:check": "oxfmt --list-different .",
+    "format:write": "oxfmt --write .",
+    "lint": "oxlint --quiet --format=unix --ignore-pattern template-dist .",
+    "lint:fix": "oxlint --format=unix --ignore-pattern template-dist . --fix",
+    "test": "node --conditions=source --experimental-strip-types --test --test-concurrency=2 --test-timeout=60000 'test/**/*.light.test.ts'",
+    "test:integration": "node --conditions=source --experimental-strip-types --test --test-concurrency=1 --test-timeout=300000 'test/**/*.integration.test.ts'",
+    "typecheck": "tsc -p tsconfig.json --noEmit --pretty false"
+  },
+  "dependencies": {
+    "@ykdz/reference-rust-bin": "workspace:*",
+    "@ykdz/template-core": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/node": "catalog:",
+    "@ykdz/reference-tooling-config": "workspace:*",
+    "@ykdz/reference-ts-lib": "workspace:*",
+    "@ykdz/template-generator": "workspace:*",
+    "@ykdz/template-workspace": "workspace:*",
+    "@ykdz/template-workspace-authoring": "workspace:*",
+    "execa": "catalog:",
+    "oxfmt": "catalog:",
+    "oxlint": "catalog:",
+    "oxlint-tsgolint": "catalog:",
+    "typescript-7": "catalog:"
+  }
+}

package/node_modules/@ykdz/preset-rust-bin/native/template-dist/definition.d.ts

@@ -0,0 +1,43 @@
+export declare const preset: {
+    readonly kind: "preset";
+    readonly metadata: {
+        readonly alias: string;
+        readonly title: string;
+        readonly description: string;
+    };
+    readonly operations: readonly import("@ykdz/template-core/preset-definition").PresetOperation[];
+    readonly nodes: Readonly<Record<string, import("@ykdz/template-core/preset-definition").PresetNode<import("@ykdz/template-workspace/reference-package").ReferencePackage<import("@ykdz/template-core/workspace-strategy").PackageCreationInput, {
+        readonly cargoManifest: {
+            readonly source: string;
+            readonly data: import("smol-toml").TomlTable;
+        };
+        readonly cargoLock: {
+            readonly source: string;
+            readonly data: import("smol-toml").TomlTable;
+        };
+        readonly toolchainConfiguration: string;
+    }>, never, never>>>;
+} & {
+    readonly owner?: import("@ykdz/template-core/preset-definition").PresetOwnerDeclaration;
+    readonly validateUpdate?: never;
+    readonly project?: never;
+} & {
+    readonly nodes: {
+        readonly binary: {
+            reference: import("@ykdz/template-workspace/reference-package").ReferencePackage<import("@ykdz/template-core/workspace-strategy").PackageCreationInput, {
+                readonly cargoManifest: {
+                    readonly source: string;
+                    readonly data: import("smol-toml").TomlTable;
+                };
+                readonly cargoLock: {
+                    readonly source: string;
+                    readonly data: import("smol-toml").TomlTable;
+                };
+                readonly toolchainConfiguration: string;
+            }>;
+        };
+    };
+} & {
+    readonly prepareArtifact: () => import("@ykdz/template-workspace-authoring/content-artifact").PreparedNativeContentArtifact;
+};
+//# sourceMappingURL=definition.d.ts.map

package/node_modules/@ykdz/preset-rust-bin/native/template-dist/definition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"definition.d.ts","sourceRoot":"","sources":["../template/definition.ts"],"names":[],"mappings":"AASA,eAAO,MAAM,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;YAWH,SAAS;;;;;;;;;;;;;;;CASxB,CAAC"}

package/node_modules/@ykdz/preset-rust-bin/native/template-dist/definition.js

@@ -0,0 +1,21 @@
+import { referencePackage } from "@ykdz/reference-rust-bin/template";
+import { definePreset, presetOwnerFromManifest, } from "@ykdz/template-core/preset-definition";
+import { defineNativeContentArtifact } from "@ykdz/template-workspace-authoring/content-artifact";
+import presetPackage from "../package.json" with { type: "json" };
+export const preset = defineNativeContentArtifact(definePreset({
+    metadata: {
+        alias: "rust-bin",
+        title: "Rust 二进制程序",
+        description: "包含 rustfmt、clippy 和 cargo 测试的 Rust 原生二进制工作区。",
+    },
+    operations: ["init", "add"],
+    owner: presetOwnerFromManifest(presetPackage, "./template"),
+    nodes: {
+        binary: { reference: referencePackage },
+    },
+}), {
+    manifest: presetPackage,
+    resourceRoot: new URL("../", import.meta.url),
+    exportPath: "./template",
+    executionDependencies: ["@ykdz/template-workspace-authoring"],
+});