@ykdz/template 0.0.38 → 0.0.40

package/node_modules/@ykdz/cli-contract/dist/contract-schema-compiler.js

@@ -0,0 +1,532 @@
+import { isSingleLineText } from "#/description";
+import { copyJsonObject, deepFreeze } from "#/json-value";
+export function compileContractSchema(schema, target, issues, description) {
+    const initialIssueCount = issues.length;
+    const standard = schema?.["~standard"];
+    if (typeof standard !== "object" || standard === null) {
+        issues.push({
+            code: "missingSchemaCapability",
+            ...target,
+            capability: "standard",
+        });
+        return undefined;
+    }
+    if (typeof standard.validate !== "function") {
+        issues.push({
+            code: "missingSchemaCapability",
+            ...target,
+            capability: "validation",
+        });
+        return undefined;
+    }
+    if (typeof standard.jsonSchema !== "object" ||
+        standard.jsonSchema === null ||
+        typeof standard.jsonSchema.input !== "function" ||
+        typeof standard.jsonSchema.output !== "function") {
+        issues.push({
+            code: "missingSchemaCapability",
+            ...target,
+            capability: "jsonSchema",
+        });
+        return undefined;
+    }
+    const exportedInput = exportSchemaProjection(standard.jsonSchema.input, target, "input", issues);
+    const exportedOutput = exportSchemaProjection(standard.jsonSchema.output, target, "output", issues);
+    const copiedInputSchema = exportedInput === undefined
+        ? undefined
+        : copySchemaProjection(exportedInput, target, "input", issues);
+    const copiedOutputSchema = exportedOutput === undefined
+        ? undefined
+        : copySchemaProjection(exportedOutput, target, "output", issues);
+    const inputSchema = copiedInputSchema === undefined || description === undefined
+        ? copiedInputSchema
+        : projectRootDescription(copiedInputSchema, description);
+    const outputSchema = copiedOutputSchema === undefined || description === undefined
+        ? copiedOutputSchema
+        : projectRootDescription(copiedOutputSchema, description);
+    if (inputSchema === undefined || outputSchema === undefined) {
+        return undefined;
+    }
+    checkDraft202012(inputSchema, target, "input", issues);
+    checkDraft202012(outputSchema, target, "output", issues);
+    checkInputDefaults(inputSchema, outputSchema, target, issues);
+    return issues.length === initialIssueCount
+        ? { inputSchema, outputSchema }
+        : undefined;
+}
+export function projectFieldDescriptions(schema, fields) {
+    return deepFreeze({
+        inputSchema: projectPropertyDescriptions(schema.inputSchema, fields),
+        outputSchema: projectPropertyDescriptions(schema.outputSchema, fields),
+    });
+}
+export function compileInputFields(definitions, inputSchema, command, issues) {
+    collectFieldDescriptionIssues(definitions, command, issues);
+    if (inputSchema.type !== "object") {
+        issues.push({
+            code: "invalidInputSchemaShape",
+            command,
+            location: "input",
+            aspect: "type",
+        });
+        return [];
+    }
+    const schemaProperties = readSchemaProperties(inputSchema);
+    if (schemaProperties === undefined) {
+        issues.push({
+            code: "invalidInputSchemaShape",
+            command,
+            location: "input",
+            aspect: "properties",
+        });
+        return [];
+    }
+    // oxlint-disable-next-line unicorn/no-array-sort -- Object.keys 新建的数组只在此处使用，原地排序不会影响共享状态。
+    const schemaKeys = Object.keys(schemaProperties).sort();
+    // oxlint-disable-next-line unicorn/no-array-sort -- Object.keys 新建的数组只在此处使用，原地排序不会影响共享状态。
+    const fieldKeys = Object.keys(definitions).sort();
+    if (schemaKeys.join("\0") !== fieldKeys.join("\0")) {
+        issues.push({
+            code: "schemaFieldSetMismatch",
+            command,
+            location: "input",
+            missingFields: schemaKeys.filter((key) => !fieldKeys.includes(key)),
+            unexpectedFields: fieldKeys.filter((key) => !schemaKeys.includes(key)),
+        });
+        return [];
+    }
+    const required = readRequiredSchemaKeys(inputSchema);
+    if (required === undefined) {
+        issues.push({
+            code: "invalidInputSchemaShape",
+            command,
+            location: "input",
+            aspect: "required",
+        });
+        return [];
+    }
+    const incompatibleFields = fieldKeys.flatMap((field) => {
+        const kind = definitions[field]?.kind;
+        const expected = kind === "flag"
+            ? "boolean"
+            : kind === "repeatableOption" || kind === "variadicPositional"
+                ? "stringArray"
+                : "string";
+        return schemaPropertyAcceptsRawValue(schemaProperties[field], expected)
+            ? []
+            : [{ field, expected }];
+    });
+    if (incompatibleFields.length > 0) {
+        issues.push({
+            code: "schemaFieldDoesNotAcceptRawValue",
+            command,
+            location: "input",
+            fields: incompatibleFields,
+        });
+        return [];
+    }
+    const fields = Object.entries(definitions).map(([key, field]) => {
+        if (!/^[a-z][A-Za-z0-9]*$/.test(key)) {
+            issues.push({ code: "invalidFieldIdentity", command, field: key });
+        }
+        const invalidKind = readInvalidFieldKind(field);
+        if (invalidKind !== undefined) {
+            issues.push({
+                code: "invalidFieldKind",
+                command,
+                field: key,
+                expected: [
+                    "positional",
+                    "variadicPositional",
+                    "flag",
+                    "valueOption",
+                    "repeatableOption",
+                ],
+                received: invalidKind,
+            });
+            return {
+                kind: "positional",
+                key,
+                description: readFieldDescription(field),
+                required: required.has(key),
+            };
+        }
+        if (field.kind !== "positional" &&
+            field.kind !== "variadicPositional" &&
+            !/^--[a-z0-9]+(?:-[a-z0-9]+)*$/.test(field.longOption)) {
+            issues.push({
+                code: "invalidFieldLongOption",
+                command,
+                field: key,
+                received: typeof field.longOption === "string" ? field.longOption : null,
+            });
+        }
+        if (field.kind !== "positional" &&
+            field.kind !== "variadicPositional" &&
+            field.shortAlias !== undefined &&
+            !/^-[A-Za-z0-9]$/.test(field.shortAlias)) {
+            issues.push({
+                code: "invalidFieldShortAlias",
+                command,
+                field: key,
+                received: typeof field.shortAlias === "string" ? field.shortAlias : null,
+            });
+        }
+        if (field.kind === "flag" &&
+            field.negatedLongOption !== undefined &&
+            !/^--[a-z0-9]+(?:-[a-z0-9]+)*$/.test(field.negatedLongOption)) {
+            issues.push({
+                code: "invalidFieldLongOption",
+                command,
+                field: key,
+                received: typeof field.negatedLongOption === "string"
+                    ? field.negatedLongOption
+                    : null,
+            });
+        }
+        // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- 字段 kind 与拼写已按声明检查，展开后保留对应联合成员。
+        return {
+            ...field,
+            key,
+            required: required.has(key),
+            ...readSchemaDefault(schemaProperties[key]),
+            ...readFieldChoices(schemaProperties[key], field.kind),
+        };
+    });
+    const fieldsByLongOption = new Map();
+    for (const field of fields) {
+        if (field.kind === "positional" || field.kind === "variadicPositional") {
+            continue;
+        }
+        for (const spelling of [
+            field.longOption,
+            field.kind === "flag" ? field.negatedLongOption : undefined,
+        ]) {
+            if (spelling === undefined)
+                continue;
+            const matchingFields = fieldsByLongOption.get(spelling) ?? [];
+            matchingFields.push(field);
+            fieldsByLongOption.set(spelling, matchingFields);
+        }
+    }
+    for (const [longOption, matchingFields] of fieldsByLongOption) {
+        if (matchingFields.length > 1) {
+            issues.push({
+                code: "duplicateFieldLongOption",
+                command,
+                longOption,
+                // oxlint-disable-next-line unicorn/no-array-sort -- 集合展开后是新数组，原地排序不修改源字段。
+                fields: [...new Set(matchingFields.map((field) => field.key))].sort(),
+            });
+        }
+    }
+    const fieldsByShortAlias = new Map();
+    for (const field of fields) {
+        if (field.kind === "positional" ||
+            field.kind === "variadicPositional" ||
+            field.shortAlias === undefined) {
+            continue;
+        }
+        const matchingFields = fieldsByShortAlias.get(field.shortAlias) ?? [];
+        matchingFields.push(field);
+        fieldsByShortAlias.set(field.shortAlias, matchingFields);
+    }
+    for (const [spelling, matchingFields] of fieldsByShortAlias) {
+        if (matchingFields.length > 1) {
+            issues.push({
+                code: "duplicateFieldOptionSpelling",
+                command,
+                spelling,
+                // oxlint-disable-next-line unicorn/no-array-sort -- map 新建的数组只用于本条问题，原地排序不修改源字段。
+                fields: matchingFields.map((field) => field.key).sort(),
+            });
+        }
+    }
+    let precedingOptionalField;
+    let variadicField;
+    for (const field of fields) {
+        if (field.kind !== "positional" && field.kind !== "variadicPositional") {
+            continue;
+        }
+        if (variadicField !== undefined) {
+            issues.push({
+                code: "positionalAfterVariadic",
+                command,
+                field: field.key,
+                variadicField,
+            });
+        }
+        if (field.kind === "variadicPositional")
+            variadicField ??= field.key;
+        if (!field.required) {
+            precedingOptionalField ??= field.key;
+        }
+        else if (precedingOptionalField !== undefined) {
+            issues.push({
+                code: "requiredPositionalAfterOptional",
+                command,
+                field: field.key,
+                precedingOptionalField,
+            });
+        }
+    }
+    return deepFreeze(fields);
+}
+function collectFieldDescriptionIssues(definitions, command, issues) {
+    for (const [field, definition] of Object.entries(definitions)) {
+        const description = readRawFieldDescription(definition);
+        if (isSingleLineText(description))
+            continue;
+        issues.push({
+            code: "invalidDescription",
+            command,
+            location: "field",
+            field,
+            received: typeof description === "string" ? description : null,
+        });
+    }
+}
+function projectRootDescription(schema, description) {
+    return deepFreeze({ ...schema, description });
+}
+function projectPropertyDescriptions(schema, fields) {
+    const properties = readSchemaProperties(schema);
+    if (properties === undefined)
+        return schema;
+    // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- 来源是已复制的 JSON Schema 属性，替换值仍是 JSON 值。
+    const projectedProperties = Object.fromEntries(Object.entries(properties).map(([key, property]) => {
+        const field = fields.find((candidate) => candidate.key === key);
+        if (field === undefined)
+            return [key, property];
+        if (property === true)
+            return [key, { description: field.description }];
+        if (typeof property !== "object" ||
+            property === null ||
+            Array.isArray(property)) {
+            return [key, property];
+        }
+        return [
+            key,
+            Object.assign({}, property, { description: field.description }),
+        ];
+    }));
+    return deepFreeze({ ...schema, properties: projectedProperties });
+}
+function readInvalidFieldKind(field) {
+    if (typeof field !== "object" || field === null || !("kind" in field)) {
+        return null;
+    }
+    const kind = field.kind;
+    return kind === "positional" ||
+        kind === "variadicPositional" ||
+        kind === "flag" ||
+        kind === "valueOption" ||
+        kind === "repeatableOption"
+        ? undefined
+        : typeof kind === "string"
+            ? kind
+            : null;
+}
+function readFieldDescription(field) {
+    return typeof field === "object" &&
+        field !== null &&
+        "description" in field &&
+        typeof field.description === "string"
+        ? field.description
+        : "";
+}
+function readRawFieldDescription(field) {
+    return typeof field === "object" && field !== null && "description" in field
+        ? field.description
+        : undefined;
+}
+function copySchemaProjection(value, target, projection, issues) {
+    try {
+        return copyJsonObject(value);
+    }
+    catch {
+        issues.push({ code: "invalidSchemaProjection", ...target, projection });
+        return undefined;
+    }
+}
+function exportSchemaProjection(exporter, target, projection, issues) {
+    try {
+        return exporter({ target: "draft-2020-12" });
+    }
+    catch {
+        issues.push({ code: "schemaExportFailed", ...target, projection });
+        return undefined;
+    }
+}
+function checkDraft202012(schema, target, projection, issues) {
+    const dialect = schema.$schema;
+    if (dialect !== "https://json-schema.org/draft/2020-12/schema") {
+        issues.push({
+            code: "schemaDialectMismatch",
+            ...target,
+            projection,
+            received: typeof dialect === "string" ? dialect : null,
+        });
+    }
+}
+function checkInputDefaults(inputSchema, outputSchema, target, issues) {
+    if (target.location !== "input")
+        return;
+    const inputProperties = readSchemaProperties(inputSchema);
+    const inputRequired = readRequiredSchemaKeys(inputSchema);
+    const outputPropertiesValid = checkOutputSchemaProperties(outputSchema, target, issues);
+    const outputRequired = readOutputRequiredSchemaKeys(outputSchema, target, issues);
+    if (inputProperties === undefined ||
+        inputRequired === undefined ||
+        !outputPropertiesValid ||
+        outputRequired === undefined) {
+        return;
+    }
+    for (const field of outputRequired) {
+        if (!Object.hasOwn(inputProperties, field)) {
+            issues.push({
+                code: "outputRequiredFieldMissingFromInput",
+                command: target.command,
+                location: "input",
+                field,
+            });
+            continue;
+        }
+        if (inputRequired.has(field)) {
+            continue;
+        }
+        if (readSchemaDefault(inputProperties[field]) === undefined) {
+            issues.push({
+                code: "missingInputDefault",
+                command: target.command,
+                location: "input",
+                field,
+            });
+        }
+    }
+}
+function checkOutputSchemaProperties(schema, target, issues) {
+    const properties = schema.properties;
+    if (properties === undefined)
+        return true;
+    if (typeof properties !== "object" ||
+        properties === null ||
+        Array.isArray(properties)) {
+        issues.push({
+            code: "invalidOutputSchemaShape",
+            command: target.command,
+            location: "input",
+            aspect: "properties",
+        });
+        return false;
+    }
+    return true;
+}
+function readOutputRequiredSchemaKeys(schema, target, issues) {
+    const required = schema.required;
+    if (required === undefined)
+        return new Set();
+    if (!Array.isArray(required) ||
+        required.some((key) => typeof key !== "string")) {
+        issues.push({
+            code: "invalidOutputSchemaShape",
+            command: target.command,
+            location: "input",
+            aspect: "required",
+        });
+        return undefined;
+    }
+    return new Set(required);
+}
+function readSchemaProperties(schema) {
+    const properties = schema.properties;
+    if (typeof properties !== "object" ||
+        properties === null ||
+        Array.isArray(properties)) {
+        return undefined;
+    }
+    // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- 已在上方排除 null 和数组；TS 对只读数组联合仍需收窄。
+    return properties;
+}
+function readSchemaDefault(propertySchema) {
+    if (typeof propertySchema !== "object" ||
+        propertySchema === null ||
+        Array.isArray(propertySchema) ||
+        !Object.hasOwn(propertySchema, "default")) {
+        return undefined;
+    }
+    // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- 模式投影在进入本函数前已复制并验证为 JSON 值。
+    const defaultValue = propertySchema.default;
+    if (defaultValue === undefined)
+        return undefined;
+    return {
+        default: defaultValue,
+    };
+}
+function readFieldChoices(propertySchema, kind) {
+    const candidate = kind === "repeatableOption" || kind === "variadicPositional"
+        ? readDirectSchemaItems(propertySchema)
+        : propertySchema;
+    const values = readDirectStringEnum(candidate);
+    if (values === undefined) {
+        return undefined;
+    }
+    return { choices: values };
+}
+function readDirectSchemaItems(propertySchema) {
+    if (typeof propertySchema !== "object" ||
+        propertySchema === null ||
+        Array.isArray(propertySchema) ||
+        !Object.hasOwn(propertySchema, "items") ||
+        !("items" in propertySchema)) {
+        return undefined;
+    }
+    return propertySchema.items;
+}
+function readDirectStringEnum(schema) {
+    if (typeof schema !== "object" || schema === null || Array.isArray(schema)) {
+        return undefined;
+    }
+    if (["anyOf", "oneOf", "$ref", "if", "then", "else"].some((keyword) => Object.hasOwn(schema, keyword))) {
+        return undefined;
+    }
+    const values = "enum" in schema ? schema.enum : undefined;
+    if (!Array.isArray(values) ||
+        values.length === 0 ||
+        values.some((value) => typeof value !== "string")) {
+        return undefined;
+    }
+    return Object.freeze([...values]);
+}
+function readRequiredSchemaKeys(schema) {
+    const required = schema.required;
+    if (required === undefined) {
+        return new Set();
+    }
+    if (!Array.isArray(required) ||
+        required.some((key) => typeof key !== "string")) {
+        return undefined;
+    }
+    return new Set(required);
+}
+function schemaPropertyAcceptsRawValue(propertySchema, rawType) {
+    if (propertySchema === true) {
+        return true;
+    }
+    if (typeof propertySchema !== "object" ||
+        propertySchema === null ||
+        Array.isArray(propertySchema) ||
+        !("type" in propertySchema)) {
+        return false;
+    }
+    if (rawType === "stringArray") {
+        return ((propertySchema.type === "array" ||
+            (Array.isArray(propertySchema.type) &&
+                propertySchema.type.includes("array"))) &&
+            "items" in propertySchema &&
+            schemaPropertyAcceptsRawValue(propertySchema.items, "string"));
+    }
+    return (propertySchema.type === rawType ||
+        (Array.isArray(propertySchema.type) &&
+            propertySchema.type.includes(rawType)));
+}

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

@@ -0,0 +1,14 @@
+import type { StandardJSONSchemaV1, StandardSchemaV1 } from "@standard-schema/spec";
+export type JsonPrimitive = boolean | null | number | string;
+export type JsonValue = JsonPrimitive | readonly JsonValue[] | {
+    readonly [key: string]: JsonValue;
+};
+export type JsonObject = {
+    readonly [key: string]: JsonValue;
+};
+export interface ContractSchema<Input = unknown, Output = Input> {
+    readonly "~standard": StandardSchemaV1.Props<Input, Output> & StandardJSONSchemaV1.Props<Input, Output>;
+}
+export type ContractSchemaInput<Schema> = Schema extends ContractSchema<infer Input, unknown> ? Input : never;
+export type ContractSchemaOutput<Schema> = Schema extends ContractSchema<unknown, infer Output> ? Output : never;
+export type EmptyCliInput = Readonly<Record<string, never>>;

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,2 @@
+export declare function isSingleLineText(value: unknown): value is string;
+export declare function copySingleLineText(value: unknown, label: string): string;

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

@@ -0,0 +1,13 @@
+export function isSingleLineText(value) {
+    return (typeof value === "string" &&
+        value.length > 0 &&
+        !value.includes("\r") &&
+        !value.includes("\n") &&
+        !value.includes("\0"));
+}
+export function copySingleLineText(value, label) {
+    if (!isSingleLineText(value)) {
+        throw new TypeError(`${label}必须是合法单行文本`);
+    }
+    return value;
+}

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

@@ -0,0 +1,8 @@
+/** 完整示例：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";
+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 { 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

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

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

@@ -0,0 +1,4 @@
+import type { JsonObject, JsonValue } from "#/contract-schema";
+export declare function copyJsonObject(value: Record<string, unknown>): JsonObject;
+export declare function copyJsonValue(value: unknown): JsonValue;
+export declare function deepFreeze<const Value>(value: Value): Readonly<Value>;

package/node_modules/@ykdz/cli-contract/dist/json-value.js

@@ -0,0 +1,64 @@
+export function copyJsonObject(value) {
+    const copy = copyJsonValue(value);
+    if (typeof copy !== "object" || copy === null || Array.isArray(copy)) {
+        throw new TypeError("invalidJsonSchemaObject");
+    }
+    // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- 上方已排除 null 和数组，复制结果只能是 JSON object。
+    return copy;
+}
+export function copyJsonValue(value) {
+    return copyJsonValueWithAncestors(value, new WeakSet());
+}
+export function deepFreeze(value) {
+    if (typeof value !== "object" || value === null || Object.isFrozen(value)) {
+        return value;
+    }
+    for (const item of Object.values(value)) {
+        deepFreeze(item);
+    }
+    return Object.freeze(value);
+}
+function copyJsonValueWithAncestors(value, ancestors) {
+    if (value === null ||
+        typeof value === "boolean" ||
+        typeof value === "string") {
+        return value;
+    }
+    if (typeof value === "number") {
+        if (!Number.isFinite(value)) {
+            throw new TypeError("nonFiniteJsonNumber");
+        }
+        return value;
+    }
+    if (typeof value !== "object") {
+        throw new TypeError("nonJsonValue");
+    }
+    if (ancestors.has(value)) {
+        throw new TypeError("cyclicJsonValue");
+    }
+    if (!Array.isArray(value) &&
+        Object.getPrototypeOf(value) !== Object.prototype &&
+        Object.getPrototypeOf(value) !== null) {
+        throw new TypeError("invalidJsonObject");
+    }
+    if (Object.getOwnPropertySymbols(value).length > 0) {
+        throw new TypeError("symbolKeyInJsonObject");
+    }
+    ancestors.add(value);
+    const copy = Array.isArray(value)
+        ? copyJsonArray(value, ancestors)
+        : Object.fromEntries(Object.entries(value).map(([key, item]) => [
+            key,
+            copyJsonValueWithAncestors(item, ancestors),
+        ]));
+    ancestors.delete(value);
+    return deepFreeze(copy);
+}
+function copyJsonArray(value, ancestors) {
+    return Array.from({ length: value.length }, (_, index) => {
+        if (!(index in value)) {
+            throw new TypeError("sparseJsonArray");
+        }
+        return copyJsonValueWithAncestors(value[index], ancestors);
+    });
+}

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

@@ -0,0 +1,21 @@
+/** 完整示例：https://github.com/YKDZ/cli-contract/tree/v0.2.1/packages/example */
+/// <reference types="node" preserve="true" />
+import type { Writable } from "node:stream";
+import type { WriteCliOutput } from "#/cli-execution";
+export interface NodeCliOutputOptions {
+    readonly stdout: Writable;
+    readonly stderr: Writable;
+}
+/**
+ * 将调用方提供的 Writable 接到核心输出端口，按核心选择的 stdout/stderr 路由写入。
+ * 每次写入等待 callback；write 返回 false 时还等待 drain，以承接执行内核的顺序与背压。
+ *
+ * 适配器不读取全局 process，也不关闭流、设置退出状态或接管 CLI 框架生命周期。
+ * 宿主应等待 executeCli 完成，再处理退出；写入异常交回调用方，不自动忽略 EPIPE。
+ */
+export declare function nodeCliOutput({ stdout, stderr, }: NodeCliOutputOptions): WriteCliOutput;
+/**
+ * 检查错误对象及其 cause 链是否携带 EPIPE，可用于识别 CliWriteError 保留的断管原因。
+ * 这里只检测断管，不吞掉异常、恢复写入或决定进程退出码；其他异常仍由宿主处理。
+ */
+export declare function isNodeBrokenPipe(error: unknown): boolean;