@oniroproject/core 0.12.0 → 0.14.0

package/dist/index.js

@@ -89,14 +89,19 @@ var OniroError = class extends Error {
   cause;
 };
 var SdkNotInstalledError = class extends OniroError {
-  constructor(api, expectedPath) {
-    super(`SDK API ${api} is not installed at ${expectedPath}.`);
+  /** `version` is the release that ships `api` (e.g. `6.0` for API 20), when one is known. */
+  constructor(api, expectedPath, version) {
+    super(
+      `SDK API ${api} is not installed at ${expectedPath}.` + (version ? ` Install it with \`oniro-app sdk install ${version}\`.` : "")
+    );
     this.api = api;
     this.expectedPath = expectedPath;
+    this.version = version;
     this.name = "SdkNotInstalledError";
   }
   api;
   expectedPath;
+  version;
 };
 var CmdToolsNotInstalledError = class extends OniroError {
   constructor(expectedPath) {
@@ -372,6 +377,24 @@ function isProjectLocalHvigorwWorking(projectDir) {
 import * as fs3 from "fs";
 import * as path4 from "path";
 import JSON5 from "json5";
+function localPropertiesSdkDir(projectRoot) {
+  try {
+    const content = fs3.readFileSync(path4.join(projectRoot, "local.properties"), "utf-8");
+    const m = /^\s*sdk\.dir\s*[=:]\s*(.+?)\s*$/m.exec(content);
+    return m ? m[1].replace(/\\(.)/g, "$1") : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function findMissingProjectSdk(config, projectRoot) {
+  const api = detectProjectSdkVersion(projectRoot);
+  if (api === void 0) return null;
+  const expected = path4.join(getOhosBaseSdkHome(config), String(api));
+  if (fs3.existsSync(expected)) return null;
+  const localSdkDir = localPropertiesSdkDir(projectRoot);
+  if (localSdkDir && fs3.existsSync(path4.join(localSdkDir, String(api)))) return null;
+  return new SdkNotInstalledError(String(api), expected, ALL_SDKS.find((s) => s.api === String(api))?.version);
+}
 function detectProjectSdkVersion(projectRoot, logger = noopLogger) {
   const buildProfilePath = path4.join(projectRoot, "build-profile.json5");
   if (!fs3.existsSync(buildProfilePath)) {
@@ -557,14 +580,14 @@ var pipelineAsync = promisify(pipeline);
 async function downloadFile(opts) {
   const { url, dest, progress, abortSignal } = opts;
   const proto = url.startsWith("https") ? https : http;
-  return new Promise((resolve6, reject) => {
+  return new Promise((resolve7, reject) => {
     const s = Math.max(0, Math.min(100, opts.start ?? 0));
     const r = Math.max(0, Math.min(100 - s, opts.range ?? 100));
     let settled = false;
     const done = (err) => {
       if (settled) return;
       settled = true;
-      err ? reject(err) : resolve6();
+      err ? reject(err) : resolve7();
     };
     if (abortSignal?.aborted) {
       done(new CancelledError("Download cancelled before start."));
@@ -1051,21 +1074,27 @@ async function installCmdTools(opts) {
     removeTempWorkDir(tmpDir, tmpRoot);
   }
 }
+function detectCmdToolsFlavour(cmdToolsPath) {
+  return fs11.existsSync(path12.join(cmdToolsPath, "sdk", "default", "hms")) ? "HarmonyOS" : "OpenHarmony";
+}
 function getCmdToolsStatus(config) {
   const cmdPath = getCmdToolsPath(config);
+  const hdcPath = getHdcPath(config);
+  const base = { path: cmdPath, hdc: { path: hdcPath, exists: fs11.existsSync(hdcPath) } };
   const binDir = path12.join(cmdPath, "bin");
   const candidates = os7.platform() === "win32" ? ["ohpm.exe", "ohpm.cmd", "ohpm.bat", "ohpm"] : ["ohpm"];
   const bin = candidates.map((c) => path12.join(binDir, c)).find((p) => fs11.existsSync(p));
   if (!bin) {
-    return { installed: false, status: "Not installed" };
+    return { installed: false, status: "Not installed", ...base };
   }
+  const installed = { installed: true, ...base, flavour: detectCmdToolsFlavour(cmdPath) };
   try {
     const versionFile = path12.join(cmdPath, "version.txt");
     if (fs11.existsSync(versionFile)) {
       const content = fs11.readFileSync(versionFile, "utf8");
       for (const line of content.split(/\r?\n/)) {
         const m = line.match(/^\s*#\s*Version:\s*(.+)$/);
-        if (m?.[1]) return { installed: true, status: `Installed (${m[1].trim()})` };
+        if (m?.[1]) return { ...installed, status: `Installed (${m[1].trim()})` };
       }
     }
   } catch {
@@ -1079,9 +1108,9 @@ function getCmdToolsStatus(config) {
     });
     if (res.error || res.status !== 0) throw res.error ?? new Error(`exit ${String(res.status)}`);
     const version = res.stdout.trim();
-    return { installed: true, status: `Installed (${version})` };
+    return { ...installed, status: `Installed (${version})` };
   } catch {
-    return { installed: true, status: "Installed (version unknown)" };
+    return { ...installed, status: "Installed (version unknown)" };
   }
 }
 function isCmdToolsInstalled(config) {
@@ -1371,6 +1400,9 @@ function modifyProfileTemplate(projectDir, apl, appFeature, logger, options = {}
     profileTemplate.acls = profileTemplate.acls ?? {};
     profileTemplate.acls["allowed-acls"] = options.acls;
   }
+  if (options.appPrivilegeCapabilities !== void 0) {
+    profileTemplate["app-privilege-capabilities"] = options.appPrivilegeCapabilities;
+  }
   fs13.writeFileSync(profileTemplatePath, JSON.stringify(profileTemplate, null, 2));
 }
 function generateP7bFile(projectDir, paths, logger, passwords) {
@@ -1460,6 +1492,12 @@ function updateBuildProfile(projectDir, kind, logger, passwords) {
       storeFile: "./signatures/OpenHarmony.p12"
     }
   }));
+  for (const product of buildProfile.app.products ?? []) {
+    if (typeof product.signingConfig !== "string" || product.signingConfig === "") {
+      product.signingConfig = configNames[0];
+      logger.info(`[sign] Pointing a product with no signingConfig at "${configNames[0]}".`);
+    }
+  }
   fs13.writeFileSync(buildProfilePath, JSON.stringify(buildProfile, null, 2));
 }
 function prepareMaterialDirectory(projectDir, logger) {
@@ -1491,7 +1529,7 @@ function generateSigningConfigs(options) {
   }
   const sdkPath = path14.join(sdkHome, String(sdkVersion));
   if (!fs13.existsSync(sdkPath)) {
-    throw new OniroError(`SDK path does not exist: ${sdkPath}`);
+    throw new SdkNotInstalledError(String(sdkVersion), sdkPath, ALL_SDKS.find((s) => s.api === String(sdkVersion))?.version);
   }
   const paths = {
     signTool: path14.join(sdkPath, "toolchains/lib/hap-sign-tool.jar"),
@@ -1503,7 +1541,11 @@ function generateSigningConfigs(options) {
   const passwords = options.passwords ?? DEFAULT_PASSWORDS;
   logger.info("[sign] Starting signing configuration generation...");
   copyFilesToProject(projectDir, paths, kind, logger, options.applicationCertPath);
-  modifyProfileTemplate(projectDir, apl, appFeature, logger, { kind, acls: options.acls });
+  modifyProfileTemplate(projectDir, apl, appFeature, logger, {
+    kind,
+    acls: options.acls,
+    appPrivilegeCapabilities: options.appPrivilegeCapabilities
+  });
   generateP7bFile(projectDir, paths, logger, passwords);
   prepareMaterialDirectory(projectDir, logger);
   updateBuildProfile(projectDir, kind, logger, passwords);
@@ -1570,7 +1612,7 @@ function runProcess(opts) {
   const { command, args, cwd, env, onOutput } = opts;
   const timeoutMs = opts.timeoutMs ?? 6e4;
   const { abortSignal } = opts;
-  return new Promise((resolve6, reject) => {
+  return new Promise((resolve7, reject) => {
     if (abortSignal?.aborted) {
       reject(new CancelledError(`Command aborted before start: ${command}`));
       return;
@@ -1635,21 +1677,41 @@ ${stderr.trim()}` : "")
         );
         return;
       }
-      resolve6({ code: code ?? -1, stdout, stderr });
+      resolve7({ code: code ?? -1, stdout, stderr });
     });
   });
 }
-function hdcExec(opts) {
+function resolveDeviceSerial(explicit, env = process.env) {
+  if (explicit && explicit !== "auto") return explicit;
+  const fromEnv = env.ONIRO_DEVICE_SERIAL || env.DEVICE_SERIAL;
+  return fromEnv && fromEnv !== "auto" ? fromEnv : void 0;
+}
+function hdcTargetArgs(explicit) {
+  const serial = resolveDeviceSerial(explicit);
+  return serial ? ["-t", serial] : [];
+}
+var HOST_COMMANDS = /* @__PURE__ */ new Set(["list", "tconn", "start", "kill", "version", "checkserver"]);
+function hdcTargetArgsFor(args, explicit) {
+  if (HOST_COMMANDS.has(args[0] ?? "")) return explicit ? ["-t", explicit] : [];
+  return hdcTargetArgs(explicit);
+}
+function hdcClientFailure(output) {
+  const first = output.split(/\r?\n/).find((l) => l.trim() !== "")?.trim() ?? "";
+  return first.startsWith("[Fail]") ? first : null;
+}
+async function hdcExec(opts) {
   const hdc = getHdcPath(opts.config);
-  const argv = opts.deviceSerial ? ["-t", opts.deviceSerial, ...opts.args] : [...opts.args];
-  return runProcess({
+  const res = await runProcess({
     command: hdc,
-    args: argv,
+    args: [...hdcTargetArgsFor(opts.args, opts.deviceSerial), ...opts.args],
     timeoutMs: opts.timeoutMs,
     abortSignal: opts.abortSignal,
     onOutput: opts.onOutput,
     logger: opts.logger
   });
+  if (res.code === 0 && hdcClientFailure(`${res.stdout}
+${res.stderr}`)) return { ...res, code: 1 };
+  return res;
 }
 function shell(opts) {
   const { command, ...rest } = opts;
@@ -1657,10 +1719,15 @@ function shell(opts) {
 }
 function ensureOk(result, command) {
   if (result.code !== 0) {
-    throw new CommandFailedError(command, result.code, result.stderr.trim());
+    throw new CommandFailedError(command, result.code, withTargetHint(result.stderr.trim() || result.stdout.trim()));
   }
   return result;
 }
+function withTargetHint(detail) {
+  if (!/need connect-key|Not match target/i.test(detail)) return detail;
+  return `${detail}
+More than one target is connected, or the serial is unknown: pass --device <serial> or set ONIRO_DEVICE_SERIAL to one listed by \`oniro-app devices\`.`;
+}
 var REMOTE_RC_RE = /__ONIRO_RC=(-?\d+)__/g;
 function parseRemoteExit(stdout) {
   let code = null;
@@ -1677,7 +1744,7 @@ async function shellChecked(opts) {
 }
 function ensureRemoteOk(result, command) {
   if (result.code !== 0) {
-    throw new CommandFailedError(command, result.code, result.stderr.trim() || result.stdout.trim());
+    throw new CommandFailedError(command, result.code, withTargetHint(result.stderr.trim() || result.stdout.trim()));
   }
   return result;
 }
@@ -1763,11 +1830,11 @@ async function startEmulator(opts) {
   fs16.writeFileSync(PID_FILE, String(child.pid));
   child.unref();
   logger.info(`Emulator launched (PID ${child.pid}). Logs: ${logPath}`);
-  const earlyExit = new Promise((resolve6) => {
-    child.once("exit", (code) => resolve6(code));
-    child.once("error", () => resolve6(-1));
+  const earlyExit = new Promise((resolve7) => {
+    child.once("exit", (code) => resolve7(code));
+    child.once("error", () => resolve7(-1));
   });
-  const liveness = new Promise((resolve6) => setTimeout(() => resolve6("alive"), 2e3));
+  const liveness = new Promise((resolve7) => setTimeout(() => resolve7("alive"), 2e3));
   const outcome = await Promise.race([earlyExit, liveness]);
   if (outcome !== "alive") {
     const tail = readTail(logPath, 4e3);
@@ -1847,6 +1914,43 @@ async function stopEmulator(logger = noopLogger) {
     if (err) logger.warn(`Could not remove PID file: ${err.message}`);
   });
 }
+async function isQemuRunning(logger) {
+  if (os8.platform() !== "win32") {
+    try {
+      const pid = Number(fs16.readFileSync(PID_FILE, "utf8").trim());
+      if (Number.isFinite(pid) && pid > 0) {
+        process.kill(pid, 0);
+        return true;
+      }
+    } catch {
+    }
+  }
+  const [cmd, ...args] = os8.platform() === "win32" ? ["tasklist", "/FI", "IMAGENAME eq qemu-system-x86_64.exe", "/NH"] : ["pgrep", "-f", "qemu-system-x86_64"];
+  try {
+    const res = await runProcess({ command: cmd, args, timeoutMs: 1e4, logger });
+    return os8.platform() === "win32" ? /qemu-system-x86_64/i.test(res.stdout) : res.code === 0;
+  } catch {
+    return false;
+  }
+}
+async function getEmulatorStatus(config, opts = {}) {
+  const logger = opts.logger ?? noopLogger;
+  const address = opts.address ?? "127.0.0.1:55555";
+  const dir = getEmulatorDir(config);
+  let connected = false;
+  try {
+    const targets = await hdcExec({ config, args: ["list", "targets", "-v"], timeoutMs: 1e4, logger });
+    connected = targets.stdout.split("\n").some((l) => l.trim().startsWith(address) && /\bConnected\b/.test(l));
+  } catch {
+  }
+  return {
+    installed: isEmulatorInstalled(config),
+    dir,
+    running: await isQemuRunning(logger),
+    address,
+    connected
+  };
+}
 
 // src/hdc/devices.ts
 var STATUS_TOKENS = /* @__PURE__ */ new Set([
@@ -1885,9 +1989,8 @@ async function listDevices(config, opts = {}) {
   return parseDeviceList(res.stdout);
 }
 async function selectDevice(config, serial, opts = {}) {
-  if (serial && serial !== "auto") return serial;
-  const envSerial = process.env.ONIRO_DEVICE_SERIAL || process.env.DEVICE_SERIAL;
-  if (envSerial && envSerial !== "auto") return envSerial;
+  const resolved = resolveDeviceSerial(serial);
+  if (resolved) return resolved;
   const usable = (await listDevices(config, opts)).filter(
     (d) => d.status === "Connected" || d.status === "Unknown"
   );
@@ -1901,6 +2004,7 @@ async function selectDevice(config, serial, opts = {}) {
 }
 
 // src/hdc/param.ts
+var PARAM_MISSING_RE = /^Get parameter ".*" fail!/;
 async function paramGet(config, key, opts = {}) {
   const res = await shell({
     config,
@@ -1910,7 +2014,30 @@ async function paramGet(config, key, opts = {}) {
     logger: opts.logger
   });
   ensureOk(res, `hdc shell param get ${key}`);
-  return res.stdout.trim();
+  const value = res.stdout.trim();
+  if (PARAM_MISSING_RE.test(value)) throw new OniroError(`System parameter ${key} is not set: ${value}`);
+  return value;
+}
+var PARAM_SEPARATOR = "__ONIRO_PARAM__";
+function parseParamValues(keys, stdout) {
+  const parts = stdout.split(PARAM_SEPARATOR);
+  const values = {};
+  keys.forEach((key, i) => {
+    const value = parts[i]?.trim();
+    values[key] = value && !PARAM_MISSING_RE.test(value) ? value : void 0;
+  });
+  return values;
+}
+async function paramGetMany(config, keys, opts = {}) {
+  const res = await shell({
+    config,
+    command: keys.map((k) => `param get ${k}; echo ${PARAM_SEPARATOR}`).join("; "),
+    deviceSerial: opts.deviceSerial,
+    timeoutMs: opts.timeoutMs ?? 1e4,
+    logger: opts.logger
+  });
+  ensureOk(res, "hdc shell param get \u2026");
+  return parseParamValues(keys, res.stdout);
 }
 async function paramSet(config, key, value, opts = {}) {
   const res = await shell({
@@ -1924,29 +2051,66 @@ async function paramSet(config, key, value, opts = {}) {
 }
 
 // src/hdc/files.ts
+import * as path17 from "path";
+function normaliseLocalPath(local) {
+  const abs = path17.resolve(local);
+  const long = toLongPath(abs);
+  return long !== abs ? long : path17.join(toLongPath(path17.dirname(abs)), path17.basename(abs));
+}
+function assertDevicePath(remote) {
+  if (/^[A-Za-z]:[\\/]/.test(remote)) {
+    throw new OniroError(
+      `The device path ${remote} is a Windows path. Git Bash rewrites arguments that start with /: run the command with MSYS_NO_PATHCONV=1, or from PowerShell or cmd.`
+    );
+  }
+}
+function appSandboxDir(bundle) {
+  return `/data/app/el2/100/base/${bundle}`;
+}
+function shQuote(s) {
+  return `'${s.replace(/'/g, `'\\''`)}'`;
+}
 async function sendFile(opts) {
+  assertDevicePath(opts.remote);
+  const local = normaliseLocalPath(opts.local);
+  const sandbox = opts.bundle ? appSandboxDir(opts.bundle) : void 0;
+  const remote = sandbox && !opts.remote.startsWith("/") ? path17.posix.join(sandbox, opts.remote) : opts.remote;
+  if (sandbox && !remote.startsWith(`${sandbox}/`)) {
+    throw new OniroError(`${remote} is outside the sandbox of ${opts.bundle} (${sandbox}).`);
+  }
+  const device = { config: opts.config, deviceSerial: opts.deviceSerial, logger: opts.logger };
+  if (sandbox) {
+    const mkdir = `mkdir -p ${shQuote(path17.posix.dirname(remote))}`;
+    ensureRemoteOk(await shellChecked({ ...device, command: mkdir }), `hdc shell ${mkdir}`);
+  }
   const res = await hdcExec({
-    config: opts.config,
-    args: ["file", "send", opts.local, opts.remote],
-    deviceSerial: opts.deviceSerial,
+    ...device,
+    args: ["file", "send", local, remote],
     timeoutMs: opts.timeoutMs ?? 6e5,
     abortSignal: opts.abortSignal,
-    onOutput: opts.onOutput,
-    logger: opts.logger
+    onOutput: opts.onOutput
   });
-  ensureOk(res, `hdc file send ${opts.local} ${opts.remote}`);
+  ensureOk(res, `hdc file send ${local} ${remote}`);
+  if (sandbox) {
+    const top = path17.posix.join(sandbox, path17.posix.relative(sandbox, remote).split("/")[0]);
+    const chown = `chown -R "$(stat -c %u:%g ${shQuote(sandbox)})" ${shQuote(top)}`;
+    ensureRemoteOk(await shellChecked({ ...device, command: chown }), `hdc shell ${chown}`);
+  }
+  return remote;
 }
 async function recvFile(opts) {
+  assertDevicePath(opts.remote);
+  const local = normaliseLocalPath(opts.local);
   const res = await hdcExec({
     config: opts.config,
-    args: ["file", "recv", opts.remote, opts.local],
+    args: ["file", "recv", opts.remote, local],
     deviceSerial: opts.deviceSerial,
     timeoutMs: opts.timeoutMs ?? 6e5,
     abortSignal: opts.abortSignal,
     onOutput: opts.onOutput,
     logger: opts.logger
   });
-  ensureOk(res, `hdc file recv ${opts.remote} ${opts.local}`);
+  ensureOk(res, `hdc file recv ${opts.remote} ${local}`);
 }
 
 // src/hdc/display.ts
@@ -1966,7 +2130,7 @@ async function getDisplaySize(config, opts = {}) {
 
 // src/hdc/wait.ts
 function delay(ms, signal) {
-  return new Promise((resolve6, reject) => {
+  return new Promise((resolve7, reject) => {
     if (signal?.aborted) {
       reject(new CancelledError("Wait cancelled."));
       return;
@@ -1981,7 +2145,7 @@ function delay(ms, signal) {
     };
     const timer = setTimeout(() => {
       cleanup();
-      resolve6();
+      resolve7();
     }, ms);
     signal?.addEventListener("abort", onAbort, { once: true });
   });
@@ -2010,20 +2174,73 @@ async function waitForCondition(opts) {
 }
 
 // src/hdc/app.ts
-import * as fs18 from "fs";
+import * as fs19 from "fs";
+import * as path20 from "path";
+
+// src/build/discoverHaps.ts
+import * as fs17 from "fs";
 import * as path18 from "path";
+function moduleOfHap(hapFileName) {
+  const dash = hapFileName.indexOf("-");
+  return dash > 0 ? hapFileName.slice(0, dash) : hapFileName.replace(/\.hap$/i, "");
+}
+async function discoverHaps(opts) {
+  const { projectDir } = opts;
+  const maxDepth = opts.maxDepth ?? 8;
+  const result = {};
+  const walk = async (dir, depth) => {
+    if (depth > maxDepth) return;
+    const entries = await fs17.promises.readdir(dir, { withFileTypes: true }).catch(() => []);
+    for (const e of entries) {
+      const full = path18.join(dir, e.name);
+      if (e.isDirectory()) {
+        if (e.name === "node_modules" || e.name === "oh_modules" || e.name === ".git") continue;
+        await walk(full, depth + 1);
+      } else if (e.isFile() && e.name.endsWith(".hap")) {
+        const moduleName = moduleOfHap(e.name);
+        const bucket = result[moduleName] ??= { signed: [], unsigned: [] };
+        if (e.name.includes("unsigned")) bucket.unsigned.push(full);
+        else if (e.name.includes("signed")) bucket.signed.push(full);
+      }
+    }
+  };
+  await walk(projectDir, 0);
+  const mtime = (p) => fs17.statSync(p).mtimeMs;
+  for (const bucket of Object.values(result)) {
+    bucket.signed.sort((a, b) => mtime(b) - mtime(a));
+    bucket.unsigned.sort((a, b) => mtime(b) - mtime(a));
+  }
+  return result;
+}
+function pickHap(haps, module) {
+  const pick = (name) => {
+    const signed = haps[name]?.signed[0];
+    if (signed) return { module: name, path: signed, signed: true };
+    const unsigned = haps[name]?.unsigned[0];
+    return unsigned ? { module: name, path: unsigned, signed: false } : null;
+  };
+  if (module) return pick(module);
+  const names = Object.keys(haps);
+  const withSigned = names.filter((n) => haps[n].signed.length > 0);
+  const candidates = withSigned.length > 0 ? withSigned : names.filter((n) => haps[n].unsigned.length > 0);
+  if (candidates.length === 0) return null;
+  if (candidates.length > 1) {
+    throw new OniroError(`Multiple modules have built HAPs (${candidates.join(", ")}). Pass a module to choose.`);
+  }
+  return pick(candidates[0]);
+}
 
 // src/hdc/project.ts
-import * as fs17 from "fs";
-import * as path17 from "path";
+import * as fs18 from "fs";
+import * as path19 from "path";
 import JSON53 from "json5";
 function readJson5(filePath) {
-  const content = fs17.readFileSync(filePath, "utf-8");
+  const content = fs18.readFileSync(filePath, "utf-8");
   return JSON53.parse(content);
 }
 function getBundleName(projectDir) {
-  const appJsonPath = path17.join(projectDir, "AppScope", "app.json5");
-  if (!fs17.existsSync(appJsonPath)) {
+  const appJsonPath = path19.join(projectDir, "AppScope", "app.json5");
+  if (!fs18.existsSync(appJsonPath)) {
     throw new OniroError(`Could not find app.json5 at ${appJsonPath}`);
   }
   const appJson = readJson5(appJsonPath);
@@ -2033,8 +2250,8 @@ function getBundleName(projectDir) {
   return appJson.app.bundleName;
 }
 function getMainAbility(projectDir, moduleName = "entry", abilityName) {
-  const moduleJsonPath = path17.join(projectDir, moduleName, "src", "main", "module.json5");
-  if (!fs17.existsSync(moduleJsonPath)) {
+  const moduleJsonPath = path19.join(projectDir, moduleName, "src", "main", "module.json5");
+  if (!fs18.existsSync(moduleJsonPath)) {
     throw new OniroError(`Could not find module.json5 at ${moduleJsonPath}`);
   }
   const moduleJson = readJson5(moduleJsonPath);
@@ -2054,13 +2271,67 @@ function getMainAbility(projectDir, moduleName = "entry", abilityName) {
 }
 
 // src/hdc/app.ts
+function detectInstallFailure(output) {
+  return /\[Fail\]|msg:\s*error|error:\s*failed to install|code:\s*95\d{5}/i.test(output) ? output.trim() : null;
+}
+function isUnsignedHap(hapPath) {
+  return path20.basename(hapPath).includes("unsigned");
+}
+function installFailureReason(output) {
+  const code = /code:\s*(\d+)/i.exec(output);
+  if (!code) return output.trim().split(/\r?\n/)[0] ?? "";
+  const message = /error:\s*([^\r\n]+)/i.exec(output.slice(code.index + code[0].length))?.[1]?.trim().replace(/\.$/, "");
+  return message ? `code ${code[1]}: ${message}` : `code ${code[1]}`;
+}
+function unsignedHapRejection(output, hap) {
+  const name = path20.basename(hap.path);
+  const reason = installFailureReason(output);
+  const what = hap.fallback ? `No signed HAP was found, so the unsigned ${name} was tried, and the target rejected it (${reason}).` : `The target rejected the unsigned ${name} (${reason}).`;
+  if (!/9568320|signature|pkcs7/i.test(reason)) return what;
+  return `${what} This target installs only signed HAPs. Sign the project for it, build again, and install the signed HAP: \`oniro-app sign\` for an OpenHarmony device or the Oniro emulator, \`oniro-app sign --harmonyos\` for a HarmonyOS device.`;
+}
+function ensureInstallOk(result, command, hap) {
+  const output = `${result.stdout}
+${result.stderr}`;
+  if (hap && isUnsignedHap(hap.path) && /code:\s*95\d{5}/i.test(output)) {
+    throw new OniroError(unsignedHapRejection(output, hap), new CommandFailedError(command, result.code || 1, output.trim()));
+  }
+  ensureOk(result, command);
+  const failure = detectInstallFailure(output);
+  if (failure) throw new CommandFailedError(command, 1, failure);
+  return result;
+}
+function existingHapOrUnsigned(hapPath) {
+  if (fs19.existsSync(hapPath)) return { path: hapPath };
+  const sibling = hapPath.replace(/-signed\.hap$/i, "-unsigned.hap");
+  return sibling !== hapPath && fs19.existsSync(sibling) ? { path: sibling, fallback: true } : void 0;
+}
+async function resolveInstallHap(opts, logger) {
+  const warnIfFallback = (hap) => {
+    if (hap.fallback) logger.warn(`No signed HAP found; installing the unsigned ${path20.basename(hap.path)}.`);
+    return hap;
+  };
+  const configured = opts.hapPath ?? opts.config.get("hapPath", "");
+  const relative3 = configured || defaultPaths.hapPath;
+  const hapPath = path20.isAbsolute(relative3) ? relative3 : path20.join(opts.projectDir, relative3);
+  if (configured) {
+    const hap = existingHapOrUnsigned(hapPath);
+    if (!hap) throw new OniroError(`HAP file not found at: ${hapPath}. Build the app first.`);
+    return warnIfFallback(hap);
+  }
+  if (fs19.existsSync(hapPath)) return { path: hapPath };
+  const haps = await discoverHaps({ projectDir: opts.projectDir });
+  const anySigned = Object.values(haps).some((m) => m.signed.length > 0);
+  const entryUnsigned = anySigned ? void 0 : existingHapOrUnsigned(hapPath);
+  if (entryUnsigned) return warnIfFallback(entryUnsigned);
+  const picked = pickHap(haps);
+  if (!picked) throw new OniroError(`No HAP found under ${opts.projectDir}. Build the app first (\`oniro-app build\`).`);
+  return warnIfFallback({ path: picked.path, fallback: !picked.signed });
+}
 async function installApp(opts) {
   const logger = scopedLogger(opts.logger ?? noopLogger, "hdc");
-  const relativeHapPath = opts.hapPath ?? opts.config.get("hapPath", defaultPaths.hapPath);
-  const hapPath = path18.isAbsolute(relativeHapPath) ? relativeHapPath : path18.join(opts.projectDir, relativeHapPath);
-  if (!fs18.existsSync(hapPath)) {
-    throw new OniroError(`HAP file not found at: ${hapPath}. Build and sign the app first.`);
-  }
+  const hap = await resolveInstallHap(opts, logger);
+  const hapPath = hap.path;
   const result = await hdcExec({
     config: opts.config,
     args: ["install", hapPath],
@@ -2069,7 +2340,7 @@ async function installApp(opts) {
   });
   if (result.stdout.trim()) logger.info(result.stdout.trim());
   if (result.stderr.trim()) logger.warn(result.stderr.trim());
-  ensureOk(result, `hdc install ${hapPath}`);
+  ensureInstallOk(result, `hdc install ${hapPath}`, hap);
   let bundleName = "";
   try {
     bundleName = getBundleName(opts.projectDir);
@@ -2077,6 +2348,18 @@ async function installApp(opts) {
   }
   return { installed: true, bundleName, hapPath, output: `${result.stdout}${result.stderr}`.trim() };
 }
+async function isBundleInstalled(opts) {
+  const safe = opts.bundle.replace(/'/g, `'\\''`);
+  const res = await shell({
+    config: opts.config,
+    command: `bm dump -n '${safe}'`,
+    deviceSerial: opts.deviceSerial,
+    timeoutMs: opts.timeoutMs ?? 15e3,
+    logger: opts.logger
+  });
+  ensureOk(res, `hdc shell bm dump -n ${opts.bundle}`);
+  return res.stdout.includes("{") && !/failed to get information/i.test(res.stdout);
+}
 function detectAaStartFailure(output) {
   return /failed to start ability|Error Code:\s*\d|Error Message:/i.test(output) ? output.trim() : null;
 }
@@ -2147,10 +2430,10 @@ function listRunningProcesses(config, options = {}) {
   const logger = options.logger ?? noopLogger;
   const timeoutMs = options.timeoutMs ?? 1e3;
   const hdc = getHdcPath(config);
-  return new Promise((resolve6, reject) => {
+  return new Promise((resolve7, reject) => {
     let proc;
     try {
-      proc = spawnCompat(hdc, ["track-jpid"]);
+      proc = spawnCompat(hdc, [...hdcTargetArgs(options.deviceSerial), "track-jpid"]);
     } catch (err) {
       reject(new OniroError(`Failed to spawn ${hdc}: ${err instanceof Error ? err.message : String(err)}`, err));
       return;
@@ -2167,7 +2450,7 @@ function listRunningProcesses(config, options = {}) {
         if (options.targetProcessName && name === options.targetProcessName && !resolved) {
           resolved = true;
           killProcessTree(proc);
-          resolve6(pid);
+          resolve7(pid);
           return;
         }
       }
@@ -2188,7 +2471,7 @@ function listRunningProcesses(config, options = {}) {
       if (options.targetProcessName) {
         reject(new OniroError(`Could not find process for bundle: ${options.targetProcessName}`));
       } else {
-        resolve6(processes);
+        resolve7(processes);
       }
     }, timeoutMs);
     proc.on("close", () => {
@@ -2198,7 +2481,7 @@ function listRunningProcesses(config, options = {}) {
       if (options.targetProcessName) {
         reject(new OniroError(`Could not find process for bundle: ${options.targetProcessName}`));
       } else {
-        resolve6(processes);
+        resolve7(processes);
       }
     });
   });
@@ -2220,7 +2503,11 @@ async function findRunningProcess(opts) {
   const pid = res.stdout.trim().split(/\s+/).filter(Boolean)[0];
   if (res.code === 0 && pid && /^\d+$/.test(pid)) return { pid, name: opts.bundle };
   try {
-    const list = await listRunningProcesses(opts.config, { timeoutMs: 1200, logger: opts.logger });
+    const list = await listRunningProcesses(opts.config, {
+      timeoutMs: 1200,
+      deviceSerial: opts.deviceSerial,
+      logger: opts.logger
+    });
     if (Array.isArray(list)) {
       const mine = (name) => name === opts.bundle || name.startsWith(`${opts.bundle}/`) || name.startsWith(`${opts.bundle}:`);
       const match = list.find((p) => p.name === opts.bundle) ?? list.find((p) => mine(p.name));
@@ -2363,12 +2650,12 @@ async function reboot(opts) {
 }
 
 // src/hdc/screen.ts
-import * as fs19 from "fs";
+import * as fs20 from "fs";
 import * as os9 from "os";
-import * as path19 from "path";
+import * as path21 from "path";
 import { randomBytes as randomBytes2 } from "crypto";
 function tmpName(ext) {
-  return path19.join(os9.tmpdir(), `oniro_screen_${randomBytes2(6).toString("hex")}.${ext}`);
+  return path21.join(os9.tmpdir(), `oniro_screen_${randomBytes2(6).toString("hex")}.${ext}`);
 }
 async function takeScreenshot(opts) {
   const remote = "/data/local/tmp/oniro_screenshot.jpeg";
@@ -2378,11 +2665,11 @@ async function takeScreenshot(opts) {
   const local = tmpName("jpeg");
   try {
     await recvFile({ config: opts.config, remote, local, deviceSerial: opts.deviceSerial, timeoutMs });
-    const pixels = await fs19.promises.readFile(local);
+    const pixels = await fs20.promises.readFile(local);
     const size = await getDisplaySize(opts.config, { deviceSerial: opts.deviceSerial }) ?? { width: 0, height: 0 };
     return { pixels, width: size.width, height: size.height };
   } finally {
-    fs19.promises.unlink(local).catch(() => {
+    fs20.promises.unlink(local).catch(() => {
     });
     void shell({ config: opts.config, command: `rm -f ${remote}`, deviceSerial: opts.deviceSerial }).catch(() => {
     });
@@ -2401,9 +2688,9 @@ async function captureBurst(opts) {
       const local = tmpName(`burst_${i}.jpeg`);
       try {
         await recvFile({ config: opts.config, remote: `${remoteDir}/f${i}.jpeg`, local, deviceSerial: opts.deviceSerial });
-        frames.push(await fs19.promises.readFile(local));
+        frames.push(await fs20.promises.readFile(local));
       } finally {
-        fs19.promises.unlink(local).catch(() => {
+        fs20.promises.unlink(local).catch(() => {
         });
       }
     }
@@ -2415,6 +2702,55 @@ async function captureBurst(opts) {
 }
 
 // src/hdc/input.ts
+var UITEST_KEY_NAMES = ["Back", "Home", "Power"];
+var KEY_IDS = {
+  back: 2,
+  home: 1,
+  power: 18,
+  volumeup: 16,
+  volumedown: 17,
+  up: 2012,
+  down: 2013,
+  left: 2014,
+  right: 2015,
+  alt: 2045,
+  shift: 2047,
+  tab: 2049,
+  space: 2050,
+  enter: 2054,
+  delete: 2055,
+  backspace: 2055,
+  pageup: 2068,
+  pagedown: 2069,
+  escape: 2070,
+  esc: 2070,
+  forwarddelete: 2071,
+  ctrl: 2072,
+  meta: 2076,
+  movehome: 2081,
+  moveend: 2082
+};
+function keyId(name) {
+  const k = name.trim().toLowerCase();
+  if (/^\d+$/.test(k)) return Number(k);
+  if (/^[a-z]$/.test(k)) return 2017 + (k.charCodeAt(0) - 97);
+  const id = KEY_IDS[k];
+  if (id === void 0) {
+    throw new OniroError(
+      `Unknown key "${name}". Use a numeric KeyCode id, a letter, or one of: ${Object.keys(KEY_IDS).join(", ")}. Combine up to three with "+", e.g. Ctrl+A.`
+    );
+  }
+  return id;
+}
+function resolveKeyEvent(key) {
+  const spec = String(key).trim();
+  if (spec === "") throw new OniroError('send input "keyEvent" requires a key.');
+  const native = UITEST_KEY_NAMES.find((n) => n.toLowerCase() === spec.toLowerCase());
+  if (native) return native;
+  const parts = spec.includes("+") ? spec.split("+") : spec.split(/\s+/);
+  if (parts.length > 3) throw new OniroError(`uitest injects at most three keys at once; got "${spec}".`);
+  return parts.map(keyId).join(" ");
+}
 function reqNum(value, name, type) {
   if (value === void 0 || Number.isNaN(value)) {
     throw new OniroError(`send input "${type}" requires a numeric ${name}.`);
@@ -2435,7 +2771,7 @@ function buildInputCommand(opts) {
     }
     case "keyEvent":
       if (opts.key === void 0 || opts.key === "") throw new OniroError('send input "keyEvent" requires a key.');
-      return `uitest uiInput keyEvent ${opts.key}`;
+      return `uitest uiInput keyEvent ${resolveKeyEvent(opts.key)}`;
     case "inputText": {
       const t = String(opts.text ?? "").replace(/'/g, `'\\''`);
       if (opts.pxX !== void 0 && opts.pxY !== void 0) {
@@ -2529,10 +2865,52 @@ async function sendRawTouch(opts) {
 }
 
 // src/hdc/dump.ts
-import * as fs20 from "fs";
+import * as fs21 from "fs";
 import * as os10 from "os";
-import * as path20 from "path";
+import * as path22 from "path";
 import { randomBytes as randomBytes3 } from "crypto";
+
+// src/hdc/ime.ts
+var INPUT_METHOD_SA_ID = 3703;
+var IME_BUNDLE_FALLBACK = /inputmethod|keyboard|(^|\.)ime(\.|$)/i;
+function parseImeBundles(output) {
+  const current = [];
+  const others = [];
+  const entry = /\{[^{}]*"ime"\s*:\s*"([^"/]+)\/[^"]*"[^{}]*\}/g;
+  for (const m of output.matchAll(entry)) {
+    const bundle = m[1];
+    const list = /"isCurrentIme"\s*:\s*"true"/.test(m[0]) ? current : others;
+    if (!current.includes(bundle) && !others.includes(bundle)) list.push(bundle);
+  }
+  return [...current, ...others];
+}
+async function getImeBundles(config, opts = {}) {
+  try {
+    const res = await shell({
+      config,
+      command: `hidumper -s ${INPUT_METHOD_SA_ID} -a '-a'`,
+      deviceSerial: opts.deviceSerial,
+      timeoutMs: 1e4,
+      logger: opts.logger
+    });
+    if (res.code === 0) return parseImeBundles(res.stdout);
+  } catch (err) {
+    opts.logger?.debug(`could not list input methods: ${err instanceof Error ? err.message : String(err)}`);
+  }
+  return [];
+}
+function findKeyboardWindow(tree, imeBundles) {
+  const isIme = (bundle) => imeBundles.length > 0 ? imeBundles.includes(bundle) : IME_BUNDLE_FALLBACK.test(bundle);
+  const stack = [tree];
+  while (stack.length > 0) {
+    const n = stack.shift();
+    if (n.bundle && isIme(n.bundle)) return n;
+    stack.push(...n.children ?? []);
+  }
+  return null;
+}
+
+// src/hdc/dump.ts
 function parseBounds(s) {
   const m = /^\[(-?\d+),(-?\d+)\]\[(-?\d+),(-?\d+)\]$/.exec(s ?? "");
   if (!m) return null;
@@ -2567,7 +2945,46 @@ var FLAG_MAP = [
   ["scrollable", "scroll"],
   ["longClickable", "longClick"]
 ];
-function pruneLayout(node, display) {
+function colorAlpha(color) {
+  const m = /^#([0-9a-f]{2})?[0-9a-f]{6}$/i.exec(color ?? "");
+  if (!m) return 0;
+  return m[1] === void 0 ? 255 : parseInt(m[1], 16);
+}
+function paintsFill(a) {
+  if (a.visible === "false") return false;
+  if (a.opacity !== void 0 && a.opacity !== "" && !(Number(a.opacity) > 0)) return false;
+  return colorAlpha(a.backgroundColor) > 0;
+}
+function findCoveredNodes(root) {
+  const order = [];
+  const fills = [];
+  const visit = (n) => {
+    const a = n.attributes ?? {};
+    const entry = { node: n, bounds: parseBounds(a.bounds), end: 0 };
+    if (entry.bounds && paintsFill(a)) fills.push(order.length);
+    order.push(entry);
+    const kids = (n.children ?? []).map((c, i) => ({ c, i, z: Number(c.attributes?.zIndex) || 0 })).sort((p, q) => p.z - q.z || p.i - q.i);
+    for (const k of kids) visit(k.c);
+    entry.end = order.length;
+  };
+  visit(root);
+  const covered = /* @__PURE__ */ new Set();
+  for (const p of order) {
+    if (!p.bounds) continue;
+    const cx = (p.bounds[0] + p.bounds[2]) / 2;
+    const cy = (p.bounds[1] + p.bounds[3]) / 2;
+    for (const j of fills) {
+      if (j < p.end) continue;
+      const q = order[j].bounds;
+      if (cx >= q[0] && cx < q[2] && cy >= q[1] && cy < q[3]) {
+        covered.add(p.node);
+        break;
+      }
+    }
+  }
+  return covered;
+}
+function pruneLayout(node, display, covered) {
   const a = node.attributes ?? {};
   const px = parseBounds(a.bounds);
   const out = {};
@@ -2585,28 +3002,125 @@ function pruneLayout(node, display) {
   if (a.type && !STRUCTURAL_TYPES.has(a.type)) out.type = a.type;
   if (a.text) out.text = a.text;
   if (a.description) out.desc = a.description;
+  if (a.hint) out.hint = a.hint;
   if (a.id) out.id = a.id;
   if (a.key && a.key !== a.id) out.key = a.key;
   if (a.bundleName) out.bundle = a.bundleName;
   for (const [attr, short] of FLAG_MAP) {
     if (a[attr] === "true") out[short] = true;
   }
+  if (a.enabled === "false") out.disabled = true;
+  if (covered?.has(node)) out.covered = true;
   const children = [];
   for (const c of node.children ?? []) {
-    const pc = pruneLayout(c, display);
+    const pc = pruneLayout(c, display, covered);
     if (pc) {
       if (Array.isArray(pc)) children.push(...pc);
       else children.push(pc);
     }
   }
   const hasSignal = Boolean(
-    out.text || out.desc || out.id || out.key || out.click || out.scroll || out.check || out.longClick || out.bundle || out.type && out.type !== "root"
+    out.text || out.desc || out.hint || out.id || out.key || out.click || out.scroll || out.check || out.longClick || out.bundle || out.type && out.type !== "root"
   );
   if (!hasSignal && children.length === 0) return null;
   if (!hasSignal) return children.length === 1 ? children[0] : children;
   if (children.length) out.children = children;
   return out;
 }
+function flattenLayout(tree) {
+  const out = [];
+  const visit = (n, window) => {
+    const { children, ...rest } = n;
+    const win = n.bundle ?? window;
+    if (Object.keys(rest).length > 0) out.push({ ...rest, ...win ? { window: win } : {} });
+    for (const c of children ?? []) visit(c, win);
+  };
+  visit(tree, void 0);
+  return out;
+}
+function assertLayoutSelector(selector) {
+  if (selector.text === void 0 && selector.id === void 0 && selector.type === void 0) {
+    throw new OniroError("A layout selector needs a text, id, or type.");
+  }
+  if (selector.text !== void 0 && selector.text.trim() === "") {
+    throw new OniroError("A layout selector text must not be blank.");
+  }
+}
+function withoutWindow(tree, bundle) {
+  const children = (tree.children ?? []).filter((c) => c.bundle !== bundle).map((c) => withoutWindow(c, bundle));
+  return tree.children ? { ...tree, children } : tree;
+}
+function findLayoutNodes(tree, selector) {
+  assertLayoutSelector(selector);
+  const type = selector.type?.toLowerCase();
+  const nodes = flattenLayout(tree).filter(
+    (n) => (type === void 0 || n.type?.toLowerCase() === type) && (selector.id === void 0 || n.id === selector.id || n.key === selector.id)
+  );
+  if (selector.text === void 0) return nodes;
+  const want = selector.text.trim().toLowerCase();
+  const labels = (n) => [n.text, n.desc, n.hint].filter((s) => !!s).map((s) => s.trim().toLowerCase());
+  const exact = nodes.filter((n) => labels(n).some((l) => l === want));
+  if (exact.length > 0) return exact;
+  return nodes.filter((n) => labels(n).some((l) => l.includes(want)));
+}
+function describeSelector(s) {
+  const parts = [];
+  if (s.text !== void 0) parts.push(`text "${s.text}"`);
+  if (s.id !== void 0) parts.push(`id "${s.id}"`);
+  if (s.type !== void 0) parts.push(`type ${s.type}`);
+  return parts.join(", ");
+}
+function describeLayoutNode(n) {
+  const label = n.text ?? n.desc ?? (n.hint !== void 0 ? `hint: ${n.hint}` : void 0);
+  const at = n.c ? ` at ${n.c[0].toFixed(3)},${n.c[1].toFixed(3)}` : "";
+  return `${n.type ?? "node"}${label !== void 0 ? ` "${label}"` : ""}${n.id ? ` #${n.id}` : ""}${at}`;
+}
+var area = (b) => b ? (b[2] - b[0]) * (b[3] - b[1]) : 0;
+function enclosesTarget(outer, inner) {
+  const b = outer.b;
+  const c = inner.c;
+  if (!b || !c) return false;
+  return c[0] >= b[0] && c[0] <= b[2] && c[1] >= b[1] && c[1] <= b[3] && area(b) > area(inner.b);
+}
+var TargetNotFoundError = class extends OniroError {
+  constructor(message, reason) {
+    super(message);
+    this.reason = reason;
+    this.name = "TargetNotFoundError";
+  }
+  reason;
+};
+function pickTarget(tree, selector, index) {
+  const matches = findLayoutNodes(tree, selector).filter((n) => n.c !== void 0);
+  const what = describeSelector(selector);
+  if (matches.length === 0) {
+    throw new TargetNotFoundError(`No on-screen element matches ${what}. Run \`oniro-app dump layout --flat\` to see what is there.`, "none");
+  }
+  const visible = matches.filter((n) => !n.covered);
+  if (visible.length === 0) {
+    throw new TargetNotFoundError(
+      `Found ${matches.length} element(s) matching ${what}, but each is covered by an overlay (dialog, keyboard, or another layer): ${matches.map(describeLayoutNode).join("; ")}.`,
+      "covered"
+    );
+  }
+  const clickable = visible.filter((n) => n.click);
+  const preferred = clickable.length > 0 ? clickable : visible;
+  const candidates = preferred.filter((n) => !preferred.some((o) => o !== n && o.click && enclosesTarget(o, n)));
+  if (index !== void 0) {
+    const picked = candidates[index];
+    if (!picked) {
+      throw new TargetNotFoundError(`Index ${index} is out of range: ${candidates.length} element(s) match ${what}.`, "ambiguous");
+    }
+    return picked;
+  }
+  if (candidates.length > 1) {
+    throw new TargetNotFoundError(
+      `${candidates.length} elements match ${what}; pass an index to choose: ` + candidates.map((n, i) => `[${i}] ${describeLayoutNode(n)}`).join("; "),
+      "ambiguous"
+    );
+  }
+  return candidates[0];
+}
 async function dumpLayout(opts) {
   const timeoutMs = opts.timeoutMs ?? 3e4;
   const bundleArg = opts.bundleName ? ` -b '${opts.bundleName.replace(/'/g, `'\\''`)}'` : "";
@@ -2616,33 +3130,193 @@ async function dumpLayout(opts) {
   if (!m) throw new OniroError(`Could not parse dumpLayout output:
 ${dump.stdout}`);
   const remote = m[1];
-  const local = path20.join(os10.tmpdir(), `oniro_layout_${randomBytes3(6).toString("hex")}.json`);
+  const local = path22.join(os10.tmpdir(), `oniro_layout_${randomBytes3(6).toString("hex")}.json`);
   try {
     await recvFile({ config: opts.config, remote, local, deviceSerial: opts.deviceSerial, timeoutMs });
-    const parsed = JSON.parse(await fs20.promises.readFile(local, "utf8"));
+    const parsed = JSON.parse(await fs21.promises.readFile(local, "utf8"));
     const display = await getDisplaySize(opts.config, { deviceSerial: opts.deviceSerial });
     if (opts.prune === false) {
       return { display, tree: parsed };
     }
-    const prunedRaw = pruneLayout(parsed, display);
+    const prunedRaw = pruneLayout(parsed, display, findCoveredNodes(parsed));
     const tree = Array.isArray(prunedRaw) ? { children: prunedRaw } : prunedRaw ?? { children: [] };
-    return { display, tree };
+    if (!opts.detectKeyboard || opts.bundleName) return { display, tree };
+    const imeBundles = await getImeBundles(opts.config, { deviceSerial: opts.deviceSerial, logger: opts.logger });
+    const kb = findKeyboardWindow(tree, imeBundles);
+    const keyboard = kb ? { shown: true, bundle: kb.bundle, ...kb.b ? { b: kb.b } : {} } : { shown: false };
+    return { display, tree, keyboard };
   } finally {
-    fs20.promises.unlink(local).catch(() => {
+    fs21.promises.unlink(local).catch(() => {
     });
     void shell({ config: opts.config, command: `rm -f ${remote}`, deviceSerial: opts.deviceSerial }).catch(() => {
     });
   }
 }
 
+// src/hdc/uiActions.ts
+var FOCUS_SETTLE_MS = 400;
+var KEYBOARD_SETTLE_MS = 400;
+var sleep = (ms) => new Promise((resolve7) => setTimeout(resolve7, ms));
+function targetTree(layout) {
+  const kb = layout.keyboard;
+  return kb?.shown && kb.bundle ? withoutWindow(layout.tree, kb.bundle) : layout.tree;
+}
+function fractionToPixel(f, size) {
+  return Math.min(size - 1, Math.round(f * size));
+}
+function pressBack(opts) {
+  return sendInput({ config: opts.config, type: "keyEvent", key: "Back", deviceSerial: opts.deviceSerial, logger: opts.logger });
+}
+async function hideKeyboard(opts) {
+  const { keyboard } = await dumpLayout({ ...opts, detectKeyboard: true });
+  if (!keyboard?.shown) return false;
+  await pressBack(opts);
+  await sleep(KEYBOARD_SETTLE_MS);
+  return true;
+}
+async function locateTarget(opts) {
+  assertLayoutSelector(opts.selector);
+  const dumpOpts = { config: opts.config, detectKeyboard: true, deviceSerial: opts.deviceSerial, logger: opts.logger };
+  let layout = await dumpLayout(dumpOpts);
+  if (!layout.display) throw new OniroError("Could not read the display size to locate the element.");
+  let keyboardHidden = false;
+  let node;
+  let failure;
+  try {
+    node = pickTarget(targetTree(layout), opts.selector, opts.index);
+  } catch (err) {
+    if (!(err instanceof TargetNotFoundError) || err.reason === "ambiguous") throw err;
+    failure = err;
+  }
+  if ((!node || !node.click) && layout.keyboard?.shown && opts.hideKeyboard !== false) {
+    opts.logger?.debug("target not reachable while the keyboard is up; dismissing it and looking again");
+    await pressBack(opts);
+    await sleep(KEYBOARD_SETTLE_MS);
+    keyboardHidden = true;
+    layout = await dumpLayout(dumpOpts);
+    if (!layout.display) throw new OniroError("Could not read the display size to locate the element.");
+    node = pickTarget(targetTree(layout), opts.selector, opts.index);
+  }
+  if (!node) throw failure;
+  if (!node.c) throw new OniroError("The element has no on-screen position.");
+  const x2 = fractionToPixel(node.c[0], layout.display.width);
+  const y = fractionToPixel(node.c[1], layout.display.height);
+  return { node, x: x2, y, display: layout.display, keyboardHidden };
+}
+function fraction(value, name) {
+  if (value === void 0) return void 0;
+  if (!(value >= 0 && value <= 1)) throw new OniroError(`${name} must be a fraction between 0 and 1; got ${value}.`);
+  return value;
+}
+function pair(a, b, names) {
+  if (a === void 0 && b === void 0) return void 0;
+  if (a === void 0 || b === void 0) throw new OniroError(`Give both ${names}.`);
+  return [a, b];
+}
+async function performInput(opts) {
+  const device = { config: opts.config, deviceSerial: opts.deviceSerial, logger: opts.logger };
+  const startFx = pair(fraction(opts.fx, "--fx"), fraction(opts.fy, "--fy"), "--fx and --fy");
+  const startPx = pair(opts.pxX, opts.pxY, "--x and --y");
+  const endFx = pair(fraction(opts.fx2, "--fx2"), fraction(opts.fy2, "--fy2"), "--fx2 and --fy2");
+  const endPx = pair(opts.pxX2, opts.pxY2, "--x2 and --y2");
+  if ([opts.target, startFx, startPx].filter((s) => s !== void 0).length > 1) {
+    throw new OniroError("Give the start point one way: a target, fractions (--fx/--fy), or pixels (--x/--y).");
+  }
+  if (endFx && endPx) throw new OniroError("Give the end point one way: fractions (--fx2/--fy2) or pixels (--x2/--y2).");
+  let display;
+  const toPx = async ([fx, fy]) => {
+    display ??= await getDisplaySize(opts.config, { deviceSerial: opts.deviceSerial, logger: opts.logger });
+    if (!display) throw new OniroError("Could not read the display size to convert fractions to pixels.");
+    return [fractionToPixel(fx, display.width), fractionToPixel(fy, display.height)];
+  };
+  const result = { keyboardHidden: false };
+  let start = startPx;
+  if (opts.target) {
+    const located = await locateTarget({ ...device, selector: opts.target, index: opts.targetIndex });
+    display = located.display;
+    start = [located.x, located.y];
+    result.target = located.node;
+    result.keyboardHidden = located.keyboardHidden;
+  } else if (startFx) {
+    start = await toPx(startFx);
+  }
+  const end = endFx ? await toPx(endFx) : endPx;
+  if (start) [result.x, result.y] = start;
+  const tapToFocus = async () => {
+    if (!start) return;
+    await sendInput({ ...device, type: "click", pxX: start[0], pxY: start[1] });
+    await sleep(FOCUS_SETTLE_MS);
+  };
+  const clearFocused = async () => {
+    await sendInput({ ...device, type: "keyEvent", key: "Ctrl+A" });
+    await sendInput({ ...device, type: "keyEvent", key: "Delete" });
+  };
+  switch (opts.type) {
+    case "hideKeyboard":
+      result.keyboardHidden = await hideKeyboard(device) || result.keyboardHidden;
+      return result;
+    case "clearText":
+      await tapToFocus();
+      await clearFocused();
+      break;
+    case "inputText":
+      if (opts.clear) {
+        await tapToFocus();
+        await clearFocused();
+        await sendInput({ ...device, type: "inputText", text: opts.text });
+      } else {
+        await sendInput({ ...device, type: "inputText", pxX: start?.[0], pxY: start?.[1], text: opts.text });
+      }
+      break;
+    default:
+      await sendInput({
+        ...device,
+        type: opts.type,
+        pxX: start?.[0],
+        pxY: start?.[1],
+        pxX2: end?.[0],
+        pxY2: end?.[1],
+        speed: opts.speed,
+        key: opts.key,
+        text: opts.text
+      });
+  }
+  if (opts.hideKeyboard) result.keyboardHidden = await hideKeyboard(device) || result.keyboardHidden;
+  return result;
+}
+async function waitForTarget(opts) {
+  const { selector } = opts;
+  assertLayoutSelector(selector);
+  let found = null;
+  await waitForCondition({
+    probe: async () => {
+      const layout = await dumpLayout({
+        config: opts.config,
+        detectKeyboard: true,
+        deviceSerial: opts.deviceSerial,
+        logger: opts.logger
+      });
+      found = findLayoutNodes(targetTree(layout), selector).find((n) => !n.covered) ?? null;
+      return opts.gone ? found === null : found !== null;
+    },
+    timeoutMs: opts.timeoutMs,
+    pollMs: opts.pollMs ?? 500,
+    abortSignal: opts.abortSignal,
+    logger: opts.logger,
+    timeoutMessage: opts.gone ? `An element matching the selector was still on screen after ${opts.timeoutMs}ms.` : `No element matching the selector appeared within ${opts.timeoutMs}ms.`
+  });
+  return opts.gone ? null : found;
+}
+
 // src/hdc/hilog.ts
+import * as fs22 from "fs";
 function setHilogLevel(opts) {
   const logger = opts.logger ?? noopLogger;
   const hdc = getHdcPath(opts.config);
-  return new Promise((resolve6, reject) => {
+  return new Promise((resolve7, reject) => {
     let child;
     try {
-      child = spawnCompat(hdc, ["shell", "hilog", "-b", opts.level]);
+      child = spawnCompat(hdc, [...hdcTargetArgs(opts.deviceSerial), "shell", "hilog", "-b", opts.level]);
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
       logger.error(`[hilog] failed to spawn hdc: ${msg}`);
@@ -2659,7 +3333,7 @@ function setHilogLevel(opts) {
     });
     child.once("close", (code) => {
       if (code === 0) {
-        resolve6();
+        resolve7();
       } else {
         const msg = stderr.trim() || `hdc shell hilog -b ${opts.level} exited with code ${code}`;
         logger.error(`[hilog] ${msg}`);
@@ -2670,8 +3344,7 @@ function setHilogLevel(opts) {
 }
 function streamHilog(opts) {
   const hdc = getHdcPath(opts.config);
-  const args = [];
-  if (opts.deviceSerial) args.push("-t", opts.deviceSerial);
+  const args = [...hdcTargetArgs(opts.deviceSerial)];
   args.push("shell", "hilog");
   if (opts.processId && opts.processId.trim() !== "") {
     args.push("-P", opts.processId.trim());
@@ -2714,7 +3387,7 @@ async function resolveProcessId(config, bundle, deviceSerial) {
   return proc?.pid;
 }
 function waitForLog(opts) {
-  return new Promise((resolve6, reject) => {
+  return new Promise((resolve7, reject) => {
     const deadline = Date.now() + opts.timeoutMs;
     let settled = false;
     let child = null;
@@ -2733,7 +3406,7 @@ function waitForLog(opts) {
       if (settled) return;
       settled = true;
       cleanup();
-      resolve6(entry);
+      resolve7(entry);
     };
     const fail = (err) => {
       if (settled) return;
@@ -2780,7 +3453,7 @@ function waitForLog(opts) {
   });
 }
 function watchLog(opts) {
-  return new Promise((resolve6, reject) => {
+  return new Promise((resolve7, reject) => {
     const matches = [];
     let settled = false;
     let child = null;
@@ -2797,7 +3470,7 @@ function watchLog(opts) {
       if (settled) return;
       settled = true;
       cleanup();
-      resolve6(opts.dedup === false ? matches : dedupEntries(matches));
+      resolve7(opts.dedup === false ? matches : dedupEntries(matches));
     };
     const onAbort = () => {
       if (settled) return;
@@ -2829,6 +3502,94 @@ function watchLog(opts) {
     });
   });
 }
+async function captureLog(opts) {
+  const logger = opts.logger ?? noopLogger;
+  if (opts.clear) {
+    const res = await shell({ config: opts.config, command: "hilog -r", deviceSerial: opts.deviceSerial, timeoutMs: 1e4, logger });
+    ensureOk(res, "hdc shell hilog -r");
+  }
+  const fd = fs22.openSync(opts.file, "a");
+  let lines = 0;
+  let reconnects = 0;
+  try {
+    await new Promise((resolve7, reject) => {
+      const deadline = opts.durationMs !== void 0 ? Date.now() + opts.durationMs : Infinity;
+      let settled = false;
+      let child = null;
+      let reconnectTimer;
+      let buf = "";
+      let open = true;
+      const write = (line) => {
+        if (!open || opts.pattern && !opts.pattern.test(line)) return;
+        fs22.writeSync(fd, `${line}
+`);
+        lines++;
+      };
+      const cleanup = () => {
+        if (timer) clearTimeout(timer);
+        if (reconnectTimer) clearTimeout(reconnectTimer);
+        opts.abortSignal?.removeEventListener("abort", finish);
+        if (buf.trim()) write(buf.trimEnd());
+        buf = "";
+        open = false;
+        if (child) {
+          child.stdout.removeAllListeners("data");
+          killProcessTree(child);
+          child = null;
+        }
+      };
+      function finish() {
+        if (settled) return;
+        settled = true;
+        cleanup();
+        resolve7();
+      }
+      const fail = (err) => {
+        if (settled) return;
+        settled = true;
+        cleanup();
+        reject(err instanceof Error ? err : new Error(String(err)));
+      };
+      const timer = opts.durationMs !== void 0 ? setTimeout(finish, opts.durationMs) : void 0;
+      if (opts.abortSignal?.aborted) {
+        finish();
+        return;
+      }
+      opts.abortSignal?.addEventListener("abort", finish, { once: true });
+      const spawnStream = () => {
+        if (settled) return;
+        const stream = streamHilog({ config: opts.config, domain: opts.domain, deviceSerial: opts.deviceSerial });
+        child = stream;
+        stream.stdout.on("data", (d) => {
+          buf += d.toString();
+          const parts = buf.split(/\r?\n/);
+          buf = parts.pop() ?? "";
+          for (const line of parts) write(line);
+        });
+        const onEnd = () => {
+          if (settled || child !== stream) return;
+          child = null;
+          if (Date.now() >= deadline) return;
+          reconnects++;
+          logger.warn(`[hilog] stream ended; reconnecting (${reconnects}).`);
+          reconnectTimer = setTimeout(() => {
+            try {
+              spawnStream();
+            } catch (err) {
+              fail(err);
+            }
+          }, 2e3);
+        };
+        stream.once("close", onEnd);
+        stream.once("error", onEnd);
+      };
+      spawnStream();
+    });
+  } finally {
+    fs22.closeSync(fd);
+  }
+  return { file: opts.file, lines, reconnects };
+}
 async function dumpLog(opts) {
   let pipe = "hilog -x";
   if (opts.domain !== void 0 && `${opts.domain}` !== "") pipe += ` -D ${opts.domain}`;
@@ -2853,17 +3614,17 @@ async function dumpLog(opts) {
 }
 
 // src/build/runHvigorw.ts
-import * as fs22 from "fs";
-import * as path22 from "path";
+import * as fs24 from "fs";
+import * as path24 from "path";
 
 // src/harmonyos/target.ts
-import * as fs21 from "fs";
-import * as path21 from "path";
+import * as fs23 from "fs";
+import * as path23 from "path";
 import JSON54 from "json5";
 function detectRuntimeOs(projectDir, productName) {
   let products = [];
   try {
-    const parsed = JSON54.parse(fs21.readFileSync(path21.join(projectDir, "build-profile.json5"), "utf-8"));
+    const parsed = JSON54.parse(fs23.readFileSync(path23.join(projectDir, "build-profile.json5"), "utf-8"));
     if (Array.isArray(parsed.app?.products)) products = parsed.app.products;
   } catch {
     return "OpenHarmony";
@@ -2904,7 +3665,7 @@ function runHvigorw(opts) {
   const { config } = opts;
   const projectDir = toLongPath(opts.projectDir);
   const logger = opts.logger ?? noopLogger;
-  if (!fs22.existsSync(path22.join(projectDir, "build-profile.json5"))) {
+  if (!fs24.existsSync(path24.join(projectDir, "build-profile.json5"))) {
     throw new OniroError(`Not an OpenHarmony project: ${projectDir} (build-profile.json5 not found).`);
   }
   let hvigorw;
@@ -2916,24 +3677,24 @@ function runHvigorw(opts) {
     hvigorw = resolved.startsWith(projectDir) ? resolved : findHarmonyOsTool(sdk, "hvigorw") ?? resolved;
     logger.info(`[build] Building for HarmonyOS against the SDK at ${sdk.sdkPath}.`);
   } else {
-    if (!fs22.existsSync(getCmdToolsPath(config))) {
+    if (!fs24.existsSync(getCmdToolsPath(config))) {
       throw new CmdToolsNotInstalledError(getCmdToolsPath(config));
     }
     sdkEnv = { OHOS_BASE_SDK_HOME: getOhosBaseSdkHome(config) };
     hvigorw = getHvigorwPath(config, projectDir);
   }
-  if (!fs22.existsSync(hvigorw)) {
+  if (!fs24.existsSync(hvigorw)) {
     throw new OniroError(`hvigorw wrapper not found at ${hvigorw}.`);
   }
   const args = buildHvigorwArgs(opts);
   if (process.platform !== "win32") {
     try {
-      fs22.chmodSync(hvigorw, 493);
+      fs24.chmodSync(hvigorw, 493);
     } catch {
     }
   }
   const env = { ...process.env, ...sdkEnv };
-  return new Promise((resolve6, reject) => {
+  return new Promise((resolve7, reject) => {
     if (opts.abortSignal?.aborted) {
       reject(new CancelledError("hvigorw build cancelled."));
       return;
@@ -2977,46 +3738,15 @@ function runHvigorw(opts) {
       settled = true;
       cleanup();
       const exitCode = code ?? 1;
-      if (exitCode === 0) resolve6({ exitCode });
+      if (exitCode === 0) resolve7({ exitCode });
       else reject(new OniroError(`hvigorw exited with code ${exitCode}`));
     });
   });
 }
 
-// src/build/discoverHaps.ts
-import * as fs23 from "fs";
-import * as path23 from "path";
-function moduleOfHap(hapFileName) {
-  const dash = hapFileName.indexOf("-");
-  return dash > 0 ? hapFileName.slice(0, dash) : hapFileName.replace(/\.hap$/i, "");
-}
-async function discoverHaps(opts) {
-  const { projectDir } = opts;
-  const maxDepth = opts.maxDepth ?? 8;
-  const result = {};
-  const walk = async (dir, depth) => {
-    if (depth > maxDepth) return;
-    const entries = await fs23.promises.readdir(dir, { withFileTypes: true }).catch(() => []);
-    for (const e of entries) {
-      const full = path23.join(dir, e.name);
-      if (e.isDirectory()) {
-        if (e.name === "node_modules" || e.name === "oh_modules" || e.name === ".git") continue;
-        await walk(full, depth + 1);
-      } else if (e.isFile() && e.name.endsWith(".hap")) {
-        const moduleName = moduleOfHap(e.name);
-        const bucket = result[moduleName] ??= { signed: [], unsigned: [] };
-        if (e.name.includes("unsigned")) bucket.unsigned.push(full);
-        else if (e.name.includes("signed")) bucket.signed.push(full);
-      }
-    }
-  };
-  await walk(projectDir, 0);
-  return result;
-}
-
 // src/build/ohpm.ts
-import * as fs24 from "fs";
-import * as path24 from "path";
+import * as fs25 from "fs";
+import * as path25 from "path";
 function runOhpm(opts) {
   return runProcess({
     command: opts.ohpmPath ?? getOhpmPath(opts.config),
@@ -3029,7 +3759,7 @@ function runOhpm(opts) {
   });
 }
 async function ensureOhModules(opts) {
-  if (fs24.existsSync(path24.join(opts.projectDir, "oh_modules"))) {
+  if (fs25.existsSync(path25.join(opts.projectDir, "oh_modules"))) {
     return { installed: false };
   }
   const res = await runOhpm({
@@ -3046,23 +3776,91 @@ async function ensureOhModules(opts) {
 }
 
 // src/build/codelinter.ts
-var FINDING_RE = /^(.*?):(\d+):(?:\d+:)?\s*(error|warning|warn|info)\b[:\s-]*(.*)$/i;
+var FINDING_RE = /^(.*?):(\d+):(?:(\d+):)?\s*(error|warning|warn|suggestion|info)\b[:\s-]*(.*)$/i;
 var TRAILING_CODE_RE = /[([]([\w@/.\-]+)[)\]]\s*$/;
-function parseCodelinterFindings(output) {
+var FILE_HEADER_RE = /^(.+\.\w+)\((\d+)\)$/;
+var ROW_RE = /^(\d+):(\d+)\s+(error|warning|warn|suggestion|info)\s+(.*)$/i;
+var RULE_RE = /^@?[\w.-]+(?:\/[\w.-]+)+$/;
+var SUMMARY_RE = /Defects:\s*(\d+);\s*Errors:\s*(\d+);\s*Warns:\s*(\d+);\s*Suggestions:\s*(\d+)/i;
+var NOTICE_RE = /does not match that of the project|error occurred during linting|incomplete report/i;
+var ANSI_RE = /\x1b\[[0-9;]*[A-Za-z]/g;
+function cleanCodelinterOutput(output) {
+  return output.replace(ANSI_RE, "").split("\n").map((line) => (line.split("\r").filter((s) => s.trim() !== "").pop() ?? "").trimEnd()).join("\n");
+}
+function normaliseSeverity(s) {
+  const lower = s.toLowerCase();
+  return lower === "warn" ? "warning" : lower;
+}
+function parseCodelinterReport(output) {
   const findings = [];
-  for (const raw of output.split("\n")) {
-    const m = FINDING_RE.exec(raw.trim());
-    if (!m) continue;
-    let message = m[4].trim();
-    let code = "";
-    const codeMatch = TRAILING_CODE_RE.exec(message);
-    if (codeMatch) {
-      code = codeMatch[1];
-      message = message.slice(0, codeMatch.index).trim();
+  const notices = [];
+  let summary = null;
+  let file = "";
+  for (const rawLine of cleanCodelinterOutput(output).split("\n")) {
+    const line = rawLine.trim();
+    if (!line) continue;
+    const row = ROW_RE.exec(line);
+    if (row) {
+      if (!file) continue;
+      const columns = row[4].trim().split(/\s{2,}/);
+      const last = columns[columns.length - 1];
+      const code = columns.length > 1 && RULE_RE.test(last) ? last : "";
+      const message = (code ? columns.slice(0, -1) : columns).join(" ").trim();
+      findings.push({
+        file,
+        line: Number(row[1]),
+        column: Number(row[2]),
+        severity: normaliseSeverity(row[3]),
+        code,
+        message
+      });
+      continue;
+    }
+    const header = FILE_HEADER_RE.exec(line);
+    if (header) {
+      file = header[1];
+      continue;
     }
-    findings.push({ file: m[1].trim(), line: Number(m[2]), severity: m[3].toLowerCase(), code, message });
+    const legacy = FINDING_RE.exec(line);
+    if (legacy) {
+      let message = legacy[5].trim();
+      let code = "";
+      const codeMatch = TRAILING_CODE_RE.exec(message);
+      if (codeMatch) {
+        code = codeMatch[1];
+        message = message.slice(0, codeMatch.index).trim();
+      }
+      const finding = {
+        file: legacy[1].trim(),
+        line: Number(legacy[2]),
+        severity: normaliseSeverity(legacy[4]),
+        code,
+        message
+      };
+      if (legacy[3]) finding.column = Number(legacy[3]);
+      findings.push(finding);
+      continue;
+    }
+    const totals = SUMMARY_RE.exec(line);
+    if (totals) {
+      summary = {
+        defects: Number(totals[1]),
+        errors: Number(totals[2]),
+        warnings: Number(totals[3]),
+        suggestions: Number(totals[4])
+      };
+      continue;
+    }
+    if (/no defects found/i.test(line)) {
+      summary = { defects: 0, errors: 0, warnings: 0, suggestions: 0 };
+      continue;
+    }
+    if (NOTICE_RE.test(line)) notices.push(line);
   }
-  return findings;
+  return { findings, summary, notices, incomplete: notices.length > 0 };
+}
+function parseCodelinterFindings(output) {
+  return parseCodelinterReport(output).findings;
 }
 async function runCodelinter(opts) {
   const res = await runProcess({
@@ -3074,16 +3872,28 @@ async function runCodelinter(opts) {
     logger: opts.logger
   });
   const raw = `${res.stdout}${res.stderr}`;
-  return { code: res.code, findings: parseCodelinterFindings(raw), raw };
+  return { code: res.code, ...parseCodelinterReport(raw), raw: cleanCodelinterOutput(raw) };
 }
 
 // src/build/buildHap.ts
+var DIAGNOSIS_OUTPUT_LIMIT = 2e6;
+function diagnoseBuildFailure(output) {
+  if (/is not exported from Kit|has no exported member .*@systemapi/i.test(output)) {
+    return "The project calls system APIs (`@systemapi`), which the public SDK leaves out. Build against the full OpenHarmony SDK: unpack its components into <root>/<os>/<api> of a separate SDK root and set ONIRO_SDK_ROOT_DIR to that root. Installing such an app also needs privileged signing (`oniro-app sign --apl system_core --acls \u2026 --app-privilege-capabilities \u2026`).";
+  }
+  if (/00308018|SDK path does not exist|SDK license agreement is not accepted/i.test(output)) {
+    return "hvigor cannot find the SDK the project compiles against: check `oniro-app sdk list` against compileSdkVersion.";
+  }
+  return void 0;
+}
 async function buildHap(opts) {
   const logger = scopedLogger(opts.logger ?? noopLogger, "build");
   const warnings = [];
   const start = Date.now();
   const projectDir = toLongPath(opts.projectDir);
   const isHarmonyOs = detectRuntimeOs(projectDir, opts.product) === "HarmonyOS";
+  const missingSdk = isHarmonyOs ? null : findMissingProjectSdk(opts.config, projectDir);
+  if (missingSdk) throw missingSdk;
   if (opts.autoInstallDeps !== false) {
     const harmonySdk = isHarmonyOs ? findHarmonyOsSdk({ config: opts.config, logger: opts.logger }) : null;
     const r = await ensureOhModules({
@@ -3096,23 +3906,35 @@ async function buildHap(opts) {
     });
     if (r.installed) logger.info("ran ohpm install --all (oh_modules was missing)");
   }
-  const { exitCode } = await runHvigorw({
-    config: opts.config,
-    projectDir,
-    product: opts.product,
-    module: opts.module,
-    buildMode: opts.mode,
-    task: opts.task,
-    parallel: opts.parallel,
-    abortSignal: opts.abortSignal,
-    onOutput: opts.onOutput,
-    logger: opts.logger
-  });
+  let output = "";
+  let exitCode;
+  try {
+    ({ exitCode } = await runHvigorw({
+      config: opts.config,
+      projectDir,
+      product: opts.product,
+      module: opts.module,
+      buildMode: opts.mode,
+      task: opts.task,
+      parallel: opts.parallel,
+      abortSignal: opts.abortSignal,
+      onOutput: (chunk, stream) => {
+        output = (output + chunk).slice(-DIAGNOSIS_OUTPUT_LIMIT);
+        opts.onOutput?.(chunk, stream);
+      },
+      logger: opts.logger
+    }));
+  } catch (err) {
+    const hint = diagnoseBuildFailure(output);
+    if (hint && err instanceof OniroError) throw new OniroError(`${err.message}
+${hint}`, err);
+    throw err;
+  }
   const discoveredHaps = await discoverHaps({ projectDir });
   const anySigned = Object.values(discoveredHaps).some((m) => m.signed.length > 0);
   if (!anySigned) {
     warnings.push(
-      isHarmonyOs ? "No signed HAPs found \u2014 run `oniro-app sign --harmonyos` to have AppGallery Connect issue a certificate and profile." : "No signed HAPs found \u2014 configure signingConfigs in build-profile.json5 (unsigned HAPs are rejected by most devices)."
+      isHarmonyOs ? "No signed HAPs found. The HarmonyOS emulator installs the unsigned HAP as it is; for a device, run `oniro-app sign --harmonyos` to have AppGallery Connect issue a certificate and profile." : "No signed HAPs found: most OpenHarmony targets reject unsigned HAPs. Run `oniro-app sign` to generate local signing material, then build again."
     );
   }
   return { exitCode, durationMs: Date.now() - start, discoveredHaps, warnings };
@@ -3129,21 +3951,21 @@ function isValidBundleName(bundleName) {
 }
 
 // src/project/templates.ts
-import * as fs25 from "fs";
-import * as path25 from "path";
+import * as fs26 from "fs";
+import * as path26 from "path";
 function toHumanTemplateName(folderName) {
   return folderName.replace(/([a-z])([A-Z])/g, "$1 $2");
 }
 function listTemplates(templateRoot) {
-  if (!fs25.existsSync(templateRoot)) return [];
-  const entries = fs25.readdirSync(templateRoot, { withFileTypes: true });
+  if (!fs26.existsSync(templateRoot)) return [];
+  const entries = fs26.readdirSync(templateRoot, { withFileTypes: true });
   return entries.filter((e) => e.isDirectory()).map((e) => {
-    const dir = path25.join(templateRoot, e.name);
-    const metaPath = path25.join(dir, "template.json");
+    const dir = path26.join(templateRoot, e.name);
+    const metaPath = path26.join(dir, "template.json");
     let meta = {};
-    if (fs25.existsSync(metaPath)) {
+    if (fs26.existsSync(metaPath)) {
       try {
-        meta = JSON.parse(fs25.readFileSync(metaPath, "utf8"));
+        meta = JSON.parse(fs26.readFileSync(metaPath, "utf8"));
       } catch {
       }
     }
@@ -3158,57 +3980,57 @@ function listTemplates(templateRoot) {
 function validateTemplateLayout(templateDir, defaultModuleName) {
   const required = [
     "build-profile.json5",
-    path25.join("AppScope", "app.json5"),
-    path25.join(defaultModuleName, "src", "main", "module.json5"),
-    path25.join(defaultModuleName, "oh-package.json5"),
+    path26.join("AppScope", "app.json5"),
+    path26.join(defaultModuleName, "src", "main", "module.json5"),
+    path26.join(defaultModuleName, "oh-package.json5"),
     "hvigorfile.ts"
   ];
-  return required.filter((rel) => !fs25.existsSync(path25.join(templateDir, rel)));
+  return required.filter((rel) => !fs26.existsSync(path26.join(templateDir, rel)));
 }
 
 // src/project/createScaffold.ts
-import * as fs27 from "fs";
-import * as path26 from "path";
+import * as fs28 from "fs";
+import * as path27 from "path";
 
 // src/project/jsonHelpers.ts
-import * as fs26 from "fs";
+import * as fs27 from "fs";
 import JSON55 from "json5";
 function readJson5File(filePath) {
-  return JSON55.parse(fs26.readFileSync(filePath, "utf8"));
+  return JSON55.parse(fs27.readFileSync(filePath, "utf8"));
 }
 function writeJson5File(filePath, value) {
-  fs26.writeFileSync(filePath, JSON.stringify(value, null, 2) + "\n", "utf8");
+  fs27.writeFileSync(filePath, JSON.stringify(value, null, 2) + "\n", "utf8");
 }
 function readJsonFile(filePath) {
-  return JSON.parse(fs26.readFileSync(filePath, "utf8"));
+  return JSON.parse(fs27.readFileSync(filePath, "utf8"));
 }
 function writeJsonFile(filePath, value) {
-  fs26.writeFileSync(filePath, JSON.stringify(value, null, 2) + "\n", "utf8");
+  fs27.writeFileSync(filePath, JSON.stringify(value, null, 2) + "\n", "utf8");
 }
 
 // src/project/createScaffold.ts
 var IGNORED_DIRS = /* @__PURE__ */ new Set(["oh_modules", "node_modules", "build", ".hvigor"]);
 async function pathExists(p) {
   try {
-    await fs27.promises.access(p);
+    await fs28.promises.access(p);
     return true;
   } catch {
     return false;
   }
 }
 async function copyDirRecursive(srcDir, destDir) {
-  await fs27.promises.mkdir(destDir, { recursive: true });
-  const entries = await fs27.promises.readdir(srcDir, { withFileTypes: true });
+  await fs28.promises.mkdir(destDir, { recursive: true });
+  const entries = await fs28.promises.readdir(srcDir, { withFileTypes: true });
   for (const entry of entries) {
-    const src = path26.join(srcDir, entry.name);
-    const dest = path26.join(destDir, entry.name);
+    const src = path27.join(srcDir, entry.name);
+    const dest = path27.join(destDir, entry.name);
     if (entry.isDirectory()) {
       await copyDirRecursive(src, dest);
     } else if (entry.isSymbolicLink()) {
       continue;
     } else if (entry.isFile()) {
       if (entry.name === "template.json") continue;
-      await fs27.promises.copyFile(src, dest);
+      await fs28.promises.copyFile(src, dest);
     }
   }
 }
@@ -3216,9 +4038,9 @@ async function normalizeJson5ToJson(projectDir, logger) {
   const stack = [projectDir];
   while (stack.length > 0) {
     const currentDir = stack.pop();
-    const entries = await fs27.promises.readdir(currentDir, { withFileTypes: true });
+    const entries = await fs28.promises.readdir(currentDir, { withFileTypes: true });
     for (const entry of entries) {
-      const fullPath = path26.join(currentDir, entry.name);
+      const fullPath = path27.join(currentDir, entry.name);
       if (entry.isDirectory()) {
         if (IGNORED_DIRS.has(entry.name)) continue;
         stack.push(fullPath);
@@ -3240,23 +4062,23 @@ function toJavaPropertiesPath(p) {
 function createOrUpdateLocalProperties(projectDir, sdkDir) {
   const content = `sdk.dir=${toJavaPropertiesPath(sdkDir)}
 `;
-  fs27.writeFileSync(path26.join(projectDir, "local.properties"), content, "utf8");
+  fs28.writeFileSync(path27.join(projectDir, "local.properties"), content, "utf8");
 }
 function renameIfExists(fromPath, toPath) {
-  if (fs27.existsSync(fromPath) && fromPath !== toPath) {
-    fs27.renameSync(fromPath, toPath);
+  if (fs28.existsSync(fromPath) && fromPath !== toPath) {
+    fs28.renameSync(fromPath, toPath);
   }
 }
 function updateTemplateConfigs(projectDir, args, sdkBaseDir) {
-  const appJsonPath = path26.join(projectDir, "AppScope", "app.json5");
-  if (fs27.existsSync(appJsonPath)) {
+  const appJsonPath = path27.join(projectDir, "AppScope", "app.json5");
+  if (fs28.existsSync(appJsonPath)) {
     const appJson = readJson5File(appJsonPath);
     appJson.app = appJson.app ?? {};
     appJson.app.bundleName = args.bundleName;
     writeJson5File(appJsonPath, appJson);
   }
-  const stringsPath = path26.join(projectDir, "AppScope", "resources", "base", "element", "string.json");
-  if (fs27.existsSync(stringsPath)) {
+  const stringsPath = path27.join(projectDir, "AppScope", "resources", "base", "element", "string.json");
+  if (fs28.existsSync(stringsPath)) {
     const strings = readJsonFile(stringsPath);
     if (Array.isArray(strings.string)) {
       const appName = strings.string.find((s) => s.name === "app_name");
@@ -3264,8 +4086,8 @@ function updateTemplateConfigs(projectDir, args, sdkBaseDir) {
     }
     writeJsonFile(stringsPath, strings);
   }
-  const buildProfilePath = path26.join(projectDir, "build-profile.json5");
-  if (fs27.existsSync(buildProfilePath)) {
+  const buildProfilePath = path27.join(projectDir, "build-profile.json5");
+  if (fs28.existsSync(buildProfilePath)) {
     const buildProfile = readJson5File(buildProfilePath);
     buildProfile.app = buildProfile.app ?? {};
     if (Array.isArray(buildProfile.app.products) && buildProfile.app.products.length > 0) {
@@ -3278,23 +4100,23 @@ function updateTemplateConfigs(projectDir, args, sdkBaseDir) {
     }
     writeJson5File(buildProfilePath, buildProfile);
   }
-  const moduleJsonPath = path26.join(projectDir, args.moduleName, "src", "main", "module.json5");
-  if (fs27.existsSync(moduleJsonPath)) {
+  const moduleJsonPath = path27.join(projectDir, args.moduleName, "src", "main", "module.json5");
+  if (fs28.existsSync(moduleJsonPath)) {
     const moduleJson = readJson5File(moduleJsonPath);
     moduleJson.module = moduleJson.module ?? {};
     moduleJson.module.name = args.moduleName;
     writeJson5File(moduleJsonPath, moduleJson);
   }
-  const moduleOhPackagePath = path26.join(projectDir, args.moduleName, "oh-package.json5");
-  if (fs27.existsSync(moduleOhPackagePath)) {
+  const moduleOhPackagePath = path27.join(projectDir, args.moduleName, "oh-package.json5");
+  if (fs28.existsSync(moduleOhPackagePath)) {
     const pkg = readJson5File(moduleOhPackagePath);
     pkg.name = args.moduleName;
     writeJson5File(moduleOhPackagePath, pkg);
   }
-  const vscodeDir = path26.join(projectDir, ".vscode");
-  fs27.mkdirSync(vscodeDir, { recursive: true });
+  const vscodeDir = path27.join(projectDir, ".vscode");
+  fs28.mkdirSync(vscodeDir, { recursive: true });
   const hapPath = `${args.moduleName}/build/default/outputs/default/${args.moduleName}-default-signed.hap`;
-  writeJsonFile(path26.join(vscodeDir, "settings.json"), {
+  writeJsonFile(path27.join(vscodeDir, "settings.json"), {
     "oniro.hapPath": hapPath,
     "files.associations": { "*.json5": "jsonc" }
   });
@@ -3311,7 +4133,7 @@ async function createScaffold(opts) {
   if (!opts.location || !await pathExists(opts.location)) {
     throw new OniroError(`Location does not exist: ${opts.location}`);
   }
-  const templateDir = path26.join(opts.templateRoot, opts.templateId);
+  const templateDir = path27.join(opts.templateRoot, opts.templateId);
   if (!await pathExists(templateDir)) {
     throw new OniroError(`Template not found: ${templateDir}`);
   }
@@ -3346,17 +4168,17 @@ async function createScaffold(opts) {
       }
     }
   }
-  const projectDir = path26.join(opts.location, opts.projectName);
+  const projectDir = path27.join(opts.location, opts.projectName);
   if (await pathExists(projectDir)) {
     if (!opts.overwrite) {
       throw new OniroError(`Destination already exists: ${projectDir}. Pass overwrite: true to replace it.`);
     }
-    await fs27.promises.rm(projectDir, { recursive: true, force: true });
+    await fs28.promises.rm(projectDir, { recursive: true, force: true });
   }
   logger.info(`[create] Scaffolding ${opts.templateId} at ${projectDir}`);
   await copyDirRecursive(templateDir, projectDir);
   if (moduleName !== defaultModuleName) {
-    renameIfExists(path26.join(projectDir, defaultModuleName), path26.join(projectDir, moduleName));
+    renameIfExists(path27.join(projectDir, defaultModuleName), path27.join(projectDir, moduleName));
   }
   updateTemplateConfigs(
     projectDir,
@@ -3373,11 +4195,11 @@ async function createScaffold(opts) {
 }
 
 // src/project/listModules.ts
-import * as fs28 from "fs";
-import * as path27 from "path";
+import * as fs29 from "fs";
+import * as path28 from "path";
 function listModules(opts) {
-  const buildProfile = path27.join(opts.projectDir, "build-profile.json5");
-  if (!fs28.existsSync(buildProfile)) {
+  const buildProfile = path28.join(opts.projectDir, "build-profile.json5");
+  if (!fs29.existsSync(buildProfile)) {
     throw new OniroError(`build-profile.json5 not found at ${buildProfile}`);
   }
   const parsed = readJson5File(buildProfile);
@@ -3389,12 +4211,12 @@ function listModules(opts) {
 }
 
 // src/project/abilities.ts
-import * as fs29 from "fs";
-import * as path28 from "path";
+import * as fs30 from "fs";
+import * as path29 from "path";
 function listAbilities(opts) {
   const moduleName = opts.moduleName ?? "entry";
-  const moduleJsonPath = path28.join(opts.projectDir, moduleName, "src", "main", "module.json5");
-  if (!fs29.existsSync(moduleJsonPath)) {
+  const moduleJsonPath = path29.join(opts.projectDir, moduleName, "src", "main", "module.json5");
+  if (!fs30.existsSync(moduleJsonPath)) {
     throw new OniroError(`Could not find module.json5 at ${moduleJsonPath}`);
   }
   const parsed = readJson5File(moduleJsonPath);
@@ -3402,12 +4224,12 @@ function listAbilities(opts) {
 }
 
 // src/project/prepareSigning.ts
-import * as fs30 from "fs";
-import * as path29 from "path";
+import * as fs31 from "fs";
+import * as path30 from "path";
 function hasSigningArtifacts(dir) {
-  if (!fs30.existsSync(path29.join(dir, "signatures"))) return false;
-  const buildProfile = path29.join(dir, "build-profile.json5");
-  if (!fs30.existsSync(buildProfile)) return false;
+  if (!fs31.existsSync(path30.join(dir, "signatures"))) return false;
+  const buildProfile = path30.join(dir, "build-profile.json5");
+  if (!fs31.existsSync(buildProfile)) return false;
   try {
     const parsed = readJson5File(buildProfile);
     return Array.isArray(parsed.app?.signingConfigs) && parsed.app.signingConfigs.length > 0;
@@ -3425,6 +4247,7 @@ function prepareSigning(opts) {
     apl: opts.apl,
     appFeature: opts.appFeature,
     acls: opts.acls,
+    appPrivilegeCapabilities: opts.appPrivilegeCapabilities,
     passwords: opts.passwords,
     logger: opts.logger
   });
@@ -3453,19 +4276,31 @@ var PROPS = [
   ["model", "const.product.model"],
   ["manufacturer", "const.product.manufacturer"],
   ["brand", "const.product.brand"],
+  ["osDistName", "const.product.os.dist.name"],
+  ["osDistVersion", "const.product.os.dist.version"],
   ["osFullName", "const.ohos.fullname"],
   ["osReleaseType", "const.ohos.releasetype"],
   ["sdkApiVersion", "const.ohos.apiversion"],
-  ["buildVersion", "const.product.software.version"]
+  ["buildVersion", "const.product.software.version"],
+  ["abi", "const.product.cpu.abilist"],
+  ["deviceType", "const.product.devicetype"]
 ];
 async function getDeviceInfo(opts) {
   const info = { serial: opts.deviceSerial ?? "(default)", display: null };
-  for (const [field, prop] of PROPS) {
-    try {
-      const value = await paramGet(opts.config, prop, { deviceSerial: opts.deviceSerial, timeoutMs: opts.timeoutMs ?? 1e4, logger: opts.logger });
+  try {
+    const values = await paramGetMany(
+      opts.config,
+      PROPS.map(([, prop]) => prop),
+      { deviceSerial: opts.deviceSerial, timeoutMs: opts.timeoutMs ?? 1e4, logger: opts.logger }
+    );
+    for (const [field, prop] of PROPS) {
+      const value = values[prop];
       if (value) info[field] = value;
-    } catch {
     }
+  } catch {
+  }
+  if (info.osDistName || info.osFullName) {
+    info.osFamily = /harmonyos/i.test(info.osDistName ?? "") ? "HarmonyOS" : "OpenHarmony";
   }
   const screen = await dumpScreen({ config: opts.config, deviceSerial: opts.deviceSerial, logger: opts.logger });
   if (screen) info.display = { width: screen.width, height: screen.height };
@@ -3497,8 +4332,8 @@ async function diffHapAssets(opts) {
 }
 
 // src/install/apply.ts
-import * as fs31 from "fs";
-import * as path30 from "path";
+import * as fs32 from "fs";
+import * as path31 from "path";
 function decideInstallMethod(s) {
   if (!s.signInfoInconsistent) return "replace";
   if (s.isSystemBundle && !s.allowUninstall) return "refuse";
@@ -3516,39 +4351,31 @@ async function pidOf(config, bundle, deviceSerial) {
   const proc = await findRunningProcess({ config, bundle, deviceSerial });
   return proc ? Number(proc.pid) : null;
 }
-async function resolveHapPath(opts) {
-  let hapPath = opts.hapPath;
-  if (hapPath) {
-    if (!path30.isAbsolute(hapPath) && opts.projectDir) hapPath = path30.join(opts.projectDir, hapPath);
+async function resolveHap(opts, logger) {
+  let hap;
+  if (opts.hapPath) {
+    const hapPath = !path31.isAbsolute(opts.hapPath) && opts.projectDir ? path31.join(opts.projectDir, opts.hapPath) : opts.hapPath;
+    hap = existingHapOrUnsigned(hapPath);
+    if (!hap) throw new OniroError(`HAP not found at ${hapPath}.`);
   } else {
     if (!opts.projectDir) throw new OniroError("applyChanges requires hapPath or projectDir.");
-    const haps = await discoverHaps({ projectDir: opts.projectDir });
-    if (opts.module) {
-      const signed = haps[opts.module]?.signed ?? [];
-      if (signed.length === 0) throw new OniroError(`No signed HAP for module ${opts.module}. Build first.`);
-      hapPath = signed[0];
-    } else {
-      const withSigned = Object.entries(haps).filter(([, m]) => m.signed.length > 0);
-      if (withSigned.length === 0) throw new OniroError("No signed HAP found. Build first.");
-      if (withSigned.length > 1) {
-        throw new OniroError(
-          `Multiple modules have signed HAPs (${withSigned.map(([k]) => k).join(", ")}). Pass module to choose.`
-        );
-      }
-      hapPath = withSigned[0][1].signed[0];
-    }
+    const picked = pickHap(await discoverHaps({ projectDir: opts.projectDir }), opts.module);
+    if (!picked) throw new OniroError(`No HAP found${opts.module ? ` for module ${opts.module}` : ""}. Build first.`);
+    hap = { path: picked.path, fallback: !picked.signed };
   }
-  if (!fs31.existsSync(hapPath)) throw new OniroError(`HAP not found at ${hapPath}.`);
-  return hapPath;
+  if (hap.fallback) logger.warn(`No signed HAP found; installing the unsigned ${path31.basename(hap.path)}.`);
+  return hap;
 }
 async function applyChanges(opts) {
   const logger = scopedLogger(opts.logger ?? noopLogger, "apply");
   const { config, bundle, deviceSerial } = opts;
   const isSystemBundle = opts.isSystemBundle ?? false;
   const allowUninstall = opts.allowUninstall ?? false;
-  const hapPath = await resolveHapPath(opts);
+  const hap = await resolveHap(opts, logger);
+  const hapPath = hap.path;
+  logger.info(`installing ${hapPath}`);
   let assetsChanged = false;
-  if (opts.installedHapPath && fs31.existsSync(opts.installedHapPath)) {
+  if (opts.installedHapPath && fs32.existsSync(opts.installedHapPath)) {
     try {
       const diff = await diffHapAssets({ installedHap: opts.installedHapPath, newHap: hapPath });
       assetsChanged = diff.addedAssetPaths.length > 0 || diff.removedAssetPaths.length > 0;
@@ -3569,12 +4396,21 @@ async function applyChanges(opts) {
   if (decision === "uninstall-install") {
     logger.warn(`sign-info inconsistent for ${bundle}; uninstalling then installing fresh.`);
     await uninstallApp({ config, bundle, deviceSerial });
-    ensureOk(await hdcExec({ config, args: ["install", hapPath], deviceSerial, timeoutMs: 3e5 }), `hdc install ${hapPath}`);
+    ensureInstallOk(
+      await hdcExec({ config, args: ["install", hapPath], deviceSerial, timeoutMs: 3e5 }),
+      `hdc install ${hapPath}`,
+      hap
+    );
     installMethod = "uninstall-install";
   } else {
-    ensureOk(replaceRes, `hdc install -r ${hapPath}`);
+    ensureInstallOk(replaceRes, `hdc install -r ${hapPath}`, hap);
     installMethod = "replace";
   }
+  if (!await isBundleInstalled({ config, bundle, deviceSerial })) {
+    throw new OniroError(
+      `hdc reported ${path31.basename(hapPath)} as installed, but bm dump does not list ${bundle}. Check that the HAP was built from this project (its bundleName must match).`
+    );
+  }
   let postInstallPid = await pidOf(config, bundle, deviceSerial);
   const rebootDecision = decideReboot({ assetsChanged, isSystemBundle, preInstallPid, postInstallPid });
   let method = installMethod;
@@ -3649,9 +4485,9 @@ var AUTH_PATHS = {
 };
 
 // src/harmonyos/auth/tokenStore.ts
-import * as fs32 from "fs";
+import * as fs33 from "fs";
 import * as os11 from "os";
-import * as path31 from "path";
+import * as path32 from "path";
 import * as crypto3 from "crypto";
 var ALGORITHM = "aes-256-gcm";
 var KEY_LENGTH = 32;
@@ -3687,7 +4523,7 @@ function permissionHint(dir) {
 }
 function ensureDir(dir) {
   try {
-    fs32.mkdirSync(dir, { recursive: true, mode: DIR_MODE });
+    fs33.mkdirSync(dir, { recursive: true, mode: DIR_MODE });
   } catch (err) {
     if (err.code === "EACCES") {
       throw new OniroError(permissionHint(dir), err);
@@ -3698,17 +4534,17 @@ function ensureDir(dir) {
 function createTokenStore(opts) {
   const logger = opts.logger ?? noopLogger;
   const authDir = opts.config.get("harmonyosAuthDir", defaultPaths.harmonyosAuthDir());
-  const tokenPath = path31.join(authDir, TOKEN_FILE);
-  const keyPath = path31.join(os11.homedir(), ".local", "share", "oniro-app", "keys", KEY_FILE);
+  const tokenPath = path32.join(authDir, TOKEN_FILE);
+  const keyPath = path32.join(os11.homedir(), ".local", "share", "oniro-app", "keys", KEY_FILE);
   function loadOrCreateKey() {
-    if (fs32.existsSync(keyPath)) {
-      const existing = fs32.readFileSync(keyPath);
+    if (fs33.existsSync(keyPath)) {
+      const existing = fs33.readFileSync(keyPath);
       if (existing.length === KEY_LENGTH) return existing;
       logger.warn("[harmonyos] The token key file was malformed; regenerating (you will need to log in again).");
     }
-    ensureDir(path31.dirname(keyPath));
+    ensureDir(path32.dirname(keyPath));
     const key = crypto3.randomBytes(KEY_LENGTH);
-    fs32.writeFileSync(keyPath, key, { mode: FILE_MODE });
+    fs33.writeFileSync(keyPath, key, { mode: FILE_MODE });
     return key;
   }
   return {
@@ -3718,12 +4554,12 @@ function createTokenStore(opts) {
       const payload = Buffer.from(JSON.stringify(session), "utf8");
       const blob = encrypt2(loadOrCreateKey(), payload);
       ensureDir(authDir);
-      fs32.writeFileSync(tokenPath, JSON.stringify(blob, null, 2), { mode: FILE_MODE });
+      fs33.writeFileSync(tokenPath, JSON.stringify(blob, null, 2), { mode: FILE_MODE });
     },
     load() {
-      if (!fs32.existsSync(tokenPath)) return null;
+      if (!fs33.existsSync(tokenPath)) return null;
       try {
-        const blob = JSON.parse(fs32.readFileSync(tokenPath, "utf8"));
+        const blob = JSON.parse(fs33.readFileSync(tokenPath, "utf8"));
         if (!isEncryptedBlob(blob)) return null;
         const { jwtToken, siteId } = JSON.parse(decrypt2(loadOrCreateKey(), blob).toString("utf8"));
         return typeof jwtToken === "string" && jwtToken && typeof siteId === "string" ? { jwtToken, siteId } : null;
@@ -3735,7 +4571,7 @@ function createTokenStore(opts) {
         }
         logger.debug(`[harmonyos] Discarding unreadable token at ${tokenPath}.`);
         try {
-          fs32.rmSync(tokenPath, { force: true });
+          fs33.rmSync(tokenPath, { force: true });
         } catch {
         }
         return null;
@@ -3743,7 +4579,7 @@ function createTokenStore(opts) {
     },
     clear() {
       try {
-        fs32.rmSync(tokenPath, { force: true });
+        fs33.rmSync(tokenPath, { force: true });
       } catch (err) {
         throw new OniroError(`Failed to remove ${tokenPath}.`, err);
       }
@@ -3857,8 +4693,8 @@ function isQuit(quit) {
 async function startCallbackServer(opts) {
   let resolveCallback;
   let rejectCallback;
-  const callback = new Promise((resolve6, reject) => {
-    resolveCallback = resolve6;
+  const callback = new Promise((resolve7, reject) => {
+    resolveCallback = resolve7;
     rejectCallback = reject;
   });
   callback.catch(() => {
@@ -3917,9 +4753,9 @@ async function startCallbackServer(opts) {
     }
   });
   server.keepAliveTimeout = 1;
-  await new Promise((resolve6, reject) => {
+  await new Promise((resolve7, reject) => {
     server.once("error", (err) => reject(new OniroError("Failed to start the local login callback server.", err)));
-    server.listen(0, "127.0.0.1", resolve6);
+    server.listen(0, "127.0.0.1", resolve7);
   });
   const port = server.address().port;
   return {
@@ -3935,12 +4771,12 @@ async function startCallbackServer(opts) {
       return Promise.race([callback, timeout]).finally(() => clearTimeout(timer));
     },
     stop() {
-      return new Promise((resolve6) => {
+      return new Promise((resolve7) => {
         server.closeAllConnections?.();
-        const timer = setTimeout(resolve6, 100);
+        const timer = setTimeout(resolve7, 100);
         server.close(() => {
           clearTimeout(timer);
-          resolve6();
+          resolve7();
         });
       });
     }
@@ -3972,11 +4808,11 @@ function openBrowser(url) {
     windowsHide: true
   });
   child.unref();
-  return new Promise((resolve6, reject) => {
+  return new Promise((resolve7, reject) => {
     child.on("error", (err) => reject(new OniroError(`Failed to open a browser (${command}).`, err)));
     child.on(
       "exit",
-      (code) => code === 0 ? resolve6() : reject(new OniroError(`Browser launcher '${command}' exited with code ${code}.`))
+      (code) => code === 0 ? resolve7() : reject(new OniroError(`Browser launcher '${command}' exited with code ${code}.`))
     );
   });
 }
@@ -4224,7 +5060,7 @@ function mapAgcError(operation, statusCode, reasonPhrase, body) {
 }
 
 // src/harmonyos/signing/profile.ts
-import * as fs33 from "fs";
+import * as fs34 from "fs";
 import { X509Certificate } from "crypto";
 import forge from "node-forge";
 function extractProfileJson(buffer) {
@@ -4256,7 +5092,7 @@ function extractProfileJson(buffer) {
 function readProvisionProfile(profilePath) {
   let raw;
   try {
-    const json = extractProfileJson(fs33.readFileSync(profilePath));
+    const json = extractProfileJson(fs34.readFileSync(profilePath));
     if (!json) return null;
     raw = JSON.parse(json);
   } catch {
@@ -4285,7 +5121,7 @@ function parseCertificate(pem) {
 }
 function keystoreHoldsKey(p12Path, keyAlias, keyPwd, certificate) {
   try {
-    const der = forge.util.createBuffer(fs33.readFileSync(p12Path).toString("binary"));
+    const der = forge.util.createBuffer(fs34.readFileSync(p12Path).toString("binary"));
     const p12 = forge.pkcs12.pkcs12FromAsn1(forge.asn1.fromDer(der), keyPwd);
     const certBag = forge.pki.oids.certBag ?? "1.2.840.113549.1.12.10.1.3";
     const wanted = certificate.publicKey.export({ type: "spki", format: "der" });
@@ -4301,7 +5137,7 @@ function keystoreHoldsKey(p12Path, keyAlias, keyPwd, certificate) {
   }
 }
 function verifySigningMaterial(opts) {
-  const pems = fs33.readFileSync(opts.cerPath, "utf8").match(/-----BEGIN CERTIFICATE-----[\s\S]*?-----END CERTIFICATE-----/g);
+  const pems = fs34.readFileSync(opts.cerPath, "utf8").match(/-----BEGIN CERTIFICATE-----[\s\S]*?-----END CERTIFICATE-----/g);
   const chain = (pems ?? []).map(parseCertificate);
   const leaf = chain.find((c) => !c.ca) ?? chain.at(-1);
   if (!leaf) throw new AgcError(SIGNING_ERRORS.CERT_INVALID);
@@ -4320,14 +5156,14 @@ function verifySigningMaterial(opts) {
 
 // src/harmonyos/signing/autoSign.ts
 import * as crypto9 from "crypto";
-import * as fs38 from "fs";
-import * as path37 from "path";
+import * as fs39 from "fs";
+import * as path38 from "path";
 import JSON57 from "json5";
 
 // src/harmonyos/signing/agc.ts
 import * as crypto6 from "crypto";
-import * as fs34 from "fs";
-import * as path32 from "path";
+import * as fs35 from "fs";
+import * as path33 from "path";
 var ENDPOINTS = {
   CERT_LIST: "/api/cps/harmony-cert-manage/v1/cert/list",
   CERT_ADD: "/api/cps/harmony-cert-manage/v1/cert/add",
@@ -4413,8 +5249,8 @@ function createAgcClient(http3, auth) {
       if (target.sha256 && actual !== target.sha256.toLowerCase()) {
         throw new ChecksumMismatchError(target.sha256, actual);
       }
-      fs34.mkdirSync(path32.dirname(dest), { recursive: true, mode: 448 });
-      fs34.writeFileSync(dest, buffer, { mode: 384 });
+      fs35.mkdirSync(path33.dirname(dest), { recursive: true, mode: 448 });
+      fs35.writeFileSync(dest, buffer, { mode: 384 });
     }
   };
 }
@@ -4465,22 +5301,22 @@ async function registerDevices(agc, connected, logger) {
 
 // src/harmonyos/signing/keystore.ts
 import * as crypto7 from "crypto";
-import * as fs36 from "fs";
-import * as path34 from "path";
+import * as fs37 from "fs";
+import * as path35 from "path";
 
 // src/harmonyos/java.ts
-import * as fs35 from "fs";
-import * as path33 from "path";
+import * as fs36 from "fs";
+import * as path34 from "path";
 var JAVA_BIN = process.platform === "win32" ? "java.exe" : "java";
 function findJava(sdk, env = process.env) {
   const candidates = [
-    env.JAVA_HOME && path33.join(env.JAVA_HOME, "bin", JAVA_BIN),
-    sdk && path33.join(sdk.installRoot, "jbr", "bin", JAVA_BIN),
+    env.JAVA_HOME && path34.join(env.JAVA_HOME, "bin", JAVA_BIN),
+    sdk && path34.join(sdk.installRoot, "jbr", "bin", JAVA_BIN),
     // macOS: the JBR is itself a bundle inside Studio's Contents.
-    sdk && path33.join(sdk.installRoot, "jbr", "Contents", "Home", "bin", JAVA_BIN),
-    ...(env.PATH ?? "").split(path33.delimiter).map((dir) => dir && path33.join(dir, JAVA_BIN))
+    sdk && path34.join(sdk.installRoot, "jbr", "Contents", "Home", "bin", JAVA_BIN),
+    ...(env.PATH ?? "").split(path34.delimiter).map((dir) => dir && path34.join(dir, JAVA_BIN))
   ];
-  const found = candidates.find((c) => !!c && fs35.existsSync(c));
+  const found = candidates.find((c) => !!c && fs36.existsSync(c));
   if (found) return found;
   throw new OniroError(
     "No Java runtime found. HarmonyOS signing runs the SDK's hap-sign-tool.jar, which needs one: install a JDK and set JAVA_HOME, or install DevEco Studio, whose bundled runtime is used automatically."
@@ -4494,13 +5330,13 @@ function redactArgs(args) {
   return args.map((arg, i) => args[i - 1] === "-keyPwd" || args[i - 1] === "-keystorePwd" ? "******" : arg);
 }
 async function generateKeystoreAndCsr(opts) {
-  const jar = path34.join(opts.sdk.sdkPath, "default", "openharmony", "toolchains", "lib", "hap-sign-tool.jar");
-  if (!fs36.existsSync(jar)) {
+  const jar = path35.join(opts.sdk.sdkPath, "default", "openharmony", "toolchains", "lib", "hap-sign-tool.jar");
+  if (!fs37.existsSync(jar)) {
     throw new OniroError(`hap-sign-tool.jar not found at ${jar}; the HarmonyOS SDK looks incomplete.`);
   }
   const java = findJava(opts.sdk);
   const keyPwd = crypto7.randomBytes(12).toString("base64url").replaceAll(/[-_]/g, "");
-  fs36.mkdirSync(path34.dirname(opts.p12Path), { recursive: true, mode: 448 });
+  fs37.mkdirSync(path35.dirname(opts.p12Path), { recursive: true, mode: 448 });
   const run = async (what, args) => {
     const argv = ["-jar", jar, ...args, "-keyAlias", KEY_ALIAS, "-keystoreFile", opts.p12Path, "-keystorePwd", keyPwd, "-keyPwd", keyPwd];
     opts.logger.debug(`[harmonyos] ${java} ${redactArgs(argv).join(" ")}`);
@@ -4514,28 +5350,28 @@ ${detail}` : ""}`);
   opts.logger.info("[harmonyos] Generating the local keystore and certificate signing request...");
   await run("generate the key pair", ["generate-keypair", "-keyAlg", "ECC", "-keySize", "NIST-P-256"]);
   await run("generate the CSR", ["generate-csr", "-subject", "CN=DebugKey", "-signAlg", SIGN_ALG, "-outFile", opts.csrPath]);
-  return { keyPwd, csr: fs36.readFileSync(opts.csrPath, "utf8") };
+  return { keyPwd, csr: fs37.readFileSync(opts.csrPath, "utf8") };
 }
 
 // src/harmonyos/signing/paths.ts
 import * as crypto8 from "crypto";
-import * as path35 from "path";
+import * as path36 from "path";
 function sanitizeNamePart(raw) {
   const safe = (raw?.trim() ?? "").replace(/[\\/:*?"<>|=.-]+/g, "_");
   return safe.slice(0, 64) || "default";
 }
 function resolveSigningMaterialPaths(config, productName, projectRoot) {
   const hash = crypto8.createHash("sha256").update(projectRoot, "utf8").digest("base64url").replaceAll(/[-_]/g, "");
-  const base = path35.join(
+  const base = path36.join(
     config.get("harmonyosSigningDir", defaultPaths.harmonyosSigningDir()),
-    `${sanitizeNamePart(productName)}_${path35.basename(projectRoot)}_${hash}=`
+    `${sanitizeNamePart(productName)}_${path36.basename(projectRoot)}_${hash}=`
   );
   return { p12Path: `${base}.p12`, csrPath: `${base}.csr`, cerPath: `${base}.cer`, profilePath: `${base}.p7b` };
 }
 
 // src/harmonyos/signing/project.ts
-import * as fs37 from "fs";
-import * as path36 from "path";
+import * as fs38 from "fs";
+import * as path37 from "path";
 import JSON56 from "json5";
 
 // src/harmonyos/signing/aclPermissionList.ts
@@ -4603,9 +5439,9 @@ var ACL_PERMISSIONS = /* @__PURE__ */ new Set([
 
 // src/harmonyos/signing/project.ts
 function readRequestedPermissions(moduleConfigPath) {
-  if (!fs37.existsSync(moduleConfigPath)) return [];
+  if (!fs38.existsSync(moduleConfigPath)) return [];
   try {
-    const parsed = JSON56.parse(fs37.readFileSync(moduleConfigPath, "utf-8"));
+    const parsed = JSON56.parse(fs38.readFileSync(moduleConfigPath, "utf-8"));
     return (parsed.module?.requestPermissions ?? []).map((p) => p?.name).filter((n) => typeof n === "string" && n.length > 0);
   } catch {
     return [];
@@ -4614,10 +5450,10 @@ function readRequestedPermissions(moduleConfigPath) {
 function collectAclPermissions(projectDir, logger = noopLogger) {
   const requested = /* @__PURE__ */ new Set();
   for (const module of listModules({ projectDir })) {
-    const moduleRoot = path36.resolve(projectDir, module.srcPath);
+    const moduleRoot = path37.resolve(projectDir, module.srcPath);
     for (const sourceSet of ["main", "ohosTest"]) {
       for (const name of readRequestedPermissions(
-        path36.join(moduleRoot, "src", sourceSet, "module.json5")
+        path37.join(moduleRoot, "src", sourceSet, "module.json5")
       )) {
         requested.add(name);
       }
@@ -4633,7 +5469,7 @@ function collectAclPermissions(projectDir, logger = noopLogger) {
 // src/harmonyos/signing/autoSign.ts
 function shouldRegenerate(input) {
   if (input.force) return "--force was passed";
-  const missing = Object.values(input.paths).find((file) => !fs38.existsSync(file));
+  const missing = Object.values(input.paths).find((file) => !fs39.existsSync(file));
   if (missing) return `${missing} is missing`;
   const config = input.buildProfile.app?.signingConfigs?.find((c) => c.name === input.productName);
   if (config?.type !== "HarmonyOS" || config.material?.profile !== input.paths.profilePath) {
@@ -4672,16 +5508,16 @@ function writeSigningConfig(opts) {
   for (const product of app.products ?? []) {
     if (product.name === opts.productName) product.signingConfig = opts.productName;
   }
-  fs38.writeFileSync(opts.buildProfilePath, JSON.stringify(opts.buildProfile, null, 2));
+  fs39.writeFileSync(opts.buildProfilePath, JSON.stringify(opts.buildProfile, null, 2));
 }
 async function harmonyOsAutoSign(opts) {
   const logger = opts.logger ?? noopLogger;
   const productName = opts.productName ?? "default";
-  const projectDir = path37.resolve(opts.projectDir);
-  const buildProfilePath = path37.join(projectDir, "build-profile.json5");
+  const projectDir = path38.resolve(opts.projectDir);
+  const buildProfilePath = path38.join(projectDir, "build-profile.json5");
   let buildProfile;
   try {
-    buildProfile = JSON57.parse(fs38.readFileSync(buildProfilePath, "utf-8"));
+    buildProfile = JSON57.parse(fs39.readFileSync(buildProfilePath, "utf-8"));
   } catch (err) {
     throw new OniroError(`Could not read ${buildProfilePath}: ${err.message}`, err);
   }
@@ -4721,7 +5557,7 @@ async function harmonyOsAutoSign(opts) {
   logger.info(`[harmonyos] Regenerating signing material: ${reason}.`);
   const agc = createAgcClient(opts.http ?? createHttpClient({ logger }), auth);
   const deviceIds = await registerDevices(agc, connected, logger);
-  for (const file of Object.values(paths)) fs38.rmSync(file, { force: true });
+  for (const file of Object.values(paths)) fs39.rmSync(file, { force: true });
   const certName = `oniro_debug_${auth.teamId.replace(/[\\/.:]/g, "")}.cer`;
   const stale = (await agc.listCertificates()).find((c) => c.certName === certName);
   if (stale) {
@@ -4752,10 +5588,10 @@ async function harmonyOsAutoSign(opts) {
   try {
     verifySigningMaterial({ ...paths, keyAlias: KEY_ALIAS, keyPwd });
   } catch (err) {
-    fs38.rmSync(paths.profilePath, { force: true });
+    fs39.rmSync(paths.profilePath, { force: true });
     throw err;
   }
-  const materialDir = path37.join(path37.dirname(paths.p12Path), "material");
+  const materialDir = path38.join(path38.dirname(paths.p12Path), "material");
   try {
     getKey(materialDir);
   } catch {
@@ -4767,7 +5603,7 @@ async function harmonyOsAutoSign(opts) {
 }
 
 // src/index.ts
-var VERSION = "0.12.0";
+var VERSION = "0.14.0";
 export {
   ALL_SDKS,
   APL_VALUES,
@@ -4786,9 +5622,13 @@ export {
   SIGNING_ERRORS,
   SdkNotInstalledError,
   TMP_DIR_HINT,
+  TargetNotFoundError,
   UnsupportedPlatformError,
   VERSION,
+  appSandboxDir,
   applyChanges,
+  assertDevicePath,
+  assertLayoutSelector,
   attemptHdcConnection,
   buildCmdWrapper,
   buildGestureCommands,
@@ -4798,6 +5638,8 @@ export {
   buildInputCommand,
   buildRawTouchCommand,
   captureBurst,
+  captureLog,
+  cleanCodelinterOutput,
   consoleLogger,
   createHarmonyOsSession,
   createInstallTempDir,
@@ -4811,10 +5653,14 @@ export {
   dedupEntries,
   defaultContext,
   defaultPaths,
+  describeLayoutNode,
   detectAaStartFailure,
+  detectCmdToolsFlavour,
+  detectInstallFailure,
   detectProjectSdkVersion,
   detectRuntimeOs,
   detectSigningConfigNames,
+  diagnoseBuildFailure,
   diffEntryNames,
   diffHapAssets,
   discoverHaps,
@@ -4827,17 +5673,24 @@ export {
   dumpWindow,
   encryptPwd,
   ensureFreeSpace,
+  ensureInstallOk,
   ensureOhModules,
   ensureOk,
   ensureRemoteOk,
   escapeCmdArgument,
   escapeCmdCommand,
+  existingHapOrUnsigned,
   extractTarball,
   extractZipWithProgress,
   findAppProcessId,
   findCmdToolsSourceDir,
+  findCoveredNodes,
   findHarmonyOsSdk,
+  findKeyboardWindow,
+  findLayoutNodes,
+  findMissingProjectSdk,
   findRunningProcess,
+  flattenLayout,
   forceStop,
   formatBytes,
   generateSigningConfigs,
@@ -4849,9 +5702,11 @@ export {
   getDeviceInfo,
   getDisplaySize,
   getEmulatorDir,
+  getEmulatorStatus,
   getFreeSpaceBytes,
   getHdcPath,
   getHvigorwPath,
+  getImeBundles,
   getInstalledSdks,
   getKey,
   getMainAbility,
@@ -4863,14 +5718,21 @@ export {
   getSupportedSdksForUi,
   harmonyOsAutoSign,
   harmonyOsSdkLabelForApi,
+  hdcClientFailure,
   hdcExec,
+  hdcTargetArgs,
+  hdcTargetArgsFor,
+  hideKeyboard,
   installApp,
   installCmdTools,
   installEmulator,
+  installFailureReason,
+  isBundleInstalled,
   isCmdToolsInstalled,
   isEmulatorInstalled,
   isOutOfSpaceError,
   isRamBackedPath,
+  isUnsignedHap,
   isValidBundleName,
   isValidProjectName,
   killProcessTree,
@@ -4880,19 +5742,28 @@ export {
   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,
@@ -4905,6 +5776,8 @@ export {
   removeSdk,
   removeTempWorkDir,
   requireHarmonyOsSdk,
+  resolveDeviceSerial,
+  resolveKeyEvent,
   resolveTmpRoot,
   runCodelinter,
   runHvigorw,
@@ -4928,14 +5801,17 @@ export {
   toLongPath,
   toSpaceError,
   uninstallApp,
+  unsignedHapRejection,
   validateTemplateLayout,
   verifySha256,
   waitForBoot,
   waitForBundle,
   waitForCondition,
   waitForLog,
+  waitForTarget,
   watchLog,
   waypointsToRawEvents,
+  withoutWindow,
   writeJson5File,
   writeJsonFile
 };