Skip to content

Commit 6541f8b

Browse files
strzhaoclaude
andcommitted
fix(harmonyos): classify uninstall probe through a live transport
bm dump alone cannot decide absence: an unreachable target answers through hdc stdout while exiting zero, and an absent bundle answers through bm with an error record while also exiting zero. The old mapping folded both into wasInstalled:false, so a disconnected device during cleanup looked like a successful no-op. The uninstall probe now confirms the shell transport with a second `shell true` call before it reports absence, and it throws COMMAND_FAILED when the dump was killed or the probe shows no live transport. parseLaunchTarget reuses the one bundle-record parser, and each operation admits through its own fact cell. The transport shapes come from a physical HarmonyOS handset; the run is recorded in docs/evidence/harmony-uninstall-transport-classification-2026-11-07.md. Co-Authored-By: Claude Code <[email protected]>
1 parent 7c0be71 commit 6541f8b

3 files changed

Lines changed: 147 additions & 31 deletions

File tree

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
# HarmonyOS uninstall transport classification, 2026-11-07
2+
3+
Source under review: `forge/harmony-uninstall` at `7c0be71b5f7ee40101d9637d438f364114338dc6`.
4+
The classification fix landed as a follow-up commit on the same branch.
5+
Device: physical HarmonyOS handset, hdc serial `77TYD26826028730`.
6+
hdc: local command-line tools at `~/.local/harmony/command-line-tools/sdk/default/openharmony/toolchains/hdc`.
7+
Purpose: record the observable `bm dump -n` shapes that decide how the uninstall probe separates an absent bundle from a dead transport.
8+
9+
## Observed shapes
10+
11+
Every command ran as `hdc -t <serial> shell <words>`. Exit codes below are host-side.
12+
13+
| Probe | Host exit | stdout |
14+
| --- | --- | --- |
15+
| `bm dump -n <installed bundle>` | 0 | `<bundle>:` line, then the JSON record |
16+
| `bm dump -n com.agentdevice.probe.absent` | 0 | `error: failed to get information and the parameters may be wrong.`, no JSON |
17+
| `bm uninstall -n com.agentdevice.probe.absent` | 0 | `error: failed to uninstall bundle.` plus failure code `9568386` |
18+
| `bm dump -n <installed bundle>` through a bogus serial | 0 | `[Fail]Not match target founded, check connect-key please` |
19+
| `shell true` on the connected target | 0 | empty |
20+
| `shell true` through the bogus serial | 0 | `[Fail]Not match target founded, check connect-key please` |
21+
22+
The installed-bundle record proves the `bm dump -n <bundle>` JSON extraction used by both deploy and uninstall.
23+
The absent-bundle row proves bm answers a missing bundle with an error record while exiting zero.
24+
The bogus-serial rows prove this hdc build reports an unreachable target through stdout while exiting zero.
25+
Exit codes alone cannot separate "bm answered absent" from "hdc never reached the target" on this hardware.
26+
The runtime therefore classifies an absent record with a `shell true` probe, and it throws `COMMAND_FAILED` when the probe shows no live transport.
27+
28+
## Coverage gaps
29+
30+
The removal itself was not executed on this device. Every installed bundle belongs to the device owner, and the repository ships no HarmonyOS fixture HAP. Installing the example test app only to capture one uninstall transcript was out of scope for this review fix. The absent-record path and the dead-transport path carry mocked tests in `packages/platform-harmonyos/src/deployment/runtime.test.ts`, and the mocked transport shapes above come from this run.

‎packages/platform-harmonyos/src/deployment/runtime.test.ts‎

Lines changed: 70 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -134,22 +134,84 @@ test('uninstall removes an installed HarmonyOS bundle through bm uninstall', asy
134134
);
135135
});
136136

137-
test.each([
138-
['a failed dump', { stdout: '[Fail]bundle not installed', stderr: '', exitCode: 1 }],
139-
['a dump without a JSON record', { stdout: '', stderr: '', exitCode: 0 }],
140-
] as const)('uninstall reports nothing removed for %s', async (_name, dump) => {
141-
const run = vi.fn(async () => dump as HostCommandResult);
142-
const commands = { which: async () => undefined, run } as HostCommandRunner;
137+
const emptyAnswer: HostCommandResult = { stdout: '', stderr: '', exitCode: 0 };
138+
139+
/**
140+
* Shapes recorded on physical hardware: an absent bundle answers through bm with an
141+
* error record, while an unreachable target answers through hdc itself and still
142+
* exits zero. The second probe call classifies the two.
143+
*/
144+
const absentBundleAnswer: HostCommandResult = {
145+
stdout: 'error: failed to get information and the parameters may be wrong.',
146+
stderr: '',
147+
exitCode: 0,
148+
};
149+
const unreachableAnswer: HostCommandResult = {
150+
stdout: '[Fail]Not match target founded, check connect-key please',
151+
stderr: '',
152+
exitCode: 0,
153+
};
154+
155+
function scriptUninstallCommands(
156+
responses: Readonly<{ dump: HostCommandResult; probe?: HostCommandResult }>,
157+
): HostCommandRunner {
158+
const run = vi.fn(async (request: { executable: string; args: readonly string[] }) => {
159+
if (request.args.includes('dump')) return responses.dump;
160+
if (request.args.includes('true')) return responses.probe ?? emptyAnswer;
161+
return emptyAnswer;
162+
});
163+
return { which: async () => undefined, run } as HostCommandRunner;
164+
}
165+
166+
test('uninstall reports an absent record as nothing removed once the transport proves alive', async () => {
167+
const commands = scriptUninstallCommands({ dump: absentBundleAnswer });
143168
const signal = new AbortController().signal;
144169
const operations = createHarmonyAppDeploymentOperations({ commands, device, signal });
145170

146171
await expect(operations.uninstallApp?.({ app: 'com.example.app' })).resolves.toEqual({
147172
wasInstalled: false,
148173
});
149-
expect(run).toHaveBeenCalledTimes(1);
150-
expect(run).toHaveBeenCalledWith(expect.objectContaining({ allowFailure: true }), signal);
174+
expect(commands.run).toHaveBeenCalledTimes(2);
175+
expect(commands.run).toHaveBeenNthCalledWith(
176+
2,
177+
expect.objectContaining({ args: ['-t', device.id, 'shell', 'true'] }),
178+
signal,
179+
);
151180
});
152181

182+
test.each([
183+
[
184+
'an unreachable target that hdc answers while exiting zero',
185+
{ dump: unreachableAnswer, probe: unreachableAnswer },
186+
2,
187+
],
188+
[
189+
'a dump that exits non-zero on a dead transport',
190+
{
191+
dump: { stdout: '[Fail]Device not connected', stderr: '', exitCode: 1 },
192+
probe: { stdout: '[Fail]Device not connected', stderr: '', exitCode: 1 },
193+
},
194+
2,
195+
],
196+
['a dump killed before an answer', { dump: { stdout: '', stderr: '', exitCode: null } }, 1],
197+
] as const)(
198+
'uninstall refuses to claim removal for %s',
199+
async (_name, responses, expectedCalls) => {
200+
const commands = scriptUninstallCommands(responses);
201+
const signal = new AbortController().signal;
202+
const operations = createHarmonyAppDeploymentOperations({ commands, device, signal });
203+
204+
await expect(operations.uninstallApp?.({ app: 'com.example.app' })).rejects.toMatchObject({
205+
code: 'COMMAND_FAILED',
206+
});
207+
expect(commands.run).toHaveBeenCalledTimes(expectedCalls);
208+
expect(commands.run).not.toHaveBeenCalledWith(
209+
expect.objectContaining({ args: expect.arrayContaining(['uninstall']) }),
210+
signal,
211+
);
212+
},
213+
);
214+
153215
test('uninstall refuses a blank bundle name', async () => {
154216
const run = vi.fn();
155217
const commands = { which: async () => undefined, run } as HostCommandRunner;

‎packages/platform-harmonyos/src/deployment/runtime.ts‎

Lines changed: 47 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -46,12 +46,19 @@ export function createHarmonyAppDeploymentOperations(params: {
4646
signal: AbortSignal;
4747
}): Partial<AppDeploymentRuntimeOperations> {
4848
const facts = harmonyAppDeploymentFacts(params.device);
49-
if (!facts.deployApp.available) return Object.freeze({});
5049
return Object.freeze({
51-
deployApp: async (input: AppDeploymentInput) =>
52-
await deployHarmonyApp(params.commands, params.device, input, params.signal),
53-
uninstallApp: async (input: AppUninstallInput) =>
54-
await uninstallHarmonyApp(params.commands, params.device, input, params.signal),
50+
...(facts.deployApp.available
51+
? {
52+
deployApp: async (input: AppDeploymentInput) =>
53+
await deployHarmonyApp(params.commands, params.device, input, params.signal),
54+
}
55+
: {}),
56+
...(facts.uninstallApp.available
57+
? {
58+
uninstallApp: async (input: AppUninstallInput) =>
59+
await uninstallHarmonyApp(params.commands, params.device, input, params.signal),
60+
}
61+
: {}),
5562
});
5663
}
5764

@@ -70,12 +77,34 @@ async function uninstallHarmonyApp(
7077
const dump = await runHdcShell(commands, device, ['bm', 'dump', '-n', bundleId], signal, {
7178
allowFailure: true,
7279
});
73-
if (dump.exitCode !== 0 || !parseBundleDump(dump.stdout)) return { wasInstalled: false };
80+
if (!parseBundleDump(dump.stdout)) {
81+
// hdc reports an unreachable target through stdout while still exiting zero, so an
82+
// absent bundle record is benign only when the shell transport itself proves alive.
83+
if (dump.exitCode === null || !(await isHarmonyShellTransportAlive(commands, device, signal))) {
84+
throw new AppError('COMMAND_FAILED', `Could not probe the installed state of ${bundleId}`, {
85+
exitCode: dump.exitCode,
86+
stdout: dump.stdout,
87+
stderr: dump.stderr,
88+
hint: 'Confirm the device connection, then check the bundle name through bm dump -a.',
89+
});
90+
}
91+
return { wasInstalled: false };
92+
}
7493
await runHdcShell(commands, device, ['bm', 'uninstall', '-n', bundleId], signal);
7594
return { wasInstalled: true, packageName: bundleId };
7695
}
7796

78-
/** A bundle is present when `bm dump -n` exits zero with its JSON record. */
97+
/** Answers whether hdc can reach the target at all, independent of any remote command. */
98+
async function isHarmonyShellTransportAlive(
99+
commands: HostCommandRunner,
100+
device: DeviceInfo,
101+
signal: AbortSignal,
102+
): Promise<boolean> {
103+
const probe = await runHdcShell(commands, device, ['true'], signal, { allowFailure: true });
104+
return probe.exitCode === 0 && probe.stdout.trim().length === 0;
105+
}
106+
107+
/** Parses the JSON bundle record out of one `bm dump -n` output. */
79108
function parseBundleDump(rawOutput: string): Record<string, unknown> | undefined {
80109
const jsonStart = rawOutput.indexOf('{');
81110
if (jsonStart === -1) return undefined;
@@ -167,22 +196,17 @@ async function openHarmonyApp(
167196
}
168197

169198
function parseLaunchTarget(rawOutput: string): { ability: string; module?: string } | undefined {
170-
const jsonStart = rawOutput.indexOf('{');
171-
if (jsonStart === -1) return undefined;
172-
try {
173-
const dump = JSON.parse(rawOutput.slice(jsonStart)) as {
174-
hapModuleInfos?: Array<{ mainElementName?: string; moduleName?: string }>;
175-
};
176-
const module = dump.hapModuleInfos?.find((item) => item.mainElementName);
177-
return module?.mainElementName
178-
? {
179-
ability: module.mainElementName,
180-
...(module.moduleName ? { module: module.moduleName } : {}),
181-
}
182-
: undefined;
183-
} catch {
184-
return undefined;
185-
}
199+
const modules = parseBundleDump(rawOutput)?.hapModuleInfos;
200+
if (!Array.isArray(modules)) return undefined;
201+
const module = (modules as Array<{ mainElementName?: string; moduleName?: string }>).find(
202+
(item) => item.mainElementName,
203+
);
204+
return module?.mainElementName
205+
? {
206+
ability: module.mainElementName,
207+
...(module.moduleName ? { module: module.moduleName } : {}),
208+
}
209+
: undefined;
186210
}
187211

188212
async function runHdc(

0 commit comments

Comments
 (0)