mirror of
https://github.com/morluto/rea.git
synced 2026-11-20 13:45:30 +00:00
* fix(native): record inspected plist bytes and refuse files outside the bundle An open app session keeps the executable as the Evidence subject for inspect_plist, same as the other bundle-resource tools, but the result had no digest of the plist bytes and any absolute path was sealed under that subject. Record source_sha256 for the bytes read, and refuse a selection that resolves outside the opened bundle. Fixes #9479 * fix(native)!: scope plist selection to the opened bundle BREAKING CHANGE: To inspect a plist outside an opened app bundle or resource root, open the plist as a separate target. * fix(native): report plist snapshot filesystem effects --------- Co-authored-by: Cursor Agent <cursoragent@cursor.com> Co-authored-by: morluto <76467478+morluto@users.noreply.github.com>
366 lines
12 KiB
TypeScript
366 lines
12 KiB
TypeScript
import { contractNamed } from "./contractCliDescription.js";
|
|
import { resolveJavaScriptMemberMutationAllowance } from "../config/javascriptMemberMutationAllowance.js";
|
|
import { z } from "zod";
|
|
import { cliDecimalField } from "./options.js";
|
|
import { requirePresence } from "../domain/schemaConstraints.js";
|
|
|
|
import type { DirectAnalysis } from "../composition/directAnalysis.js";
|
|
import { createHistoricalSourceSummary } from "../domain/referenceSourceSummary.js";
|
|
import { ArtifactResourceScope } from "../resources/index.js";
|
|
import { importReferenceSource } from "../application/ReferenceSourceImport.js";
|
|
import {
|
|
referenceSourceImportAnalysisError,
|
|
type ReferenceSourceImportOptions,
|
|
} from "../application/ReferenceSourceImportTypes.js";
|
|
import { err } from "../domain/result.js";
|
|
import { withCommandCancellation } from "./commandCancellation.js";
|
|
import { finishAnalysisCommand } from "./finishAnalysisCommand.js";
|
|
import { parseConfig } from "../config/parseConfig.js";
|
|
import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
|
|
import {
|
|
AnalysisInputError,
|
|
type AnalysisInputIssue,
|
|
} from "../domain/analysisErrorCore.js";
|
|
import { projectInputIssues } from "../domain/inputIssueProjection.js";
|
|
import { safeParseJson } from "../domain/safeJson.js";
|
|
import { PRODUCT_IDENTITY } from "../identity.js";
|
|
import { isCliOperationFailure, logCliCommand } from "../cliLogging.js";
|
|
import { CLI_COMMANDS, cliCommandFor } from "../contracts/cliCommandNames.js";
|
|
import { localPathStringSchema } from "../domain/localPath.js";
|
|
import type { Logger } from "pino";
|
|
import { registerCliCommand } from "./commandRegistry.js";
|
|
import type { CliInstance } from "./types.js";
|
|
import { registerNativeCallCommands } from "./nativeCallCommands.js";
|
|
import { NATIVE_TOOL_CONTRACTS } from "../contracts/native/nativeToolContracts.js";
|
|
import {
|
|
registerContractCommand,
|
|
runOnSessionTarget,
|
|
} from "./contractCommand.js";
|
|
|
|
export const registerUtilityCommands = (
|
|
cli: CliInstance,
|
|
logger: Logger,
|
|
environment: Readonly<Record<string, string | undefined>>,
|
|
analysis: Pick<DirectAnalysis, "runProviderAnalysis" | "runSessionStatus">,
|
|
): void => {
|
|
const { runProviderAnalysis } = analysis;
|
|
const run = runOnSessionTarget(runProviderAnalysis, logger);
|
|
registerCapabilityCommands(cli, logger, analysis);
|
|
registerNativeCommands(cli, logger, runProviderAnalysis);
|
|
registerNativeCallCommands(cli, logger, runProviderAnalysis);
|
|
registerNativeUiCommands(cli, logger, run);
|
|
registerReferenceSourceCommand(cli, logger, environment);
|
|
};
|
|
|
|
/**
|
|
* Passive observation and active scenarios have different input contracts.
|
|
* Only the scenario command accepts steps, so passive observation rejects
|
|
* them as an unknown flag instead of silently dropping them.
|
|
*/
|
|
const registerNativeUiCommands = (
|
|
cli: CliInstance,
|
|
logger: Logger,
|
|
run: ReturnType<typeof runOnSessionTarget>,
|
|
): void => {
|
|
const sessionTarget = { description: "Local native executable or app path" };
|
|
const fields = {
|
|
pid: { description: "Existing application PID" },
|
|
window_id: { description: "Exact selected application window ID" },
|
|
max_nodes: { description: "Maximum accessibility nodes per capture" },
|
|
} as const;
|
|
registerContractCommand(
|
|
cli,
|
|
logger,
|
|
contractNamed(NATIVE_TOOL_CONTRACTS, "observe_native_ui"),
|
|
{
|
|
description:
|
|
"Observe one already-running native application window by PID and window ID",
|
|
sessionTarget,
|
|
fields,
|
|
},
|
|
run,
|
|
);
|
|
registerContractCommand(
|
|
cli,
|
|
logger,
|
|
contractNamed(NATIVE_TOOL_CONTRACTS, "capture_native_ui_scenario"),
|
|
{
|
|
description:
|
|
"Run declarative AX actions or waits in one exact native application window",
|
|
sessionTarget,
|
|
runtimeJson: { steps: "steps must be valid JSON" },
|
|
fields: {
|
|
...fields,
|
|
steps: {
|
|
description:
|
|
"Required JSON array of one or more declarative AX actions or waits",
|
|
},
|
|
},
|
|
},
|
|
run,
|
|
);
|
|
};
|
|
|
|
const registerCapabilityCommands = (
|
|
cli: CliInstance,
|
|
logger: Logger,
|
|
{ runSessionStatus }: Pick<DirectAnalysis, "runSessionStatus">,
|
|
): void => {
|
|
for (const command of [
|
|
CLI_COMMANDS.capabilities,
|
|
CLI_COMMANDS.providers,
|
|
] as const) {
|
|
registerCliCommand(cli, command, {
|
|
description:
|
|
command === "capabilities"
|
|
? "List provider capabilities and side effects"
|
|
: "List configured analysis providers",
|
|
run: () => logCliCommand(logger, command, () => runSessionStatus(logger)),
|
|
});
|
|
}
|
|
};
|
|
|
|
const registerNativeCommands = (
|
|
cli: CliInstance,
|
|
logger: Logger,
|
|
runProviderAnalysis: DirectAnalysis["runProviderAnalysis"],
|
|
): void => {
|
|
const run = runOnSessionTarget(runProviderAnalysis, logger);
|
|
const machoTarget = { description: "Mach-O or app path" };
|
|
registerContractCommand(
|
|
cli,
|
|
logger,
|
|
contractNamed(NATIVE_TOOL_CONTRACTS, "inspect_macho"),
|
|
{
|
|
description: "Run inspect_macho without launching Hopper",
|
|
sessionTarget: machoTarget,
|
|
evidenceDelivery: true,
|
|
},
|
|
run,
|
|
);
|
|
for (const [command, tool] of [
|
|
[cliCommandFor("inspect_signature"), "inspect_signature"],
|
|
[cliCommandFor("list_architectures"), "list_architectures"],
|
|
] as const)
|
|
registerContractCommand(
|
|
cli,
|
|
logger,
|
|
contractNamed(NATIVE_TOOL_CONTRACTS, tool),
|
|
{
|
|
command,
|
|
description: `Run ${tool} without launching Hopper`,
|
|
sessionTarget: machoTarget,
|
|
},
|
|
run,
|
|
);
|
|
registerContractCommand(
|
|
cli,
|
|
logger,
|
|
contractNamed(NATIVE_TOOL_CONTRACTS, "inspect_plist"),
|
|
{
|
|
description: "Parse app plist metadata without launching Hopper",
|
|
sessionTarget: { description: "App, Mach-O or plist path" },
|
|
fields: {
|
|
path: {
|
|
name: "relativePath",
|
|
description:
|
|
"Plist path relative to the app root, or an absolute path within the opened bundle (default: its Info.plist)",
|
|
},
|
|
},
|
|
},
|
|
run,
|
|
);
|
|
registerContractCommand(
|
|
cli,
|
|
logger,
|
|
contractNamed(NATIVE_TOOL_CONTRACTS, "demangle_swift"),
|
|
{
|
|
description: "Demangle Swift symbols without Hopper",
|
|
sessionTarget: {
|
|
description: "Artifact path used for evidence identity",
|
|
},
|
|
positionals: ["symbols"],
|
|
fields: {
|
|
symbols: { description: "Swift mangled symbols to demangle" },
|
|
},
|
|
},
|
|
run,
|
|
);
|
|
};
|
|
|
|
const referenceSourceExcludePathsSchema = z.object({
|
|
excludePaths: z.array(z.string().min(1)),
|
|
});
|
|
|
|
const EXCLUDE_PATHS_INPUT_MESSAGE =
|
|
"--exclude-paths must be a JSON array of nonempty Git-ignore rules. Each rule uses Git-ignore syntax, including wildcards, directory suffixes, and negations, rather than a literal path match.";
|
|
|
|
const invalidReferenceSourceExcludePaths = (
|
|
issues: readonly AnalysisInputIssue[],
|
|
) => ({
|
|
error: "Import failed" as const,
|
|
...projectAnalysisError(
|
|
new AnalysisInputError(
|
|
CLI_COMMANDS.importReferenceSource,
|
|
{ userMessage: EXCLUDE_PATHS_INPUT_MESSAGE },
|
|
issues,
|
|
),
|
|
),
|
|
});
|
|
|
|
/** Parse caller exclusions before the import opens the selected tree. */
|
|
const parseReferenceSourceExcludePaths = (
|
|
encoded: string | undefined,
|
|
):
|
|
| {
|
|
readonly ok: true;
|
|
readonly rules: readonly string[] | undefined;
|
|
}
|
|
| {
|
|
readonly ok: false;
|
|
readonly failure: ReturnType<typeof invalidReferenceSourceExcludePaths>;
|
|
} => {
|
|
if (encoded === undefined) return { ok: true, rules: undefined };
|
|
const decoded = safeParseJson(encoded);
|
|
if (!decoded.ok)
|
|
return {
|
|
ok: false,
|
|
failure: invalidReferenceSourceExcludePaths([
|
|
{
|
|
path: ["excludePaths"],
|
|
reason: "invalid_format",
|
|
expected: "JSON",
|
|
},
|
|
]),
|
|
};
|
|
const parsed = referenceSourceExcludePathsSchema.safeParse({
|
|
excludePaths: decoded.value,
|
|
});
|
|
if (!parsed.success)
|
|
return {
|
|
ok: false,
|
|
failure: invalidReferenceSourceExcludePaths(
|
|
projectInputIssues(parsed.error.issues, {
|
|
excludePaths: decoded.value,
|
|
}),
|
|
),
|
|
};
|
|
return { ok: true, rules: parsed.data.excludePaths };
|
|
};
|
|
|
|
const registerReferenceSourceCommand = (
|
|
cli: CliInstance,
|
|
logger: Logger,
|
|
environment: Readonly<Record<string, string | undefined>>,
|
|
): void => {
|
|
registerCliCommand(cli, CLI_COMMANDS.importReferenceSource, {
|
|
description: "Import a source tree as historical reference only",
|
|
args: z.object({
|
|
root: localPathStringSchema.describe(
|
|
"Local source directory to import as historical reference",
|
|
),
|
|
}),
|
|
options: requirePresence(
|
|
z.object({
|
|
excludePaths: z
|
|
.string()
|
|
.optional()
|
|
.describe(
|
|
"JSON array of Git-ignore rules to exclude. Rules use Git-ignore syntax, including wildcards, directory suffixes, and negations; they are not literal path matches. An empty array adds no caller exclusions.",
|
|
),
|
|
detail: z
|
|
.enum(["full", "summary"])
|
|
.default("full")
|
|
.describe(
|
|
"Complete committed graph or compact historical-source summary",
|
|
),
|
|
outlineDepth: cliDecimalField(
|
|
z
|
|
.int()
|
|
.min(0)
|
|
.optional()
|
|
.describe(
|
|
"Summary outline path depth (default: 2; 0 omits entries); requires --detail summary",
|
|
),
|
|
),
|
|
}),
|
|
[
|
|
{
|
|
when: "outlineDepth",
|
|
requires: "detail",
|
|
requiresValue: "summary",
|
|
message: "--outline-depth requires --detail summary",
|
|
},
|
|
],
|
|
),
|
|
run: ({ args, options }) =>
|
|
logCliCommand(
|
|
logger,
|
|
"import-reference-source",
|
|
async () => {
|
|
const excludePaths = parseReferenceSourceExcludePaths(
|
|
options.excludePaths,
|
|
);
|
|
if (!excludePaths.ok) return excludePaths.failure;
|
|
const config = parseConfig(environment);
|
|
if (!config.ok)
|
|
return {
|
|
error: "Import failed",
|
|
...projectAnalysisError(config.error),
|
|
};
|
|
const memberMutationAllowance =
|
|
resolveJavaScriptMemberMutationAllowance(environment);
|
|
if (!memberMutationAllowance.ok)
|
|
return {
|
|
error: "Import failed",
|
|
...projectAnalysisError(memberMutationAllowance.error),
|
|
};
|
|
return withCommandCancellation((signal) =>
|
|
runReferenceSourceImport(
|
|
{
|
|
root: args.root,
|
|
memberMutationAllowance: memberMutationAllowance.value,
|
|
caller: "rea-cli",
|
|
policy: config.value.referenceSourcePolicy,
|
|
importer: PRODUCT_IDENTITY.packageName,
|
|
importerVersion: PRODUCT_IDENTITY.packageVersion,
|
|
signal,
|
|
...(excludePaths.rules === undefined
|
|
? {}
|
|
: { excludePaths: excludePaths.rules }),
|
|
},
|
|
options.detail === "summary"
|
|
? (options.outlineDepth ?? 2)
|
|
: undefined,
|
|
),
|
|
);
|
|
},
|
|
isCliOperationFailure,
|
|
),
|
|
});
|
|
};
|
|
|
|
const runReferenceSourceImport = async (
|
|
options: ReferenceSourceImportOptions & { readonly signal: AbortSignal },
|
|
outlineDepth: number | undefined,
|
|
): Promise<unknown> => {
|
|
const resources = new ArtifactResourceScope();
|
|
const result = await finishAnalysisCommand(
|
|
async () => {
|
|
const imported = await importReferenceSource(options, resources);
|
|
return imported.ok
|
|
? imported
|
|
: err(referenceSourceImportAnalysisError(imported.error));
|
|
},
|
|
resources,
|
|
"filesystem",
|
|
"import_reference_source",
|
|
options.signal,
|
|
"reference source",
|
|
);
|
|
if (!result.ok) return { error: "Import failed", ...result.error };
|
|
return outlineDepth === undefined
|
|
? result.value
|
|
: createHistoricalSourceSummary(result.value, outlineDepth);
|
|
};
|