@actiondock/core 2.5.1 → 2.7.0

package/dist/input/describe.d.ts

@@ -0,0 +1,106 @@
+import type { ActionSpec } from "../app/types.js";
+/**
+ * 字段级异常明细。
+ */
+export interface ActionDescribeIssue {
+    /** 字段路径 */
+    path: string;
+    /** 异常代码 */
+    code: string;
+}
+/**
+ * Action 输入模式建议契约。
+ */
+export interface ActionDescribeAdvice {
+    /** 建议契约版本号 */
+    version: 1;
+    /** 推荐的输入模式 */
+    recommendedMode: "flat" | "full-json" | "none";
+    /** 扁平入参赋值操作符字典（属性名 -> "=" 或 ":="） */
+    assignments?: Record<string, "=" | ":=">;
+    /** 推荐原因代码 */
+    reason?: string;
+    /** 字段级异常与警告清单 */
+    issues?: ActionDescribeIssue[];
+}
+/**
+ * 统一 Action 描述载荷契约。
+ */
+export interface ActionDescribePayload {
+    /** Action 唯一标识 */
+    id: string;
+    /** 所属包唯一标识 */
+    packageId?: string;
+    /** Action 描述信息 */
+    description?: string;
+    /** 输入模式规范 */
+    inputSchema?: unknown;
+    /** 输出模式规范 */
+    outputSchema?: unknown;
+    /** 标签列表 */
+    tags?: string[];
+    /** 协议注解元数据 */
+    annotations?: Record<string, unknown>;
+    /** 依赖的 Action 列表 */
+    uses?: string[];
+    /** 入口相对路径 */
+    entry?: string;
+    /** 统一输入模式建议 */
+    inputAdvice: ActionDescribeAdvice;
+}
+/**
+ * 构造 Action 描述载荷的可选选项。
+ */
+export interface BuildActionDescribePayloadOptions {
+    /** 所属包唯一标识（当 spec 中未携带时作为回退） */
+    packageId?: string;
+}
+/**
+ * 计算 Action 输入建议。
+ *
+ * @param schema Action 的 inputSchema 定义
+ * @returns 统一输入建议结构
+ */
+export declare function computeActionDescribeAdvice(schema: unknown): ActionDescribeAdvice;
+/**
+ * 构造统一 Action 描述载荷数据。
+ * 普通 CLI 与 Standalone 必须通过该函数生成统一数据。
+ *
+ * @param spec Action 规范信息
+ * @param options 可选配置选项
+ * @returns 统一 Action 描述载荷
+ */
+export declare function buildActionDescribePayload(spec: {
+    id: string;
+    packageId?: string;
+    description?: string;
+    inputSchema?: unknown;
+    outputSchema?: unknown;
+    tags?: string[];
+    annotations?: Record<string, unknown>;
+    uses?: string[];
+    entry?: string;
+    [key: string]: any;
+}, options?: BuildActionDescribePayloadOptions): ActionDescribePayload;
+/**
+ * 格式化渲染 Action 详情人类可读文本。
+ * 普通 CLI 与 Standalone 统一复用该函数，避免长期排版漂移。
+ *
+ * @param input Action 描述载荷或 Action 规范
+ * @returns 格式化后的说明文本
+ */
+export declare function formatActionDetail(input: ActionDescribePayload | (Partial<ActionSpec> & {
+    id: string;
+}) | {
+    id: string;
+    packageId?: string;
+    projectRoot?: string;
+    description?: string;
+    inputSchema?: unknown;
+    outputSchema?: unknown;
+    tags?: string[];
+    annotations?: Record<string, unknown>;
+    uses?: string[];
+    entry?: string;
+    [key: string]: any;
+}): string;

package/dist/input/describe.js

@@ -0,0 +1,176 @@
+import { buildCliInputAdviceV1 } from "./advice.js";
+import { isForbiddenActionInputPropertyName } from "./flat-predicates.js";
+/**
+ * 计算 Action 输入建议。
+ *
+ * @param schema Action 的 inputSchema 定义
+ * @returns 统一输入建议结构
+ */
+export function computeActionDescribeAdvice(schema) {
+    const v1Advice = buildCliInputAdviceV1(schema);
+    const issues = [];
+    for (const field of v1Advice.fields) {
+        if (field.reason) {
+            issues.push({ path: field.path, code: field.reason });
+        }
+    }
+    // 检查 required 列表中未被 fields 覆盖的禁止属性
+    if (typeof schema === "object" && schema !== null) {
+        const s = schema;
+        if (Array.isArray(s.required)) {
+            for (const reqKey of s.required) {
+                if (typeof reqKey === "string" && isForbiddenActionInputPropertyName(reqKey)) {
+                    if (!issues.some((i) => i.path === reqKey)) {
+                        issues.push({ path: reqKey, code: "FORBIDDEN_PROPERTY" });
+                    }
+                }
+            }
+        }
+    }
+    if (v1Advice.schemaRecommendedMode === "none") {
+        return {
+            version: 1,
+            recommendedMode: "none",
+            reason: v1Advice.feasibilityCode || "SCHEMA_REJECTS_ALL",
+            ...(issues.length > 0 ? { issues } : {}),
+        };
+    }
+    // 空对象模式判定：根模式为 object，无声明属性，且必填已满足（即无必填字段）
+    const isEmptyObjectSchema = v1Advice.schemaState === "object" &&
+        v1Advice.requiredSatisfiable === true &&
+        v1Advice.fields.length === 0;
+    if (v1Advice.schemaRecommendedMode === "flat" || isEmptyObjectSchema) {
+        const assignments = {};
+        for (const field of v1Advice.fields) {
+            if (field.flatSafe && field.operator) {
+                assignments[field.path] = field.operator;
+            }
+        }
+        return {
+            version: 1,
+            recommendedMode: "flat",
+            assignments,
+            ...(issues.length > 0 ? { issues } : {}),
+        };
+    }
+    // full-json 模式原因推导
+    let reason = "COMPLEX_SCHEMA";
+    if (v1Advice.analysisCode) {
+        reason = v1Advice.analysisCode;
+    }
+    else if (v1Advice.schemaState === "json-only") {
+        reason = "NON_OBJECT_SCHEMA";
+    }
+    else if (v1Advice.schemaState === "object") {
+        if (v1Advice.requiredSatisfiable === false) {
+            reason = "REQUIRED_FIELD_NOT_FLAT_SAFE";
+        }
+        else if (!v1Advice.flatAvailable) {
+            reason = "NO_FLAT_FIELDS";
+        }
+        else if (v1Advice.requiredSatisfiable === null) {
+            reason = "UNDECLARED_REQUIRED_FIELDS";
+        }
+    }
+    else if (v1Advice.schemaState === "absent") {
+        reason = "NO_SCHEMA";
+    }
+    else if (v1Advice.schemaState === "any") {
+        reason = "ARBITRARY_SCHEMA";
+    }
+    return {
+        version: 1,
+        recommendedMode: "full-json",
+        reason,
+        ...(issues.length > 0 ? { issues } : {}),
+    };
+}
+/**
+ * 构造统一 Action 描述载荷数据。
+ * 普通 CLI 与 Standalone 必须通过该函数生成统一数据。
+ *
+ * @param spec Action 规范信息
+ * @param options 可选配置选项
+ * @returns 统一 Action 描述载荷
+ */
+export function buildActionDescribePayload(spec, options) {
+    const packageId = spec.packageId ?? options?.packageId;
+    const payload = {
+        id: spec.id,
+        ...(packageId !== undefined ? { packageId } : {}),
+        ...(spec.description !== undefined ? { description: spec.description } : {}),
+        ...(spec.inputSchema !== undefined ? { inputSchema: spec.inputSchema } : {}),
+        ...(spec.outputSchema !== undefined ? { outputSchema: spec.outputSchema } : {}),
+        ...(spec.tags && spec.tags.length > 0 ? { tags: spec.tags } : {}),
+        ...(spec.annotations && Object.keys(spec.annotations).length > 0
+            ? { annotations: spec.annotations }
+            : {}),
+        ...(spec.uses && spec.uses.length > 0 ? { uses: spec.uses } : {}),
+        ...(spec.entry !== undefined ? { entry: spec.entry } : {}),
+        inputAdvice: computeActionDescribeAdvice(spec.inputSchema),
+    };
+    return payload;
+}
+/**
+ * 格式化渲染 Action 详情人类可读文本。
+ * 普通 CLI 与 Standalone 统一复用该函数，避免长期排版漂移。
+ *
+ * @param input Action 描述载荷或 Action 规范
+ * @returns 格式化后的说明文本
+ */
+export function formatActionDetail(input) {
+    const payload = "inputAdvice" in input && input.inputAdvice
+        ? input
+        : buildActionDescribePayload(input);
+    const lines = [];
+    lines.push(`Action: ${payload.id}`);
+    if (payload.packageId) {
+        lines.push(`Package: ${payload.packageId}`);
+    }
+    if (payload.description) {
+        lines.push(`Description: ${payload.description}`);
+    }
+    if (payload.tags && payload.tags.length > 0) {
+        lines.push(`Tags: ${payload.tags.join(", ")}`);
+    }
+    if (payload.uses && payload.uses.length > 0) {
+        lines.push(`Uses: ${payload.uses.join(", ")}`);
+    }
+    if (payload.entry) {
+        lines.push(`Entry: ${payload.entry}`);
+    }
+    if (payload.inputSchema !== undefined) {
+        lines.push("");
+        lines.push("Input Schema:");
+        lines.push(typeof payload.inputSchema === "string"
+            ? payload.inputSchema
+            : JSON.stringify(payload.inputSchema, null, 2));
+    }
+    if (payload.outputSchema !== undefined) {
+        lines.push("");
+        lines.push("Output Schema:");
+        lines.push(typeof payload.outputSchema === "string"
+            ? payload.outputSchema
+            : JSON.stringify(payload.outputSchema, null, 2));
+    }
+    lines.push("");
+    lines.push(`Recommended Input: ${payload.inputAdvice.recommendedMode}`);
+    if (payload.inputAdvice.reason) {
+        lines.push(`Reason: ${payload.inputAdvice.reason}`);
+    }
+    if (payload.inputAdvice.assignments && Object.keys(payload.inputAdvice.assignments).length > 0) {
+        lines.push("");
+        lines.push("Assignments:");
+        for (const [key, op] of Object.entries(payload.inputAdvice.assignments)) {
+            lines.push(`  ${key}${op}`);
+        }
+    }
+    if (payload.inputAdvice.issues && payload.inputAdvice.issues.length > 0) {
+        lines.push("");
+        lines.push("Issues:");
+        for (const issue of payload.inputAdvice.issues) {
+            lines.push(`  - ${issue.path}: ${issue.code}`);
+        }
+    }
+    return lines.join("\n");
+}

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

@@ -0,0 +1,54 @@
+import { type FileHandle } from "node:fs/promises";
+import type { Stats } from "node:fs";
+/** 默认最大输入字节数限制（10MB） */
+export declare const DEFAULT_MAX_INPUT_BYTES: number;
+/**
+ * 安全打开的常规文件描述句柄包装。
+ */
+export interface OpenedRegularFile {
+    /** 底层 Node.js 文件句柄 */
+    readonly handle: FileHandle;
+    /** 文件路径 */
+    readonly path: string;
+    /** 文件元信息 */
+    readonly stat: Stats;
+    /** 文件字节大小 */
+    readonly size: number;
+    /**
+     * 在指定字节上限约束下读取文件完整内容。
+     *
+     * @param maxInputBytes 最大允许读取字节数
+     * @param signal 可选的中断信号
+     * @returns 读取的文件内容 Buffer
+     */
+    readBounded(maxInputBytes: number, signal?: AbortSignal): Promise<Buffer>;
+    /**
+     * 关闭文件句柄，释放操作系统文件描述符。
+     */
+    close(): Promise<void>;
+}
+/**
+ * 安全打开常规输入文件。
+ *
+ * 安全契约：
+ * - 最终打开目标必须为 regular file（允许普通文件及指向普通文件的符号链接 symlink）。
+ * - 严厉拒绝目录、FIFO 管道、socket、字符设备与块设备等，抛出 INPUT_FILE_READ_FAILED（reason: "UNSUPPORTED_FILE_TYPE"）。
+ * - 完美支持 AbortSignal 取消。若信号在 open 完成前触发，执行逻辑取消；若 open 滞后成功，立即执行 handle.close() 关闭句柄，严防文件描述符泄漏。
+ * - 大小预检与有界读取：当文件大小超出 maxInputBytes 时抛出 INPUT_LIMIT_EXCEEDED（reason: "MAX_INPUT_BYTES"）。
+ *
+ * @param filePath 输入文件路径
+ * @param signal 可选的取消信号
+ * @returns 包装后的常规文件句柄对象
+ */
+export declare function openRegularInputFile(filePath: string, signal?: AbortSignal): Promise<OpenedRegularFile>;
+/**
+ * 以有界大小限制安全读取常规文件的全部内容并自动关闭句柄。
+ *
+ * @param filePath 输入文件路径
+ * @param options 读取配置选项
+ * @returns 文件的原始字节 Buffer
+ */
+export declare function readRegularFileBounded(filePath: string, options?: {
+    maxInputBytes?: number;
+    signal?: AbortSignal;
+}): Promise<Buffer>;

package/dist/input/file-input.js

@@ -0,0 +1,124 @@
+import { open } from "node:fs/promises";
+import { inputFileNotFound, inputFileReadFailed, inputLimitExceeded, } from "./flat-errors.js";
+/** 默认最大输入字节数限制（10MB） */
+export const DEFAULT_MAX_INPUT_BYTES = 10 * 1024 * 1024;
+/**
+ * 安全打开常规输入文件。
+ *
+ * 安全契约：
+ * - 最终打开目标必须为 regular file（允许普通文件及指向普通文件的符号链接 symlink）。
+ * - 严厉拒绝目录、FIFO 管道、socket、字符设备与块设备等，抛出 INPUT_FILE_READ_FAILED（reason: "UNSUPPORTED_FILE_TYPE"）。
+ * - 完美支持 AbortSignal 取消。若信号在 open 完成前触发，执行逻辑取消；若 open 滞后成功，立即执行 handle.close() 关闭句柄，严防文件描述符泄漏。
+ * - 大小预检与有界读取：当文件大小超出 maxInputBytes 时抛出 INPUT_LIMIT_EXCEEDED（reason: "MAX_INPUT_BYTES"）。
+ *
+ * @param filePath 输入文件路径
+ * @param signal 可选的取消信号
+ * @returns 包装后的常规文件句柄对象
+ */
+export async function openRegularInputFile(filePath, signal) {
+    if (signal?.aborted) {
+        throw signal.reason ?? new DOMException("The operation was aborted", "AbortError");
+    }
+    let handle;
+    let aborted = false;
+    const onAbort = () => {
+        aborted = true;
+        if (handle) {
+            handle.close().catch(() => { });
+        }
+    };
+    if (signal) {
+        signal.addEventListener("abort", onAbort, { once: true });
+    }
+    try {
+        try {
+            handle = await open(filePath, "r");
+        }
+        catch (err) {
+            if (err && err.code === "ENOENT") {
+                throw inputFileNotFound(filePath);
+            }
+            throw inputFileReadFailed(filePath, err);
+        }
+        // 若在 open 等待期间触发 abort，立即关闭滞后打开的句柄并中止
+        if (aborted || signal?.aborted) {
+            await handle.close().catch(() => { });
+            throw signal?.reason ?? new DOMException("The operation was aborted", "AbortError");
+        }
+        let stat;
+        try {
+            stat = await handle.stat();
+        }
+        catch (err) {
+            await handle.close().catch(() => { });
+            throw inputFileReadFailed(filePath, err);
+        }
+        if (aborted || signal?.aborted) {
+            await handle.close().catch(() => { });
+            throw signal?.reason ?? new DOMException("The operation was aborted", "AbortError");
+        }
+        // 严厉校验目标是否为常规文件（排除目录、FIFO、socket、设备等）
+        if (!stat.isFile()) {
+            await handle.close().catch(() => { });
+            throw inputFileReadFailed(filePath, new Error("Unsupported file type"), {
+                reason: "UNSUPPORTED_FILE_TYPE",
+            });
+        }
+        let isClosed = false;
+        const openedFile = {
+            handle,
+            path: filePath,
+            stat,
+            size: stat.size,
+            close: async () => {
+                if (!isClosed) {
+                    isClosed = true;
+                    await handle.close().catch(() => { });
+                }
+            },
+            readBounded: async (maxInputBytes, readSignal) => {
+                const effectiveSignal = readSignal ?? signal;
+                if (effectiveSignal?.aborted) {
+                    throw effectiveSignal.reason ?? new DOMException("The operation was aborted", "AbortError");
+                }
+                // 大小预检：若 stat.size 明确超过上限，直接拦截
+                if (stat.size > maxInputBytes) {
+                    throw inputLimitExceeded(`File size (${stat.size} bytes) exceeds limit of ${maxInputBytes} bytes`, { reason: "MAX_INPUT_BYTES" });
+                }
+                // 分配有界缓冲区（多读 1 字节以探测并发写入扩大的竞态）
+                const buffer = Buffer.alloc(Math.min(stat.size, maxInputBytes) + 1);
+                const { bytesRead } = await handle.read(buffer, 0, buffer.length, 0);
+                if (effectiveSignal?.aborted) {
+                    throw effectiveSignal.reason ?? new DOMException("The operation was aborted", "AbortError");
+                }
+                if (bytesRead > maxInputBytes) {
+                    throw inputLimitExceeded(`File read size (${bytesRead} bytes) exceeds limit of ${maxInputBytes} bytes`, { reason: "MAX_INPUT_BYTES" });
+                }
+                return buffer.subarray(0, bytesRead);
+            },
+        };
+        return openedFile;
+    }
+    finally {
+        if (signal) {
+            signal.removeEventListener("abort", onAbort);
+        }
+    }
+}
+/**
+ * 以有界大小限制安全读取常规文件的全部内容并自动关闭句柄。
+ *
+ * @param filePath 输入文件路径
+ * @param options 读取配置选项
+ * @returns 文件的原始字节 Buffer
+ */
+export async function readRegularFileBounded(filePath, options) {
+    const maxBytes = options?.maxInputBytes ?? DEFAULT_MAX_INPUT_BYTES;
+    const opened = await openRegularInputFile(filePath, options?.signal);
+    try {
+        return await opened.readBounded(maxBytes, options?.signal);
+    }
+    finally {
+        await opened.close();
+    }
+}

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

@@ -0,0 +1,11 @@
+import type { JsonValue } from "@actiondock/sdk";
+import { type FlatParserOptions } from "./flat-parser.js";
+import { type FlatMaterializerOptions } from "./flat-materializer.js";
+/**
+ * 将扁平入参字符串列表解码并物化为标准 JSON 值对象。
+ *
+ * @param tokens 扁平入参字符串列表
+ * @param options 解析与物化安全阈值选项
+ * @returns 物化后的 JSON 值对象
+ */
+export declare function decodeFlatInput(tokens: string[], options?: FlatParserOptions & FlatMaterializerOptions): JsonValue;

package/dist/input/flat-decode.js

@@ -0,0 +1,13 @@
+import { parseFlatAssignments } from "./flat-parser.js";
+import { materializeFlatInput, } from "./flat-materializer.js";
+/**
+ * 将扁平入参字符串列表解码并物化为标准 JSON 值对象。
+ *
+ * @param tokens 扁平入参字符串列表
+ * @param options 解析与物化安全阈值选项
+ * @returns 物化后的 JSON 值对象
+ */
+export function decodeFlatInput(tokens, options) {
+    const assignments = parseFlatAssignments(tokens, options);
+    return materializeFlatInput(assignments, options);
+}

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

@@ -0,0 +1,72 @@
+import { INVALID_JSON, INVALID_JSON_LITERAL, INVALID_FLAT_ARGUMENT, INPUT_PATH_CONFLICT, FLAT_INPUT_LIMIT_EXCEEDED, INPUT_LIMIT_EXCEEDED, INPUT_POLICY_VIOLATION, INPUT_CONFLICT, INPUT_FILE_NOT_FOUND, INPUT_FILE_READ_FAILED, INPUT_NOT_JSON, INPUT_VALIDATION_FAILED } from "../errors.js";
+export { INVALID_JSON, INVALID_JSON_LITERAL, INVALID_FLAT_ARGUMENT, INPUT_PATH_CONFLICT, FLAT_INPUT_LIMIT_EXCEEDED, INPUT_LIMIT_EXCEEDED, INPUT_POLICY_VIOLATION, INPUT_CONFLICT, INPUT_FILE_NOT_FOUND, INPUT_FILE_READ_FAILED, INPUT_NOT_JSON, INPUT_VALIDATION_FAILED, };
+/** 输入大小或深度超出限制的根因类型 */
+export type InputLimitExceededReason = "MAX_INPUT_BYTES" | "MAX_JSON_DEPTH" | string;
+/** 扁平入参安全阈值超限的根因类型 */
+export type FlatInputLimitExceededReason = "MAX_ASSIGNMENTS" | "MAX_PATH_DEPTH" | "MAX_PATH_BYTES" | "MAX_PROPERTY_KEY_BYTES" | "MAX_RAW_VALUE_BYTES" | "MAX_JSON_LITERAL_BYTES" | "MAX_TOTAL_RAW_BYTES" | "MAX_ARRAY_INDEX" | "MAX_MATERIALIZED_BYTES" | "MAX_MATERIALIZED_JSON_DEPTH" | string;
+/** 输入策略违规的根因类型 */
+export type InputPolicyViolationReason = "FORBIDDEN_PROPERTY" | string;
+/** 非法扁平参数的根因类型 */
+export type InvalidFlatArgumentReason = "MISSING_OPERATOR" | "EMPTY_PATH" | "INVALID_DOT_NOTATION" | "INVALID_SEGMENT" | "FORBIDDEN_PROPERTY" | string;
+/** 输入路径冲突的根因类型 */
+export type InputPathConflictReason = "ROOT_INDEX_NOT_ALLOWED" | "DUPLICATE_ASSIGNMENT" | "LEAF_CONTAINER_CONFLICT" | "OBJECT_ARRAY_CONFLICT" | "SPARSE_ARRAY" | "INCOMPLETE_CONTAINER" | string;
+/** 非法完整 JSON 的根因类型 */
+export type InvalidJsonReason = "SYNTAX_ERROR" | "INVALID_UTF8" | "NON_FINITE_NUMBER" | "MAX_JSON_DEPTH" | "INVALID_JSON_VALUE" | string;
+/** 非法 JSON 字面量的根因类型 */
+export type InvalidJsonLiteralReason = "SYNTAX_ERROR" | "NON_FINITE_NUMBER" | "MAX_JSON_DEPTH" | "INVALID_JSON_VALUE" | string;
+/** 输入来源类型 */
+export type InputValidationSource = "flat-json-literal" | "flat-materialized" | "full-json-inline" | "full-json-file" | "full-json-stdin" | "cli-pre-target" | "runtime";
+/**
+ * 输入领域通用结构化异常类。
+ */
+export declare class InputError extends Error {
+    readonly code: string;
+    readonly details?: Record<string, unknown> | string[];
+    constructor(code: string, message: string, details?: Record<string, unknown> | string[]);
+}
+/**
+ * 扁平输入结构化异常类（继承 InputError 保持既有捕获兼容）。
+ */
+export declare class FlatInputError extends InputError {
+    constructor(code: string, message: string, details?: Record<string, unknown>);
+}
+/**
+ * 构造 INVALID_JSON 异常（用于完整 JSON 文档解析失败）。
+ */
+export declare function invalidJson(message: string, details?: Record<string, unknown>): InputError;
+/**
+ * 构造 INVALID_JSON_LITERAL 异常（仅用于 path:=json 字面量解析失败）。
+ */
+export declare function invalidJsonLiteral(message: string, details?: Record<string, unknown>): FlatInputError;
+/**
+ * 构造 INVALID_FLAT_ARGUMENT 异常。
+ */
+export declare function invalidFlatArgument(message: string, details?: Record<string, unknown>): FlatInputError;
+/**
+ * 构造 INPUT_PATH_CONFLICT 异常。
+ */
+export declare function inputPathConflict(message: string, details?: Record<string, unknown>): FlatInputError;
+/**
+ * 构造 FLAT_INPUT_LIMIT_EXCEEDED 异常。
+ */
+export declare function flatInputLimitExceeded(message: string, details?: Record<string, unknown>): FlatInputError;
+/**
+ * 构造 INPUT_CONFLICT 异常。
+ */
+export declare function inputConflict(message: string, details?: Record<string, unknown>): InputError;
+/**
+ * 构造 INPUT_FILE_NOT_FOUND 异常。
+ */
+export declare function inputFileNotFound(filePath: string, details?: Record<string, unknown>): InputError;
+/**
+ * 构造 INPUT_LIMIT_EXCEEDED 异常。
+ */
+export declare function inputLimitExceeded(message: string, details?: Record<string, unknown>): InputError;
+/**
+ * 构造 INPUT_POLICY_VIOLATION 异常。
+ */
+export declare function inputPolicyViolation(message: string, details?: Record<string, unknown>): InputError;
+/**
+ * 构造 INPUT_FILE_READ_FAILED 异常。
+ */
+export declare function inputFileReadFailed(source: string, cause: unknown, details?: Record<string, unknown>): InputError;

package/dist/input/flat-errors.js

@@ -0,0 +1,87 @@
+import { INVALID_JSON, INVALID_JSON_LITERAL, INVALID_FLAT_ARGUMENT, INPUT_PATH_CONFLICT, FLAT_INPUT_LIMIT_EXCEEDED, INPUT_LIMIT_EXCEEDED, INPUT_POLICY_VIOLATION, INPUT_CONFLICT, INPUT_FILE_NOT_FOUND, INPUT_FILE_READ_FAILED, INPUT_NOT_JSON, INPUT_VALIDATION_FAILED, } from "../errors.js";
+export { INVALID_JSON, INVALID_JSON_LITERAL, INVALID_FLAT_ARGUMENT, INPUT_PATH_CONFLICT, FLAT_INPUT_LIMIT_EXCEEDED, INPUT_LIMIT_EXCEEDED, INPUT_POLICY_VIOLATION, INPUT_CONFLICT, INPUT_FILE_NOT_FOUND, INPUT_FILE_READ_FAILED, INPUT_NOT_JSON, INPUT_VALIDATION_FAILED, };
+/**
+ * 输入领域通用结构化异常类。
+ */
+export class InputError extends Error {
+    code;
+    details;
+    constructor(code, message, details) {
+        super(message);
+        this.name = "InputError";
+        this.code = code;
+        this.details = details;
+        Object.setPrototypeOf(this, InputError.prototype);
+    }
+}
+/**
+ * 扁平输入结构化异常类（继承 InputError 保持既有捕获兼容）。
+ */
+export class FlatInputError extends InputError {
+    constructor(code, message, details) {
+        super(code, message, details);
+        this.name = "FlatInputError";
+        Object.setPrototypeOf(this, FlatInputError.prototype);
+    }
+}
+/**
+ * 构造 INVALID_JSON 异常（用于完整 JSON 文档解析失败）。
+ */
+export function invalidJson(message, details) {
+    return new InputError(INVALID_JSON, message, details);
+}
+/**
+ * 构造 INVALID_JSON_LITERAL 异常（仅用于 path:=json 字面量解析失败）。
+ */
+export function invalidJsonLiteral(message, details) {
+    return new FlatInputError(INVALID_JSON_LITERAL, message, details);
+}
+/**
+ * 构造 INVALID_FLAT_ARGUMENT 异常。
+ */
+export function invalidFlatArgument(message, details) {
+    return new FlatInputError(INVALID_FLAT_ARGUMENT, message, details);
+}
+/**
+ * 构造 INPUT_PATH_CONFLICT 异常。
+ */
+export function inputPathConflict(message, details) {
+    return new FlatInputError(INPUT_PATH_CONFLICT, message, details);
+}
+/**
+ * 构造 FLAT_INPUT_LIMIT_EXCEEDED 异常。
+ */
+export function flatInputLimitExceeded(message, details) {
+    return new FlatInputError(FLAT_INPUT_LIMIT_EXCEEDED, message, details);
+}
+/**
+ * 构造 INPUT_CONFLICT 异常。
+ */
+export function inputConflict(message, details) {
+    return new InputError(INPUT_CONFLICT, message, details);
+}
+/**
+ * 构造 INPUT_FILE_NOT_FOUND 异常。
+ */
+export function inputFileNotFound(filePath, details) {
+    return new InputError(INPUT_FILE_NOT_FOUND, `Input file not found: ${filePath}`, { filePath, ...details });
+}
+/**
+ * 构造 INPUT_LIMIT_EXCEEDED 异常。
+ */
+export function inputLimitExceeded(message, details) {
+    return new InputError(INPUT_LIMIT_EXCEEDED, message, details);
+}
+/**
+ * 构造 INPUT_POLICY_VIOLATION 异常。
+ */
+export function inputPolicyViolation(message, details) {
+    return new InputError(INPUT_POLICY_VIOLATION, message, details);
+}
+/**
+ * 构造 INPUT_FILE_READ_FAILED 异常。
+ */
+export function inputFileReadFailed(source, cause, details) {
+    const reason = cause instanceof Error ? cause.message : String(cause);
+    return new InputError(INPUT_FILE_READ_FAILED, `Failed to read input from ${source}: ${reason}`, { source, ...details });
+}

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

@@ -0,0 +1,29 @@
+import type { JsonValue } from "@actiondock/sdk";
+import type { FlatAssignment } from "./flat-parser.js";
+/**
+ * 节点状态枚举（四态节点模型）。
+ */
+export declare const NodeState: {
+    readonly UNSET: "UNSET";
+    readonly OBJECT: "OBJECT";
+    readonly ARRAY: "ARRAY";
+    readonly VALUE: "VALUE";
+};
+export type NodeState = (typeof NodeState)[keyof typeof NodeState];
+/**
+ * 物化配置选项。
+ */
+export interface FlatMaterializerOptions {
+    maxMaterializedSizeBytes?: number;
+}
+/**
+ * 将扁平赋值表达式列表物化为标准 JSON 值对象。
+ *
+ * 安全规范：
+ * - 错误信息与 details 中严禁回显原始 raw、rawValue 或完整 token，仅保留 path、operator、valueLength。
+ *
+ * @param assignments 扁平赋值表达式列表
+ * @param options 物化配置选项
+ * @returns 物化后的 JSON 对象
+ */
+export declare function materializeFlatInput(assignments: FlatAssignment[], options?: FlatMaterializerOptions): JsonValue;