@oniroproject/core 0.6.2 → 0.8.0

package/dist/index.d.ts

@@ -8,6 +8,12 @@ interface Logger {
 }
 declare const noopLogger: Logger;
 declare const consoleLogger: Logger;
+/**
+ * Wrap a Logger so every message is prefixed with `[<scope>] `. Standardizes the
+ * ad-hoc `[hdc]` / `[build]` / `[sign]` / `[hilog]` / `[emulator]` prefixes that
+ * were previously hand-written at each call site.
+ */
+declare function scopedLogger(logger: Logger, scope: string): Logger;
 
 interface ProgressUpdate {
     message?: string;
@@ -22,7 +28,7 @@ declare const noopProgress: ProgressReporter;
  * Keys read from the ConfigProvider by core. Frontends (CLI, VS Code extension)
  * implement the provider however they like (env vars, settings.json, etc.).
  */
-type ConfigKey = 'sdkRootDir' | 'cmdToolsPath' | 'emulatorDir' | 'hapPath' | 'cmdToolsUrlLinux' | 'cmdToolsUrlWindows' | 'cmdToolsUrlMac' | 'emulatorUrl';
+type ConfigKey = 'sdkRootDir' | 'cmdToolsPath' | 'hdcPath' | 'emulatorDir' | 'hapPath' | 'cmdToolsUrlLinux' | 'cmdToolsUrlWindows' | 'cmdToolsUrlMac' | 'emulatorUrl' | 'tmpDir' | 'sdkUrlBase' | 'applicationCertPath';
 interface ConfigProvider {
     /**
      * Get the configured value for `key`, or `fallback` if unset/empty.
@@ -90,9 +96,29 @@ declare class ChecksumMismatchError extends OniroError {
     readonly actual: string;
     constructor(expected: string, actual: string);
 }
+/**
+ * A download/extract ran out of room on the filesystem holding its scratch
+ * directory. The message is built by the caller (see `sdk/tmp.ts`) so it can name
+ * the directory, whether it is RAM-backed, and how to point elsewhere.
+ */
+declare class InsufficientSpaceError extends OniroError {
+    readonly dir: string;
+    constructor(message: string, dir: string, cause?: unknown);
+}
 declare class CancelledError extends OniroError {
     constructor(message?: string);
 }
+/**
+ * A spawned command ran to completion but exited non-zero. Lets callers
+ * distinguish "the tool ran and failed" from "the tool could not be spawned"
+ * (a missing binary surfaces as an OniroError / CmdToolsNotInstalledError).
+ */
+declare class CommandFailedError extends OniroError {
+    readonly command: string;
+    readonly exitCode: number;
+    readonly stderr: string;
+    constructor(command: string, exitCode: number, stderr: string);
+}
 
 /**
  * Carries the cross-cutting dependencies most core functions need: a Logger and a ConfigProvider.
@@ -107,6 +133,17 @@ declare function defaultContext(overrides?: Partial<OniroContext>): OniroContext
 interface SdkRelease {
     version: string;
     api: string;
+    /**
+     * Number of leading path components to strip when extracting the release
+     * tarball, per OS family. The Huawei mirror packs linux+windows in one
+     * tarball (no top-level wrapper for some releases → 0, else 1); macOS
+     * tarballs have a deeper layout (3). This table is the single source of
+     * truth read by `getSdkFilename()`.
+     */
+    tarballStrip: {
+        linuxWindows: number;
+        darwin: number;
+    };
 }
 /**
  * Known OpenHarmony SDK releases. Kept in sync with the bash CLI / extension.
@@ -131,9 +168,9 @@ interface SdkArchiveInfo {
  * Resolve the SDK archive filename, OS folder, and tar strip count for the current platform.
  *
  * The Huawei mirror packages Linux and Windows together in one tarball with `linux/` and
- * `windows/` subfolders. For 5.0.0/5.0.1/6.0 the tarball has no extra top-level wrapper
- * (strip=0); newer/older releases wrap the OS folders in a single top-level directory (strip=1).
- * macOS tarballs have a deeper layout (strip=3).
+ * `windows/` subfolders; macOS tarballs have a deeper layout. The per-release strip counts
+ * live in {@link ALL_SDKS} (`tarballStrip`). An unrecognized version falls back to the
+ * historical default (linux/windows=1, darwin=3).
  */
 declare function getSdkFilename(version?: string): SdkArchiveInfo;
 
@@ -146,18 +183,27 @@ declare function getOhosBaseSdkHome(config: ConfigProvider): string;
 declare function getCmdToolsPath(config: ConfigProvider): string;
 declare function getEmulatorDir(config: ConfigProvider): string;
 /**
- * Resolve the OHPM binary path inside the command-line tools install.
- * On Windows tries common executable suffixes (.exe, .cmd, .bat) before the POSIX name.
+ * Resolve a binary inside the command-line tools `bin/` directory by name
+ * (e.g. `'ohpm'`, `'hvigorw'`, `'codelinter'`). On Windows tries common
+ * executable suffixes (.exe, .cmd, .bat) before the POSIX name.
  */
-declare function getCmdToolsBin(config: ConfigProvider): string;
+declare function getCmdToolsBin(config: ConfigProvider, name?: string): string;
+/** Resolve the OHPM binary path inside the command-line tools install. */
+declare function getOhpmPath(config: ConfigProvider): string;
 /**
- * Resolve the hdc binary path inside the SDK toolchains tree.
+ * Resolve the hdc binary. An explicit `hdcPath` override (config key / `ONIRO_HDC`
+ * env var) wins — point it at a wrapper/proxy hdc when the device is not directly
+ * attached here (e.g. a remote device behind an SSH-tunnel `hdc` wrapper). When
+ * unset, fall back to the hdc bundled in the SDK toolchains tree.
  */
 declare function getHdcPath(config: ConfigProvider): string;
 /**
- * Resolve the hvigorw wrapper for a project, preferring the project-local copy
- * (which carries the project's pinned hvigor version) and falling back to the
- * one shipped with the command-line tools.
+ * Resolve the hvigorw wrapper for a project. Prefers the project-local copy
+ * (which carries the project's pinned hvigor version) — but ONLY when that
+ * wrapper is structurally complete. HMOS-vendored projects (systemui, launcher)
+ * ship a project-local `hvigorw` whose `hvigor/` install is absent, so the
+ * wrapper crashes on startup; in that case we fall back to the hvigorw bundled
+ * with the command-line tools, which is always installed.
  */
 declare function getHvigorwPath(config: ConfigProvider, projectDir: string): string;
 
@@ -168,6 +214,82 @@ declare function getHvigorwPath(config: ConfigProvider, projectDir: string): str
  */
 declare function detectProjectSdkVersion(projectRoot: string, logger?: Logger): number | undefined;
 
+/** Name of the scratch folder created next to an install target. */
+declare const INSTALL_TMP_DIRNAME = ".oniro-tmp";
+/** Advice appended to out-of-space failures in the scratch directory. */
+declare const TMP_DIR_HINT: string;
+/**
+ * Resolve the directory that download/extract scratch space is created in.
+ *
+ * Precedence: explicit override (CLI `--tmp-dir`) → `tmpDir` config key
+ * (`ONIRO_TMP_DIR`) → `<installRoot>/.oniro-tmp` → the system temp dir.
+ *
+ * The default sits next to the install target so that the unpacked tree is renamed
+ * into place rather than copied across a device boundary, and so the system temp dir
+ * — a RAM-backed `tmpfs` on most Linux systems, and far smaller than a multi-GB
+ * archive — is never in the picture.
+ */
+declare function resolveTmpRoot(config: ConfigProvider, override?: string, installRoot?: string): string;
+/** Create a private scratch directory under `root`, creating `root` if needed. */
+declare function createTempWorkDir(root: string, prefix: string): string;
+/**
+ * Remove a scratch directory once an install is done, taking the `.oniro-tmp` root
+ * with it when that leaves it empty. A root the caller named explicitly is left alone,
+ * as are roots another install is still using (the rmdir simply fails).
+ */
+declare function removeTempWorkDir(dir: string, root?: string): void;
+interface InstallTempDirOptions {
+    config: ConfigProvider;
+    /** Explicit scratch directory (CLI `--tmp-dir`). */
+    override?: string;
+    /** Directory the install lands in; the default scratch root is created inside it. */
+    installRoot: string;
+    prefix: string;
+    logger?: Logger;
+}
+interface InstallTempDir {
+    /** The private per-run scratch directory. Remove it when the install finishes. */
+    dir: string;
+    /** The configurable root it was created under, for out-of-space messages. */
+    root: string;
+}
+/**
+ * Create the scratch directory for an install, defaulting to `<installRoot>/.oniro-tmp`.
+ *
+ * When that default is unusable — a read-only or root-owned install parent, say — the
+ * system temp dir is used instead. A directory the caller asked for explicitly is never
+ * swapped out silently, and a full filesystem is reported rather than papered over.
+ */
+declare function createInstallTempDir(opts: InstallTempDirOptions): InstallTempDir;
+/**
+ * Bytes available to an unprivileged user on the filesystem holding `dir`.
+ * Returns null when the platform cannot report it.
+ */
+declare function getFreeSpaceBytes(dir: string): number | null;
+/**
+ * Whether `dir` lives on a RAM-backed filesystem (`tmpfs`/`ramfs`), i.e. one whose
+ * capacity comes out of memory rather than disk.
+ */
+declare function isRamBackedPath(dir: string): boolean;
+declare function formatBytes(bytes: number): string;
+/** Recognise an out-of-disk-space failure from fs/stream errors and their wrappers. */
+declare function isOutOfSpaceError(err: unknown): boolean;
+/**
+ * Fail before writing a byte when the filesystem holding `dir` cannot take
+ * `requiredBytes`. A no-op when free space cannot be determined.
+ */
+declare function ensureFreeSpace(dir: string, requiredBytes: number, what: string): void;
+/**
+ * Convert an out-of-space failure into an {@link InsufficientSpaceError}; any other
+ * error is returned unchanged, so callers can `throw toSpaceError(err, ...)`.
+ *
+ * `tmpRoot` is the scratch directory the operation was using. Failures under it are
+ * reported against it (not the per-run subdirectory the user cannot configure) and get
+ * the `--tmp-dir` remedy; failures elsewhere — an install target that is full — name
+ * their own directory and skip the remedy, which would not help.
+ */
+declare function toSpaceError(err: unknown, tmpRoot: string, what: string): unknown;
+
 interface DownloadOptions {
     url: string;
     dest: string;
@@ -177,10 +299,21 @@ interface DownloadOptions {
     start?: number;
     /** Overall progress range to consume (0..100). Default 100. */
     range?: number;
+    /** What the download is for, used in out-of-space messages. */
+    what?: string;
+    /**
+     * Configurable scratch root that `dest` lives under, if any. Out-of-space messages
+     * name it instead of the per-run subdirectory, since that is what the user can change.
+     */
+    tmpRoot?: string;
 }
 /**
  * Stream a remote file to disk with optional progress reporting and cancellation.
  * Follows redirects via the `follow-redirects` library.
+ *
+ * Fails fast with an `InsufficientSpaceError` when the destination filesystem cannot
+ * hold the advertised `content-length` — the common case being a system temp dir on a
+ * RAM-backed tmpfs that is far smaller than the SDK/tools archives.
  */
 declare function downloadFile(opts: DownloadOptions): Promise<void>;
 /**
@@ -239,6 +372,11 @@ interface InstallSdkOptions {
     progress?: ProgressReporter;
     abortSignal?: AbortSignal;
     logger?: Logger;
+    /**
+     * Scratch directory for the download/extract temporaries. Overrides the `tmpDir`
+     * config key and the default location next to the install target.
+     */
+    tmpDir?: string;
 }
 /**
  * Download and install an OpenHarmony SDK release into `<sdkRootDir>/<osFolder>/<api>`.
@@ -276,6 +414,11 @@ interface InstallCmdToolsOptions {
     logger?: Logger;
     /** Skip download and install from a local zip the caller already has. */
     localZipPath?: string;
+    /**
+     * Scratch directory for the download/extract temporaries. Overrides the `tmpDir`
+     * config key and the default location next to the install target.
+     */
+    tmpDir?: string;
 }
 /**
  * Install the OpenHarmony command-line tools into `<cmdToolsPath>`.
@@ -321,6 +464,11 @@ type Apl = 'normal' | 'system_basic' | 'system_core';
 type AppFeature = 'hos_normal_app' | 'hos_system_app';
 declare const APL_VALUES: readonly Apl[];
 declare const APP_FEATURE_VALUES: readonly AppFeature[];
+/** Keystore passwords. These must match the keystore in use. */
+interface SigningPasswords {
+    store: string;
+    key: string;
+}
 /**
  * Which signing key pairs with the chosen `apl`.
  *
@@ -362,6 +510,18 @@ interface GenerateSigningConfigsOptions {
      * existing `allowed-acls` is left alone.
      */
     acls?: string[];
+    /**
+     * Keystore passwords written into the profile sign step and the build-profile
+     * signingConfigs. Defaults to `'123456'` (the SDK's bundled OpenHarmony.p12
+     * password). Only override when supplying a matching custom keystore.
+     */
+    passwords?: SigningPasswords;
+    /**
+     * Override the bundled application cert chain (application-release kind only).
+     * When set, this file is copied to `signatures/OpenHarmonyApplication.cer`
+     * instead of the inlined cert. May also be sourced from `config.applicationCertPath`.
+     */
+    applicationCertPath?: string;
     /** Optional logger; defaults to no-op. */
     logger?: Logger;
 }
@@ -386,14 +546,20 @@ interface InstallEmulatorOptions {
     progress?: ProgressReporter;
     abortSignal?: AbortSignal;
     logger?: Logger;
+    /**
+     * Scratch directory for the downloaded ZIP. Overrides the `tmpDir` config key and
+     * the default location next to the install target.
+     */
+    tmpDir?: string;
 }
 /**
  * Download and extract the Oniro emulator into the configured `emulatorDir`.
  */
 declare function installEmulator(opts: InstallEmulatorOptions): Promise<void>;
 /**
- * Heuristic: emulator is considered installed if `images/run.sh` is present.
- * On Windows-only emulator builds (when they exist) this may not apply.
+ * Heuristic: the emulator is considered installed if either bundled launcher
+ * (`images/run.sh` or `images/run.bat`) is present, so a Windows-only build is
+ * detected too.
  */
 declare function isEmulatorInstalled(config: ConfigProvider): boolean;
 declare function removeEmulator(config: ConfigProvider): void;
@@ -439,16 +605,485 @@ interface StartEmulatorOptions {
 declare function startEmulator(opts: StartEmulatorOptions): Promise<void>;
 declare function stopEmulator(logger?: Logger): Promise<void>;
 
+/** Result of a spawned command. `code` is the process exit code (-1 if it was killed). */
+interface HdcExecResult {
+    code: number;
+    stdout: string;
+    stderr: string;
+}
+/** Streamed output callback, invoked per stdout/stderr chunk as it arrives. */
+type OutputSink = (chunk: string, stream: 'stdout' | 'stderr') => void;
+interface RunProcessOptions {
+    /** Executable to spawn. */
+    command: string;
+    /** Args passed verbatim (spawn runs with `shell: false`, so no shell parsing). */
+    args: readonly string[];
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    /** Kill the process after this many ms and reject. Default 60_000. */
+    timeoutMs?: number;
+    /** Abort the process; rejects with CancelledError. */
+    abortSignal?: AbortSignal;
+    /** Receive stdout/stderr chunks as they arrive (in addition to the buffered result). */
+    onOutput?: OutputSink;
+    /** Reserved for future scoped diagnostics; the buffered result is returned regardless. */
+    logger?: Logger;
+}
+/**
+ * Spawn an arbitrary process with `shell: false` and collect its output. The
+ * single low-level primitive every other command in the package builds on —
+ * because args are passed as an array and never interpolated into a shell
+ * string, command construction is injection-safe by construction.
+ *
+ * Resolves with `{ code, stdout, stderr }` for ANY exit code (callers opt into
+ * throw-on-non-zero via {@link ensureOk}). Rejects only on spawn failure
+ * (e.g. missing binary), timeout, or abort.
+ */
+declare function runProcess(opts: RunProcessOptions): Promise<HdcExecResult>;
+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]`. */
+    deviceSerial?: string;
+    /** Default 60_000. */
+    timeoutMs?: number;
+    abortSignal?: AbortSignal;
+    onOutput?: OutputSink;
+    logger?: Logger;
+}
+/**
+ * Run `hdc [-t <serial>] <args...>`. Resolves with `{ code, stdout, stderr }`
+ * for any exit code; use {@link ensureOk} to throw on non-zero.
+ */
+declare function hdcExec(opts: HdcExecOptions): Promise<HdcExecResult>;
+interface HdcShellOptions extends Omit<HdcExecOptions, 'args'> {
+    /** A single shell command, run as `hdc shell <command>` (one argv element — not host word-split). */
+    command: string;
+}
+/** Convenience wrapper for `hdc shell <command>`. */
+declare function shell(opts: HdcShellOptions): Promise<HdcExecResult>;
+/**
+ * Throw a typed {@link CommandFailedError} when `result.code !== 0`, otherwise
+ * return the result unchanged. Lets callers opt into throw-semantics.
+ */
+declare function ensureOk(result: HdcExecResult, command: string): HdcExecResult;
+/**
+ * Parse the exit-code marker appended by {@link shellChecked}. Pure/testable.
+ * Returns the remote exit code plus stdout with every marker occurrence
+ * stripped, or `null` when no marker is present (the command was killed/timed
+ * out, or the device shell never reached the trailing `echo`).
+ */
+declare function parseRemoteExit(stdout: string): {
+    code: number;
+    stdout: string;
+} | null;
+/**
+ * Like {@link shell}, but recovers the REMOTE command's exit status.
+ *
+ * `hdc shell "<cmd>"` reports hdc's OWN exit code (≈ always 0) regardless of
+ * whether `<cmd>` succeeded on the device — so on-device failures (`uinput`
+ * rejecting its args, a `bm install` error, a missing binary) otherwise look
+ * like success. We append an exit-code marker, parse it back out, and report
+ * it as `code`, with the marker stripped from stdout. Pair with
+ * {@link ensureRemoteOk} to throw on a non-zero remote exit.
+ */
+declare function shellChecked(opts: HdcShellOptions): Promise<HdcExecResult>;
+/**
+ * Throw a typed {@link CommandFailedError} on a non-zero result, preferring
+ * stderr but falling back to stdout for the detail — device tools like
+ * `uinput`/`uitest` print their errors to stdout, not stderr.
+ */
+declare function ensureRemoteOk(result: HdcExecResult, command: string): HdcExecResult;
+
+interface DeviceInfo {
+    /** Connect key — a USB serial or a `host:port` for a TCP target. */
+    serial: string;
+    /** 'Connected' | 'Offline' | 'Unauthorized' | … | 'Unknown' when not reported. */
+    status: string;
+    /** 'USB' | 'TCP' | … when reported by `-v`. */
+    connection?: string;
+    /** Device model, populated by getDeviceInfo (not by the bare target list). */
+    model?: string;
+}
+/**
+ * Parse the output of `hdc list targets -v` into structured rows. The first token
+ * of each non-empty row is the connect key (serial); connection/status are matched
+ * by keyword among the remaining tokens. `[Empty]` (no devices) yields `[]`.
+ */
+declare function parseDeviceList(stdout: string): DeviceInfo[];
+/** List connected hdc targets via `hdc list targets -v`. Empty list when none. */
+declare function listDevices(config: ConfigProvider, opts?: {
+    timeoutMs?: number;
+    logger?: Logger;
+}): Promise<DeviceInfo[]>;
+/**
+ * Resolve which device serial to address: an explicit `serial` wins, then the
+ * `ONIRO_DEVICE_SERIAL` / `DEVICE_SERIAL` env vars, then the single connected
+ * device. Throws when none or more than one is connected and nothing was specified.
+ */
+declare function selectDevice(config: ConfigProvider, serial?: string, opts?: {
+    timeoutMs?: number;
+    logger?: Logger;
+}): Promise<string>;
+
+interface ParamOptions {
+    deviceSerial?: string;
+    timeoutMs?: number;
+    logger?: Logger;
+}
+/** Read a system property via `hdc shell param get <key>`. Returns the trimmed value. */
+declare function paramGet(config: ConfigProvider, key: string, opts?: ParamOptions): Promise<string>;
+/**
+ * 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>;
+
+interface SendFileOptions {
+    config: ConfigProvider;
+    /** Local source path. */
+    local: string;
+    /** Remote destination path on the device. */
+    remote: 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>;
+interface RecvFileOptions {
+    config: ConfigProvider;
+    /** Remote source path on the device. */
+    remote: string;
+    /** Local destination path. */
+    local: string;
+    deviceSerial?: string;
+    timeoutMs?: number;
+    abortSignal?: AbortSignal;
+    onOutput?: OutputSink;
+    logger?: Logger;
+}
+/** Pull a file from the device via `hdc file recv <remote> <local>`. */
+declare function recvFile(opts: RecvFileOptions): Promise<void>;
+
+interface DisplaySize {
+    width: number;
+    height: number;
+}
+interface DisplaySizeOptions {
+    deviceSerial?: string;
+    timeoutMs?: number;
+    logger?: Logger;
+}
+/**
+ * Resolve the device's render resolution from `hidumper -s 10 -a screen`
+ * (`render resolution=WxH`). Returns null when unavailable. This is the W/H
+ * source for screenshots and the 0–1 normalization of layout bounds — no image
+ * decoding is involved.
+ */
+declare function getDisplaySize(config: ConfigProvider, opts?: DisplaySizeOptions): Promise<DisplaySize | null>;
+
+interface WaitForConditionOptions {
+    /** Resolves true when the condition is satisfied. Called once per poll. */
+    probe: () => Promise<boolean>;
+    /** Overall deadline. */
+    timeoutMs: number;
+    /** Poll interval. Default 2000. */
+    pollMs?: number;
+    /** Abort the wait; rejects with CancelledError. */
+    abortSignal?: AbortSignal;
+    /** Called every `heartbeatEvery` attempts (default 6) with progress info. */
+    onHeartbeat?: (attempt: number, remainingMs: number) => void;
+    heartbeatEvery?: number;
+    logger?: Logger;
+    /** Message for the timeout error. */
+    timeoutMessage?: string;
+}
+/**
+ * Generic deadline + poll + heartbeat loop. Calls `probe()` every `pollMs` until
+ * it resolves true (→ resolve) or the deadline passes (→ throw OniroError).
+ * A probe that throws is treated as "not yet" (the loop keeps polling) — this is
+ * what lets device waits tolerate transient hdc disconnects mid-reboot. Aborting
+ * the signal rejects with CancelledError.
+ *
+ * Extracted from the emulator hdc-wait loop so device lifecycle helpers share it.
+ */
+declare function waitForCondition(opts: WaitForConditionOptions): Promise<void>;
+
+interface WaitForBundleOptions {
+    config: ConfigProvider;
+    bundle: string;
+    deviceSerial?: string;
+    timeoutMs?: number;
+    abortSignal?: AbortSignal;
+    logger?: Logger;
+}
+/**
+ * Poll `pidof <bundle>` until the bundle has a clean numeric pid. Empty/failed
+ * pidof responses (including while the device is unreachable) do NOT count.
+ */
+declare function waitForBundle(opts: WaitForBundleOptions): Promise<void>;
+interface WaitForBootOptions {
+    config: ConfigProvider;
+    /** Require a clean numeric pid for this process/bundle name before returning. */
+    untilPidOf?: string;
+    deviceSerial?: string;
+    timeoutMs?: number;
+    abortSignal?: AbortSignal;
+    logger?: Logger;
+}
+/**
+ * Poll until the device responds AND (when `untilPidOf` is set) that process has
+ * a clean numeric pid. Tolerates the transient hdc disconnect during a reboot.
+ */
+declare function waitForBoot(opts: WaitForBootOptions): Promise<void>;
+interface RebootOptions {
+    config: ConfigProvider;
+    /** 'system' (default) reboots via param set; bootloader/recovery via `reboot <mode>`. */
+    mode?: 'system' | 'bootloader' | 'recovery';
+    /** When set (system mode), block until this bundle has a clean numeric pid after the reboot. */
+    waitForBundle?: string;
+    deviceSerial?: string;
+    timeoutMs?: number;
+    abortSignal?: AbortSignal;
+    logger?: Logger;
+}
+/**
+ * Reboot the device. System reboots use `param set ohos.startup.powerctrl reboot`
+ * (the path that works when force-stopping systemui is blocked); bootloader/
+ * recovery use `hdc shell reboot <mode>`. A reboot frequently tears down the hdc
+ * connection before the command returns, so command failure here is tolerated.
+ *
+ * When `waitForBundle` is set (system mode), waits for the device to drop and
+ * come back with the bundle running — so it doesn't return on the pre-reboot pid.
+ * A TCP target (e.g. an emulator at `127.0.0.1:55555`) is reconnected via
+ * `hdc tconn` during that wait, since hdc does not auto-reconnect TCP sessions
+ * across a reboot the way it does USB devices — pass the address as `deviceSerial`.
+ */
+declare function reboot(opts: RebootOptions): Promise<void>;
+
+interface Screenshot {
+    /** Raw JPEG bytes, exactly as `snapshot_display` wrote them (no decode/resize). */
+    pixels: Buffer;
+    /** Device render width/height from hidumper; 0 when it couldn't be resolved. */
+    width: number;
+    height: number;
+}
+interface ScreenshotOptions {
+    config: ConfigProvider;
+    deviceSerial?: string;
+    timeoutMs?: number;
+    logger?: Logger;
+}
+/**
+ * Capture the screen via on-device `snapshot_display`, pull the JPEG bytes back,
+ * and return them raw alongside the device resolution. The agent-facing grid
+ * overlay / downscale / base64 encoding stays in the MCP — core does no image
+ * decoding and adds no image dependency.
+ */
+declare function takeScreenshot(opts: ScreenshotOptions): Promise<Screenshot>;
+interface CaptureBurstOptions {
+    config: ConfigProvider;
+    count: number;
+    /** Delay between device-side captures, ms. */
+    intervalMs: number;
+    deviceSerial?: string;
+    timeoutMs?: number;
+    logger?: Logger;
+}
+/**
+ * Capture `count` frames `intervalMs` apart in a single device-side loop, then
+ * pull each frame back. Returns the raw JPEG buffers in order. The MCP composites
+ * these into a contact sheet + per-frame diff; core just returns the frames.
+ */
+declare function captureBurst(opts: CaptureBurstOptions): Promise<Buffer[]>;
+
+type InputType = 'click' | 'doubleClick' | 'longClick' | 'swipe' | 'drag' | 'fling' | 'keyEvent' | 'inputText';
+interface SendInputOptions {
+    config: ConfigProvider;
+    type: InputType;
+    /** Pixel coordinates. The %→px conversion lives in the MCP, not core. */
+    pxX?: number;
+    pxY?: number;
+    pxX2?: number;
+    pxY2?: number;
+    /** Velocity for swipe/drag/fling. */
+    speed?: number;
+    /** Key id or symbolic name (Back/Home/Power) for keyEvent. */
+    key?: string | number;
+    /** Text for inputText. */
+    text?: string;
+    deviceSerial?: string;
+    logger?: Logger;
+}
+/**
+ * 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
+ * minus the percentage→pixel step.
+ */
+declare function buildInputCommand(opts: SendInputOptions): string;
+/** Inject a UI input action via `uitest uiInput` (pixel coordinates). */
+declare function sendInput(opts: SendInputOptions): Promise<void>;
+interface Waypoint {
+    /** Pixel x. */
+    x: number;
+    /** Pixel y. */
+    y: number;
+    /** Time in ms relative to the gesture start. */
+    t: number;
+}
+interface SendGestureOptions {
+    config: ConfigProvider;
+    waypoints: Waypoint[];
+    /** Hold at the first point before moving (ms). Honored via the raw-touch path. */
+    holdStartMs?: number;
+    /** Hold at the last point before lifting (ms). Honored via the raw-touch path. */
+    holdEndMs?: number;
+    deviceSerial?: string;
+    logger?: Logger;
+}
+/**
+ * Build the chained `uitest uiInput drag` commands for a multi-segment path.
+ * Per segment, speed is derived from the waypoint time deltas (px/s). Pure.
+ */
+declare function buildGestureCommands(waypoints: Waypoint[]): string[];
+interface RawTouchEvent {
+    type: 'down' | 'move' | 'up';
+    x: number;
+    y: number;
+    /** Time in ms relative to the gesture start. */
+    t: number;
+}
+interface SendRawTouchOptions {
+    config: ConfigProvider;
+    events: RawTouchEvent[];
+    deviceSerial?: string;
+    logger?: Logger;
+}
+/**
+ * Build a single `uinput -T` touch operation sequence from down/move/up events,
+ * interleaving `-i <ms>` intervals from the event time deltas. Pure.
+ */
+declare function buildRawTouchCommand(events: RawTouchEvent[]): string;
+/** Expand a waypoint path (+ optional holds) into raw down/move/up events for
+ *  the `uinput` escape hatch ({@link sendRawTouch} / {@link buildRawTouchCommand}). */
+declare function waypointsToRawEvents(waypoints: Waypoint[], holdStartMs?: number, holdEndMs?: number): RawTouchEvent[];
+interface GestureUitestOptions {
+    /** A leading press-hold; when > 0 the stroke uses `drag` (press-and-hold,
+     *  then move) instead of `swipe`. uitest has no arbitrary hold duration. */
+    holdStartMs?: number;
+}
+/**
+ * Build a single continuous `uitest uiInput` stroke for a waypoint path. Pure.
+ *
+ * uitest has no polyline or stationary-hold primitive, so the path is collapsed
+ * to first→last (gesture-nav strokes are straight lines) with the velocity
+ * derived from the total elapsed time and clamped to uitest's range. A
+ * requested `holdStartMs` maps to `drag` (which presses-and-holds before
+ * moving — uitest's nearest equivalent to a leading hold); otherwise `swipe`.
+ */
+declare function buildGestureUitestCommand(waypoints: Waypoint[], opts?: GestureUitestOptions): string;
+/**
+ * Drive a swipe-style gesture via a single continuous `uitest uiInput` stroke —
+ * the MMI-injection path that `inputMonitor`-based services (gesture-nav,
+ * systemui overlays) actually observe. Preferred over raw `uinput`, whose
+ * kernel virtual-device events do not reach `inputMonitor` on some native-boot
+ * devices (and whose multi-op form some on-device `uinput` builds reject).
+ *
+ * uitest has no polyline or stationary-hold primitive: a multi-waypoint path is
+ * collapsed to first→last, `holdStartMs` maps to `drag` (press-hold-then-move),
+ * and `holdEndMs` has no equivalent (ignored). For true press-time control use
+ * {@link sendRawTouch} (raw `uinput`) — accepting the device caveats above.
+ */
+declare function sendGesture(opts: SendGestureOptions): Promise<void>;
+/**
+ * Low-level touch injection via `uinput -T`. The escape hatch when press timing
+ * matters (e.g. Quickstep motion-pause), which `uitest uiInput` can't express.
+ *
+ * WARNING: uinput's gesture form `uinput -T -g x1 y1 x2 y2 [press] [total]`
+ * silently no-ops if `press < 500ms` or `total - press < 500ms` ("press time is
+ * out of range" — it runs nothing). Keep press and post-press windows ≥ 500ms.
+ *
+ * DEVICE CAVEAT: on some native-boot devices these kernel-`uinput` events never
+ * reach MMI `inputMonitor` services (gesture-nav, systemui), and some on-device
+ * `uinput` builds reject the multi-op `-d/-m/-u` form with "wrong number of
+ * parameters". Prefer {@link sendGesture} (uitest) for those; this path now
+ * surfaces such failures instead of silently succeeding.
+ */
+declare function sendRawTouch(opts: SendRawTouchOptions): Promise<void>;
+
+/** A raw `uitest dumpLayout` node (attributes are strings). */
+interface RawLayoutNode {
+    attributes?: Record<string, string>;
+    children?: RawLayoutNode[];
+}
+/** A pruned, 0–1-normalized layout node. */
+interface LayoutNode {
+    /** bounds [x1,y1,x2,y2] normalized to 0–1 of the display. */
+    b?: [number, number, number, number];
+    /** center [x,y] normalized to 0–1. */
+    c?: [number, number];
+    type?: string;
+    text?: string;
+    desc?: string;
+    id?: string;
+    key?: string;
+    bundle?: string;
+    click?: boolean;
+    check?: boolean;
+    checked?: boolean;
+    sel?: boolean;
+    focus?: boolean;
+    scroll?: boolean;
+    longClick?: boolean;
+    children?: LayoutNode[];
+}
+interface DumpLayoutResult {
+    display: DisplaySize | null;
+    tree: LayoutNode;
+}
+/** 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;
+/**
+ * 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`.
+ */
+declare function pruneLayout(node: RawLayoutNode, display: DisplaySize | null): LayoutNode | LayoutNode[] | null;
+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;
+    deviceSerial?: string;
+    timeoutMs?: number;
+    logger?: Logger;
+}
+/**
+ * Dump the current on-screen layout via `uitest dumpLayout`, pull the JSON, and
+ * return a pruned, 0–1-normalized tree (or the raw parsed tree when `prune:false`).
+ */
+declare function dumpLayout(opts: DumpLayoutOptions): Promise<DumpLayoutResult>;
+
 /**
  * Read the project's bundle name from `AppScope/app.json5`.
  */
 declare function getBundleName(projectDir: string): string;
 /**
- * Read the main ability from `<module>/src/main/module.json5`. Defaults to `entry`
- * for the module folder name if not provided — projects with custom module names
- * should pass it explicitly.
+ * Read the ability to launch from `<module>/src/main/module.json5`. Defaults to
+ * `entry` for the module folder name. Resolution order:
+ *   1. `abilityName`, if given and present in `module.abilities[]`.
+ *   2. `module.mainElement`.
+ *   3. The first `visible` ability, then the first ability, from `module.abilities[]`.
+ * Modules with multiple abilities can be targeted explicitly via `abilityName`.
  */
-declare function getMainAbility(projectDir: string, moduleName?: string): string;
+declare function getMainAbility(projectDir: string, moduleName?: string, abilityName?: string): string;
 
 interface InstallAppOptions {
     config: ConfigProvider;
@@ -460,14 +1095,48 @@ interface InstallAppOptions {
     hapPath?: string;
     logger?: Logger;
 }
-declare function installApp(opts: InstallAppOptions): Promise<void>;
+interface InstallAppResult {
+    installed: boolean;
+    /** Bundle name read from the project's AppScope/app.json5, or '' if unavailable. */
+    bundleName: string;
+    /** The resolved absolute HAP path that was installed. */
+    hapPath: string;
+    /** Combined stdout+stderr from the install, trimmed. */
+    output: string;
+}
+declare function installApp(opts: InstallAppOptions): Promise<InstallAppResult>;
 interface LaunchAppOptions {
     config: ConfigProvider;
-    projectDir: string;
-    /** Override the module name if it isn't the default `entry`. */
+    /** Project mode: resolve bundle + main ability from the project. Required unless `bundleName` is given. */
+    projectDir?: string;
+    /**
+     * Bundle mode: launch an already-installed app directly by bundle name (no
+     * project needed). When set, `projectDir` is ignored. If `abilityName` is
+     * omitted, the main ability is resolved from the device via `bm dump -n`.
+     */
+    bundleName?: string;
+    /** Override the module name if it isn't the default `entry` (project mode). */
     moduleName?: string;
+    /** Explicit ability to launch; defaults to the module's mainElement / first visible ability (project mode) or the installed bundle's main ability (bundle mode). */
+    abilityName?: string;
+    deviceSerial?: string;
     logger?: Logger;
 }
+/**
+ * `aa start` exits 0 even when the launch is refused — a locked screen
+ * (`Error Code:10106102`), a missing ability, a permission denial, etc. The failure
+ * only shows up in its output. Returns the offending text when the output indicates a
+ * failed launch, or null when it looks like a success.
+ */
+declare function detectAaStartFailure(output: string): string | null;
+/**
+ * Parse the main ability of an installed bundle from `bm dump -n <bundle>`
+ * output. Pure/testable. The output is a bundle-name prefix line followed by a
+ * JSON blob; we take the entry module's `mainElementName` (fallback
+ * `mainAbility`), or the first module that declares one. Returns null when the
+ * bundle isn't installed or the output is unparseable.
+ */
+declare function parseMainAbilityFromBmDump(stdout: string): string | null;
 declare function launchApp(opts: LaunchAppOptions): Promise<void>;
 interface RunningProcess {
     pid: string;
@@ -484,6 +1153,30 @@ declare function listRunningProcesses(config: ConfigProvider, options?: {
     logger?: Logger;
 }): Promise<RunningProcess[] | string>;
 declare function findAppProcessId(config: ConfigProvider, projectDir: string, logger?: Logger): Promise<string>;
+interface BundleOptions {
+    config: ConfigProvider;
+    bundle: string;
+    deviceSerial?: string;
+    timeoutMs?: number;
+    logger?: Logger;
+}
+/**
+ * Non-throwing companion to {@link listRunningProcesses}: resolve a running
+ * process for a bundle, or `null` when it isn't running. Suitable for "is X
+ * running?" checks (e.g. the pre/post-install pid comparison in applyChanges).
+ *
+ * `pidof` matches the bundle's main (UIAbility) process. When that isn't found,
+ * we fall back to `track-jpid` to also catch **extension-ability** processes,
+ * which run under a separate process name `"<bundle>:<ext>"` (e.g. a
+ * ServiceExtension, FormExtension, UIExtension or input method). Without this,
+ * "verify the running process took the change" silently reported nothing for an
+ * app whose only live process is an extension.
+ */
+declare function findRunningProcess(opts: BundleOptions): Promise<RunningProcess | null>;
+/** Uninstall an app by bundle name (`hdc uninstall <bundle>`). */
+declare function uninstallApp(opts: BundleOptions): Promise<void>;
+/** Force-stop an app (`hdc shell aa force-stop <bundle>`). */
+declare function forceStop(opts: BundleOptions): Promise<void>;
 
 type HilogLevel = 'DEBUG' | 'INFO' | 'WARN' | 'ERROR' | 'FATAL';
 /** A parsed line of `hdc shell hilog` output. */
@@ -512,11 +1205,16 @@ interface StreamHilogOptions {
     config: ConfigProvider;
     /** Restrict the stream to a single process id (passed as `-P <pid>`). */
     processId?: string;
+    /** Filter by hilog domain, e.g. '0xD003900' (passed as `-D <domain>`). */
+    domain?: string | number;
+    /** Address a specific device (`-t <serial>`). */
+    deviceSerial?: string;
 }
 /**
- * Spawn `hdc shell hilog [-P <pid>]` and return the child process. The caller
- * owns the stdout/stderr streams (typically wired through `parseHilogLine`) and
- * is responsible for killing the process when streaming should stop.
+ * Spawn `hdc [-t serial] shell hilog [-P <pid>] [-D <domain>]` and return the
+ * child process. The caller owns the stdout/stderr streams (typically wired
+ * through `parseHilogLine`) and is responsible for killing the process when
+ * streaming should stop.
  */
 declare function streamHilog(opts: StreamHilogOptions): ChildProcessWithoutNullStreams;
 /**
@@ -525,6 +1223,61 @@ declare function streamHilog(opts: StreamHilogOptions): ChildProcessWithoutNullS
  * banners, blank lines, or partial chunks).
  */
 declare function parseHilogLine(line: string): HilogEntry | null;
+/** Collapse consecutive duplicate entries (same level/tag/message), ignoring time/pid. */
+declare function dedupEntries(entries: HilogEntry[]): HilogEntry[];
+interface WaitForLogOptions {
+    config: ConfigProvider;
+    /** Tested against `"<tag>: <message>"` of each parsed line. */
+    pattern: RegExp;
+    timeoutMs: number;
+    /** Restrict to a bundle's pid (resolved via pidof; re-resolved on each reconnect). */
+    bundle?: string;
+    domain?: string | number;
+    deviceSerial?: string;
+    abortSignal?: AbortSignal;
+    logger?: Logger;
+}
+/**
+ * Resolve with the first hilog entry whose `"<tag>: <message>"` matches `pattern`.
+ * The underlying stream is auto-respawned if it dies before the deadline, so the
+ * wait survives a reboot mid-observation. Rejects on timeout (OniroError) or
+ * abort (CancelledError).
+ */
+declare function waitForLog(opts: WaitForLogOptions): Promise<HilogEntry>;
+interface WatchLogOptions {
+    config: ConfigProvider;
+    pattern: RegExp;
+    /** How long to collect matching entries. */
+    durationMs: number;
+    bundle?: string;
+    domain?: string | number;
+    deviceSerial?: string;
+    /** Collapse consecutive duplicate lines. Default true. */
+    dedup?: boolean;
+    abortSignal?: AbortSignal;
+    logger?: Logger;
+}
+/** Collect all hilog entries matching `pattern` for `durationMs`. Deduped by default. */
+declare function watchLog(opts: WatchLogOptions): Promise<HilogEntry[]>;
+interface DumpLogOptions {
+    config: ConfigProvider;
+    /** Cap the result to the last N lines (device-side `tail -n`). */
+    lines?: number;
+    /** Restrict to a bundle's running pid (no output if it isn't running). */
+    bundle?: string;
+    /** Extended-regex string applied device-side via `grep -E`. */
+    grep?: string;
+    domain?: string | number;
+    deviceSerial?: string;
+    timeoutMs?: number;
+    logger?: Logger;
+}
+/**
+ * One-shot `hilog -x` dump, optionally filtered by domain, bundle pid, and a
+ * grep regex, capped to the last `lines`. Mirrors the proven MCP get_logs
+ * pipeline. Returns parsed entries.
+ */
+declare function dumpLog(opts: DumpLogOptions): Promise<HilogEntry[]>;
 
 interface RunHvigorwOptions {
     config: ConfigProvider;
@@ -539,6 +1292,13 @@ interface RunHvigorwOptions {
     task?: string;
     /** Extra raw args appended after the standard ones. */
     extraArgs?: readonly string[];
+    /**
+     * Build modules in parallel. Default `true`. Pass `false` to add `--no-parallel`
+     * for projects that require serial builds.
+     */
+    parallel?: boolean;
+    /** Abort the build; rejects with CancelledError and kills the hvigorw process. */
+    abortSignal?: AbortSignal;
     logger?: Logger;
     /**
      * Optional callback for each stdout/stderr chunk, lets callers stream output
@@ -549,12 +1309,132 @@ interface RunHvigorwOptions {
 interface RunHvigorwResult {
     exitCode: number;
 }
+/**
+ * Build the hvigorw argv. Pure (no I/O) so it is unit-testable. `--no-parallel`
+ * is added ONLY when `parallel === false` — builds are parallel by default.
+ */
+declare function buildHvigorwArgs(opts: {
+    task?: string;
+    product?: string;
+    module?: string;
+    buildMode?: string;
+    parallel?: boolean;
+    extraArgs?: readonly string[];
+}): string[];
 /**
  * Run the project's `hvigorw` wrapper. Replaces the extension's vscode-tasks indirection
  * and the bash CLI's chained `clean` + `assembleHap` calls with a single direct spawn.
  */
 declare function runHvigorw(opts: RunHvigorwOptions): Promise<RunHvigorwResult>;
 
+interface ModuleHaps {
+    signed: string[];
+    unsigned: string[];
+}
+interface DiscoverHapsOptions {
+    projectDir: string;
+    /** Max directory recursion depth. Default 8. */
+    maxDepth?: number;
+}
+/**
+ * Walk a project's build outputs and group `*-signed.hap` / `*-unsigned.hap`
+ * 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.
+ */
+declare function discoverHaps(opts: DiscoverHapsOptions): Promise<Record<string, ModuleHaps>>;
+
+interface RunOhpmOptions {
+    config: ConfigProvider;
+    projectDir: string;
+    args: readonly string[];
+    timeoutMs?: number;
+    abortSignal?: AbortSignal;
+    onOutput?: OutputSink;
+    logger?: Logger;
+}
+/** Run `ohpm <args>` in the project directory. Resolves with the raw result (any exit code). */
+declare function runOhpm(opts: RunOhpmOptions): Promise<HdcExecResult>;
+/**
+ * Install dependencies (`ohpm install --all`) only when `oh_modules/` is missing.
+ * Returns `{ installed: true }` when it ran. Throws CommandFailedError if the
+ * install ran and failed.
+ */
+declare function ensureOhModules(opts: {
+    config: ConfigProvider;
+    projectDir: string;
+    abortSignal?: AbortSignal;
+    onOutput?: OutputSink;
+    logger?: Logger;
+}): Promise<{
+    installed: boolean;
+}>;
+
+interface CodelinterFinding {
+    file: string;
+    line: number;
+    severity: string;
+    /** Rule code/id when present in the output, else ''. */
+    code: string;
+    message: string;
+}
+interface CodelinterResult {
+    /** codelinter process exit code. */
+    code: number;
+    findings: CodelinterFinding[];
+    /** Combined stdout+stderr, for callers that want the raw report. */
+    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.
+ */
+declare function parseCodelinterFindings(output: string): CodelinterFinding[];
+interface RunCodelinterOptions {
+    config: ConfigProvider;
+    projectDir: string;
+    /** Files/globs to lint; when omitted, codelinter is run with no file args. */
+    files?: readonly string[];
+    timeoutMs?: number;
+    abortSignal?: AbortSignal;
+    logger?: Logger;
+}
+/** Run the OpenHarmony codelinter and return parsed findings + the raw report. */
+declare function runCodelinter(opts: RunCodelinterOptions): Promise<CodelinterResult>;
+
+interface BuildHapOptions {
+    config: ConfigProvider;
+    projectDir: string;
+    product?: string;
+    module?: string;
+    /** Forwarded as hvigor `buildMode` (e.g. release, debug). */
+    mode?: string;
+    /** hvigor task. Default `assembleHap`. */
+    task?: string;
+    /** Run `ohpm install --all` first when `oh_modules/` is missing. Default true. */
+    autoInstallDeps?: boolean;
+    /** Build modules in parallel. Default true (see runHvigorw). */
+    parallel?: boolean;
+    abortSignal?: AbortSignal;
+    onOutput?: (chunk: string, stream: 'stdout' | 'stderr') => void;
+    logger?: Logger;
+}
+interface BuildHapResult {
+    exitCode: number;
+    durationMs: number;
+    /** Built HAPs grouped by module folder. */
+    discoveredHaps: Record<string, ModuleHaps>;
+    warnings: string[];
+}
+/**
+ * High-level build orchestration: ensure deps → run hvigorw → discover the
+ * produced HAPs. The single call the CLI and MCP want; `runHvigorw` stays a raw
+ * single-spawn primitive.
+ */
+declare function buildHap(opts: BuildHapOptions): Promise<BuildHapResult>;
+
 /**
  * Conservative project-folder-name validator (no path separators, conservative charset).
  */
@@ -610,6 +1490,55 @@ interface CreateScaffoldResult {
  */
 declare function createScaffold(opts: CreateScaffoldOptions): Promise<CreateScaffoldResult>;
 
+interface ProjectModule {
+    name: string;
+    /** Source path relative to the project root (e.g. `./entry`). */
+    srcPath: string;
+    /** Target names declared under the module (often empty). */
+    targets: string[];
+}
+/**
+ * Read the `modules[]` declared in `build-profile.json5` so callers can target a
+ * specific module in a multi-module project.
+ */
+declare function listModules(opts: {
+    projectDir: string;
+}): ProjectModule[];
+
+interface AbilityInfo {
+    name: string;
+    type?: string;
+    visible?: boolean;
+    srcEntry?: string;
+}
+/**
+ * Read all abilities declared in a module's `module.json5` `abilities[]`.
+ * Defaults to the `entry` module folder.
+ */
+declare function listAbilities(opts: {
+    projectDir: string;
+    moduleName?: string;
+}): AbilityInfo[];
+
+interface PrepareSigningOptions {
+    config: ConfigProvider;
+    projectDir: string;
+    apl?: Apl;
+    appFeature?: AppFeature;
+    acls?: string[];
+    passwords?: SigningPasswords;
+    logger?: Logger;
+}
+interface PrepareSigningResult {
+    source: 'present' | 'fresh';
+}
+/**
+ * Ensure a project has signing material: a no-op when `signatures/` +
+ * signingConfigs already exist ('present'), otherwise generate them via
+ * {@link generateSigningConfigs} ('fresh', which needs java + the SDK).
+ */
+declare function prepareSigning(opts: PrepareSigningOptions): PrepareSigningResult;
+
 declare function readJson5File<T>(filePath: string): T;
 /**
  * Write strict JSON content (quoted keys) to a `.json5` file. Keeps the file
@@ -619,6 +1548,127 @@ declare function writeJson5File(filePath: string, value: unknown): void;
 declare function readJsonFile<T>(filePath: string): T;
 declare function writeJsonFile(filePath: string, value: unknown): void;
 
+interface HidumperOptions {
+    config: ConfigProvider;
+    deviceSerial?: string;
+    timeoutMs?: number;
+    logger?: Logger;
+}
+interface ScreenDump {
+    width: number;
+    height: number;
+    /** Raw hidumper screen output. */
+    raw: string;
+}
+/** `hidumper -s 10 -a screen` → parsed render resolution + raw text, or null. */
+declare function dumpScreen(opts: HidumperOptions): Promise<ScreenDump | null>;
+/** `hidumper -s WindowManagerService -a -a` — windows in z-order with surface presence. */
+declare function dumpWindow(opts: HidumperOptions): Promise<string>;
+/** `hidumper -s RenderService -a allInfo` — composition state / refresh rate. */
+declare function dumpRenderService(opts: HidumperOptions): Promise<string>;
+
+interface DeviceFullInfo {
+    serial: string;
+    model?: string;
+    manufacturer?: string;
+    brand?: string;
+    osFullName?: string;
+    osReleaseType?: string;
+    sdkApiVersion?: string;
+    buildVersion?: string;
+    display: {
+        width: number;
+        height: number;
+    } | null;
+}
+interface GetDeviceInfoOptions {
+    config: ConfigProvider;
+    deviceSerial?: string;
+    timeoutMs?: number;
+    logger?: Logger;
+}
+/** Collate device properties (`param get` × N) and the display resolution. */
+declare function getDeviceInfo(opts: GetDeviceInfoOptions): Promise<DeviceFullInfo>;
+
+interface HapAssetDiff {
+    /** File paths present in the new HAP but not the installed one. */
+    addedAssetPaths: string[];
+    /** File paths present in the installed HAP but not the new one. */
+    removedAssetPaths: string[];
+}
+/** Pure set-diff of two file-name listings, sorted. */
+declare function diffEntryNames(installed: Iterable<string>, next: Iterable<string>): HapAssetDiff;
+/**
+ * Diff the file manifests of two HAP (zip) archives. Drives the ACE-extractor
+ * cache-invalidation reboot decision in `applyChanges`: when the new HAP adds or
+ * renames file paths vs the installed one, the path-keyed asset cache can serve
+ * stale "GetAsset failed" errors until a reboot.
+ */
+declare function diffHapAssets(opts: {
+    installedHap: string;
+    newHap: string;
+}): Promise<HapAssetDiff>;
+
+type InstallMethod = 'replace' | 'uninstall-install' | 'refuse';
+/**
+ * P0-5a decision: how to install given whether `hdc install -r` reported a
+ * sign-info-inconsistent error (9568332). System bundles are NOT silently
+ * uninstalled (that can brick the device) unless explicitly allowed.
+ */
+declare function decideInstallMethod(s: {
+    signInfoInconsistent: boolean;
+    isSystemBundle: boolean;
+    allowUninstall: boolean;
+}): InstallMethod;
+interface RebootDecision {
+    reboot: boolean;
+    reason: 'asset-cache' | 'pid-unchanged' | 'none';
+}
+/**
+ * P0-5b/c decision: whether to reboot after installing. Reboot when the HAP's
+ * asset paths changed (ACE extractor cache is path-keyed and survives a process
+ * kill), or when a persistent/system bundle's process didn't restart.
+ */
+declare function decideReboot(s: {
+    assetsChanged: boolean;
+    isSystemBundle: boolean;
+    preInstallPid: number | null;
+    postInstallPid: number | null;
+}): RebootDecision;
+interface ApplyChangesOptions {
+    config: ConfigProvider;
+    bundle: string;
+    /** Explicit HAP path. If omitted, resolved from projectDir (+ module) via discoverHaps. */
+    hapPath?: string;
+    projectDir?: string;
+    module?: string;
+    /** Local path to the currently-installed HAP; enables the asset-cache diff/reboot. */
+    installedHapPath?: string;
+    /** Persistent/system bundle (e.g. systemui). Default false. */
+    isSystemBundle?: boolean;
+    /** Permit uninstalling a system bundle on sign-info mismatch (dangerous). Default false. */
+    allowUninstall?: boolean;
+    deviceSerial?: string;
+    abortSignal?: AbortSignal;
+    logger?: Logger;
+}
+interface ApplyChangesResult {
+    method: 'replace' | 'uninstall-install' | 'reboot';
+    preInstallPid: number | null;
+    postInstallPid: number | null;
+    replaced: boolean;
+    /** True when an asset-path change forced the reboot. */
+    cacheCleared: boolean;
+}
+/**
+ * Install a HAP and verify the running process took the change. Handles the
+ * three failure modes the naive "install the most recent signed HAP" deploy
+ * ignores: sign-info-inconsistent on `-r`, asset-cache invalidation, and a
+ * persistent bundle that didn't restart. See {@link decideInstallMethod} /
+ * {@link decideReboot} for the (pure, tested) branch logic.
+ */
+declare function applyChanges(opts: ApplyChangesOptions): Promise<ApplyChangesResult>;
+
 declare const VERSION: string;
 
-export { ALL_SDKS, APL_VALUES, APP_FEATURE_VALUES, type Apl, type AppFeature, CancelledError, ChecksumMismatchError, CmdToolsNotInstalledError, type CmdToolsStatus, type ConfigKey, type ConfigProvider, type CreateScaffoldOptions, type CreateScaffoldResult, type DownloadOptions, type ExtractZipOptions, type GenerateSigningConfigsOptions, type HilogEntry, type HilogLevel, type InstallAppOptions, type InstallCmdToolsOptions, type InstallEmulatorOptions, type InstallSdkOptions, type LaunchAppOptions, type Logger, OHOS_URL_BASE, type OniroContext, OniroError, type OsFolder, type ProgressReporter, type ProgressUpdate, type Prompter, type RunHvigorwOptions, type RunHvigorwResult, type RunningProcess, type SdkArchiveInfo, type SdkInfo, SdkNotInstalledError, type SdkRelease, type SetHilogLevelOptions, type SigningKind, type StartEmulatorOptions, type StreamHilogOptions, type TemplateOption, UnsupportedPlatformError, VERSION, attemptHdcConnection, consoleLogger, createMaterial, createScaffold, decryptPwd, defaultContext, defaultPaths, detectProjectSdkVersion, detectSigningConfigNames, downloadAndInstallSdk, downloadFile, encryptPwd, extractTarball, extractZipWithProgress, findAppProcessId, findCmdToolsSourceDir, generateSigningConfigs, getBundleName, getCmdToolsBin, getCmdToolsDownloadUrl, getCmdToolsPath, getCmdToolsStatus, getEmulatorDir, getHdcPath, getHvigorwPath, getInstalledSdks, getKey, getMainAbility, getOhosBaseSdkHome, getOsFolder, getSdkFilename, getSdkRootDir, getSupportedSdksForUi, installApp, installCmdTools, installEmulator, isCmdToolsInstalled, isEmulatorInstalled, isValidBundleName, isValidProjectName, launchApp, listRunningProcesses, listTemplates, nonInteractivePrompter, noopLogger, noopProgress, parseHilogLine, pickSigningKind, readJson5File, readJsonFile, removeCmdTools, removeEmulator, removeSdk, runHvigorw, setHilogLevel, startEmulator, staticConfig, stopEmulator, streamHilog, validateTemplateLayout, verifySha256, writeJson5File, writeJsonFile };
+export { ALL_SDKS, APL_VALUES, APP_FEATURE_VALUES, type AbilityInfo, type Apl, type AppFeature, type ApplyChangesOptions, type ApplyChangesResult, type BuildHapOptions, type BuildHapResult, type BundleOptions, CancelledError, type CaptureBurstOptions, ChecksumMismatchError, CmdToolsNotInstalledError, type CmdToolsStatus, type CodelinterFinding, type CodelinterResult, CommandFailedError, type ConfigKey, type ConfigProvider, type CreateScaffoldOptions, type CreateScaffoldResult, 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, type HapAssetDiff, type HdcExecOptions, type HdcExecResult, type HdcShellOptions, type HidumperOptions, type HilogEntry, type HilogLevel, 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 RawLayoutNode, type RawTouchEvent, type RebootDecision, type RebootOptions, type RecvFileOptions, type RunCodelinterOptions, type RunHvigorwOptions, type RunHvigorwResult, type RunOhpmOptions, type RunProcessOptions, type RunningProcess, 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 SigningPasswords, type StartEmulatorOptions, type StreamHilogOptions, TMP_DIR_HINT, type TemplateOption, UnsupportedPlatformError, VERSION, type WaitForBootOptions, type WaitForBundleOptions, type WaitForConditionOptions, type WaitForLogOptions, type WatchLogOptions, type Waypoint, applyChanges, attemptHdcConnection, buildGestureCommands, buildGestureUitestCommand, buildHap, buildHvigorwArgs, buildInputCommand, buildRawTouchCommand, captureBurst, consoleLogger, createInstallTempDir, createMaterial, createScaffold, createTempWorkDir, decideInstallMethod, decideReboot, decryptPwd, dedupEntries, defaultContext, defaultPaths, detectAaStartFailure, detectProjectSdkVersion, detectSigningConfigNames, diffEntryNames, diffHapAssets, discoverHaps, downloadAndInstallSdk, downloadFile, dumpLayout, dumpLog, dumpRenderService, dumpScreen, dumpWindow, encryptPwd, ensureFreeSpace, ensureOhModules, ensureOk, ensureRemoteOk, extractTarball, extractZipWithProgress, findAppProcessId, findCmdToolsSourceDir, findRunningProcess, forceStop, formatBytes, generateSigningConfigs, getBundleName, getCmdToolsBin, getCmdToolsDownloadUrl, getCmdToolsPath, getCmdToolsStatus, getDeviceInfo, getDisplaySize, getEmulatorDir, getFreeSpaceBytes, getHdcPath, getHvigorwPath, getInstalledSdks, getKey, getMainAbility, getOhosBaseSdkHome, getOhpmPath, getOsFolder, getSdkFilename, getSdkRootDir, getSupportedSdksForUi, hdcExec, installApp, installCmdTools, installEmulator, isCmdToolsInstalled, isEmulatorInstalled, isOutOfSpaceError, isRamBackedPath, isValidBundleName, isValidProjectName, launchApp, listAbilities, listDevices, listModules, listRunningProcesses, listTemplates, nonInteractivePrompter, noopLogger, noopProgress, paramGet, paramSet, parseBounds, parseCodelinterFindings, parseDeviceList, parseHilogLine, parseMainAbilityFromBmDump, parseRemoteExit, pickSigningKind, prepareSigning, pruneLayout, readJson5File, readJsonFile, reboot, recvFile, removeCmdTools, removeEmulator, removeSdk, removeTempWorkDir, resolveTmpRoot, runCodelinter, runHvigorw, runOhpm, runProcess, scopedLogger, selectDevice, sendFile, sendGesture, sendInput, sendRawTouch, setHilogLevel, shell, shellChecked, startEmulator, staticConfig, stopEmulator, streamHilog, takeScreenshot, toSpaceError, uninstallApp, validateTemplateLayout, verifySha256, waitForBoot, waitForBundle, waitForCondition, waitForLog, watchLog, waypointsToRawEvents, writeJson5File, writeJsonFile };