Files
reverse-engineering-anything/src/contracts/sessionLifecycleInputs.ts
T
morluto 10309f9c69 refactor(targets): share the resolved target format vocabulary (#12165)
* refactor(targets): share the resolved target format vocabulary

* test(targets): verify each format kind at compile time

* refactor(targets): share Evidence and explicit format vocabulary (#12168)
2026-11-19 03:54:56 +00:00

166 lines
6.0 KiB
TypeScript

import { TARGET_FORMAT_HINTS } from "../domain/targetFormats.js";
import { absoluteLocalPathStringSchema } from "../domain/localPath.js";
import {
binaryArchitectureSchema,
rawBinaryEntryPointSchema,
rawBinarySelectionError,
} from "../domain/rawBinary.js";
import { z } from "zod";
import {
espFlashAddressSchema,
espFlashSelectionError,
parseEspFlashAddress,
} from "../domain/firmware/espFlashSelection.js";
import { analysisProviderSelectorSchema } from "../domain/providerSelection.js";
/** Caller-supplied analysis snapshot path; must name its destination absolutely. */
const snapshotPathSchema = absoluteLocalPathStringSchema.describe(
"Absolute local filesystem path for the analysis snapshot; relative paths are rejected.",
);
/** Caller-supplied analysis target path; must name the target absolutely. */
const binaryTargetPathSchema = absoluteLocalPathStringSchema.describe(
"Absolute local filesystem path for the analysis target; relative paths are rejected.",
);
/** Explicit format selection, including the ESP flash archive interpretation. */
const targetFormatHintSchema = z.enum(TARGET_FORMAT_HINTS);
/** Input contract for opening a target with an optional staged snapshot. */
export const openBinaryInputSchema = z
.strictObject({
path: binaryTargetPathSchema,
format: targetFormatHintSchema
.optional()
.describe(
"Explicit interpretation: dos-com or raw-binary (headerless), gamecube-dol (GameCube/Wii DOL, never auto-detected), or esp-flash-image (an ESP flash dump read with flash_offset and partition_table_offset). Omission preserves header-based detection.",
),
architecture: binaryArchitectureSchema
.optional()
.describe(
"Caller-supplied CPU family. Required with format=raw-binary; rejected otherwise. format=gamecube-dol takes powerpc from the header, so it must be omitted.",
),
entry_point: rawBinaryEntryPointSchema
.optional()
.describe(
"Caller-supplied load and entry address (0xhex). File offset 0 is mapped here. Required with format=raw-binary; rejected otherwise. Optional with format=gamecube-dol; must equal the DOL header entry.",
),
flash_offset: espFlashAddressSchema
.optional()
.describe(
"Flash address (0xhex) of the dump's first byte, when it does not start at flash address 0. Only with format=esp-flash-image.",
),
partition_table_offset: espFlashAddressSchema
.optional()
.describe(
"Flash address (0xhex, a multiple of 0x1000) of the partition table, which disables the table scan. Only with format=esp-flash-image.",
),
provider_id: analysisProviderSelectorSchema.optional(),
snapshot_path: snapshotPathSchema.optional(),
})
.superRefine((value, context) => {
const flash = espFlashSelectionError({
format: value.format,
flashOffset:
value.flash_offset === undefined
? undefined
: parseEspFlashAddress(value.flash_offset),
partitionTableOffset:
value.partition_table_offset === undefined
? undefined
: parseEspFlashAddress(value.partition_table_offset),
});
if (flash !== undefined)
context.addIssue({
code: "custom",
path: [
value.partition_table_offset === undefined
? "flash_offset"
: "partition_table_offset",
],
message: flash,
});
const pairing = rawBinarySelectionError({
...(value.format === undefined ? {} : { format: value.format }),
...(value.architecture === undefined
? {}
: { architecture: value.architecture }),
...(value.entry_point === undefined
? {}
: { entryPoint: value.entry_point }),
});
if (pairing === undefined) return;
context.addIssue({
code: "custom",
path:
value.format === "raw-binary"
? value.architecture === undefined
? ["architecture"]
: ["entry_point"]
: value.architecture === undefined
? ["entry_point"]
: ["architecture"],
message: pairing,
});
});
/** Open only app resources when no declared executable is available. */
export const openBundleResourcesInputSchema = z.strictObject({
path: binaryTargetPathSchema,
});
/** Input contract for closing a target after an optional atomic snapshot. */
export const closeBinaryInputSchema = z.strictObject({
snapshot_path: snapshotPathSchema.optional(),
overwrite: z.boolean().default(false),
});
/** Optional complete checkpoint before explicitly ending the current investigation. */
export const resetInvestigationInputSchema = z.strictObject({
save_path: absoluteLocalPathStringSchema
.describe(
"Absolute path for a complete Evidence bundle saved before clearing records.",
)
.optional(),
overwrite: z.boolean().default(false),
});
/**
* The target interpretation an `open_binary` input selects, in the spelling
* every target open takes. MCP and CLI commands that open a target with these
* fields share this mapping.
*/
export const openBinaryTargetSelection = (
input: Pick<
z.output<typeof openBinaryInputSchema>,
| "format"
| "architecture"
| "entry_point"
| "flash_offset"
| "partition_table_offset"
>,
) => ({
...(input.format === undefined ? {} : { formatHint: input.format }),
...(input.architecture === undefined
? {}
: { architecture: input.architecture }),
...(input.entry_point === undefined ? {} : { entryPoint: input.entry_point }),
...(input.flash_offset === undefined &&
input.partition_table_offset === undefined
? {}
: {
espFlash: {
...(input.flash_offset === undefined
? {}
: { flashOffset: parseEspFlashAddress(input.flash_offset) }),
...(input.partition_table_offset === undefined
? {}
: {
partitionTableOffset: parseEspFlashAddress(
input.partition_table_offset,
),
}),
},
}),
});