Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
128 changes: 128 additions & 0 deletions docs/evidence/harmonyos-managed-platform-2026-11-20.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,128 @@
# HarmonyOS managed platform plugin — packed-plugin evidence (2026-11-20)

Head: `refactor/0.22-harmonyos-platform-plugin`. Issue #4317, PR #4857.

## Live HarmonyOS target: not available on this host

The host has the toolchain but no target, so no real device or emulator was driven for this change.

| Check | Result |
| --- | --- |
| `hdc` present | Yes — `/Applications/DevEco-Studio.app/Contents/sdk/default/openharmony/toolchains/hdc` (with `DEVECO_SDK_HOME=/Applications/DevEco-Studio.app/Contents/sdk`) |
| `hdc list targets` | `[Empty]` (re-checked after the first run) |
| Startable emulator image | None. `/Applications/DevEco-Studio.app/Contents/tools/emulator` carries the emulator binary, and there is no image directory (`~/.Huawei` and `~/Library/Huawei` do not exist; the only Huawei support directory is `Library/Application Support/Huawei/DevEcoStudio5.1`, which holds IDE settings). Downloading an image needs the IDE's signed-in account and its license acceptance, which is not something this run can do unattended. |

No live-device claim is made anywhere in this PR. The device-facing behavior is covered by the packed
fixture below plus the plugin's unit coverage of every HDC argv.

## Packed plugin, one stub HDC, reachable only through `HDC_SDK_PATH`

`packages/platform-harmonyos/test/package-smoke.mjs` runs this sequence as a gate inside
`pnpm run check:package`: `devices`, `open`, `snapshot -i`, `screenshot`, `press` and `close`, each
asserted on its CLI reply and on the argv the stub recorded. What follows is a manual run of the same
sequence against this host, kept because it shows the raw replies and the exec trace the plugin's
commands land in.

Setup: a scratch project, an isolated store (`AGENT_DEVICE_HOME`, `AGENT_DEVICE_STATE_DIR`,
`AGENT_DEVICE_CLAIMS_DIR` under scratch), `PATH` reduced to the Node directory, `/usr/bin` and
`/bin`, and the three documented toolchain roots unset except `HDC_SDK_PATH`. The stub `hdc` is
written into that root only, so any call that reaches it came from the plugin's own root probing and
not from a host `PATH` lookup. The core was packed and installed, then
`agent-device plugins add ./harmonyos.tgz`.

```
########## agent-device devices --platform harmonyos --json
{
"success": true,
"data": {
"devices": [
{ "platform": "harmonyos", "id": "127.0.0.1:5555", "name": "StubPhone",
"kind": "device", "target": "mobile", "booted": true }
]
}
}

########## agent-device open com.example.app --platform harmonyos --json
{
"success": true,
"data": {
"session": "default",
"appName": "com.example.app",
"appBundleId": "com.example.app",
"selection": { "reason": "single-booted-local", "source": "local", "candidateCount": 1 },
"platform": "harmonyos",
"target": "mobile",
"device": "StubPhone",
"id": "127.0.0.1:5555",
"message": "Opened: com.example.app"
}
}

########## agent-device snapshot -i --platform harmonyos --json
{
"success": true,
"data": {
"nodes": [
{ "index": 0, "type": "Button", "value": "Continue",
"rect": { "x": 84, "y": 1127, "width": 1088, "height": 168 },
"enabled": true, "visibleToUser": true, "hittable": true, "depth": 1,
"ref": "e1", "kind": "button" }
],
"visibility": { "partial": false, "visibleNodeCount": 1, "totalNodeCount": 1 },
"keyboard": { "kind": "unmeasurable", "reason": "keyboard-window-not-listed" },
"snapshotDiagnostics": {
"stats": { "count": 1, "platform": "harmonyos", "backends": { "harmonyos-uitest": 1 } }
}
}
}

########## agent-device press 100 200 --platform harmonyos --json
{ "success": true, "data": { "x": 100, "y": 200, "message": "Tapped (100, 200)", "targetKind": "point" } }

########## agent-device screenshot /tmp/hdckit/shot.png --platform harmonyos --json
{ "success": true, "data": { "path": "/tmp/hdckit/shot.png" } }

########## agent-device close --platform harmonyos --json
{ "success": true, "data": { "session": "default", "message": "Closed: default" } }
```

Every HDC call the packed bundle made, with the `PATH` it was handed (the stub's own record):

```
ARGS: list targets
ARGS: -t 127.0.0.1:5555 shell param get const.product.name
ARGS: -t 127.0.0.1:5555 shell param get const.build.characteristics
ARGS: -t 127.0.0.1:5555 shell bm dump -n com.example.app
ARGS: -t 127.0.0.1:5555 shell aa start -a EntryAbility -b com.example.app -m entry
ARGS: -t 127.0.0.1:5555 shell uitest dumpLayout -p /data/local/tmp/agent-device-layout-….json
ARGS: -t 127.0.0.1:5555 file recv /data/local/tmp/agent-device-layout-….json …/layout.json
ARGS: -t 127.0.0.1:5555 shell rm -f /data/local/tmp/agent-device-layout-….json
ARGS: -t 127.0.0.1:5555 shell hidumper -s WindowManagerService -a -a
ARGS: -t 127.0.0.1:5555 shell uitest uiInput click 100 200
ARGS: -t 127.0.0.1:5555 shell snapshot_display -f /data/local/tmp/agent-device-screen-….jpeg
ARGS: -t 127.0.0.1:5555 file recv /data/local/tmp/agent-device-screen-….jpeg /tmp/hdckit/shot.png
ARGS: -t 127.0.0.1:5555 shell rm -f /data/local/tmp/agent-device-screen-….jpeg
```

Each line's recorded `PATH` was `/tmp/hdckit:` followed by the host `PATH`: the plugin prepends the
root it resolved, so the calls reached the stub while the core named no HarmonyOS configuration.

The same request under `--debug` shows the spawns in the request's own exec trace, which is what
binding to the setup host buys — a plugin that spawned through its bundled host-kit copy would trace
nothing here:

```
{"phase":"exec_command","requestId":"6a550a1ab3605fb3","command":"press","data":{"execId":"cc614109-…","command":"hdc","event":"spawn","pid":49635,"timeoutMs":15000}}
{"phase":"exec_command","requestId":"6a550a1ab3605fb3","command":"press","data":{"execId":"cc614109-…","command":"hdc","event":"exit","pid":49635,"exitCode":0,"signal":null}}
{"phase":"request_success","requestId":"6a550a1ab3605fb3","command":"press"}
```

## What this proves and what it does not

Proves: the packed plugin resolves HDC from `HDC_SDK_PATH` through the host it was set up with, runs
discovery, launch, snapshot, interaction, capture and close on that route, and its commands are
traceable to the request that asked for them.

Does not prove anything about a real HarmonyOS device: no target exists on this host, so device-side
behavior (real layout shape, real `aa start` output, real capture encoding, keyboard measurement) is
unchanged from before this refactor and unverified by it.
3 changes: 1 addition & 2 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -166,7 +166,7 @@
"depgraph:test": "node --experimental-strip-types scripts/node-test-tmpdir.ts --experimental-strip-types --test scripts/depgraph/model.test.ts scripts/depgraph/entries.test.ts scripts/depgraph/import-graph.test.ts scripts/depgraph/affected.test.ts scripts/depgraph/structure-summary.test.ts tools/depgraph-view/*.test.mjs",
"check:production-exports": "fallow dead-code --config fallow-production-exports.json --production --unused-exports --fail-on-issues",
"check:bundle-owner-files": "node --experimental-strip-types scripts/check-bundle-owner-files.ts",
"check:package": "node --experimental-strip-types scripts/node-test-tmpdir.ts --experimental-strip-types --test packages/maestro/test/package-artifact.test.mjs packages/maestro/test/package-smoke.mjs packages/replay/test/package-smoke.mjs packages/platform-web/test/package-smoke.mjs packages/platform-vega/test/package-smoke.mjs && node --experimental-strip-types scripts/check-package.ts",
"check:package": "node --experimental-strip-types scripts/node-test-tmpdir.ts --experimental-strip-types --test packages/maestro/test/package-artifact.test.mjs packages/maestro/test/package-smoke.mjs packages/replay/test/package-smoke.mjs packages/platform-web/test/package-smoke.mjs packages/platform-vega/test/package-smoke.mjs packages/platform-harmonyos/test/package-smoke.mjs && node --experimental-strip-types scripts/check-package.ts",
"check:provider-plugin": "node scripts/check-provider-plugin.mjs",
"check:command-docs": "vitest run --project unit-core test/repo-guards/command-doc-coverage.test.ts test/repo-guards/command-doc-generated-blocks.test.ts",
"generate:command-docs": "node --experimental-strip-types scripts/command-docs/generate.ts --write",
Expand Down Expand Up @@ -328,7 +328,6 @@
"@agent-device/kernel": "workspace:*",
"@agent-device/platform-android": "workspace:*",
"@agent-device/platform-apple": "workspace:*",
"@agent-device/platform-harmonyos": "workspace:*",
"@agent-device/platform-linux": "workspace:*",
"@agent-device/plugins": "workspace:*",
"@agent-device/provider-limrun": "workspace:*",
Expand Down
1 change: 1 addition & 0 deletions packages/build-config/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@
}
},
"devDependencies": {
"@agent-device/test-kit": "workspace:*",
"rolldown": "1.2.5"
}
}
120 changes: 120 additions & 0 deletions packages/build-config/src/index.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,120 @@
import { strict as assert } from 'node:assert';
import { mkdtempForTestSync } from '@agent-device/test-kit';
import fs from 'node:fs';
import path from 'node:path';
import { pathToFileURL } from 'node:url';
import { test } from 'vitest';
import { assertManagedPlatformPluginFactory } from './index.ts';

const HARMONYOS_CLAIM = { apiVersion: 3, platform: 'harmonyos' };

/** Writes a `package.json` holding one managed platform claim and returns its URL, as a build calls it. */
function claimManifestUrl(claim: { apiVersion: unknown; platform?: unknown }): URL {
const directory = mkdtempForTestSync('build-config-claim-');
const file = path.join(directory, 'package.json');
fs.writeFileSync(file, JSON.stringify({ name: '@agent-device/example', 'agent-device': claim }));
return pathToFileURL(file);
}

/** One factory shaped like a managed platform plugin's default export, with the pair a case names. */
function factoryContribution(
apiVersion: unknown,
contributes: readonly { kind: unknown; family: unknown }[],
) {
return () => ({ apiVersion, contributes });
}

const validFactory = factoryContribution(3, [{ kind: 'platform', family: 'harmonyos' }]);

test('accepts a factory whose pair matches the package claim', () => {
assert.doesNotThrow(() =>
assertManagedPlatformPluginFactory(
claimManifestUrl(HARMONYOS_CLAIM),
validFactory,
'HarmonyOS',
),
);
});

test('rejects a factory on an api version the package does not claim', () => {
assert.throws(
() =>
assertManagedPlatformPluginFactory(
claimManifestUrl(HARMONYOS_CLAIM),
factoryContribution(2, [{ kind: 'platform', family: 'harmonyos' }]),
'HarmonyOS',
),
/managed HarmonyOS factory must match its package claim/,
);
});

test('rejects a factory contributing the wrong kind', () => {
assert.throws(
() =>
assertManagedPlatformPluginFactory(
claimManifestUrl(HARMONYOS_CLAIM),
factoryContribution(3, [{ kind: 'provider', family: 'harmonyos' }]),
'HarmonyOS',
),
/managed HarmonyOS factory must match its package claim/,
);
});

test('rejects a factory contributing a family the package does not claim', () => {
assert.throws(
() =>
assertManagedPlatformPluginFactory(
claimManifestUrl(HARMONYOS_CLAIM),
factoryContribution(3, [{ kind: 'platform', family: 'vega' }]),
'HarmonyOS',
),
/managed HarmonyOS factory must match its package claim/,
);
});

for (const [name, contributes] of [
['no contribution', []],
[
'two contributions',
[
{ kind: 'platform', family: 'harmonyos' },
{ kind: 'platform', family: 'vega' },
],
],
] as const) {
test(`rejects a factory contributing ${name}`, () => {
assert.throws(
() =>
assertManagedPlatformPluginFactory(
claimManifestUrl(HARMONYOS_CLAIM),
factoryContribution(3, contributes),
'HarmonyOS',
),
/managed HarmonyOS factory must match its package claim/,
);
});
}

test('rejects a manifest that carries no platform claim', () => {
assert.throws(
() =>
assertManagedPlatformPluginFactory(
claimManifestUrl({ apiVersion: 3 }),
validFactory,
'HarmonyOS',
),
/managed HarmonyOS factory must match its package claim/,
);
});

test('rejects a location the bundler cannot read', () => {
// The guard reads the manifest off the filesystem, so a non-file URL fails the read rather than
// passing an unchecked factory.
assert.throws(() =>
assertManagedPlatformPluginFactory(
new URL('https://example.test/package.json'),
validFactory,
'HarmonyOS',
),
);
});
47 changes: 47 additions & 0 deletions packages/build-config/src/index.ts
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
import { readFileSync } from 'node:fs';
import type { InputOptions } from 'rolldown';

export const strictBundlerInputOptions: InputOptions = {
Expand All @@ -19,3 +20,49 @@ export const providerPluginBuildConfig = {
deps: { alwaysBundle: [/^@agent-device\//] },
inputOptions: strictBundlerInputOptions,
};

/**
* The bundler options every managed platform plugin package builds with: its own `agent-device`
* entry, emitted types, and `agent-device/plugins` kept external because the running core owns
* that contract. Each package's `build.mjs` spreads this and calls `build`.
*/
export const managedPlatformPluginBuildConfig = {
...providerPluginBuildConfig,
config: false,
dts: true,
tsconfig: '../../tsconfig.lib.json',
deps: {
...providerPluginBuildConfig.deps,
neverBundle: ['agent-device/plugins'],
},
};

/**
* Checks a managed platform plugin's default-exported factory against the `agent-device` claim in
* its own package.json — the same pair the loader reads at install time, so a package that
* contributes another family, or a stale contract version, fails its build rather than its users.
* The caller passes its `package.json` URL and the factory it imported.
*/
export function assertManagedPlatformPluginFactory(
packageJsonUrl: URL,
factory: () => {
apiVersion: unknown;
contributes: readonly { kind: unknown; family: unknown }[];
},
label: string,
): void {
const manifest = JSON.parse(readFileSync(packageJsonUrl, 'utf8'))['agent-device'] as {
apiVersion: unknown;
platform: unknown;
};
const { apiVersion, contributes } = factory();
const [platform] = contributes;
if (
apiVersion !== manifest.apiVersion ||
contributes.length !== 1 ||
platform?.kind !== 'platform' ||
platform.family !== manifest.platform
) {
throw new Error(`The managed ${label} factory must match its package claim`);
}
}
2 changes: 1 addition & 1 deletion packages/build-config/tsconfig.json
Original file line number Diff line number Diff line change
Expand Up @@ -10,5 +10,5 @@
"tsBuildInfoFile": "./dist-types/index.tsbuildinfo"
},
"include": ["src"],
"references": []
"references": [{ "path": "../test-kit" }]
}
6 changes: 3 additions & 3 deletions packages/capture-kit/src/app-log-pid-process.ts
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ export type PidScopedAppLogProcessOptions = Readonly<{
processStart: AppLogProcessStart;
setupSignal: AbortSignal;
resolvePid(signal?: AbortSignal): Promise<string>;
command(pid: string): AppLogProcessCommand;
command(pid: string): AppLogProcessCommand | Promise<AppLogProcessCommand>;
cleanupFailureMessage: string;
}>;

Expand All @@ -42,7 +42,7 @@ export async function createPidScopedAppLogProcess(
try {
active = await options.processStart(
{
command: options.command(initialPid),
command: await options.command(initialPid),
output,
markerPath: options.pidPath,
},
Expand Down Expand Up @@ -79,7 +79,7 @@ export async function createPidScopedAppLogProcess(
resolvePid: async () => await options.resolvePid(),
startProcess: async (pid) =>
await options.processStart({
command: options.command(pid),
command: await options.command(pid),
output,
markerPath: options.pidPath,
}),
Expand Down
Loading
Loading