@oniroproject/core 0.12.0 → 0.14.0

package/dist/index.d.cts

@@ -83,7 +83,9 @@ declare class OniroError extends Error {
 declare class SdkNotInstalledError extends OniroError {
     readonly api: string;
     readonly expectedPath: string;
-    constructor(api: string, expectedPath: string);
+    readonly version?: string | undefined;
+    /** `version` is the release that ships `api` (e.g. `6.0` for API 20), when one is known. */
+    constructor(api: string, expectedPath: string, version?: string | undefined);
 }
 declare class CmdToolsNotInstalledError extends OniroError {
     readonly expectedPath: string;
@@ -240,6 +242,15 @@ declare function getHdcPath(config: ConfigProvider): string;
  */
 declare function getHvigorwPath(config: ConfigProvider, projectDir: string, platform?: NodeJS.Platform): string;
 
+/**
+ * The OpenHarmony SDK an OpenHarmony project builds against is missing, as a typed
+ * error naming the release to install, or null when it is installed or the project
+ * declares no numeric `compileSdkVersion`. hvigor looks for
+ * `<sdk home>/<compileSdkVersion>`, the home being `OHOS_BASE_SDK_HOME` or the
+ * project's `local.properties` `sdk.dir`, and otherwise fails late with
+ * `00308018 SDK path does not exist` / "SDK license agreement is not accepted".
+ */
+declare function findMissingProjectSdk(config: ConfigProvider, projectRoot: string): SdkNotInstalledError | null;
 /**
  * Detect the SDK API a project targets by reading `build-profile.json5`.
  * Returns the `compileSdkVersion` of the first declared product, or undefined
@@ -461,11 +472,28 @@ declare function installCmdTools(opts: InstallCmdToolsOptions): Promise<void>;
 interface CmdToolsStatus {
     installed: boolean;
     status: string;
+    /** Install directory (the configured `cmdToolsPath`). */
+    path: string;
+    /** Which SDK flavour the tools ship; see {@link detectCmdToolsFlavour}. Set when installed. */
+    flavour?: CmdToolsFlavour;
+    /** The hdc binary commands use, and whether it exists. */
+    hdc: {
+        path: string;
+        exists: boolean;
+    };
 }
+type CmdToolsFlavour = 'HarmonyOS' | 'OpenHarmony';
+/**
+ * The flavour of a command-line tools install: `HarmonyOS` when it bundles the
+ * HarmonyOS SDK (`sdk/default/hms`, as the Huawei developer-portal download
+ * does), otherwise `OpenHarmony`. codelinter only fully checks projects of its
+ * own flavour (`runtimeOS` in build-profile.json5).
+ */
+declare function detectCmdToolsFlavour(cmdToolsPath: string): CmdToolsFlavour;
 /**
- * Reports whether ohpm is present at the configured path, and if so its version.
- * Prefers reading `version.txt` (`# Version: x.y.z`) before falling back to executing
- * the binary with `-v`.
+ * Reports whether ohpm is present at the configured path, and if so its version,
+ * flavour, and the hdc binary in use. Prefers reading `version.txt`
+ * (`# Version: x.y.z`) before falling back to executing the binary with `-v`.
  */
 declare function getCmdToolsStatus(config: ConfigProvider): CmdToolsStatus;
 declare function isCmdToolsInstalled(config: ConfigProvider): boolean;
@@ -543,6 +571,14 @@ interface GenerateSigningConfigsOptions {
      * existing `allowed-acls` is left alone.
      */
     acls?: string[];
+    /**
+     * Privileges to write into the profile's `app-privilege-capabilities`, e.g.
+     * `AllowAppUsePrivilegeExtension` for an app that declares a privileged extension
+     * ability (else install fails with 9568344 "not allow use privilege extension"),
+     * `AllowAppMultiProcess` or `AllowAppDesktopIconHide`. When omitted, the
+     * template's value is left alone.
+     */
+    appPrivilegeCapabilities?: string[];
     /**
      * Keystore passwords written into the profile sign step and the build-profile
      * signingConfigs. Defaults to `'123456'` (the SDK's bundled OpenHarmony.p12
@@ -637,6 +673,26 @@ interface StartEmulatorOptions {
  */
 declare function startEmulator(opts: StartEmulatorOptions): Promise<void>;
 declare function stopEmulator(logger?: Logger): Promise<void>;
+interface EmulatorStatus {
+    installed: boolean;
+    /** The configured emulator directory. */
+    dir: string;
+    /** Whether an emulator QEMU process is alive. */
+    running: boolean;
+    /** The hdc address checked for `connected`. */
+    address: string;
+    /** hdc lists `address` as a Connected target. */
+    connected: boolean;
+}
+/**
+ * Report on the Oniro emulator without starting it: installed, running, and whether
+ * hdc sees it at `address` (default `127.0.0.1:55555`). Other emulators, such as
+ * DevEco Studio's HarmonyOS emulator, are not covered: they appear in `listDevices`.
+ */
+declare function getEmulatorStatus(config: ConfigProvider, opts?: {
+    address?: string;
+    logger?: Logger;
+}): Promise<EmulatorStatus>;
 
 /**
  * True when `command` must be routed through `cmd.exe` to run at all —
@@ -736,11 +792,33 @@ interface RunProcessOptions {
  * (e.g. missing binary), timeout, or abort.
  */
 declare function runProcess(opts: RunProcessOptions): Promise<HdcExecResult>;
+/**
+ * The device to address: an explicit serial wins, then the `ONIRO_DEVICE_SERIAL` /
+ * `DEVICE_SERIAL` env vars. `auto`, or nothing at all, leaves the choice to hdc,
+ * which only works while a single target is connected.
+ */
+declare function resolveDeviceSerial(explicit?: string, env?: NodeJS.ProcessEnv): string | undefined;
+/** `['-t', <serial>]` for the device {@link resolveDeviceSerial} picks, or `[]` to let hdc choose. */
+declare function hdcTargetArgs(explicit?: string): string[];
+/** The `-t <serial>` prefix for `hdc <args...>`, following {@link HdcExecOptions.deviceSerial}'s rules. */
+declare function hdcTargetArgsFor(args: readonly string[], explicit?: string): string[];
+/**
+ * The `[Fail]…` line hdc printed instead of running the command, or null. hdc
+ * exits 0 even then: `[Fail]ExecuteCommand need connect-key?` (several targets
+ * and no `-t`), `[Fail]Not match target founded` (unknown serial), a failed file
+ * transfer. Only the first line of output counts, so device-side output further
+ * down that happens to contain the marker is left alone. Pure/testable.
+ */
+declare function hdcClientFailure(output: string): string | null;
 interface HdcExecOptions {
     config: ConfigProvider;
     /** Args passed to hdc verbatim, e.g. `['shell','aa','start','-a',ability,'-b',bundle]`. */
     args: readonly string[];
-    /** Device serial; when set, prepends `['-t', serial]`. */
+    /**
+     * Device serial; prepends `['-t', serial]`. When unset, `ONIRO_DEVICE_SERIAL`
+     * applies (see {@link resolveDeviceSerial}), except for hdc server commands
+     * such as `list targets` and `tconn`.
+     */
     deviceSerial?: string;
     /** Default 60_000. */
     timeoutMs?: number;
@@ -750,7 +828,8 @@ interface HdcExecOptions {
 }
 /**
  * Run `hdc [-t <serial>] <args...>`. Resolves with `{ code, stdout, stderr }`
- * for any exit code; use {@link ensureOk} to throw on non-zero.
+ * for any exit code; use {@link ensureOk} to throw on non-zero. A `[Fail]` line
+ * from hdc itself is reported as exit code 1 (see {@link hdcClientFailure}).
  */
 declare function hdcExec(opts: HdcExecOptions): Promise<HdcExecResult>;
 interface HdcShellOptions extends Omit<HdcExecOptions, 'args'> {
@@ -828,28 +907,62 @@ interface ParamOptions {
     timeoutMs?: number;
     logger?: Logger;
 }
-/** Read a system property via `hdc shell param get <key>`. Returns the trimmed value. */
+/** Read a system property via `hdc shell param get <key>`. Returns the trimmed value; throws when it is unset. */
 declare function paramGet(config: ConfigProvider, key: string, opts?: ParamOptions): Promise<string>;
+/**
+ * Split the output of {@link paramGetMany}'s single shell call back into one value
+ * per key; unset properties come back undefined. Pure/testable.
+ */
+declare function parseParamValues(keys: readonly string[], stdout: string): Record<string, string | undefined>;
+/** Read several system properties in one `hdc shell` round trip. Unset properties come back undefined. */
+declare function paramGetMany(config: ConfigProvider, keys: readonly string[], opts?: ParamOptions): Promise<Record<string, string | undefined>>;
 /**
  * Set a system property via `hdc shell param set <key> <value>`. The canonical
  * reboot path is `paramSet(config, 'ohos.startup.powerctrl', 'reboot')`.
  */
 declare function paramSet(config: ConfigProvider, key: string, value: string, opts?: ParamOptions): Promise<void>;
 
+/**
+ * A host path in the form hdc understands: absolute, with native separators and,
+ * on Windows, no 8.3 short names. hdc treats a forward-slash Windows path such as
+ * `C:/Users/me/x.txt` as relative and joins it onto the current directory. The
+ * last component may not exist yet (a `recv` destination).
+ */
+declare function normaliseLocalPath(local: string): string;
+/**
+ * Reject a device path that a Windows shell already rewrote into a host path:
+ * Git Bash turns `/data/local/tmp/x` into `C:/Program Files/Git/data/local/tmp/x`
+ * before the CLI sees it. Device paths never start with a drive letter.
+ */
+declare function assertDevicePath(remote: string): void;
+/** Where `hdc shell` sees an app's el2 sandbox; the app itself sees it as `/data/storage/el2/base`. */
+declare function appSandboxDir(bundle: string): string;
 interface SendFileOptions {
     config: ConfigProvider;
     /** Local source path. */
     local: string;
-    /** Remote destination path on the device. */
+    /**
+     * Remote destination path on the device. With `bundle`, a relative path is
+     * resolved inside that app's sandbox (`files/x` is the app's application-level
+     * filesDir, `haps/entry/files/x` the entry module's).
+     */
     remote: string;
+    /**
+     * Push into this app's sandbox and give the file to the app's user afterwards:
+     * hdc writes files as root, which the app cannot read until they are chowned.
+     */
+    bundle?: string;
     deviceSerial?: string;
     timeoutMs?: number;
     abortSignal?: AbortSignal;
     onOutput?: OutputSink;
     logger?: Logger;
 }
-/** Push a local file to the device via `hdc file send <local> <remote>`. */
-declare function sendFile(opts: SendFileOptions): Promise<void>;
+/**
+ * Push a local file to the device via `hdc file send <local> <remote>`. Returns
+ * the device path the file was written to.
+ */
+declare function sendFile(opts: SendFileOptions): Promise<string>;
 interface RecvFileOptions {
     config: ConfigProvider;
     /** Remote source path on the device. */
@@ -1008,13 +1121,20 @@ interface SendInputOptions {
     pxY2?: number;
     /** Velocity for swipe/drag/fling. */
     speed?: number;
-    /** Key id or symbolic name (Back/Home/Power) for keyEvent. */
+    /** Key for keyEvent: a KeyCode id, a name (Back, Delete, Enter, …), or a combo like `Ctrl+A`. See {@link resolveKeyEvent}. */
     key?: string | number;
     /** Text for inputText. */
     text?: string;
     deviceSerial?: string;
     logger?: Logger;
 }
+/**
+ * Resolve a key spec to `uitest uiInput keyEvent` arguments. Accepts uitest's
+ * own names (Back/Home/Power), numeric KeyCode ids, named keys (Delete, Enter,
+ * Tab, Escape, MoveHome, …), single letters, and combos of up to three keys
+ * joined by "+" (e.g. `Ctrl+A`) or given as space-separated ids. Pure.
+ */
+declare function resolveKeyEvent(key: string | number): string;
 /**
  * Build the `uitest uiInput …` command for an input action, in pixel space.
  * Pure (no I/O) so it is unit-testable. Mirrors the proven MCP construction
@@ -1125,6 +1245,8 @@ interface LayoutNode {
     type?: string;
     text?: string;
     desc?: string;
+    /** Placeholder text, e.g. an empty TextInput's "you@example.com". */
+    hint?: string;
     id?: string;
     key?: string;
     bundle?: string;
@@ -1135,28 +1257,105 @@ interface LayoutNode {
     focus?: boolean;
     scroll?: boolean;
     longClick?: boolean;
+    /** The component is disabled (`enabled: false`). */
+    disabled?: boolean;
+    /** The node's center is painted over by a later filled node (an overlay, a
+     *  dialog scrim, the soft keyboard), so a tap there would land on that instead. */
+    covered?: boolean;
     children?: LayoutNode[];
 }
+/** The soft keyboard, when an input-method window is on screen. */
+interface KeyboardState {
+    shown: boolean;
+    /** Bundle of the input-method window. */
+    bundle?: string;
+    /** Bounds [x1,y1,x2,y2] normalized to 0–1 of the display. */
+    b?: [number, number, number, number];
+}
 interface DumpLayoutResult {
     display: DisplaySize | null;
     tree: LayoutNode;
+    /** Present when the dump was asked to detect the soft keyboard. */
+    keyboard?: KeyboardState;
 }
 /** Parse a uitest bounds string `"[x1,y1][x2,y2]"` into a tuple, or null. */
 declare function parseBounds(s: string | undefined): [number, number, number, number] | null;
+/**
+ * Find nodes whose center is painted over by a later node with a visible
+ * background fill — a full-screen overlay, a dialog scrim, a sticky bar, or the
+ * soft-keyboard window. Paint order is depth-first, siblings ordered by
+ * `zIndex`, windows in dump order; ancestors and descendants never cover a node.
+ *
+ * A heuristic: only background fills count (an Image or Text drawn on top does
+ * not), which is what overlays in practice use.
+ */
+declare function findCoveredNodes(root: RawLayoutNode): Set<RawLayoutNode>;
 /**
  * Prune a raw `uitest dumpLayout` tree into a compact, signal-bearing tree with
  * bounds/center normalized to 0–1 of the display. Structural wrapper nodes with
  * no signal collapse into their children. Returns a node, a flat list of nodes
  * (collapsed wrapper with multiple children), or null (nothing useful). Ported
- * verbatim from the proven MCP `pruneNode`.
+ * from the proven MCP `pruneNode`; `covered` (from {@link findCoveredNodes})
+ * marks nodes hidden under an overlay.
+ */
+declare function pruneLayout(node: RawLayoutNode, display: DisplaySize | null, covered?: ReadonlySet<RawLayoutNode>): LayoutNode | LayoutNode[] | null;
+/** A pruned layout node without children, tagged with the window it belongs to. */
+interface FlatLayoutNode extends Omit<LayoutNode, 'children'> {
+    /** Bundle of the enclosing window (the nearest node carrying `bundle`). */
+    window?: string;
+}
+/** Flatten a pruned layout tree into a depth-first (paint-order) list. */
+declare function flattenLayout(tree: LayoutNode): FlatLayoutNode[];
+/** Selects layout nodes by what an agent can read off the screen. */
+interface LayoutSelector {
+    /** Matches `text`, `desc`, or `hint`: case-insensitive exact matches win; otherwise substring matches. */
+    text?: string;
+    /** Matches `id` or `key` exactly. */
+    id?: string;
+    /** Restricts to a component type (e.g. `Button`, `TextInput`); case-insensitive. */
+    type?: string;
+}
+/** Throw unless `selector` constrains something: a non-blank text, an id, or a type. */
+declare function assertLayoutSelector(selector: LayoutSelector): void;
+/**
+ * The tree without the windows owned by `bundle` — e.g. the soft keyboard, whose
+ * keys ("Done", "9") would otherwise match element selectors. Pure.
+ */
+declare function withoutWindow(tree: LayoutNode, bundle: string): LayoutNode;
+/**
+ * Find the nodes matching `selector` in a pruned layout tree, in paint order.
+ * For `text`, exact (case-insensitive, trimmed) matches are returned when any
+ * exist; otherwise substring matches. Covered nodes are included — callers
+ * decide what to do with them (see {@link pickTarget}).
+ */
+declare function findLayoutNodes(tree: LayoutNode, selector: LayoutSelector): FlatLayoutNode[];
+/** One-line summary of a node, used in errors and logs. */
+declare function describeLayoutNode(n: FlatLayoutNode): string;
+/** Why {@link pickTarget} could not choose a node. */
+type PickTargetFailure = 'none' | 'covered' | 'ambiguous';
+declare class TargetNotFoundError extends OniroError {
+    readonly reason: PickTargetFailure;
+    constructor(message: string, reason: PickTargetFailure);
+}
+/**
+ * Choose the single node to act on for `selector`. Covered nodes are skipped;
+ * clickable matches are preferred over plain ones (a "Sign in" Button over the
+ * "Sign in" title); a match nested inside another clickable match collapses
+ * into it. `index` picks among what remains, in paint order. Throws
+ * {@link TargetNotFoundError} when nothing (or more than one node) qualifies.
  */
-declare function pruneLayout(node: RawLayoutNode, display: DisplaySize | null): LayoutNode | LayoutNode[] | null;
+declare function pickTarget(tree: LayoutNode, selector: LayoutSelector, index?: number): FlatLayoutNode;
 interface DumpLayoutOptions {
     config: ConfigProvider;
     /** Filter to a single window/bundle (`uitest dumpLayout -b '<bundle>'`). */
     bundleName?: string;
     /** When false, return the parsed-but-unpruned tree. Default true. */
     prune?: boolean;
+    /**
+     * Also report whether the soft keyboard is on screen (one extra `hidumper` call).
+     * Ignored with `bundleName`, which filters the keyboard window out of the dump.
+     */
+    detectKeyboard?: boolean;
     deviceSerial?: string;
     timeoutMs?: number;
     logger?: Logger;
@@ -1167,6 +1366,125 @@ interface DumpLayoutOptions {
  */
 declare function dumpLayout(opts: DumpLayoutOptions): Promise<DumpLayoutResult>;
 
+/**
+ * Extract input-method bundle names from `hidumper -s 3703 -a -a` output, whose
+ * `imeList` entries look like `"ime": "com.example.kikakeyboard/ServiceExtAbility"`.
+ * The current IME comes first. Pure.
+ */
+declare function parseImeBundles(output: string): string[];
+/**
+ * List the installed input-method bundles (current first). Empty when hidumper
+ * fails or times out, so keyboard detection never fails the caller.
+ */
+declare function getImeBundles(config: ConfigProvider, opts?: {
+    deviceSerial?: string;
+    logger?: Logger;
+}): Promise<string[]>;
+/**
+ * Find the input-method window in a pruned layout tree. uitest lists the soft
+ * keyboard as its own window (a node carrying the IME's `bundle`) only while it
+ * is shown. With no known IME bundles, falls back to a name heuristic. Pure.
+ */
+declare function findKeyboardWindow(tree: LayoutNode, imeBundles: readonly string[]): LayoutNode | null;
+
+/** `uitest uiInput` actions plus the composite ones built on top of them. */
+type UiInputType = InputType | 'clearText' | 'hideKeyboard';
+interface DeviceOptions {
+    config: ConfigProvider;
+    deviceSerial?: string;
+    logger?: Logger;
+}
+/**
+ * Dismiss the soft keyboard with Back — only when it is actually on screen, since
+ * Back without a keyboard navigates away. Returns whether a keyboard was dismissed.
+ */
+declare function hideKeyboard(opts: DeviceOptions): Promise<boolean>;
+interface LocateTargetOptions extends DeviceOptions {
+    selector: LayoutSelector;
+    /** Picks among several matching elements (see {@link pickTarget}). */
+    index?: number;
+    /**
+     * When the soft keyboard is up and the target is missing, covered, or matches
+     * only a non-clickable label (the button may be hidden below the keyboard),
+     * dismiss the keyboard and look again. Default true.
+     */
+    hideKeyboard?: boolean;
+}
+interface LocatedTarget {
+    node: FlatLayoutNode;
+    /** Center of the element in device pixels. */
+    x: number;
+    y: number;
+    display: DisplaySize;
+    /** The soft keyboard was dismissed to reach the element. */
+    keyboardHidden: boolean;
+}
+/**
+ * Resolve a selector against the live layout to one element and its pixel
+ * center. Keys on the soft keyboard are not candidates.
+ */
+declare function locateTarget(opts: LocateTargetOptions): Promise<LocatedTarget>;
+interface PerformInputOptions extends DeviceOptions {
+    type: UiInputType;
+    /** Start point in device pixels. */
+    pxX?: number;
+    pxY?: number;
+    /** End point in device pixels (swipe/drag/fling). */
+    pxX2?: number;
+    pxY2?: number;
+    /** Start point as 0–1 fractions of the display. */
+    fx?: number;
+    fy?: number;
+    /** End point as 0–1 fractions of the display. */
+    fx2?: number;
+    fy2?: number;
+    /** Start point: the center of the element matching this selector. */
+    target?: LayoutSelector;
+    /** Picks among several elements matching `target`. */
+    targetIndex?: number;
+    /** Velocity for swipe/drag/fling. */
+    speed?: number;
+    /** Key for keyEvent (see `resolveKeyEvent`). */
+    key?: string | number;
+    /** Text for inputText. */
+    text?: string;
+    /** inputText: clear the field before typing. */
+    clear?: boolean;
+    /** Dismiss the soft keyboard after the action, if it is up. */
+    hideKeyboard?: boolean;
+}
+interface PerformInputResult {
+    /** Resolved start point in device pixels, when the action has one. */
+    x?: number;
+    y?: number;
+    /** The element `target` resolved to. */
+    target?: FlatLayoutNode;
+    /** The soft keyboard was dismissed (to reach the target, or because it was asked to). */
+    keyboardHidden: boolean;
+}
+/**
+ * Perform a UI input action. Beyond the raw `uitest uiInput` primitives, this
+ * resolves the start point from an element selector (`target`), 0–1 display
+ * fractions, or pixels; clears text fields (Ctrl+A, Delete); and dismisses the
+ * soft keyboard only when it is up.
+ */
+declare function performInput(opts: PerformInputOptions): Promise<PerformInputResult>;
+interface WaitForTargetOptions extends DeviceOptions {
+    selector: LayoutSelector;
+    /** Wait until no uncovered element matches, instead of until one does. */
+    gone?: boolean;
+    timeoutMs: number;
+    /** Poll interval. Default 500 (each poll is a full layout dump). */
+    pollMs?: number;
+    abortSignal?: AbortSignal;
+}
+/**
+ * Poll the layout until an uncovered element matches `selector` (resolving with
+ * it), or with `gone`, until none does (resolving null). Keys on the soft
+ * keyboard are ignored. Throws on timeout.
+ */
+declare function waitForTarget(opts: WaitForTargetOptions): Promise<FlatLayoutNode | null>;
+
 /**
  * Read the project's bundle name from `AppScope/app.json5`.
  */
@@ -1185,8 +1503,10 @@ interface InstallAppOptions {
     config: ConfigProvider;
     projectDir: string;
     /**
-     * Explicit path (absolute, or relative to projectDir) to the signed `.hap`.
-     * Falls back to the `hapPath` config key, then to the well-known default.
+     * Explicit path (absolute, or relative to projectDir) to the `.hap`. Falls back
+     * to the `hapPath` config key, then to the well-known signed entry HAP, then to
+     * the HAPs the build produced (signed first, else unsigned). A `*-signed.hap`
+     * that does not exist falls back to its `*-unsigned.hap` sibling.
      */
     hapPath?: string;
     deviceSerial?: string;
@@ -1201,7 +1521,50 @@ interface InstallAppResult {
     /** Combined stdout+stderr from the install, trimmed. */
     output: string;
 }
+/**
+ * The bundle manager's rejection in `hdc install` output, or null when the
+ * install went through. hdc exits 0 either way: success prints `msg:install
+ * bundle successfully.`, a rejection `msg:error: failed to install bundle.`
+ * with a `code:95xxxxx`. Pure/testable.
+ */
+declare function detectInstallFailure(output: string): string | null;
+/** The HAP an install is about to push, and how it was chosen. */
+interface InstallCandidate {
+    path: string;
+    /** True when no signed HAP was found and this unsigned one was taken instead. */
+    fallback?: boolean;
+}
+/** Whether a HAP is an `*-unsigned.hap`, by its file name as hvigor writes it. */
+declare function isUnsignedHap(hapPath: string): boolean;
+/**
+ * The bundle manager's reason from rejected `hdc install` output, e.g. `code
+ * 9568320: no signature file`, else the output's first line. Pure/testable.
+ */
+declare function installFailureReason(output: string): string;
+/**
+ * The message for a target that rejected an unsigned HAP: what was tried, the
+ * bundle manager's reason, and, when the reason is the missing signature, how to
+ * sign for the target. Pure/testable.
+ */
+declare function unsignedHapRejection(output: string, hap: InstallCandidate): string;
+/**
+ * Throw when hdc or the bundle manager rejected an install: a typed
+ * {@link CommandFailedError}, or, when the bundle manager turned down an unsigned
+ * `hap`, an {@link OniroError} explaining {@link unsignedHapRejection why}.
+ */
+declare function ensureInstallOk(result: HdcExecResult, command: string, hap?: InstallCandidate): HdcExecResult;
+/**
+ * An existing HAP at `hapPath`, or, when that is a `*-signed.hap` that does not
+ * exist, its `*-unsigned.hap` sibling. Undefined when neither exists.
+ */
+declare function existingHapOrUnsigned(hapPath: string): InstallCandidate | undefined;
 declare function installApp(opts: InstallAppOptions): Promise<InstallAppResult>;
+/**
+ * Whether `bm dump -n <bundle>` finds the bundle on the device. A missing bundle
+ * prints `error: failed to get information…`; an installed one, `<bundle>:` and
+ * its JSON.
+ */
+declare function isBundleInstalled(opts: BundleOptions): Promise<boolean>;
 interface LaunchAppOptions {
     config: ConfigProvider;
     /** Project mode: resolve bundle + main ability from the project. Required unless `bundleName` is given. */
@@ -1247,6 +1610,7 @@ interface RunningProcess {
 declare function listRunningProcesses(config: ConfigProvider, options?: {
     targetProcessName?: string;
     timeoutMs?: number;
+    deviceSerial?: string;
     logger?: Logger;
 }): Promise<RunningProcess[] | string>;
 declare function findAppProcessId(config: ConfigProvider, projectDir: string, logger?: Logger): Promise<string>;
@@ -1290,6 +1654,7 @@ interface HilogEntry {
 interface SetHilogLevelOptions {
     config: ConfigProvider;
     level: HilogLevel;
+    deviceSerial?: string;
     logger?: Logger;
 }
 /**
@@ -1304,7 +1669,7 @@ interface StreamHilogOptions {
     processId?: string;
     /** Filter by hilog domain, e.g. '0xD003900' (passed as `-D <domain>`). */
     domain?: string | number;
-    /** Address a specific device (`-t <serial>`). */
+    /** Address a specific device (`-t <serial>`); defaults to `ONIRO_DEVICE_SERIAL`. */
     deviceSerial?: string;
 }
 /**
@@ -1356,6 +1721,38 @@ interface WatchLogOptions {
 }
 /** Collect all hilog entries matching `pattern` for `durationMs`. Deduped by default. */
 declare function watchLog(opts: WatchLogOptions): Promise<HilogEntry[]>;
+interface CaptureLogOptions {
+    config: ConfigProvider;
+    /** File the hilog lines are appended to. */
+    file: string;
+    /** Stop after this long. Default: run until `abortSignal` fires. */
+    durationMs?: number;
+    /** Keep only the lines this matches. Default: every line. */
+    pattern?: RegExp;
+    /** Clear the device's log buffer first (`hilog -r`), so the file covers only this session. */
+    clear?: boolean;
+    domain?: string | number;
+    deviceSerial?: string;
+    abortSignal?: AbortSignal;
+    logger?: Logger;
+}
+interface CaptureLogResult {
+    file: string;
+    /** Lines written to `file`. */
+    lines: number;
+    /** How many times the stream dropped and was respawned. */
+    reconnects: number;
+}
+/**
+ * Stream hilog into `file` until `durationMs` passes or `abortSignal` fires. The
+ * device's log buffer is small (256 KB per type by default) and chatty components
+ * such as ArkWeb wrap it within seconds, so a dump taken at the end of a session
+ * loses its start; a capture running throughout does not. Each chunk is written
+ * synchronously, so killing the process keeps what was captured. The stream is
+ * respawned when it drops (a reboot, a lost connection). Resolves at the deadline
+ * or on abort.
+ */
+declare function captureLog(opts: CaptureLogOptions): Promise<CaptureLogResult>;
 interface DumpLogOptions {
     config: ConfigProvider;
     /** Cap the result to the last N lines (device-side `tail -n`). */
@@ -1438,9 +1835,23 @@ interface DiscoverHapsOptions {
  * by build module name (parsed from the HAP filename). Skips `node_modules` /
  * `oh_modules` / `.git`. Ported from the proven MCP `findHaps`, extended with
  * per-module grouping so multi-module projects can install the right HAP.
- * Empty object when nothing is built.
+ * Each list is newest first, so a fresh build wins over HAPs committed to the
+ * repository. Empty object when nothing is built.
  */
 declare function discoverHaps(opts: DiscoverHapsOptions): Promise<Record<string, ModuleHaps>>;
+interface PickedHap {
+    module: string;
+    path: string;
+    /** False for an `*-unsigned.hap`, which targets that verify signatures reject. */
+    signed: boolean;
+}
+/**
+ * The HAP to install from {@link discoverHaps} output: a module's newest signed
+ * HAP, else its newest unsigned one. Without `module`, the single module that
+ * has a signed HAP, else the single one that has any HAP. Null when nothing is
+ * built; throws when several modules qualify and none was named.
+ */
+declare function pickHap(haps: Record<string, ModuleHaps>, module?: string): PickedHap | null;
 
 interface RunOhpmOptions {
     config: ConfigProvider;
@@ -1478,23 +1889,52 @@ declare function ensureOhModules(opts: {
 interface CodelinterFinding {
     file: string;
     line: number;
+    /** Column, when the report gives one. */
+    column?: number;
+    /** `error`, `warning`, `suggestion` or `info` (codelinter's `warn` reads as `warning`). */
     severity: string;
     /** Rule code/id when present in the output, else ''. */
     code: string;
     message: string;
 }
-interface CodelinterResult {
-    /** codelinter process exit code. */
-    code: number;
+/** codelinter's own totals, from its `-Defects: N; Errors: N; Warns: N; Suggestions: N;` line. */
+interface CodelinterSummary {
+    defects: number;
+    errors: number;
+    warnings: number;
+    suggestions: number;
+}
+interface CodelinterReport {
     findings: CodelinterFinding[];
-    /** Combined stdout+stderr, for callers that want the raw report. */
+    /** The totals codelinter printed (all zero for "No defects found"), or null when it printed none. */
+    summary: CodelinterSummary | null;
+    /**
+     * codelinter's remarks about the run itself rather than the code, e.g. "The type of
+     * command line tools does not match that of the project".
+     */
+    notices: string[];
+    /** True when codelinter warned that the report may be incomplete. */
+    incomplete: boolean;
+}
+interface CodelinterResult extends CodelinterReport {
+    /** codelinter process exit code: 1 whenever it found any defect, warnings included. */
+    code: number;
+    /** Combined stdout+stderr, with colour codes and progress-bar redraws removed. */
     raw: string;
 }
 /**
- * Best-effort parser for codelinter output lines of the shape
- * `<file>:<line>[:<col>]: <severity>: <message> [<rule-code>]`. Lines that don't
- * match are ignored. Exported as a pure function so it is unit-testable.
+ * codelinter output as plain lines: colour codes stripped, and of each line redrawn
+ * with `\r` (its progress bar) only the final state kept.
  */
+declare function cleanCodelinterOutput(output: string): string;
+/**
+ * Parse a codelinter report. Pure/testable. Understands the table codelinter prints
+ * (a `<file>(<count>)` header followed by `<line>:<col>  <severity>  <message>  <rule>`
+ * rows, then a `-Defects: …` summary) and the one-line
+ * `<file>:<line>[:<col>]: <severity>: <message> [<rule>]` shape. Other lines are ignored.
+ */
+declare function parseCodelinterReport(output: string): CodelinterReport;
+/** The findings of a codelinter report; see {@link parseCodelinterReport}. */
 declare function parseCodelinterFindings(output: string): CodelinterFinding[];
 interface RunCodelinterOptions {
     config: ConfigProvider;
@@ -1505,9 +1945,14 @@ interface RunCodelinterOptions {
     abortSignal?: AbortSignal;
     logger?: Logger;
 }
-/** Run the OpenHarmony codelinter and return parsed findings + the raw report. */
+/** Run the OpenHarmony codelinter and return the parsed report + the cleaned raw output. */
 declare function runCodelinter(opts: RunCodelinterOptions): Promise<CodelinterResult>;
 
+/**
+ * A hint for build output whose cause the compiler errors do not name, or
+ * undefined. Pure/testable.
+ */
+declare function diagnoseBuildFailure(output: string): string | undefined;
 interface BuildHapOptions {
     config: ConfigProvider;
     projectDir: string;
@@ -1630,6 +2075,7 @@ interface PrepareSigningOptions {
     apl?: Apl;
     appFeature?: AppFeature;
     acls?: string[];
+    appPrivilegeCapabilities?: string[];
     passwords?: SigningPasswords;
     logger?: Logger;
 }
@@ -1676,10 +2122,20 @@ interface DeviceFullInfo {
     model?: string;
     manufacturer?: string;
     brand?: string;
+    /** `HarmonyOS` when the device reports a HarmonyOS distribution, else `OpenHarmony` (Oniro included). */
+    osFamily?: 'HarmonyOS' | 'OpenHarmony';
+    /** Distribution name (`const.product.os.dist.name`): `HarmonyOS`; unset on OpenHarmony. */
+    osDistName?: string;
+    /** Distribution version (`const.product.os.dist.version`), e.g. `6.1.0` on HarmonyOS. */
+    osDistVersion?: string;
     osFullName?: string;
     osReleaseType?: string;
     sdkApiVersion?: string;
     buildVersion?: string;
+    /** CPU ABIs (`const.product.cpu.abilist`), e.g. `arm64-v8a` or `x86_64`: native libraries must match. */
+    abi?: string;
+    /** `phone`, `tablet`, `wearable`, `default`, … */
+    deviceType?: string;
     display: {
         width: number;
         height: number;
@@ -1691,7 +2147,7 @@ interface GetDeviceInfoOptions {
     timeoutMs?: number;
     logger?: Logger;
 }
-/** Collate device properties (`param get` × N) and the display resolution. */
+/** Collate device properties (one `param get` round trip) and the display resolution. */
 declare function getDeviceInfo(opts: GetDeviceInfoOptions): Promise<DeviceFullInfo>;
 
 interface HapAssetDiff {
@@ -2069,4 +2525,4 @@ declare function harmonyOsAutoSign(opts: HarmonyOsAutoSignOptions): Promise<Harm
 
 declare const VERSION: string;
 
-export { ALL_SDKS, APL_VALUES, APP_FEATURE_VALUES, type AbilityInfo, type AgcAuthInfo, AgcError, type Apl, type AppFeature, type ApplyChangesOptions, type ApplyChangesResult, type BuildHapOptions, type BuildHapResult, type BundleOptions, CancelledError, type CaptureBurstOptions, ChecksumMismatchError, CmdToolsNotInstalledError, type CmdToolsStatus, type CmdWrapper, type CodelinterFinding, type CodelinterResult, CommandFailedError, type ConfigKey, type ConfigProvider, type CreateScaffoldOptions, type CreateScaffoldResult, type DeveloperAgreementStatus, type DeviceFullInfo, type DeviceInfo, type DiscoverHapsOptions, type DisplaySize, type DisplaySizeOptions, type DownloadOptions, type DumpLayoutOptions, type DumpLayoutResult, type DumpLogOptions, type ExtractZipOptions, type GenerateSigningConfigsOptions, type GestureUitestOptions, type GetDeviceInfoOptions, HARMONYOS_SDK_VERSIONS, HUAWEI_SITES, type HapAssetDiff, type HarmonyOsAutoSignOptions, type HarmonyOsSdk, type HarmonyOsSession, type HarmonyOsSessionOptions, type HarmonyOsSigningResult, type HdcExecOptions, type HdcExecResult, type HdcShellOptions, type HidumperOptions, type HilogEntry, type HilogLevel, type HuaweiSite, type HuaweiSiteCode, type HuaweiTeam, type HuaweiUserInfo, INSTALL_TMP_DIRNAME, type InputType, type InstallAppOptions, type InstallAppResult, type InstallCmdToolsOptions, type InstallEmulatorOptions, type InstallMethod, type InstallSdkOptions, type InstallTempDir, type InstallTempDirOptions, InsufficientSpaceError, type LaunchAppOptions, type LayoutNode, type Logger, type ModuleHaps, OHOS_URL_BASE, type OniroContext, OniroError, type OsFolder, type OutputSink, type ParamOptions, type PrepareSigningOptions, type PrepareSigningResult, type ProgressReporter, type ProgressUpdate, type ProjectModule, type Prompter, type ProvisionProfileInfo, type RawLayoutNode, type RawTouchEvent, type RebootDecision, type RebootOptions, type RecvFileOptions, type RunCodelinterOptions, type RunHvigorwOptions, type RunHvigorwResult, type RunOhpmOptions, type RunProcessOptions, type RunningProcess, type RuntimeOs, SIGNING_ERRORS, type ScreenDump, type Screenshot, type ScreenshotOptions, type SdkArchiveInfo, type SdkInfo, SdkNotInstalledError, type SdkRelease, type SendFileOptions, type SendGestureOptions, type SendInputOptions, type SendRawTouchOptions, type SetHilogLevelOptions, type SigningKind, type SigningMaterialPaths, type SigningPasswords, type StartEmulatorOptions, type StoredSession, type StreamHilogOptions, TMP_DIR_HINT, type TemplateOption, type TokenStore, UnsupportedPlatformError, VERSION, type WaitForBootOptions, type WaitForBundleOptions, type WaitForConditionOptions, type WaitForLogOptions, type WatchLogOptions, type Waypoint, applyChanges, attemptHdcConnection, buildCmdWrapper, buildGestureCommands, buildGestureUitestCommand, buildHap, buildHvigorwArgs, buildInputCommand, buildRawTouchCommand, captureBurst, consoleLogger, createHarmonyOsSession, createInstallTempDir, createMaterial, createScaffold, createTempWorkDir, createTokenStore, decideInstallMethod, decideReboot, decryptPwd, dedupEntries, defaultContext, defaultPaths, detectAaStartFailure, detectProjectSdkVersion, detectRuntimeOs, detectSigningConfigNames, diffEntryNames, diffHapAssets, discoverHaps, downloadAndInstallSdk, downloadFile, dumpLayout, dumpLog, dumpRenderService, dumpScreen, dumpWindow, encryptPwd, ensureFreeSpace, ensureOhModules, ensureOk, ensureRemoteOk, escapeCmdArgument, escapeCmdCommand, extractTarball, extractZipWithProgress, findAppProcessId, findCmdToolsSourceDir, findHarmonyOsSdk, findRunningProcess, forceStop, formatBytes, generateSigningConfigs, getBundleName, getCmdToolsBin, getCmdToolsDownloadUrl, getCmdToolsPath, getCmdToolsStatus, getDeviceInfo, getDisplaySize, getEmulatorDir, getFreeSpaceBytes, getHdcPath, getHvigorwPath, getInstalledSdks, getKey, getMainAbility, getOhosBaseSdkHome, getOhpmPath, getOsFolder, getSdkFilename, getSdkRootDir, getSupportedSdksForUi, harmonyOsAutoSign, harmonyOsSdkLabelForApi, hdcExec, installApp, installCmdTools, installEmulator, isCmdToolsInstalled, isEmulatorInstalled, isOutOfSpaceError, isRamBackedPath, isValidBundleName, isValidProjectName, killProcessTree, launchApp, listAbilities, listDevices, listModules, listRunningProcesses, listTemplates, needsCmdWrapper, nonInteractivePrompter, noopLogger, noopProgress, paramGet, paramSet, parseBounds, parseCodelinterFindings, parseDeviceList, parseHilogLine, parseMainAbilityFromBmDump, parseRemoteExit, pickSigningKind, prepareSigning, pruneLayout, readJson5File, readJsonFile, readProvisionProfile, reboot, recvFile, removeCmdTools, removeEmulator, removeSdk, removeTempWorkDir, requireHarmonyOsSdk, resolveTmpRoot, runCodelinter, runHvigorw, runOhpm, runProcess, scopedLogger, selectDevice, sendFile, sendGesture, sendInput, sendRawTouch, setHilogLevel, shell, shellChecked, spawnCompat, startEmulator, staticConfig, stopEmulator, streamHilog, takeScreenshot, toLongPath, toSpaceError, uninstallApp, validateTemplateLayout, verifySha256, waitForBoot, waitForBundle, waitForCondition, waitForLog, watchLog, waypointsToRawEvents, writeJson5File, writeJsonFile };
+export { ALL_SDKS, APL_VALUES, APP_FEATURE_VALUES, type AbilityInfo, type AgcAuthInfo, AgcError, type Apl, type AppFeature, type ApplyChangesOptions, type ApplyChangesResult, type BuildHapOptions, type BuildHapResult, type BundleOptions, CancelledError, type CaptureBurstOptions, type CaptureLogOptions, type CaptureLogResult, ChecksumMismatchError, type CmdToolsFlavour, CmdToolsNotInstalledError, type CmdToolsStatus, type CmdWrapper, type CodelinterFinding, type CodelinterReport, type CodelinterResult, type CodelinterSummary, CommandFailedError, type ConfigKey, type ConfigProvider, type CreateScaffoldOptions, type CreateScaffoldResult, type DeveloperAgreementStatus, type DeviceFullInfo, type DeviceInfo, type DiscoverHapsOptions, type DisplaySize, type DisplaySizeOptions, type DownloadOptions, type DumpLayoutOptions, type DumpLayoutResult, type DumpLogOptions, type EmulatorStatus, type ExtractZipOptions, type FlatLayoutNode, type GenerateSigningConfigsOptions, type GestureUitestOptions, type GetDeviceInfoOptions, HARMONYOS_SDK_VERSIONS, HUAWEI_SITES, type HapAssetDiff, type HarmonyOsAutoSignOptions, type HarmonyOsSdk, type HarmonyOsSession, type HarmonyOsSessionOptions, type HarmonyOsSigningResult, type HdcExecOptions, type HdcExecResult, type HdcShellOptions, type HidumperOptions, type HilogEntry, type HilogLevel, type HuaweiSite, type HuaweiSiteCode, type HuaweiTeam, type HuaweiUserInfo, INSTALL_TMP_DIRNAME, type InputType, type InstallAppOptions, type InstallAppResult, type InstallCandidate, type InstallCmdToolsOptions, type InstallEmulatorOptions, type InstallMethod, type InstallSdkOptions, type InstallTempDir, type InstallTempDirOptions, InsufficientSpaceError, type KeyboardState, type LaunchAppOptions, type LayoutNode, type LayoutSelector, type LocateTargetOptions, type LocatedTarget, type Logger, type ModuleHaps, OHOS_URL_BASE, type OniroContext, OniroError, type OsFolder, type OutputSink, type ParamOptions, type PerformInputOptions, type PerformInputResult, type PickTargetFailure, type PickedHap, type PrepareSigningOptions, type PrepareSigningResult, type ProgressReporter, type ProgressUpdate, type ProjectModule, type Prompter, type ProvisionProfileInfo, type RawLayoutNode, type RawTouchEvent, type RebootDecision, type RebootOptions, type RecvFileOptions, type RunCodelinterOptions, type RunHvigorwOptions, type RunHvigorwResult, type RunOhpmOptions, type RunProcessOptions, type RunningProcess, type RuntimeOs, SIGNING_ERRORS, type ScreenDump, type Screenshot, type ScreenshotOptions, type SdkArchiveInfo, type SdkInfo, SdkNotInstalledError, type SdkRelease, type SendFileOptions, type SendGestureOptions, type SendInputOptions, type SendRawTouchOptions, type SetHilogLevelOptions, type SigningKind, type SigningMaterialPaths, type SigningPasswords, type StartEmulatorOptions, type StoredSession, type StreamHilogOptions, TMP_DIR_HINT, TargetNotFoundError, type TemplateOption, type TokenStore, type UiInputType, UnsupportedPlatformError, VERSION, type WaitForBootOptions, type WaitForBundleOptions, type WaitForConditionOptions, type WaitForLogOptions, type WaitForTargetOptions, type WatchLogOptions, type Waypoint, appSandboxDir, applyChanges, assertDevicePath, assertLayoutSelector, attemptHdcConnection, buildCmdWrapper, buildGestureCommands, buildGestureUitestCommand, buildHap, buildHvigorwArgs, buildInputCommand, buildRawTouchCommand, captureBurst, captureLog, cleanCodelinterOutput, consoleLogger, createHarmonyOsSession, createInstallTempDir, createMaterial, createScaffold, createTempWorkDir, createTokenStore, decideInstallMethod, decideReboot, decryptPwd, dedupEntries, defaultContext, defaultPaths, describeLayoutNode, detectAaStartFailure, detectCmdToolsFlavour, detectInstallFailure, detectProjectSdkVersion, detectRuntimeOs, detectSigningConfigNames, diagnoseBuildFailure, diffEntryNames, diffHapAssets, discoverHaps, downloadAndInstallSdk, downloadFile, dumpLayout, dumpLog, dumpRenderService, dumpScreen, dumpWindow, encryptPwd, ensureFreeSpace, ensureInstallOk, ensureOhModules, ensureOk, ensureRemoteOk, escapeCmdArgument, escapeCmdCommand, existingHapOrUnsigned, extractTarball, extractZipWithProgress, findAppProcessId, findCmdToolsSourceDir, findCoveredNodes, findHarmonyOsSdk, findKeyboardWindow, findLayoutNodes, findMissingProjectSdk, findRunningProcess, flattenLayout, forceStop, formatBytes, generateSigningConfigs, getBundleName, getCmdToolsBin, getCmdToolsDownloadUrl, getCmdToolsPath, getCmdToolsStatus, getDeviceInfo, getDisplaySize, getEmulatorDir, getEmulatorStatus, getFreeSpaceBytes, getHdcPath, getHvigorwPath, getImeBundles, getInstalledSdks, getKey, getMainAbility, getOhosBaseSdkHome, getOhpmPath, getOsFolder, getSdkFilename, getSdkRootDir, getSupportedSdksForUi, harmonyOsAutoSign, harmonyOsSdkLabelForApi, hdcClientFailure, hdcExec, hdcTargetArgs, hdcTargetArgsFor, hideKeyboard, installApp, installCmdTools, installEmulator, installFailureReason, isBundleInstalled, isCmdToolsInstalled, isEmulatorInstalled, isOutOfSpaceError, isRamBackedPath, isUnsignedHap, isValidBundleName, isValidProjectName, killProcessTree, launchApp, listAbilities, listDevices, listModules, listRunningProcesses, listTemplates, locateTarget, needsCmdWrapper, nonInteractivePrompter, noopLogger, noopProgress, normaliseLocalPath, paramGet, paramGetMany, paramSet, parseBounds, parseCodelinterFindings, parseCodelinterReport, parseDeviceList, parseHilogLine, parseImeBundles, parseMainAbilityFromBmDump, parseParamValues, parseRemoteExit, performInput, pickHap, pickSigningKind, pickTarget, prepareSigning, pruneLayout, readJson5File, readJsonFile, readProvisionProfile, reboot, recvFile, removeCmdTools, removeEmulator, removeSdk, removeTempWorkDir, requireHarmonyOsSdk, resolveDeviceSerial, resolveKeyEvent, resolveTmpRoot, runCodelinter, runHvigorw, runOhpm, runProcess, scopedLogger, selectDevice, sendFile, sendGesture, sendInput, sendRawTouch, setHilogLevel, shell, shellChecked, spawnCompat, startEmulator, staticConfig, stopEmulator, streamHilog, takeScreenshot, toLongPath, toSpaceError, uninstallApp, unsignedHapRejection, validateTemplateLayout, verifySha256, waitForBoot, waitForBundle, waitForCondition, waitForLog, waitForTarget, watchLog, waypointsToRawEvents, withoutWindow, writeJson5File, writeJsonFile };