fix(adb): share actionable provider configuration refusals

Catch binary selection failures at the adapter boundary and share the domain error projection with apktool. Missing and relative adb paths now report capability_unavailable with host configuration guidance in both message and remediation.

Validation: ADB/apktool provider suites and public CLI refusal suites pass. No connected-device behavior changed or verified. Refs #1952.
This commit is contained in:
morluto
2026-10-12 04:33:34 +08:00
parent 52e76c5d39
commit c42232f566
5 changed files with 78 additions and 23 deletions
+26
View File
@@ -336,12 +336,38 @@ it("reports a missing selected binary as a capability gap with recovery", async
if (result.ok) return;
const projected = projectAnalysisError(result.error);
expect(projected).toMatchObject({ code: "capability_unavailable" });
expect(projected.message).toContain("REA_ADB_PATH");
expect(projected.remediation).toMatchObject({
action: expect.stringContaining("REA_ADB_PATH") as unknown,
});
expect(projected.details).toMatchObject({
provider_id: "adb",
reason: expect.stringContaining("not found") as unknown,
});
});
it("reports relative adb configuration as an actionable refusal", async () => {
const provider = new AdbProvider({
environment: { REA_ADB_PATH: "relative/adb" },
});
const availability = await provider.inspectAvailability();
expect(availability).toMatchObject({
status: "unavailable",
reason: expect.stringContaining("REA_ADB_PATH") as unknown,
});
const projected = await refusedBy(provider, {
operation: "list_adb_devices",
input: {},
});
expect(projected).toMatchObject({
code: "capability_unavailable",
message: expect.stringContaining("REA_ADB_PATH") as unknown,
remediation: {
action: expect.stringContaining("REA_ADB_PATH") as unknown,
},
});
});
it("cancels before spawning anything", async () => {
const { binary, root } = await writeAdbStub(
(root) => `: > ${join(root, "spawned")}
+6 -8
View File
@@ -8,6 +8,7 @@ import type {
ExecutionOptions,
ProviderAvailability,
} from "../application/AnalysisProvider.js";
import { providerConfigurationRefusal } from "../domain/providerConfigurationRefusal.js";
import {
createAnalysisExecution,
type AnalysisExecution,
@@ -15,7 +16,6 @@ import {
import type { AdbRequest } from "../domain/adb/adbDeviceAnalysis.js";
import {
AnalysisArtifactChangedError,
AnalysisCapabilityUnavailableError,
AnalysisCancelledError,
AnalysisInputError,
AnalysisOutputError,
@@ -417,8 +417,8 @@ export class AdbProvider {
async inspectAvailability(
signal?: AbortSignal,
): Promise<ProviderAvailability> {
const selection = this.selection();
try {
const selection = this.selection();
await inspectAdbClient(selection, signal);
return {
status: "available",
@@ -555,21 +555,19 @@ export class AdbProvider {
const signal = options?.signal;
if (signal?.aborted === true)
return err(new AnalysisCancelledError(request.operation));
const selection = this.selection();
let selection: AdbBinarySelection;
let identity: AdbClientIdentity;
try {
selection = this.selection();
identity = await inspectAdbClient(selection, signal);
} catch (cause) {
if (cause instanceof AnalysisCancelledError) return err(cause);
if (cause instanceof AdbConfigurationFailure)
return err(
new AnalysisCapabilityUnavailableError(
providerConfigurationRefusal(
ADB_PROVIDER_IDENTITY.id,
request.operation,
typeof cause.diagnostics.remediation === "string"
? `${cause.message} ${cause.diagnostics.remediation}`
: cause.message,
{ cause },
cause,
),
);
return err(
+3 -8
View File
@@ -20,6 +20,7 @@ import type {
ExecutionOptions,
ProviderAvailability,
} from "../application/AnalysisProvider.js";
import { providerConfigurationRefusal } from "../domain/providerConfigurationRefusal.js";
import {
createAnalysisExecution,
type AnalysisExecution,
@@ -410,17 +411,11 @@ export class ApktoolProvider {
} catch (cause) {
if (cause instanceof AnalysisCancelledError) return err(cause);
if (cause instanceof ApktoolConfigurationFailure) {
// A host configuration refusal; the target is not the problem.
const reason =
typeof cause.diagnostics.remediation === "string"
? `${cause.message}. ${cause.diagnostics.remediation}.`
: `${cause.message}.`;
return err(
new AnalysisCapabilityUnavailableError(
providerConfigurationRefusal(
APKTOOL_PROVIDER_IDENTITY.id,
request.operation,
reason,
{ cause, userMessage: reason },
cause,
),
);
}
@@ -0,0 +1,21 @@
import { AnalysisCapabilityUnavailableError } from "./analysisErrorCore.js";
import type { JsonValue } from "./jsonValue.js";
/** Convert a provider's host configuration failure into actionable refusal evidence. */
export const providerConfigurationRefusal = (
providerId: string,
operation: string,
failure: Error & {
readonly diagnostics?: Readonly<Record<string, JsonValue>>;
},
): AnalysisCapabilityUnavailableError => {
const remediation = failure.diagnostics?.remediation;
const reason =
typeof remediation === "string"
? `${failure.message}. ${remediation}.`
: `${failure.message}.`;
return new AnalysisCapabilityUnavailableError(providerId, operation, reason, {
cause: failure,
userMessage: reason,
});
};
+22 -7
View File
@@ -34,13 +34,28 @@ it.each([
expect(schema).toBeTruthy();
});
it("reports a missing adb binary with recovery guidance", async () => {
const result = await serve(["inspect-adb-client", "--json"], {
REA_ADB_PATH: "/nonexistent/adb",
});
expect(result.stdout).toContain("capability_unavailable");
expect(result.stdout).toContain("REA_ADB_PATH");
});
it.each([
["inspect-adb-client", "/nonexistent/adb", "not found"],
["list-adb-devices", "relative/adb", "absolute path"],
])(
"%s names the adb configuration requirement",
async (command, binary, cause) => {
const result = await serve([command, "--json"], {
REA_ADB_PATH: binary,
});
const output = JSON.parse(result.stdout) as {
code?: unknown;
message?: unknown;
remediation?: { action?: unknown };
};
expect(output.code).toBe("capability_unavailable");
expect(output.message).toEqual(expect.stringContaining(cause));
expect(output.message).toEqual(expect.stringContaining("REA_ADB_PATH"));
expect(output.remediation?.action).toEqual(
expect.stringContaining("REA_ADB_PATH"),
);
},
);
it("validates device serials before contacting any device", async () => {
const result = await serve(["inspect-adb-device", "bad serial", "--json"]);