mirror of
https://github.com/morluto/rea.git
synced 2026-11-20 05:32:44 +00:00
* fix(cli): reject blank paths in JSON input schemas * docs(cli): describe JSON caller paths as nonblank
482 lines
16 KiB
TypeScript
482 lines
16 KiB
TypeScript
import { addAbortListener } from "node:events";
|
|
import { isAbortOf } from "../process/SignalAbort.js";
|
|
import type { Readable } from "node:stream";
|
|
import { getHeapStatistics } from "node:v8";
|
|
|
|
import { absoluteCallerPath } from "../filesystem/callerPath.js";
|
|
import { localPathStringSchema } from "../domain/localPath.js";
|
|
|
|
import { sealOwnedJsonInput } from "../application/OwnedJsonInput.js";
|
|
import {
|
|
JsonInputCancellationFailure,
|
|
JsonInputPhysicalReadFailure,
|
|
readJsonInputFile,
|
|
nativeJsonParseRequiredBytes,
|
|
} from "../application/JsonInputFile.js";
|
|
import { NonRegularFileReadError } from "../filesystem/RegularFile.js";
|
|
import {
|
|
RegularFileCleanupFailure,
|
|
regularFileCancellation,
|
|
} from "../filesystem/OwnedRegularFile.js";
|
|
import { ownCliProcessResource } from "./cliResources.js";
|
|
import { ProviderCleanupError } from "../domain/providerCleanupError.js";
|
|
import { AnalysisError } from "../domain/analysisErrorBase.js";
|
|
import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js";
|
|
import { ArtifactResourceScope } from "../resources/index.js";
|
|
import {
|
|
AnalysisAccessDeniedError,
|
|
AnalysisInputError,
|
|
AnalysisResourceConstraintError,
|
|
cancelledBy,
|
|
carriedReason,
|
|
} from "../domain/analysisErrorCore.js";
|
|
import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
|
|
import { err, ok, type Result } from "../domain/result.js";
|
|
import type { JsonValue } from "../domain/jsonValue.js";
|
|
import { safeParseJson } from "../domain/safeJson.js";
|
|
import {
|
|
JSON_INPUT_RESOURCE_REMEDIATION,
|
|
parseUtf8Json,
|
|
} from "../application/Utf8JsonInput.js";
|
|
|
|
/**
|
|
* Scopes of JSON-input files whose close still failed after their owner's
|
|
* retry. The process owns them until final CLI cleanup retries the close, so
|
|
* a handle never loses its owner when parsing returns, and a later read never
|
|
* inherits an earlier file's cleanup.
|
|
*/
|
|
const retainedJsonInputs = new Set<ArtifactResourceScope>();
|
|
ownCliProcessResource("json-input", async () => {
|
|
const failures: unknown[] = [];
|
|
for (const resources of retainedJsonInputs)
|
|
try {
|
|
await resources.close();
|
|
retainedJsonInputs.delete(resources);
|
|
} catch (cause: unknown) {
|
|
failures.push(cause);
|
|
}
|
|
if (failures.length === 1) throw failures[0];
|
|
if (failures.length > 1)
|
|
throw new AggregateError(failures, "JSON input cleanup failed");
|
|
});
|
|
|
|
/** Parse inline JSON, standard input ('-'), or one local JSON file, honoring optional caller cancellation. */
|
|
export const parseCliJsonInput = async (
|
|
value: string,
|
|
operation: string,
|
|
signal?: AbortSignal,
|
|
options?: {
|
|
readonly snapshot?: boolean;
|
|
readonly stdin?: Readable;
|
|
},
|
|
): Promise<
|
|
| { readonly ok: true; readonly value: unknown }
|
|
| { readonly ok: false; readonly error: JsonValue }
|
|
> => {
|
|
const cancelled = (cause: unknown) => ({
|
|
ok: false as const,
|
|
error: {
|
|
error: "Application workflow failed",
|
|
...projectAnalysisError(cancelledBy(operation, carriedReason(cause))),
|
|
},
|
|
});
|
|
if (signal?.aborted) return cancelled(signal.reason);
|
|
// Lets the file's owner retry a refused close before reporting it.
|
|
const resources = new ArtifactResourceScope();
|
|
try {
|
|
const inline = safeParseJson(value);
|
|
if (inline.ok) {
|
|
if (!options?.snapshot) return { ok: true, value: inline.value };
|
|
const sealed = await sealOwnedJsonInput(inline.value, operation, signal);
|
|
return sealed.ok
|
|
? { ok: true, value: sealed.value }
|
|
: {
|
|
ok: false,
|
|
error: {
|
|
error: "Application workflow failed",
|
|
...projectAnalysisError(sealed.error),
|
|
},
|
|
};
|
|
}
|
|
const parsed =
|
|
value === "-"
|
|
? await readCliJsonStdin(operation, signal, options)
|
|
: await readJsonInputFile(
|
|
value,
|
|
operation,
|
|
signal,
|
|
resources,
|
|
options?.snapshot ?? false,
|
|
);
|
|
if (parsed.ok && signal?.aborted) return cancelled(signal.reason);
|
|
return parsed.ok
|
|
? { ok: true, value: parsed.value }
|
|
: {
|
|
ok: false,
|
|
error: {
|
|
error: "Application workflow failed",
|
|
...projectAnalysisError(parsed.error),
|
|
input_path: value,
|
|
input_reason:
|
|
parsed.error._tag === "AnalysisInputError"
|
|
? "invalid-json"
|
|
: "too-large",
|
|
},
|
|
};
|
|
} catch (cause: unknown) {
|
|
if (cause instanceof RegularFileCleanupFailure) {
|
|
retainedJsonInputs.add(resources);
|
|
return jsonFileCleanupError(value, operation, cause);
|
|
}
|
|
if (cause instanceof JsonInputCancellationFailure)
|
|
return cancelled(cause.reason);
|
|
if (cause instanceof JsonInputPhysicalReadFailure)
|
|
return jsonFileReadError(value, operation, cause.physicalCause);
|
|
if (isAbortOf(cause, signal)) return cancelled(signal.reason);
|
|
if (accessDeniedSystemCode(cause) !== undefined)
|
|
return jsonFileReadError(value, operation, cause);
|
|
if (
|
|
["{", "["].includes(value.trimStart()[0] ?? "") &&
|
|
cannotBeAnExistingFile(cause) &&
|
|
!hasExplicitJsonFileExtension(value)
|
|
)
|
|
return { ok: false, error: inputError(operation) };
|
|
if (
|
|
!(cause instanceof Error) ||
|
|
!("code" in cause) ||
|
|
typeof cause.code !== "string"
|
|
)
|
|
throw cause;
|
|
return jsonFileReadError(value, operation, cause);
|
|
}
|
|
};
|
|
|
|
const DEFAULT_MAX_STDIN_BYTES = 8 * 1024 * 1024;
|
|
|
|
const readCliJsonStdin = async (
|
|
operation: string,
|
|
signal?: AbortSignal,
|
|
options?: {
|
|
readonly snapshot?: boolean;
|
|
readonly stdin?: Readable;
|
|
},
|
|
): Promise<
|
|
Result<unknown, AnalysisInputError | AnalysisResourceConstraintError>
|
|
> => {
|
|
const stream = options?.stdin ?? process.stdin;
|
|
const maxBytes = DEFAULT_MAX_STDIN_BYTES;
|
|
const chunks: Buffer[] = [];
|
|
let totalBytes = 0;
|
|
const requireHeadroom = (): void => {
|
|
const heap = getHeapStatistics();
|
|
const requiredBytes = nativeJsonParseRequiredBytes(
|
|
totalBytes,
|
|
options?.snapshot,
|
|
);
|
|
if (requiredBytes > heap.total_available_size)
|
|
throw new AnalysisResourceConstraintError(
|
|
operation,
|
|
"memory",
|
|
"Insufficient heap headroom to read and parse the complete JSON stdin document",
|
|
{
|
|
input_path: "-",
|
|
input_bytes: totalBytes,
|
|
required_heap_bytes: requiredBytes,
|
|
available_heap_bytes: heap.total_available_size,
|
|
heap_size_limit_bytes: heap.heap_size_limit,
|
|
},
|
|
{ remediationAction: JSON_INPUT_RESOURCE_REMEDIATION },
|
|
);
|
|
};
|
|
// Destroying the reader wakes an idle next(); polling inside the loop cannot.
|
|
const abort =
|
|
signal === undefined
|
|
? undefined
|
|
: addAbortListener(signal, () => {
|
|
stream.destroy(new JsonInputCancellationFailure(signal.reason));
|
|
});
|
|
try {
|
|
try {
|
|
for await (const chunk of stream) {
|
|
signal?.throwIfAborted();
|
|
totalBytes +=
|
|
typeof chunk === "string"
|
|
? Buffer.byteLength(chunk)
|
|
: chunk.byteLength;
|
|
if (totalBytes > maxBytes)
|
|
return err(
|
|
new AnalysisResourceConstraintError(
|
|
operation,
|
|
"memory",
|
|
"JSON input exceeds the maximum allowed stdin size",
|
|
{
|
|
input_path: "-",
|
|
input_bytes: totalBytes,
|
|
max_stdin_bytes: maxBytes,
|
|
},
|
|
{ remediationAction: JSON_INPUT_RESOURCE_REMEDIATION },
|
|
),
|
|
);
|
|
requireHeadroom();
|
|
chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
|
|
}
|
|
} catch (cause: unknown) {
|
|
if (
|
|
cause instanceof JsonInputCancellationFailure ||
|
|
isAbortOf(cause, signal)
|
|
)
|
|
throw cause;
|
|
if (cause instanceof AnalysisResourceConstraintError) return err(cause);
|
|
throw new JsonInputPhysicalReadFailure(cause);
|
|
} finally {
|
|
abort?.[Symbol.dispose]();
|
|
}
|
|
signal?.throwIfAborted();
|
|
// Recheck live headroom before concatenation, UTF-8 decoding and JSON.parse.
|
|
requireHeadroom();
|
|
const parsed = parseUtf8Json(
|
|
Buffer.concat(chunks, totalBytes),
|
|
operation,
|
|
"-",
|
|
);
|
|
if (!parsed.ok)
|
|
return err(
|
|
new AnalysisInputError(
|
|
operation,
|
|
{
|
|
cause: parsed.cause,
|
|
...(parsed.userMessage === undefined
|
|
? {}
|
|
: { userMessage: parsed.userMessage }),
|
|
},
|
|
[
|
|
{
|
|
path: [],
|
|
reason: "invalid_format",
|
|
expected: "JSON",
|
|
...(parsed.userMessage === undefined
|
|
? {}
|
|
: { message: parsed.userMessage }),
|
|
},
|
|
],
|
|
),
|
|
);
|
|
return options?.snapshot
|
|
? await sealOwnedJsonInput(parsed.value, operation, signal)
|
|
: ok(parsed.value);
|
|
} catch (cause: unknown) {
|
|
if (cause instanceof AnalysisResourceConstraintError) return err(cause);
|
|
throw cause;
|
|
}
|
|
};
|
|
|
|
const accessDeniedSystemCode = (
|
|
cause: unknown,
|
|
): "EACCES" | "EPERM" | undefined => {
|
|
if (!(cause instanceof Error) || !("code" in cause)) return undefined;
|
|
return cause.code === "EACCES" || cause.code === "EPERM"
|
|
? cause.code
|
|
: undefined;
|
|
};
|
|
|
|
/**
|
|
* A `file:` URL or `scheme://` URL is not an operator-relative filesystem path.
|
|
* One-letter prefixes stay paths so Windows drive paths resolve normally.
|
|
*/
|
|
const URL_REFERENCE_SOURCE = "(?:[Ff][Ii][Ll][Ee]:|[A-Za-z][A-Za-z0-9+.-]+://)";
|
|
const URL_REFERENCE = new RegExp(`^${URL_REFERENCE_SOURCE}`, "u");
|
|
|
|
/**
|
|
* A caller-path field of a CLI JSON document as the CLI admits it: any
|
|
* nonblank local spelling, which it resolves, but not a URL, which it leaves
|
|
* for the contract to refuse. The URL pattern spells case-insensitivity out so
|
|
* JSON Schema, which carries no regex flags, advertises the same rule.
|
|
*/
|
|
export const cliJsonCallerPathSchema = localPathStringSchema
|
|
.regex(/\S/u, "must be a nonblank local path")
|
|
.regex(
|
|
new RegExp(`^(?!${URL_REFERENCE_SOURCE})`, "u"),
|
|
"must be a local path, not a URL",
|
|
);
|
|
|
|
/**
|
|
* Resolve named string fields of CLI-supplied JSON against the operator
|
|
* working directory. Each entry is a key path from the document root; only
|
|
* fields holding nonblank, non-URL strings are resolved, everything else passes
|
|
* through untouched so shared schemas can reject blank paths and URLs. Shared MCP
|
|
* contracts reject relative paths, so CLI workflows resolve operator-relative
|
|
* values before validation.
|
|
*/
|
|
export const resolveCliJsonPaths = (
|
|
value: unknown,
|
|
paths: ReadonlyArray<ReadonlyArray<string>>,
|
|
): unknown => {
|
|
let resolved = value;
|
|
for (const keys of paths) resolved = resolveJsonPath(resolved, keys);
|
|
return resolved;
|
|
};
|
|
|
|
const resolveJsonPath = (
|
|
value: unknown,
|
|
keys: ReadonlyArray<string>,
|
|
): unknown => {
|
|
const [head, ...tail] = keys;
|
|
if (typeof value !== "object" || value === null || Array.isArray(value))
|
|
return value;
|
|
const entries = Object.entries(value).map(
|
|
([key, entry]: readonly [string, unknown]): readonly [string, unknown] => {
|
|
if (key !== head) return [key, entry];
|
|
if (tail.length === 0)
|
|
return [
|
|
key,
|
|
typeof entry === "string" &&
|
|
entry.trim().length > 0 &&
|
|
!URL_REFERENCE.test(entry)
|
|
? absoluteCallerPath(entry)
|
|
: entry,
|
|
];
|
|
return [key, resolveJsonPath(entry, tail)];
|
|
},
|
|
);
|
|
return Object.fromEntries(entries);
|
|
};
|
|
|
|
const cannotBeAnExistingFile = (cause: unknown): boolean =>
|
|
typeof cause === "object" &&
|
|
cause !== null &&
|
|
"code" in cause &&
|
|
(cause.code === "ENOENT" ||
|
|
cause.code === "ENAMETOOLONG" ||
|
|
cause.code === "ENOTDIR");
|
|
|
|
const hasExplicitJsonFileExtension = (value: string): boolean =>
|
|
value.toLowerCase().endsWith(".json");
|
|
|
|
const inputError = (operation: string): JsonValue => ({
|
|
error: "Application workflow failed",
|
|
...projectAnalysisError(
|
|
new AnalysisInputError(operation, undefined, [
|
|
{ path: [], reason: "invalid_format", expected: "JSON" },
|
|
]),
|
|
),
|
|
});
|
|
|
|
/**
|
|
* The file's final close failed after its owner's retry, so the handle
|
|
* stays retained with the process until final CLI cleanup. Report the
|
|
* incomplete cleanup and the file, keeping why the read stopped (its typed
|
|
* refusal, descriptor failure or cancellation) as the primary failure.
|
|
*/
|
|
const jsonFileCleanupError = (
|
|
path: string,
|
|
operation: string,
|
|
failure: RegularFileCleanupFailure,
|
|
) => {
|
|
const cleanup = new ProviderCleanupError(
|
|
"json-input-file",
|
|
[path],
|
|
{
|
|
reason:
|
|
failure.cleanupCause instanceof Error
|
|
? failure.cleanupCause.message
|
|
: "file close failed",
|
|
},
|
|
{ operation, cause: failure },
|
|
);
|
|
const primary = jsonFileCleanupPrimary(path, operation, failure);
|
|
return {
|
|
ok: false as const,
|
|
error: {
|
|
error: "Application workflow failed",
|
|
...projectAnalysisError(
|
|
primary === undefined
|
|
? cleanup
|
|
: analysisErrorWithCleanupFailure(primary, cleanup, operation),
|
|
"invocation",
|
|
),
|
|
input_path: path,
|
|
},
|
|
};
|
|
};
|
|
|
|
/** Translate the read's recorded outcome once, before cleanup is composed. */
|
|
const jsonFileCleanupPrimary = (
|
|
path: string,
|
|
operation: string,
|
|
failure: RegularFileCleanupFailure,
|
|
): AnalysisError | undefined => {
|
|
const cancellation = regularFileCancellation(failure);
|
|
const { outcome } = failure;
|
|
if (outcome.kind === "failed") {
|
|
const { cause } = outcome;
|
|
if (cancellation !== undefined)
|
|
return cancelledBy(operation, carriedReason(cancellation.reason));
|
|
if (cause instanceof AnalysisError) return cause;
|
|
if (cause instanceof JsonInputCancellationFailure)
|
|
return cancelledBy(operation, carriedReason(cause.reason));
|
|
return jsonFileReadFailure(
|
|
path,
|
|
operation,
|
|
cause instanceof JsonInputPhysicalReadFailure
|
|
? cause.physicalCause
|
|
: cause,
|
|
);
|
|
}
|
|
// The read's own refusal, returned as a failed result.
|
|
const decoded = outcome.value as
|
|
| { readonly ok?: unknown; readonly error?: unknown }
|
|
| undefined;
|
|
if (decoded?.ok === false && decoded.error instanceof AnalysisError)
|
|
return decoded.error;
|
|
return cancellation === undefined
|
|
? undefined
|
|
: cancelledBy(operation, carriedReason(cancellation.reason));
|
|
};
|
|
|
|
/** A descriptor or selection failure, refused as access or as an unreadable input. */
|
|
const jsonFileReadFailure = (
|
|
path: string,
|
|
operation: string,
|
|
cause: unknown,
|
|
): AnalysisInputError | AnalysisAccessDeniedError => {
|
|
const systemCode = accessDeniedSystemCode(cause);
|
|
return systemCode === undefined
|
|
? new AnalysisInputError(operation, { cause }, [
|
|
readFailureIssue(path, cause),
|
|
])
|
|
: new AnalysisAccessDeniedError(operation, path, systemCode, { cause });
|
|
};
|
|
|
|
const jsonFileReadError = (
|
|
path: string,
|
|
operation: string,
|
|
cause: unknown,
|
|
) => ({
|
|
ok: false as const,
|
|
error: {
|
|
error: "Application workflow failed",
|
|
...projectAnalysisError(jsonFileReadFailure(path, operation, cause)),
|
|
input_path: path,
|
|
input_reason: "read-failed" as const,
|
|
},
|
|
});
|
|
|
|
/** Preserve file-selection and system failures alongside the requested path. */
|
|
const readFailureIssue = (path: string, cause: unknown) => {
|
|
const code =
|
|
typeof cause === "object" &&
|
|
cause !== null &&
|
|
"code" in cause &&
|
|
typeof cause.code === "string"
|
|
? ` (${cause.code})`
|
|
: "";
|
|
return {
|
|
path: [],
|
|
reason: "invalid_value" as const,
|
|
message:
|
|
cause instanceof NonRegularFileReadError && cause.code === "ENOTFILE"
|
|
? `The JSON input must be a regular file${code}: ${path}`
|
|
: `The JSON input file could not be read${code}: ${path}`,
|
|
};
|
|
};
|