Skip to content

Commit e36de17

Browse files
strzhaoclaude
andcommitted
fix(harmonyos): answer uninstall state from the shared bundle inventory
bm dump -n JSON plus a live-transport probe kept a second interpreter of bundle state, and an unparseable dump read as a completed removal. Both probes now read the bm dump -a inventory through the shared parseHarmonyBundleList: one non-empty list proves the transport answered and answers membership; a failed exit refuses through execFailureDetails and an unreadable answer refuses instead of counting as absence. The transport probe and its dead exit-code guard are gone. Co-Authored-By: Claude Code <[email protected]>
1 parent 6da80f0 commit e36de17

5 files changed

Lines changed: 115 additions & 150 deletions

File tree

‎docs/evidence/harmony-uninstall-transport-classification-2026-11-07.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,9 @@
11
# HarmonyOS uninstall transport classification, 2026-11-07
22

33
Source under review: `forge/harmony-uninstall` at `7c0be71b5f7ee40101d9637d438f364114338dc6`.
4-
The classification fix landed as a follow-up commit on the same branch.
4+
The classification fix landed as a follow-up commit on the same branch,
5+
`6541f8b6b` (`fix(harmonyos): classify uninstall probe through a live transport`),
6+
which is the head this note's behavior corresponds to.
57
Device: physical HarmonyOS handset, hdc serial `77TYD26826028730`.
68
hdc: local command-line tools at `~/.local/harmony/command-line-tools/sdk/default/openharmony/toolchains/hdc`.
79
Purpose: record the observable `bm dump -n` shapes that decide how the uninstall probe separates an absent bundle from a dead transport.

‎docs/evidence/harmonyos-uninstall-2026-11-08.md‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ hdc -t 77TYD26826028730 shell "bm dump -n com.stringzhao.adtrajdriver"
2020
hdc -t 77TYD26826028730 shell "bm dump -n com.example.never.existed"
2121
```
2222

23-
## Observed output (verbatim)
23+
## Observed output (excerpts; the bundle record is truncated at the ellipsis)
2424

2525
Installed bundle answers with the metadata JSON:
2626

@@ -51,3 +51,8 @@ error: failed to get information and the parameters may be wrong.
5151
`bm dump` misses and `bm` failures carry their verdict in stdout text at exit
5252
code 0 on this build (7.0.0.111). `install`/`uninstall` success detection keys
5353
on stream content; an exit-code check would read every failure as success.
54+
55+
Addendum 2026-11-13: the uninstall route no longer interprets this per-bundle
56+
dump. Both probes read the `bm dump -a` inventory through the shared
57+
`parseHarmonyBundleList`, and an unreadable answer refuses instead of counting
58+
as absence; these shapes remain the recorded reason unknown reads cannot pass.

‎docs/evidence/harmonyos-uninstall-verified-2026-11-12.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,8 @@ agent-device uninstall com.stringzhao.adtrajdriver --platform harmonyos --serial
2525

2626
## Observed output (verbatim)
2727

28-
Install admits the bundle:
28+
Abridged install answer (the full payload also carries the resolved
29+
`appPath`, elided here for length):
2930

3031
```json
3132
{

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

Lines changed: 65 additions & 107 deletions
Original file line numberDiff line numberDiff line change
@@ -99,21 +99,41 @@ test('exposes HarmonyOS deployApp and uninstallApp after fact admission', async
9999
).toEqual({});
100100
});
101101

102-
const installedDump: HostCommandResult = {
103-
stdout: '{"hapModuleInfos":[{"mainElementName":"MainAbility","moduleName":"entry"}]}',
102+
/** Answers each call in order; the last answer repeats when a script runs past its end. */
103+
function scriptAnswers(answers: readonly HostCommandResult[]) {
104+
let next = 0;
105+
return async (): Promise<HostCommandResult> => answers[Math.min(next++, answers.length - 1)]!;
106+
}
107+
108+
const bundleInventory = (entries: string[]): HostCommandResult => ({
109+
stdout: [...entries, ''].join('\n'),
110+
stderr: '',
111+
exitCode: 0,
112+
});
113+
114+
const uninstallAnswer: HostCommandResult = {
115+
stdout: 'uninstall bundle successfully.',
116+
stderr: '',
117+
exitCode: 0,
118+
};
119+
120+
/** `bm dump -a` inventory answers: one bundle name per line, the shared parseHarmonyBundleList shape. */
121+
const installedInventory = bundleInventory(['com.example.other', 'com.example.app']);
122+
const absentInventory = bundleInventory(['com.example.other']);
123+
124+
/**
125+
* Shapes recorded on physical hardware: bm prints its per-bundle failures into
126+
* stdout while the host exit code stays 0, so this answer is an unknown read,
127+
* never a proof of absence.
128+
*/
129+
const unknownInventoryRead: HostCommandResult = {
130+
stdout: 'error: failed to get information and the parameters may be wrong.',
104131
stderr: '',
105132
exitCode: 0,
106133
};
107134

108135
test('uninstall removes an installed HarmonyOS bundle through bm uninstall', async () => {
109-
const uninstallAnswer: HostCommandResult = {
110-
stdout: 'uninstall bundle successfully.',
111-
stderr: '',
112-
exitCode: 0,
113-
};
114-
const run = vi.fn(
115-
scriptAnswers([installedDump, uninstallAnswer, absentBundleAnswer, emptyAnswer]),
116-
);
136+
const run = vi.fn(scriptAnswers([installedInventory, uninstallAnswer, absentInventory]));
117137
const commands = { which: async () => undefined, run } as HostCommandRunner;
118138
const signal = new AbortController().signal;
119139
const operations = createHarmonyAppDeploymentOperations({ commands, device, signal });
@@ -122,12 +142,12 @@ test('uninstall removes an installed HarmonyOS bundle through bm uninstall', asy
122142
wasInstalled: true,
123143
packageName: 'com.example.app',
124144
});
125-
expect(run).toHaveBeenCalledTimes(4);
145+
expect(run).toHaveBeenCalledTimes(3);
126146
expect(run).toHaveBeenNthCalledWith(
127147
1,
128148
expect.objectContaining({
129149
executable: 'hdc',
130-
args: ['-t', device.id, 'shell', 'bm', 'dump', '-n', 'com.example.app'],
150+
args: ['-t', device.id, 'shell', 'bm', 'dump', '-a'],
131151
}),
132152
signal,
133153
);
@@ -143,24 +163,30 @@ test('uninstall removes an installed HarmonyOS bundle through bm uninstall', asy
143163
3,
144164
expect.objectContaining({
145165
executable: 'hdc',
146-
args: ['-t', device.id, 'shell', 'bm', 'dump', '-n', 'com.example.app'],
166+
args: ['-t', device.id, 'shell', 'bm', 'dump', '-a'],
147167
}),
148168
signal,
149169
);
150-
expect(run).toHaveBeenNthCalledWith(
151-
4,
152-
expect.objectContaining({ args: ['-t', device.id, 'shell', 'true'] }),
170+
});
171+
172+
test('uninstall reports an absent bundle without uninstalling', async () => {
173+
const run = vi.fn(scriptAnswers([absentInventory]));
174+
const commands = { which: async () => undefined, run } as HostCommandRunner;
175+
const signal = new AbortController().signal;
176+
const operations = createHarmonyAppDeploymentOperations({ commands, device, signal });
177+
178+
await expect(operations.uninstallApp?.({ app: 'com.example.app' })).resolves.toEqual({
179+
wasInstalled: false,
180+
});
181+
expect(run).toHaveBeenCalledTimes(1);
182+
expect(run).not.toHaveBeenCalledWith(
183+
expect.objectContaining({ args: expect.arrayContaining(['uninstall']) }),
153184
signal,
154185
);
155186
});
156187

157-
test('uninstall refuses to claim removal when the bundle record survives bm uninstall', async () => {
158-
const lyingUninstallAnswer: HostCommandResult = {
159-
stdout: 'uninstall bundle successfully.',
160-
stderr: '',
161-
exitCode: 0,
162-
};
163-
const run = vi.fn(scriptAnswers([installedDump, lyingUninstallAnswer, installedDump]));
188+
test('uninstall refuses to claim removal when the inventory still lists the bundle', async () => {
189+
const run = vi.fn(scriptAnswers([installedInventory, uninstallAnswer, installedInventory]));
164190
const commands = { which: async () => undefined, run } as HostCommandRunner;
165191
const signal = new AbortController().signal;
166192
const operations = createHarmonyAppDeploymentOperations({ commands, device, signal });
@@ -171,109 +197,41 @@ test('uninstall refuses to claim removal when the bundle record survives bm unin
171197
details: { stdout: 'uninstall bundle successfully.' },
172198
});
173199
expect(run).toHaveBeenCalledTimes(3);
174-
expect(run).not.toHaveBeenCalledWith(
175-
expect.objectContaining({ args: ['-t', device.id, 'shell', 'true'] }),
176-
signal,
177-
);
178200
});
179201

180-
/** Answers each call in order; the last answer repeats when a script runs past its end. */
181-
function scriptAnswers(answers: readonly HostCommandResult[]) {
182-
let next = 0;
183-
return async (): Promise<HostCommandResult> => answers[Math.min(next++, answers.length - 1)]!;
184-
}
185-
186-
const emptyAnswer: HostCommandResult = { stdout: '', stderr: '', exitCode: 0 };
187-
188-
/**
189-
* Shapes recorded on physical hardware: an absent bundle answers through bm with an
190-
* error record, while an unreachable target answers through hdc itself and still
191-
* exits zero. The second probe call classifies the two.
192-
*/
193-
const absentBundleAnswer: HostCommandResult = {
194-
stdout: 'error: failed to get information and the parameters may be wrong.',
195-
stderr: '',
196-
exitCode: 0,
197-
};
198-
const unreachableAnswer: HostCommandResult = {
199-
stdout: '[Fail]Not match target founded, check connect-key please',
200-
stderr: '',
201-
exitCode: 0,
202-
};
203-
204-
function scriptUninstallCommands(
205-
responses: Readonly<{ dump: HostCommandResult; probe?: HostCommandResult }>,
206-
): HostCommandRunner {
207-
const run = vi.fn(async (request: { executable: string; args: readonly string[] }) => {
208-
if (request.args.includes('dump')) return responses.dump;
209-
if (request.args.includes('true')) return responses.probe ?? emptyAnswer;
210-
return emptyAnswer;
211-
});
212-
return { which: async () => undefined, run } as HostCommandRunner;
213-
}
214-
215-
test('uninstall reports an absent record as nothing removed once the transport proves alive', async () => {
216-
const commands = scriptUninstallCommands({ dump: absentBundleAnswer });
202+
test('uninstall refuses an inventory read it cannot interpret', async () => {
203+
const run = vi.fn(scriptAnswers([unknownInventoryRead]));
204+
const commands = { which: async () => undefined, run } as HostCommandRunner;
217205
const signal = new AbortController().signal;
218206
const operations = createHarmonyAppDeploymentOperations({ commands, device, signal });
219207

220-
await expect(operations.uninstallApp?.({ app: 'com.example.app' })).resolves.toEqual({
221-
wasInstalled: false,
208+
await expect(operations.uninstallApp?.({ app: 'com.example.app' })).rejects.toMatchObject({
209+
code: 'COMMAND_FAILED',
210+
message: 'Could not read the installed bundle inventory',
222211
});
223-
expect(commands.run).toHaveBeenCalledTimes(2);
224-
expect(commands.run).toHaveBeenNthCalledWith(
225-
2,
226-
expect.objectContaining({ args: ['-t', device.id, 'shell', 'true'] }),
212+
expect(run).toHaveBeenCalledTimes(1);
213+
expect(run).not.toHaveBeenCalledWith(
214+
expect.objectContaining({ args: expect.arrayContaining(['uninstall']) }),
227215
signal,
228216
);
229217
});
230218

231-
test.each([
232-
[
233-
'an unreachable target that hdc answers while exiting zero',
234-
{ dump: unreachableAnswer, probe: unreachableAnswer },
235-
2,
236-
],
237-
[
238-
'a dump that exits non-zero on a dead transport',
239-
{
240-
dump: { stdout: '[Fail]Device not connected', stderr: '', exitCode: 1 },
241-
probe: { stdout: '[Fail]Device not connected', stderr: '', exitCode: 1 },
242-
},
243-
2,
244-
],
245-
['a dump killed before an answer', { dump: { stdout: '', stderr: '', exitCode: null } }, 1],
246-
] as const)(
247-
'uninstall refuses to claim removal for %s',
248-
async (_name, responses, expectedCalls) => {
249-
const commands = scriptUninstallCommands(responses);
250-
const signal = new AbortController().signal;
251-
const operations = createHarmonyAppDeploymentOperations({ commands, device, signal });
252-
253-
await expect(operations.uninstallApp?.({ app: 'com.example.app' })).rejects.toMatchObject({
254-
code: 'COMMAND_FAILED',
255-
});
256-
expect(commands.run).toHaveBeenCalledTimes(expectedCalls);
257-
expect(commands.run).not.toHaveBeenCalledWith(
258-
expect.objectContaining({ args: expect.arrayContaining(['uninstall']) }),
259-
signal,
260-
);
261-
},
262-
);
263-
264-
test('uninstall refuses to claim removal when the post-uninstall dump cannot be verified', async () => {
219+
test('uninstall refuses to claim removal when the inventory probe exits non-zero', async () => {
265220
const run = vi.fn(
266-
scriptAnswers([installedDump, emptyAnswer, absentBundleAnswer, unreachableAnswer]),
221+
scriptAnswers([
222+
{ stdout: '[Fail]Device not connected', stderr: '[Fail]Device not connected', exitCode: 1 },
223+
]),
267224
);
268225
const commands = { which: async () => undefined, run } as HostCommandRunner;
269226
const signal = new AbortController().signal;
270227
const operations = createHarmonyAppDeploymentOperations({ commands, device, signal });
271228

272229
await expect(operations.uninstallApp?.({ app: 'com.example.app' })).rejects.toMatchObject({
273230
code: 'COMMAND_FAILED',
274-
message: 'Could not verify the uninstall of com.example.app',
231+
message: 'Could not read the installed bundle inventory',
232+
details: { processExitError: true, exitCode: 1 },
275233
});
276-
expect(run).toHaveBeenCalledTimes(4);
234+
expect(run).toHaveBeenCalledTimes(1);
277235
});
278236

279237
test('uninstall refuses a blank bundle name', async () => {

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

Lines changed: 39 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,8 @@ import type { RuntimeOperationFact } from '@agent-device/contracts/platform-runt
1010
import type { DeviceInfo } from '@agent-device/kernel/device';
1111
import { deviceShellArgv, type ShellWord } from '@agent-device/kernel/device-shell';
1212
import { AppError } from '@agent-device/kernel/errors';
13+
import { execFailureDetails } from '@agent-device/host-kit/command';
14+
import { parseHarmonyBundleList } from '../app-lifecycle.ts';
1315
import { setTimeout as sleep } from 'node:timers/promises';
1416

1517
const available = Object.freeze({ available: true } as const);
@@ -74,22 +76,7 @@ async function uninstallHarmonyApp(
7476
hint: 'Pass the bundle name reported by bm dump, such as com.example.app.',
7577
});
7678
}
77-
const dump = await runHdcShell(commands, device, ['bm', 'dump', '-n', bundleId], signal, {
78-
allowFailure: true,
79-
});
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-
// exec-guard-allow: reachable at exit 0 — hdc reports unreachable targets through
85-
// stdout at exit zero, so processExitError would never fire; trio is probe context.
86-
throw new AppError('COMMAND_FAILED', `Could not probe the installed state of ${bundleId}`, {
87-
exitCode: dump.exitCode,
88-
stdout: dump.stdout,
89-
stderr: dump.stderr,
90-
hint: 'Confirm the device connection, then check the bundle name through bm dump -a.',
91-
});
92-
}
79+
if (!(await readBundleInventory(commands, device, signal)).includes(bundleId)) {
9380
return { wasInstalled: false };
9481
}
9582
const uninstall = await runHdcShell(
@@ -98,43 +85,55 @@ async function uninstallHarmonyApp(
9885
['bm', 'uninstall', '-n', bundleId],
9986
signal,
10087
);
101-
const after = await runHdcShell(commands, device, ['bm', 'dump', '-n', bundleId], signal, {
102-
allowFailure: true,
103-
});
104-
if (parseBundleDump(after.stdout)) {
105-
// bm prints its verdict into stdout at exit code 0, so only a second dump that no
106-
// longer finds the record proves the removal.
107-
// exec-guard-allow: reachable at exit 0 — bm reports the removal verdict in stdout
108-
// at exit 0, so the trio here documents bm's own answer rather than an exec failure;
109-
// stderr enrichment would only repeat the line the message already quotes.
88+
const remaining = await readBundleInventory(commands, device, signal);
89+
if (remaining.includes(bundleId)) {
90+
// bm prints its verdict into stdout at exit code 0, so only an inventory that no
91+
// longer lists the bundle proves the removal.
11092
throw new AppError('COMMAND_FAILED', `${bundleId} is still installed after bm uninstall`, {
11193
exitCode: uninstall.exitCode,
11294
stdout: uninstall.stdout,
11395
stderr: uninstall.stderr,
11496
hint: 'Read the bm uninstall output above for the bm reason; system and shared bundles refuse removal.',
11597
});
11698
}
117-
if (after.exitCode === null || !(await isHarmonyShellTransportAlive(commands, device, signal))) {
118-
// exec-guard-allow: reachable at exit 0 — a failed post-uninstall dump still exits
119-
// zero through hdc, so processExitError would never fire; trio is probe context.
120-
throw new AppError('COMMAND_FAILED', `Could not verify the uninstall of ${bundleId}`, {
121-
exitCode: after.exitCode,
122-
stdout: after.stdout,
123-
stderr: after.stderr,
124-
hint: 'Confirm the device connection, then check the bundle name through bm dump -a.',
125-
});
126-
}
12799
return { wasInstalled: true, packageName: bundleId };
128100
}
129101

130-
/** Answers whether hdc can reach the target at all, independent of any remote command. */
131-
async function isHarmonyShellTransportAlive(
102+
/**
103+
* The one bundle-state interpreter for the uninstall route: the Bundle Manager's own
104+
* inventory (`bm dump -a`) read through the shared `parseHarmonyBundleList`. A non-empty
105+
* list proves the transport answered and answers membership; a failed exit or an empty
106+
* read refuses instead of counting as absence, because a real device always lists its
107+
* system bundles.
108+
*/
109+
async function readBundleInventory(
132110
commands: HostCommandRunner,
133111
device: DeviceInfo,
134112
signal: AbortSignal,
135-
): Promise<boolean> {
136-
const probe = await runHdcShell(commands, device, ['true'], signal, { allowFailure: true });
137-
return probe.exitCode === 0 && probe.stdout.trim().length === 0;
113+
): Promise<string[]> {
114+
const inventory = await runHdcShell(commands, device, ['bm', 'dump', '-a'], signal, {
115+
allowFailure: true,
116+
timeoutMs: 15_000,
117+
});
118+
if (inventory.exitCode !== 0) {
119+
throw new AppError(
120+
'COMMAND_FAILED',
121+
'Could not read the installed bundle inventory',
122+
execFailureDetails(inventory),
123+
);
124+
}
125+
const bundles = parseHarmonyBundleList(inventory.stdout);
126+
if (bundles.length === 0) {
127+
// bm prints its failures into stdout at exit code 0, so an unparseable answer is an
128+
// unknown read, never a proof of absence.
129+
throw new AppError('COMMAND_FAILED', 'Could not read the installed bundle inventory', {
130+
exitCode: inventory.exitCode,
131+
stdout: inventory.stdout,
132+
stderr: inventory.stderr,
133+
hint: 'Confirm the device connection, then check bm dump -a output on the device.',
134+
});
135+
}
136+
return bundles;
138137
}
139138

140139
/** Parses the JSON bundle record out of one `bm dump -n` output. */

0 commit comments

Comments
 (0)