@actiondock/core 2.5.1 → 2.7.0

package/dist/input/flat-materializer.js

@@ -0,0 +1,179 @@
+import { inputPathConflict, flatInputLimitExceeded, invalidFlatArgument, } from "./flat-errors.js";
+import { isForbiddenActionInputPropertyName } from "./flat-predicates.js";
+import { DEFAULT_MAX_MATERIALIZED_SIZE_BYTES } from "./flat-parser.js";
+import { validateJsonValue } from "../json/value-validator.js";
+/**
+ * 节点状态枚举（四态节点模型）。
+ */
+export const NodeState = {
+    UNSET: "UNSET",
+    OBJECT: "OBJECT",
+    ARRAY: "ARRAY",
+    VALUE: "VALUE",
+};
+function createNode(pathStr, state = NodeState.UNSET) {
+    return {
+        state,
+        pathStr,
+        objectChildren: Object.create(null),
+        arrayChildren: new Map(),
+        value: undefined,
+    };
+}
+function materializeNode(node) {
+    switch (node.state) {
+        case NodeState.VALUE:
+            return node.value;
+        case NodeState.OBJECT: {
+            const result = {};
+            const keys = Object.keys(node.objectChildren).sort();
+            for (const key of keys) {
+                result[key] = materializeNode(node.objectChildren[key]);
+            }
+            return result;
+        }
+        case NodeState.ARRAY: {
+            const count = node.arrayChildren.size;
+            if (count === 0) {
+                return [];
+            }
+            const result = [];
+            for (let i = 0; i < count; i++) {
+                const child = node.arrayChildren.get(i);
+                if (!child) {
+                    throw inputPathConflict(`Sparse array detected at "${node.pathStr}": missing index ${i}`, { path: node.pathStr, missingIndex: i, reason: "SPARSE_ARRAY" });
+                }
+                result.push(materializeNode(child));
+            }
+            return result;
+        }
+        case NodeState.UNSET:
+        default:
+            throw inputPathConflict(`Incomplete intermediate node at "${node.pathStr}"`, { path: node.pathStr, reason: "INCOMPLETE_CONTAINER" });
+    }
+}
+/**
+ * 将扁平赋值表达式列表物化为标准 JSON 值对象。
+ *
+ * 安全规范：
+ * - 错误信息与 details 中严禁回显原始 raw、rawValue 或完整 token，仅保留 path、operator、valueLength。
+ *
+ * @param assignments 扁平赋值表达式列表
+ * @param options 物化配置选项
+ * @returns 物化后的 JSON 对象
+ */
+export function materializeFlatInput(assignments, options) {
+    const root = createNode("", NodeState.OBJECT);
+    for (const assignment of assignments) {
+        const { path, value, operator, rawValue } = assignment;
+        const valueLength = Buffer.byteLength(rawValue, "utf8");
+        if (path.length === 0) {
+            throw inputPathConflict(`Cannot assign value directly to root object`, { operator, valueLength, reason: "LEAF_CONTAINER_CONFLICT" });
+        }
+        let current = root;
+        for (let i = 0; i < path.length; i++) {
+            const seg = path[i];
+            const isLast = i === path.length - 1;
+            const currentPathStr = path.slice(0, i + 1).join(".");
+            if (typeof seg === "string") {
+                if (isForbiddenActionInputPropertyName(seg)) {
+                    throw invalidFlatArgument(`Forbidden property "${seg}" in path: "${currentPathStr}"`, { path: currentPathStr, segment: seg, reason: "FORBIDDEN_PROPERTY" });
+                }
+                if (current.state !== NodeState.OBJECT) {
+                    throw inputPathConflict(`Path conflict at "${current.pathStr}": expected object container but found ${current.state.toLowerCase()}`, { path: currentPathStr, operator, valueLength, reason: "OBJECT_ARRAY_CONFLICT" });
+                }
+                let child = Object.hasOwn(current.objectChildren, seg)
+                    ? current.objectChildren[seg]
+                    : undefined;
+                if (!child) {
+                    child = createNode(currentPathStr);
+                    current.objectChildren[seg] = child;
+                }
+                if (isLast) {
+                    if (child.state === NodeState.UNSET) {
+                        child.state = NodeState.VALUE;
+                        child.value = value;
+                    }
+                    else if (child.state === NodeState.VALUE) {
+                        throw inputPathConflict(`Duplicate assignment to leaf path "${currentPathStr}"`, { path: currentPathStr, operator, valueLength, reason: "DUPLICATE_ASSIGNMENT" });
+                    }
+                    else {
+                        throw inputPathConflict(`Path conflict at "${currentPathStr}": cannot assign value to existing container (${child.state.toLowerCase()})`, { path: currentPathStr, operator, valueLength, reason: "LEAF_CONTAINER_CONFLICT" });
+                    }
+                }
+                else {
+                    const nextSeg = path[i + 1];
+                    const nextExpectedState = typeof nextSeg === "number" ? NodeState.ARRAY : NodeState.OBJECT;
+                    if (child.state === NodeState.UNSET) {
+                        child.state = nextExpectedState;
+                    }
+                    else if (child.state === NodeState.VALUE) {
+                        throw inputPathConflict(`Path conflict at "${currentPathStr}": cannot access property "${nextSeg}" on existing value`, { path: currentPathStr, operator, valueLength, reason: "LEAF_CONTAINER_CONFLICT" });
+                    }
+                    else if (child.state !== nextExpectedState) {
+                        throw inputPathConflict(`Path conflict at "${currentPathStr}": expected ${nextExpectedState.toLowerCase()} but found ${child.state.toLowerCase()}`, { path: currentPathStr, operator, valueLength, reason: "OBJECT_ARRAY_CONFLICT" });
+                    }
+                    current = child;
+                }
+            }
+            else {
+                // seg is a number
+                if (current.state !== NodeState.ARRAY) {
+                    throw inputPathConflict(`Path conflict at "${current.pathStr || "root"}": expected array container but found ${current.state.toLowerCase()}`, {
+                        path: currentPathStr,
+                        operator,
+                        valueLength,
+                        reason: current.pathStr === "" ? "ROOT_INDEX_NOT_ALLOWED" : "OBJECT_ARRAY_CONFLICT",
+                    });
+                }
+                let child = current.arrayChildren.get(seg);
+                if (!child) {
+                    child = createNode(currentPathStr);
+                    current.arrayChildren.set(seg, child);
+                }
+                if (isLast) {
+                    if (child.state === NodeState.UNSET) {
+                        child.state = NodeState.VALUE;
+                        child.value = value;
+                    }
+                    else if (child.state === NodeState.VALUE) {
+                        throw inputPathConflict(`Duplicate assignment to leaf path "${currentPathStr}"`, { path: currentPathStr, operator, valueLength, reason: "DUPLICATE_ASSIGNMENT" });
+                    }
+                    else {
+                        throw inputPathConflict(`Path conflict at "${currentPathStr}": cannot assign value to existing container (${child.state.toLowerCase()})`, { path: currentPathStr, operator, valueLength, reason: "LEAF_CONTAINER_CONFLICT" });
+                    }
+                }
+                else {
+                    const nextSeg = path[i + 1];
+                    const nextExpectedState = typeof nextSeg === "number" ? NodeState.ARRAY : NodeState.OBJECT;
+                    if (child.state === NodeState.UNSET) {
+                        child.state = nextExpectedState;
+                    }
+                    else if (child.state === NodeState.VALUE) {
+                        throw inputPathConflict(`Path conflict at "${currentPathStr}": cannot access index/property "${nextSeg}" on existing value`, { path: currentPathStr, operator, valueLength, reason: "LEAF_CONTAINER_CONFLICT" });
+                    }
+                    else if (child.state !== nextExpectedState) {
+                        throw inputPathConflict(`Path conflict at "${currentPathStr}": expected ${nextExpectedState.toLowerCase()} but found ${child.state.toLowerCase()}`, { path: currentPathStr, operator, valueLength, reason: "OBJECT_ARRAY_CONFLICT" });
+                    }
+                    current = child;
+                }
+            }
+        }
+    }
+    const result = materializeNode(root);
+    const check = validateJsonValue(result);
+    if (!check.valid) {
+        throw flatInputLimitExceeded(`Materialized input validation failed: ${check.reason}`, {
+            reason: check.code === "MAX_JSON_DEPTH"
+                ? "MAX_MATERIALIZED_JSON_DEPTH"
+                : "INVALID_JSON_VALUE",
+        });
+    }
+    const maxMaterializedSizeBytes = options?.maxMaterializedSizeBytes ?? DEFAULT_MAX_MATERIALIZED_SIZE_BYTES;
+    const serialized = JSON.stringify(result);
+    const byteLength = Buffer.byteLength(serialized, "utf8");
+    if (byteLength > maxMaterializedSizeBytes) {
+        throw flatInputLimitExceeded(`Materialized input size (${byteLength} bytes) exceeds limit (${maxMaterializedSizeBytes} bytes)`, { byteLength, maxMaterializedSizeBytes, reason: "MAX_MATERIALIZED_BYTES" });
+    }
+    return result;
+}

package/dist/input/flat-parser.d.ts

@@ -0,0 +1,50 @@
+import type { JsonValue } from "@actiondock/sdk";
+/** 最大赋值表达式总数 */
+export declare const DEFAULT_MAX_ASSIGNMENTS = 1000;
+/** 最大路径段深度 */
+export declare const DEFAULT_MAX_PATH_DEPTH = 32;
+/** 原始路径字符串最大字节数 */
+export declare const DEFAULT_MAX_PATH_LENGTH = 1024;
+/** 单个属性名最大字节数 */
+export declare const DEFAULT_MAX_PROPERTY_KEY_LENGTH = 128;
+/** 原始值字符串最大字节数 (1 MiB) */
+export declare const DEFAULT_MAX_RAW_VALUE_LENGTH: number;
+/** JSON 字面量最大字节数 (1 MiB) */
+export declare const DEFAULT_MAX_JSON_LITERAL_LENGTH: number;
+/** 原始输入总字节数上限 (10 MiB) */
+export declare const DEFAULT_MAX_TOTAL_RAW_BYTES: number;
+/** 数组索引数值上限 */
+export declare const DEFAULT_MAX_ARRAY_INDEX = 10000;
+/** 物化后总大小字节上限 (10 MiB) */
+export declare const DEFAULT_MAX_MATERIALIZED_SIZE_BYTES: number;
+/**
+ * 扁平赋值表达式结构。
+ */
+export interface FlatAssignment {
+    raw: string;
+    path: Array<string | number>;
+    operator: "=" | ":=";
+    rawValue: string;
+    value: JsonValue;
+}
+/**
+ * 扁平解析器配置选项。
+ */
+export interface FlatParserOptions {
+    maxAssignments?: number;
+    maxPathDepth?: number;
+    maxPathLength?: number;
+    maxPropertyKeyLength?: number;
+    maxRawValueLength?: number;
+    maxJsonLiteralLength?: number;
+    maxArrayIndex?: number;
+    maxTotalRawBytes?: number;
+}
+/**
+ * 解析扁平赋值表达式列表。
+ *
+ * @param tokens 待解析的表达式字符串列表
+ * @param options 解析安全阈值配置选项
+ * @returns 解析后的结构化赋值列表
+ */
+export declare function parseFlatAssignments(tokens: string[], options?: FlatParserOptions): FlatAssignment[];

package/dist/input/flat-parser.js

@@ -0,0 +1,169 @@
+import { invalidFlatArgument, invalidJsonLiteral, flatInputLimitExceeded, } from "./flat-errors.js";
+import { isFlatPathPropertyName, isForbiddenActionInputPropertyName, } from "./flat-predicates.js";
+import { validateJsonValue } from "../json/value-validator.js";
+/** 最大赋值表达式总数 */
+export const DEFAULT_MAX_ASSIGNMENTS = 1000;
+/** 最大路径段深度 */
+export const DEFAULT_MAX_PATH_DEPTH = 32;
+/** 原始路径字符串最大字节数 */
+export const DEFAULT_MAX_PATH_LENGTH = 1024;
+/** 单个属性名最大字节数 */
+export const DEFAULT_MAX_PROPERTY_KEY_LENGTH = 128;
+/** 原始值字符串最大字节数 (1 MiB) */
+export const DEFAULT_MAX_RAW_VALUE_LENGTH = 1024 * 1024;
+/** JSON 字面量最大字节数 (1 MiB) */
+export const DEFAULT_MAX_JSON_LITERAL_LENGTH = 1024 * 1024;
+/** 原始输入总字节数上限 (10 MiB) */
+export const DEFAULT_MAX_TOTAL_RAW_BYTES = 10 * 1024 * 1024;
+/** 数组索引数值上限 */
+export const DEFAULT_MAX_ARRAY_INDEX = 10_000;
+/** 物化后总大小字节上限 (10 MiB) */
+export const DEFAULT_MAX_MATERIALIZED_SIZE_BYTES = 10 * 1024 * 1024;
+const ARRAY_INDEX_REGEX = /^(0|[1-9][0-9]*)$/;
+/**
+ * 解析单个扁平赋值表达式。
+ *
+ * 安全规范：
+ * - 错误信息与 details 中严禁回显未经脱敏的原始 rawValue 或 token，防止敏感凭据泄露至日志。
+ * - 资源限制统一使用 UTF-8 字节计算。
+ */
+function parseSingleFlatAssignment(token, options) {
+    const maxPathDepth = options?.maxPathDepth ?? DEFAULT_MAX_PATH_DEPTH;
+    const maxPathLength = options?.maxPathLength ?? DEFAULT_MAX_PATH_LENGTH;
+    const maxPropertyKeyLength = options?.maxPropertyKeyLength ?? DEFAULT_MAX_PROPERTY_KEY_LENGTH;
+    const maxRawValueLength = options?.maxRawValueLength ?? DEFAULT_MAX_RAW_VALUE_LENGTH;
+    const maxJsonLiteralLength = options?.maxJsonLiteralLength ?? DEFAULT_MAX_JSON_LITERAL_LENGTH;
+    const maxArrayIndex = options?.maxArrayIndex ?? DEFAULT_MAX_ARRAY_INDEX;
+    const colonEqIndex = token.indexOf(":=");
+    const eqIndex = token.indexOf("=");
+    let opIndex = -1;
+    let operator = "=";
+    if (colonEqIndex !== -1 && eqIndex !== -1) {
+        if (colonEqIndex < eqIndex) {
+            opIndex = colonEqIndex;
+            operator = ":=";
+        }
+        else {
+            opIndex = eqIndex;
+            operator = "=";
+        }
+    }
+    else if (colonEqIndex !== -1) {
+        opIndex = colonEqIndex;
+        operator = ":=";
+    }
+    else if (eqIndex !== -1) {
+        opIndex = eqIndex;
+        operator = "=";
+    }
+    else {
+        throw invalidFlatArgument(`Missing assignment operator in flat argument (length: ${token.length})`, { length: token.length, reason: "MISSING_OPERATOR" });
+    }
+    const rawPath = token.slice(0, opIndex);
+    const rawValue = token.slice(opIndex + operator.length);
+    const rawValueBytes = Buffer.byteLength(rawValue, "utf8");
+    if (rawPath.length === 0) {
+        throw invalidFlatArgument(`Empty path in flat assignment with operator '${operator}'`, { operator, valueLength: rawValueBytes, reason: "EMPTY_PATH" });
+    }
+    const pathByteLength = Buffer.byteLength(rawPath, "utf8");
+    if (pathByteLength > maxPathLength) {
+        throw flatInputLimitExceeded(`Path length (${pathByteLength} bytes) exceeds limit (${maxPathLength} bytes)`, { path: rawPath, length: pathByteLength, maxPathLength, reason: "MAX_PATH_BYTES" });
+    }
+    if (rawPath.startsWith(".") ||
+        rawPath.endsWith(".") ||
+        rawPath.includes("..")) {
+        throw invalidFlatArgument(`Invalid dot notation in path: "${rawPath}"`, { path: rawPath, reason: "INVALID_DOT_NOTATION" });
+    }
+    const rawSegments = rawPath.split(".");
+    if (rawSegments.length > maxPathDepth) {
+        throw flatInputLimitExceeded(`Path depth (${rawSegments.length}) exceeds limit (${maxPathDepth}) in path: "${rawPath}"`, { path: rawPath, depth: rawSegments.length, maxPathDepth, reason: "MAX_PATH_DEPTH" });
+    }
+    const path = [];
+    for (const seg of rawSegments) {
+        if (seg.length === 0) {
+            throw invalidFlatArgument(`Empty path segment in path: "${rawPath}"`, { path: rawPath, reason: "INVALID_SEGMENT" });
+        }
+        if (isForbiddenActionInputPropertyName(seg)) {
+            throw invalidFlatArgument(`Forbidden property "${seg}" in path: "${rawPath}"`, { path: rawPath, segment: seg, reason: "FORBIDDEN_PROPERTY" });
+        }
+        const segByteLength = Buffer.byteLength(seg, "utf8");
+        if (segByteLength > maxPropertyKeyLength) {
+            throw flatInputLimitExceeded(`Path segment length (${segByteLength} bytes) exceeds limit (${maxPropertyKeyLength} bytes) in path: "${rawPath}"`, { path: rawPath, segment: seg, length: segByteLength, maxPropertyKeyLength, reason: "MAX_PROPERTY_KEY_BYTES" });
+        }
+        if (ARRAY_INDEX_REGEX.test(seg)) {
+            const index = Number(seg);
+            if (index > maxArrayIndex) {
+                throw flatInputLimitExceeded(`Array index (${index}) exceeds limit (${maxArrayIndex}) in path: "${rawPath}"`, { path: rawPath, segment: seg, index, maxArrayIndex, reason: "MAX_ARRAY_INDEX" });
+            }
+            path.push(index);
+        }
+        else if (isFlatPathPropertyName(seg)) {
+            path.push(seg);
+        }
+        else {
+            throw invalidFlatArgument(`Invalid path segment "${seg}" in path: "${rawPath}"`, { path: rawPath, segment: seg, reason: "INVALID_SEGMENT" });
+        }
+    }
+    if (rawValueBytes > maxRawValueLength) {
+        throw flatInputLimitExceeded(`Raw value length (${rawValueBytes} bytes) exceeds limit (${maxRawValueLength} bytes) for path "${rawPath}"`, { path: rawPath, operator, valueLength: rawValueBytes, maxRawValueLength, reason: "MAX_RAW_VALUE_BYTES" });
+    }
+    let value;
+    if (operator === "=") {
+        value = rawValue;
+    }
+    else {
+        if (rawValueBytes > maxJsonLiteralLength) {
+            throw flatInputLimitExceeded(`JSON literal length (${rawValueBytes} bytes) exceeds limit (${maxJsonLiteralLength} bytes) for path "${rawPath}"`, { path: rawPath, operator: ":=", valueLength: rawValueBytes, maxJsonLiteralLength, reason: "MAX_JSON_LITERAL_BYTES" });
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(rawValue);
+        }
+        catch {
+            throw invalidJsonLiteral(`Failed to parse JSON literal for path "${rawPath}" (length: ${rawValueBytes} bytes)`, { path: rawPath, operator: ":=", valueLength: rawValueBytes, reason: "SYNTAX_ERROR" });
+        }
+        const check = validateJsonValue(parsed);
+        if (!check.valid) {
+            throw invalidJsonLiteral(`Invalid JSON literal for path "${rawPath}": ${check.reason}`, {
+                path: rawPath,
+                operator: ":=",
+                valueLength: rawValueBytes,
+                reason: check.code === "NON_FINITE_NUMBER"
+                    ? "NON_FINITE_NUMBER"
+                    : check.code === "MAX_JSON_DEPTH"
+                        ? "MAX_JSON_DEPTH"
+                        : "INVALID_JSON_VALUE",
+            });
+        }
+        value = parsed;
+    }
+    return {
+        raw: token,
+        path,
+        operator,
+        rawValue,
+        value,
+    };
+}
+/**
+ * 解析扁平赋值表达式列表。
+ *
+ * @param tokens 待解析的表达式字符串列表
+ * @param options 解析安全阈值配置选项
+ * @returns 解析后的结构化赋值列表
+ */
+export function parseFlatAssignments(tokens, options) {
+    const maxAssignments = options?.maxAssignments ?? DEFAULT_MAX_ASSIGNMENTS;
+    if (tokens.length > maxAssignments) {
+        throw flatInputLimitExceeded(`Total assignments (${tokens.length}) exceeds limit (${maxAssignments})`, { count: tokens.length, maxAssignments, reason: "MAX_ASSIGNMENTS" });
+    }
+    const maxTotalRawBytes = options?.maxTotalRawBytes ?? DEFAULT_MAX_TOTAL_RAW_BYTES;
+    let totalRawBytes = 0;
+    for (const token of tokens) {
+        totalRawBytes += Buffer.byteLength(token, "utf8");
+        if (totalRawBytes > maxTotalRawBytes) {
+            throw flatInputLimitExceeded(`Total raw input bytes (${totalRawBytes}) exceeds limit (${maxTotalRawBytes})`, { totalBytes: totalRawBytes, maxTotalRawBytes, reason: "MAX_TOTAL_RAW_BYTES" });
+        }
+    }
+    return tokens.map((token) => parseSingleFlatAssignment(token, options));
+}

package/dist/input/flat-predicates.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 属性名与路径谓词定义。
+ *
+ * 职责：
+ * - 提供扁平入参路径属性名与全局禁止属性名的校验谓词。
+ * - 作为输入解析器与编码顾问共享的属性安全判定单一事实源。
+ */
+/**
+ * 全局禁止的 Action 输入属性名只读列表。
+ */
+export declare const FORBIDDEN_ACTION_INPUT_PROPERTIES: readonly ["__proto__", "constructor", "prototype"];
+/**
+ * 校验属性名是否符合扁平路径段命名规范。
+ * 规范：必须以英文字母或下划线开头，仅包含英文字母、数字、下划线与中划线。
+ *
+ * @param key 待校验的属性名
+ * @returns 是否符合扁平路径段规范
+ */
+export declare function isFlatPathPropertyName(key: string): boolean;
+/**
+ * 判定属性名是否属于全局禁止的 Action 输入危险属性名。
+ * 禁止属性：__proto__、constructor、prototype。
+ *
+ * @param key 待判定的属性名
+ * @returns 是否属于禁止属性
+ */
+export declare function isForbiddenActionInputPropertyName(key: string): boolean;
+/**
+ * 判定属性名是否既符合扁平路径段规范且不属于禁止属性。
+ *
+ * @param key 待判定的属性名
+ * @returns 是否为扁平安全的属性名
+ */
+export declare function isFlatSafePropertyName(key: string): boolean;

package/dist/input/flat-predicates.js

@@ -0,0 +1,50 @@
+/**
+ * 属性名与路径谓词定义。
+ *
+ * 职责：
+ * - 提供扁平入参路径属性名与全局禁止属性名的校验谓词。
+ * - 作为输入解析器与编码顾问共享的属性安全判定单一事实源。
+ */
+const FLAT_PATH_PROPERTY_NAME_REGEX = /^[A-Za-z_][A-Za-z0-9_-]*$/;
+const FORBIDDEN_PROPERTY_SET = new Set([
+    "__proto__",
+    "constructor",
+    "prototype",
+]);
+/**
+ * 全局禁止的 Action 输入属性名只读列表。
+ */
+export const FORBIDDEN_ACTION_INPUT_PROPERTIES = Object.freeze([
+    "__proto__",
+    "constructor",
+    "prototype",
+]);
+/**
+ * 校验属性名是否符合扁平路径段命名规范。
+ * 规范：必须以英文字母或下划线开头，仅包含英文字母、数字、下划线与中划线。
+ *
+ * @param key 待校验的属性名
+ * @returns 是否符合扁平路径段规范
+ */
+export function isFlatPathPropertyName(key) {
+    return FLAT_PATH_PROPERTY_NAME_REGEX.test(key);
+}
+/**
+ * 判定属性名是否属于全局禁止的 Action 输入危险属性名。
+ * 禁止属性：__proto__、constructor、prototype。
+ *
+ * @param key 待判定的属性名
+ * @returns 是否属于禁止属性
+ */
+export function isForbiddenActionInputPropertyName(key) {
+    return FORBIDDEN_PROPERTY_SET.has(key);
+}
+/**
+ * 判定属性名是否既符合扁平路径段规范且不属于禁止属性。
+ *
+ * @param key 待判定的属性名
+ * @returns 是否为扁平安全的属性名
+ */
+export function isFlatSafePropertyName(key) {
+    return isFlatPathPropertyName(key) && !isForbiddenActionInputPropertyName(key);
+}

package/dist/input/index.d.ts

@@ -0,0 +1,14 @@
+export * from "./flat-errors.js";
+export * from "./flat-predicates.js";
+export * from "./validation-mapper.js";
+export * from "./flat-parser.js";
+export * from "./flat-materializer.js";
+export * from "./flat-decode.js";
+export * from "./json-depth-scanner.js";
+export * from "./utf8.js";
+export * from "./file-input.js";
+export * from "./stdin-input.js";
+export * from "./input-resolver.js";
+export * from "./advice.js";
+export * from "./metadata.js";
+export * from "./describe.js";

package/dist/input/index.js

@@ -0,0 +1,14 @@
+export * from "./flat-errors.js";
+export * from "./flat-predicates.js";
+export * from "./validation-mapper.js";
+export * from "./flat-parser.js";
+export * from "./flat-materializer.js";
+export * from "./flat-decode.js";
+export * from "./json-depth-scanner.js";
+export * from "./utf8.js";
+export * from "./file-input.js";
+export * from "./stdin-input.js";
+export * from "./input-resolver.js";
+export * from "./advice.js";
+export * from "./metadata.js";
+export * from "./describe.js";

package/dist/input/input-resolver.d.ts

@@ -0,0 +1,63 @@
+import type { JsonValue } from "@actiondock/sdk";
+import type { FlatParserOptions } from "./flat-parser.js";
+import type { FlatMaterializerOptions } from "./flat-materializer.js";
+export { stripBom } from "./utf8.js";
+/**
+ * 输入解析策略配置。
+ */
+export interface InputResolutionPolicy {
+    /** 最大允许输入字节数（默认 10MB） */
+    maxInputBytes?: number;
+    /** 最大允许 JSON 嵌套深度（默认 256） */
+    maxJsonDepth?: number;
+    /** 是否启用严格 UTF-8 校验（默认 true） */
+    strictUtf8?: boolean;
+    /** 是否对面向 Agent 的错误信息进行脱敏（默认 false） */
+    sanitizeInputErrors?: boolean;
+    /** 是否仅允许字节流输入（默认 false） */
+    byteStreamOnly?: boolean;
+}
+/**
+ * 从标准输入流中完整读取全部数据并转换为 UTF-8 字符串（保持历史接口兼容）。
+ *
+ * @param stream 标准输入可读流，默认为 process.stdin
+ */
+export declare function readStdin(stream?: NodeJS.ReadableStream): Promise<string>;
+/**
+ * Action 执行输入解析选项。
+ */
+export interface ResolveActionInputOptions {
+    input?: string;
+    inputFile?: string;
+    flatArgs?: string[];
+    stdin?: NodeJS.ReadableStream;
+    flatOptions?: FlatParserOptions & FlatMaterializerOptions;
+    policy?: InputResolutionPolicy;
+    signal?: AbortSignal;
+}
+/**
+ * 解析完整 JSON 文档字符串。
+ * 若解析失败抛出 INVALID_JSON 异常。
+ *
+ * @param text 待解析文本
+ * @param source 输入源描述（如 --input、文件路径或 stdin）
+ * @param policy 解析策略选项
+ */
+export declare function parseJson(text: string, source: string, policy?: InputResolutionPolicy): JsonValue;
+/**
+ * 统一解析 Action 执行入参。
+ *
+ * 输入模式仲裁规则（Input Mode Arbitration）：
+ * - effectiveFlat: flatArgs 存在且 length > 0
+ * - hasInlineJson: options.input !== undefined（即使为 ""）
+ * - hasFileJson: options.inputFile !== undefined（包含 "-"）
+ * - 最多一个为 true；若超过一个，抛出 INPUT_CONFLICT（reason: "MULTIPLE_INPUT_MODES"）。
+ * - 若三个均为 false，返回默认 {}。
+ * - flatArgs = [] 视为未指定。
+ * - options.input === "" 为显式 Full JSON 模式，进入解析并得到 INVALID_JSON / SYNTAX_ERROR，不可退化为 {}。
+ * - 显式空 JSON 输入（--input ""、0 字节文件、空 stdin、纯空白、纯 BOM）统一返回 INVALID_JSON / SYNTAX_ERROR。
+ *
+ * @param options 输入解析选项
+ * @returns 解析后的 JSON 对象
+ */
+export declare function resolveActionInput(options: ResolveActionInputOptions): Promise<JsonValue>;