@oniroproject/oniro-app 0.12.0 → 0.14.0

package/dist/oniro-app.js

@@ -175,7 +175,9 @@ function registerCmdToolsCommand(program) {
     await installCmdTools({ config, progress, logger, localZipPath: opts.fromZip, tmpDir: opts.tmpDir });
     logger.info("Command-line tools installed.");
   });
-  cmdtools.command("status").description("Report whether the command-line tools are installed and their version.").option("--json", "Emit machine-readable JSON.").action((opts) => {
+  cmdtools.command("status").description(
+    "Report whether the command-line tools are installed, their version and flavour (HarmonyOS or OpenHarmony), and the hdc binary every device command uses."
+  ).option("--json", "Emit machine-readable JSON.").action((opts) => {
     const { config } = getRuntime();
     const status = getCmdToolsStatus(config);
     if (opts.json) {
@@ -184,6 +186,12 @@ function registerCmdToolsCommand(program) {
       return;
     }
     process.stdout.write(`${status.status}
+`);
+    process.stdout.write(`path:    ${status.path}
+`);
+    if (status.flavour) process.stdout.write(`flavour: ${status.flavour}
+`);
+    process.stdout.write(`hdc:     ${status.hdc.path}${status.hdc.exists ? "" : " (missing)"}
 `);
     if (!status.installed) process.exit(1);
   });
@@ -197,6 +205,7 @@ function registerCmdToolsCommand(program) {
 // src/commands/emulator.ts
 import {
   attemptHdcConnection,
+  getEmulatorStatus,
   installEmulator,
   isEmulatorInstalled,
   removeEmulator,
@@ -230,6 +239,24 @@ function registerEmulatorCommand(program) {
     });
     logger.info("Emulator start command complete.");
   });
+  emu.command("status").description(
+    "Report whether the Oniro emulator is installed, running, and connected to hdc, without starting it. Exits 1 when it is not installed."
+  ).option("--address <addr>", "hdc address the emulator listens on", "127.0.0.1:55555").option("--json", "Emit machine-readable JSON.").action(async (opts) => {
+    const { config, logger } = getRuntime();
+    const status = await getEmulatorStatus(config, { address: opts.address, logger });
+    if (opts.json) {
+      process.stdout.write(`${JSON.stringify(status, null, 2)}
+`);
+    } else {
+      process.stdout.write(
+        `installed: ${status.installed ? "yes" : "no"} (${status.dir})
+running:   ${status.running ? "yes" : "no"}
+connected: ${status.connected ? "yes" : "no"} (${status.address})
+`
+      );
+    }
+    if (!status.installed) process.exitCode = 1;
+  });
   emu.command("stop").description("Kill running emulator processes.").action(async () => {
     const { logger } = getRuntime();
     await stopEmulator(logger);
@@ -253,15 +280,15 @@ function registerEmulatorCommand(program) {
 
 // src/commands/build.ts
 import * as path2 from "path";
-import { buildHap } from "@oniroproject/core";
+import { SdkNotInstalledError, buildHap, downloadAndInstallSdk as downloadAndInstallSdk2 } from "@oniroproject/core";
 function registerBuildCommand(program) {
   program.command("build [project-dir]").description(
-    'Build an OpenHarmony or HarmonyOS app via hvigorw. Defaults to the current directory. Projects declaring runtimeOS "HarmonyOS" build against the HarmonyOS SDK (ONIRO_HARMONYOS_SDK_PATH or an installed DevEco Studio).'
-  ).option("--product <product>", "hvigor product name", "default").option("--module <module>", "restrict the build to a specific module").option("--mode <mode>", "hvigor build mode (e.g. release, debug)").option("--task <task>", "hvigor task to run", "assembleHap").option("--no-deps", "skip the automatic `ohpm install --all` when oh_modules/ is missing").option("--no-parallel", "build modules serially (default: parallel)").option("--json", "emit the build result (discovered HAPs, warnings) as JSON").action(async (projectDir, opts) => {
-    const { config, logger } = getRuntime();
+    'Build an OpenHarmony or HarmonyOS app via hvigorw. Defaults to the current directory. Projects declaring runtimeOS "HarmonyOS" build against the HarmonyOS SDK (ONIRO_HARMONYOS_SDK_PATH or an installed DevEco Studio). An OpenHarmony project fails early, naming the release to install, when the SDK for its compileSdkVersion is missing.'
+  ).option("--product <product>", "hvigor product name", "default").option("--module <module>", "restrict the build to a specific module").option("--mode <mode>", "hvigor build mode (e.g. release, debug)").option("--task <task>", "hvigor task to run", "assembleHap").option("--no-deps", "skip the automatic `ohpm install --all` when oh_modules/ is missing").option("--no-parallel", "build modules serially (default: parallel)").option("--install-sdk", "install the OpenHarmony SDK the project compiles against when it is missing, then build").option("--json", "emit the build result (discovered HAPs, warnings) as JSON").action(async (projectDir, opts) => {
+    const { config, logger, progress } = getRuntime();
     const dir = path2.resolve(projectDir ?? process.cwd());
     logger.info(`Building project at ${dir}...`);
-    const result = await buildHap({
+    const build = () => buildHap({
       config,
       projectDir: dir,
       product: opts.product,
@@ -275,6 +302,15 @@ function registerBuildCommand(program) {
       onOutput: () => {
       }
     });
+    let result;
+    try {
+      result = await build();
+    } catch (err) {
+      if (!(err instanceof SdkNotInstalledError && err.version && opts.installSdk)) throw err;
+      logger.info(`Installing OpenHarmony SDK ${err.version} (api ${err.api}), which the project compiles against...`);
+      await downloadAndInstallSdk2({ config, version: err.version, api: err.api, progress, logger });
+      result = await build();
+    }
     for (const w of result.warnings) logger.warn(w);
     if (opts.json) {
       process.stdout.write(`${JSON.stringify(result, null, 2)}
@@ -326,6 +362,11 @@ function registerSignCommand(program) {
       "--acls <list>",
       "Comma-separated permission names to write into the profile's acls.allowed-acls. Required for apps that request permissions above their apl (e.g. a system_basic app requesting ohos.permission.CAPTURE_SCREEN). Example: --acls ohos.permission.REBOOT,ohos.permission.INJECT_INPUT_EVENT"
     ).argParser(parseAclsList)
+  ).addOption(
+    new Option(
+      "--app-privilege-capabilities <list>",
+      `Comma-separated privileges to write into the profile's app-privilege-capabilities. An app that declares a privileged extension ability (e.g. an AccessibilityExtensionAbility) needs AllowAppUsePrivilegeExtension, else install fails with 9568344 "not allow use privilege extension". Others include AllowAppMultiProcess and AllowAppDesktopIconHide.`
+    ).argParser(parseAclsList)
   ).option(
     "--harmonyos",
     "Sign a HarmonyOS project through AppGallery Connect. Needs `oniro-app auth login`, and a connected device unless the team already has devices registered."
@@ -359,6 +400,7 @@ function registerSignCommand(program) {
           apl: opts.apl,
           appFeature: opts.appFeature,
           acls: opts.acls,
+          appPrivilegeCapabilities: opts.appPrivilegeCapabilities,
           passwords,
           logger
         });
@@ -373,6 +415,7 @@ function registerSignCommand(program) {
         apl: opts.apl,
         appFeature: opts.appFeature,
         acls: opts.acls,
+        appPrivilegeCapabilities: opts.appPrivilegeCapabilities,
         passwords,
         logger
       });
@@ -448,12 +491,16 @@ import * as path4 from "path";
 import { installApp, launchApp, uninstallApp, forceStop, applyChanges, getBundleName } from "@oniroproject/core";
 function registerAppCommand(program) {
   const app = program.command("app").description("Install, launch, and manage built apps on a connected device/emulator.");
-  app.command("install [project-dir]").description("Install the signed .hap on the connected device/emulator via hdc.").option("--hap <path>", "Override the .hap path (relative to project-dir or absolute).").option("--device <serial>", "Target device serial.").action(async (projectDir, opts) => {
+  app.command("install [project-dir-or-hap]").description(
+    "Install a built .hap on the connected device/emulator via hdc. Takes a project dir (default: the current one), whose newest signed HAP is installed, else its unsigned one, or a .hap file. Fails when the bundle manager rejects the HAP, and says how to sign when a target refuses an unsigned one."
+  ).option("--hap <path>", "Override the .hap path (relative to project-dir or absolute).").option("--device <serial>", "Target device serial.").action(async (target, opts) => {
     const { config, logger } = getRuntime();
-    const dir = path4.resolve(projectDir ?? process.cwd());
-    logger.info(`Installing app from ${dir}...`);
-    await installApp({ config, projectDir: dir, hapPath: opts.hap, deviceSerial: opts.device, logger });
-    logger.info("App installed.");
+    const isHap = target !== void 0 && /\.hap$/i.test(target);
+    const dir = isHap ? process.cwd() : path4.resolve(target ?? process.cwd());
+    const hapPath = isHap ? path4.resolve(target) : opts.hap;
+    logger.info(`Installing ${hapPath ?? `app from ${dir}`}...`);
+    const result = await installApp({ config, projectDir: dir, hapPath, deviceSerial: opts.device, logger });
+    logger.info(`Installed ${result.hapPath}.`);
   });
   app.command("launch [project-dir]").description(
     "Launch an app on the connected device/emulator. Project mode (default): resolves bundle + main ability from the project. Bundle mode (--bundle): launch an already-installed app by bundle name, no project needed."
@@ -614,11 +661,40 @@ function registerRebootCommand(program) {
 }
 
 // src/commands/wait.ts
-import { waitForLog, waitForBoot, waitForBundle } from "@oniroproject/core";
+import { waitForLog, waitForBoot, waitForBundle, waitForTarget, describeLayoutNode } from "@oniroproject/core";
+
+// src/lib/target.ts
+function addTargetOptions(cmd, verb, opts = {}) {
+  cmd.option(
+    "--target <text>",
+    `${verb} the element whose text, description, or placeholder matches (case-insensitive; exact matches win, else substring). Covered elements are skipped.`
+  ).option("--target-id <id>", "Match the element by its id or key.").option("--target-type <type>", "Restrict the match to a component type (e.g. Button, TextInput).");
+  if (opts.index !== false) {
+    cmd.option("--target-index <n>", "Pick the n-th (0-based) of several matching elements.");
+  }
+  return cmd;
+}
+function selectorFrom(opts) {
+  if (opts.target === void 0 && opts.targetId === void 0 && opts.targetType === void 0) return void 0;
+  return { text: opts.target, id: opts.targetId, type: opts.targetType };
+}
+function targetIndexFrom(opts) {
+  if (opts.targetIndex === void 0) return void 0;
+  const n = Number(opts.targetIndex);
+  if (!Number.isInteger(n) || n < 0) throw new Error(`--target-index must be a non-negative integer; got ${opts.targetIndex}.`);
+  return n;
+}
+
+// src/commands/wait.ts
 function registerWaitCommand(program) {
-  program.command("wait").description("Wait for a device condition: a log line (--log), boot (--boot), or a bundle to start (--bundle).").option("--log <pattern>", "Resolve when a hilog line (tag: message) matches this regex.").option("--boot", "Resolve when the device is reachable (optionally also --pid-of).").option("--bundle <bundle>", "With --log: filter to this bundle. Alone: wait until this bundle is running.").option("--pid-of <name>", "With --boot: also require this process to have a pid.").option("--domain <domain>", "With --log: hilog domain filter (e.g. 0xD003900).").option("--timeout <ms>", "Max wait, ms.", "30000").option("--device <serial>", "Target device serial.").option("--json", "With --log: emit the matched entry as JSON.").action(async (opts) => {
+  const wait = program.command("wait").description(
+    "Wait for a device condition: a log line (--log), boot (--boot), a bundle to start (--bundle), or an on-screen element (--target / --target-id / --target-type)."
+  ).option("--log <pattern>", "Resolve when a hilog line (tag: message) matches this regex.").option("--boot", "Resolve when the device is reachable (optionally also --pid-of).").option("--bundle <bundle>", "With --log: filter to this bundle. Alone: wait until this bundle is running.").option("--pid-of <name>", "With --boot: also require this process to have a pid.").option("--domain <domain>", "With --log: hilog domain filter (e.g. 0xD003900).");
+  addTargetOptions(wait, "Resolve when", { index: false });
+  wait.option("--gone", "With --target*: resolve when no uncovered element matches any more.").option("--interval <ms>", "With --target*: poll interval, ms (each poll is a layout dump).", "500").option("--timeout <ms>", "Max wait, ms.", "30000").option("--device <serial>", "Target device serial.").option("--json", "With --log or --target*: emit the matched entry/element as JSON.").action(async (opts) => {
     const { config, logger } = getRuntime();
     const timeoutMs = Number(opts.timeout);
+    const selector = selectorFrom(opts);
     if (opts.log) {
       const entry = await waitForLog({
         config,
@@ -639,12 +715,31 @@ function registerWaitCommand(program) {
       logger.info("Device booted.");
       return;
     }
+    if (selector) {
+      const node = await waitForTarget({
+        config,
+        selector,
+        gone: opts.gone,
+        timeoutMs,
+        pollMs: Number(opts.interval) || 500,
+        deviceSerial: opts.device,
+        logger
+      });
+      if (!node) {
+        logger.info("Element is gone.");
+        return;
+      }
+      if (opts.json) process.stdout.write(`${JSON.stringify(node, null, 2)}
+`);
+      else logger.info(`found: ${describeLayoutNode(node)}`);
+      return;
+    }
     if (opts.bundle) {
       await waitForBundle({ config, bundle: opts.bundle, timeoutMs, deviceSerial: opts.device, logger });
       logger.info(`Bundle ${opts.bundle} is running.`);
       return;
     }
-    throw new Error("Specify one of --log <pattern>, --boot, or --bundle <bundle>.");
+    throw new Error("Specify one of --log <pattern>, --boot, --bundle <bundle>, or --target <text> (or --target-id / --target-type).");
   });
 }
 
@@ -677,7 +772,7 @@ function registerWatchCommand(program) {
 // src/commands/screenshot.ts
 import * as fs3 from "fs";
 import * as path7 from "path";
-import { takeScreenshot, captureBurst } from "@oniroproject/core";
+import { takeScreenshot, captureBurst, locateTarget, describeLayoutNode as describeLayoutNode2 } from "@oniroproject/core";
 
 // src/lib/screenshotImage.ts
 import sharp from "sharp";
@@ -732,6 +827,32 @@ async function renderWithGrid(jpeg, opts) {
   const buf = await sharp(resized).composite([{ input: Buffer.from(svg) }]).jpeg({ quality: 80 }).toBuffer();
   return { buf, width, height, originalWidth, originalHeight };
 }
+function parseCropRect(spec) {
+  const parts = spec.split(",").map((s) => Number(s.trim()));
+  if (parts.length !== 4 || parts.some((n) => !Number.isFinite(n) || n < 0 || n > 1)) {
+    throw new Error(`--crop expects four 0-1 fractions "x1,y1,x2,y2"; got "${spec}".`);
+  }
+  const [x1, y1, x2, y2] = parts;
+  if (!(x2 > x1 && y2 > y1)) throw new Error(`--crop needs x1 < x2 and y1 < y2; got "${spec}".`);
+  return [x1, y1, x2, y2];
+}
+function padCropRect(r, pad) {
+  return [Math.max(0, r[0] - pad), Math.max(0, r[1] - pad), Math.min(1, r[2] + pad), Math.min(1, r[3] + pad)];
+}
+async function cropImage(jpeg, rect, opts) {
+  const meta = await sharp(jpeg).metadata();
+  const w = meta.width ?? 1;
+  const h = meta.height ?? 1;
+  const left = Math.min(w - 1, Math.floor(rect[0] * w));
+  const top = Math.min(h - 1, Math.floor(rect[1] * h));
+  const cropWidth = Math.max(1, Math.min(w, Math.ceil(rect[2] * w)) - left);
+  const cropHeight = Math.max(1, Math.min(h, Math.ceil(rect[3] * h)) - top);
+  const scale = Math.min(1, opts.maxDim / Math.max(cropWidth, cropHeight));
+  const width = Math.max(1, Math.round(cropWidth * scale));
+  const height = Math.max(1, Math.round(cropHeight * scale));
+  const buf = await sharp(jpeg).extract({ left, top, width: cropWidth, height: cropHeight }).resize(width, height).jpeg({ quality: 85 }).toBuffer();
+  return { buf, width, height, left, top, cropWidth, cropHeight };
+}
 function buildTileLabelSvg(width, height, idx, diff) {
   const fontSize = Math.max(12, Math.round(Math.min(width, height) / 16));
   const pad = Math.round(fontSize * 0.4);
@@ -796,18 +917,53 @@ async function frameDiffs(frames, opts = {}) {
 
 // src/commands/screenshot.ts
 var DEFAULT_CONTACT_SHEET_FRAMES = 8;
+var TARGET_CROP_PAD = 0.02;
 function clampMaxDim(raw) {
   const n = Number(raw);
   if (!Number.isFinite(n)) return 1024;
   return Math.max(256, Math.min(4096, Math.round(n)));
 }
 function registerScreenshotCommand(program) {
-  program.command("screenshot").description(
-    "Capture the screen. Default: full-resolution raw JPEG. --grid: downscaled JPEG with a 10x10 grid (axes 0.0-1.0) for picking tap coordinates. --contact-sheet: capture a burst and tile it into one image with per-frame change diffs."
-  ).option("-o, --output <file>", "Output file path.", "screenshot.jpeg").option("--grid", "Downscale (to --max-dim) and overlay a 10x10 coordinate grid.").option("--max-dim <px>", "Longest-side cap for --grid / --contact-sheet (256-4096).", "1024").option("--contact-sheet", "Capture a burst and composite it into one tiled contact sheet.").option("--burst <count>", "Capture N frames; writes <base>-<i><ext> (or feeds --contact-sheet).").option("--interval <ms>", "Delay between burst frames, ms.", "50").option("--json", "Emit the full result object as JSON on stdout (with --contact-sheet).").option("--device <serial>", "Target device serial.").action(async (opts, command) => {
+  const screenshot = program.command("screenshot").description(
+    "Capture the screen. Default: full-resolution raw JPEG. --grid: downscaled JPEG with a 10x10 grid (axes 0.0-1.0) for picking tap coordinates. --crop / --target: a full-resolution crop of one region or element, for checking detail cheaply. --contact-sheet: capture a burst and tile it into one image with per-frame change diffs."
+  ).option("-o, --output <file>", "Output file path.", "screenshot.jpeg").option("--grid", "Downscale (to --max-dim) and overlay a 10x10 coordinate grid.").option("--max-dim <px>", "Longest-side cap for --grid / --crop / --target / --contact-sheet (256-4096).", "1024").option("--crop <x1,y1,x2,y2>", "Crop to this region, given as 0-1 fractions of the screen.");
+  addTargetOptions(screenshot, "Crop to");
+  screenshot.option("--contact-sheet", "Capture a burst and composite it into one tiled contact sheet.").option("--burst <count>", "Capture N frames; writes <base>-<i><ext> (or feeds --contact-sheet).").option("--interval <ms>", "Delay between burst frames, ms.", "50").option("--json", "Emit the full result object as JSON on stdout (with --contact-sheet).").option("--device <serial>", "Target device serial.").action(async (opts, command) => {
     const { config, logger } = getRuntime();
     const maxDim = clampMaxDim(opts.maxDim);
     const intervalMs = Number(opts.interval) || 50;
+    const selector = selectorFrom(opts);
+    if (opts.crop !== void 0 || selector) {
+      if (opts.crop !== void 0 && selector) throw new Error("Use either --crop or --target*, not both.");
+      if (opts.grid || opts.contactSheet || opts.burst) {
+        throw new Error("--crop / --target cannot be combined with --grid, --contact-sheet, or --burst.");
+      }
+      let rect;
+      let label;
+      if (selector) {
+        const located = await locateTarget({
+          config,
+          selector,
+          index: targetIndexFrom(opts),
+          hideKeyboard: false,
+          deviceSerial: opts.device,
+          logger
+        });
+        if (!located.node.b) throw new Error(`${describeLayoutNode2(located.node)} has no bounds to crop to.`);
+        rect = padCropRect(located.node.b, TARGET_CROP_PAD);
+        label = describeLayoutNode2(located.node);
+      } else {
+        rect = parseCropRect(opts.crop);
+        label = rect.map((n) => n.toFixed(3)).join(",");
+      }
+      const shot2 = await takeScreenshot({ config, deviceSerial: opts.device, logger });
+      const cropped = await cropImage(shot2.pixels, rect, { maxDim });
+      fs3.writeFileSync(opts.output, cropped.buf);
+      logger.info(
+        `Wrote ${opts.output} (${cropped.width}x${cropped.height} from a ${cropped.cropWidth}x${cropped.cropHeight} crop at ${cropped.left},${cropped.top}: ${label}).`
+      );
+      return;
+    }
     if (opts.contactSheet) {
       const count = opts.burst ? Math.max(1, Number(opts.burst)) : DEFAULT_CONTACT_SHEET_FRAMES;
       const frames = await captureBurst({ config, count, intervalMs, deviceSerial: opts.device, logger });
@@ -879,31 +1035,125 @@ function registerScreenshotCommand(program) {
 
 // src/commands/dump.ts
 import { dumpLayout } from "@oniroproject/core";
+
+// src/lib/layoutText.ts
+import { flattenLayout } from "@oniroproject/core";
+var MAX_TEXT = 80;
+function quote(s) {
+  return JSON.stringify(s.length > MAX_TEXT ? `${s.slice(0, MAX_TEXT - 1)}\u2026` : s);
+}
+function flags(n) {
+  const out = [];
+  if (n.click) out.push("click");
+  if (n.longClick) out.push("longClick");
+  if (n.scroll) out.push("scroll");
+  if (n.checked) out.push("checked");
+  else if (n.check) out.push("checkable");
+  if (n.sel) out.push("selected");
+  if (n.focus) out.push("focus");
+  if (n.disabled) out.push("disabled");
+  if (n.covered) out.push("covered");
+  return out;
+}
+function formatLayoutLine(n) {
+  const parts = [n.type ?? "node"];
+  if (n.text !== void 0) parts.push(quote(n.text));
+  if (n.desc !== void 0) parts.push(`desc=${quote(n.desc)}`);
+  if (n.hint !== void 0) parts.push(`hint=${quote(n.hint)}`);
+  if (n.id !== void 0) parts.push(`#${n.id}`);
+  if (n.key !== void 0) parts.push(`key=${n.key}`);
+  if (n.c) parts.push(`c=${n.c[0].toFixed(3)},${n.c[1].toFixed(3)}`);
+  parts.push(...flags(n));
+  return parts.join(" ");
+}
+function isListed(n) {
+  const labelled = n.text !== void 0 || n.desc !== void 0 || n.hint !== void 0;
+  return labelled || !!(n.click || n.longClick || n.scroll || n.check || n.focus);
+}
+function formatFlatLayout(result) {
+  const lines = [];
+  const d = result.display;
+  lines.push(
+    `# display ${d ? `${d.width}x${d.height}` : "unknown"}; c = element center as 0-1 fractions (input --fx/--fy), or act by label with input --target "<text>"`
+  );
+  const keyboardBundle = result.keyboard?.shown ? result.keyboard.bundle : void 0;
+  let window;
+  for (const n of flattenLayout(result.tree)) {
+    if (n.window !== window) {
+      window = n.window;
+      if (window !== void 0 && window === keyboardBundle) {
+        lines.push(`[keyboard ${window}] up \u2014 dismiss with input --type hideKeyboard`);
+      } else if (window !== void 0) {
+        lines.push(`[window ${window}]`);
+      }
+    }
+    if (window !== void 0 && window === keyboardBundle) continue;
+    if (n.bundle !== void 0 && n.text === void 0 && !n.click) continue;
+    if (isListed(n)) lines.push(formatLayoutLine(n));
+  }
+  return `${lines.join("\n")}
+`;
+}
+
+// src/commands/dump.ts
 function registerDumpCommand(program) {
-  program.command("dump [target]").description("Dump device state as JSON. Currently supports `dump layout` (the default target).").option("--bundle <bundle>", "Filter the layout to a single window/bundle.").option("--raw", "Return the unpruned layout tree.").option("--device <serial>", "Target device serial.").action(async (target, opts) => {
+  program.command("dump [target]").description(
+    "Dump device state. Currently supports `dump layout` (the default target): JSON by default, or one line per element with --flat."
+  ).option("--bundle <bundle>", "Filter the layout to a single window/bundle.").option("--raw", "Return the unpruned layout tree.").option("--flat", "One line per element (type, label, center as 0-1 fractions, flags) instead of a JSON tree.").option("--device <serial>", "Target device serial.").action(async (target, opts) => {
     const { config, logger } = getRuntime();
     const what = target ?? "layout";
     if (what !== "layout") throw new Error(`Unknown dump target "${what}". Supported: layout.`);
+    if (opts.raw && opts.flat) throw new Error("--raw and --flat cannot be combined.");
     const result = await dumpLayout({
       config,
       bundleName: opts.bundle,
       prune: !opts.raw,
+      detectKeyboard: !opts.raw,
       deviceSerial: opts.device,
       logger
     });
-    process.stdout.write(`${JSON.stringify(result, null, 2)}
+    process.stdout.write(opts.flat ? formatFlatLayout(result) : `${JSON.stringify(result, null, 2)}
 `);
   });
 }
 
 // src/commands/devices.ts
-import { listDevices } from "@oniroproject/core";
+import { getDeviceInfo, listDevices } from "@oniroproject/core";
+function formatLongDevice(d, info) {
+  const head = `${d.serial}	${d.connection ?? ""}	${d.status}`;
+  if (!info) return head;
+  const os2 = [info.osFamily, info.osFamily === "HarmonyOS" ? info.osDistVersion : void 0].filter(Boolean).join(" ");
+  const fields = [
+    ["os", os2 || void 0],
+    ["api", info.sdkApiVersion],
+    ["abi", info.abi],
+    ["type", info.deviceType],
+    ["model", info.model],
+    ["fullname", info.osFullName]
+  ];
+  const rest = fields.filter(([, v]) => v).map(([k, v]) => `${k}=${/\s/.test(v) ? JSON.stringify(v) : v}`);
+  return [head, ...rest].join("	");
+}
 function registerDevicesCommand(program) {
-  program.command("devices").description("List connected hdc devices.").option("--json", "Emit machine-readable JSON.").action(async (opts) => {
-    const { config } = getRuntime();
+  program.command("devices").description("List connected hdc devices.").option(
+    "--long",
+    "Also ask each connected device for its OS family (HarmonyOS / OpenHarmony), version, API level, CPU ABI, device type and model."
+  ).option("--json", "Emit machine-readable JSON.").action(async (opts) => {
+    const { config, logger } = getRuntime();
     const devices = await listDevices(config);
+    const infos = /* @__PURE__ */ new Map();
+    if (opts.long) {
+      for (const d of devices.filter((x) => x.status === "Connected")) {
+        try {
+          infos.set(d.serial, await getDeviceInfo({ config, deviceSerial: d.serial, logger }));
+        } catch (err) {
+          logger.warn(`Could not query ${d.serial}: ${err.message}`);
+        }
+      }
+    }
     if (opts.json) {
-      process.stdout.write(`${JSON.stringify(devices, null, 2)}
+      const out = opts.long ? devices.map((d) => ({ ...d, info: infos.get(d.serial) ?? null })) : devices;
+      process.stdout.write(`${JSON.stringify(out, null, 2)}
 `);
       return;
     }
@@ -912,7 +1162,7 @@ function registerDevicesCommand(program) {
       return;
     }
     for (const d of devices) {
-      process.stdout.write(`${d.serial}	${d.connection ?? ""}	${d.status}
+      process.stdout.write(`${opts.long ? formatLongDevice(d, infos.get(d.serial)) : `${d.serial}	${d.connection ?? ""}	${d.status}`}
 `);
     }
   });
@@ -922,10 +1172,14 @@ function registerDevicesCommand(program) {
 import { sendFile, recvFile } from "@oniroproject/core";
 function registerFileCommand(program) {
   const file = program.command("file").description("Transfer files to/from the device (hdc file send/recv).");
-  file.command("send <local> <remote>").description("Push a local file to the device.").option("--device <serial>", "Target device serial.").action(async (local, remote, opts) => {
+  file.command("send <local> <remote>").description(
+    "Push a local file to the device. With --bundle, <remote> may be relative to that app's sandbox (files/x is its filesDir, haps/entry/files/x the entry module's), and the file is chowned to the app so it can read it. Prints the device path."
+  ).option("--bundle <bundle>", "Push into this app's sandbox and give the file to the app's user.").option("--device <serial>", "Target device serial.").action(async (local, remote, opts) => {
     const { config, logger } = getRuntime();
-    await sendFile({ config, local, remote, deviceSerial: opts.device, logger });
-    logger.info(`Sent ${local} -> ${remote}.`);
+    const written = await sendFile({ config, local, remote, bundle: opts.bundle, deviceSerial: opts.device, logger });
+    logger.info(`Sent ${local} -> ${written}${opts.bundle ? ` (owned by ${opts.bundle})` : ""}.`);
+    process.stdout.write(`${written}
+`);
   });
   file.command("recv <remote> <local>").description("Pull a file from the device.").option("--device <serial>", "Target device serial.").action(async (remote, local, opts) => {
     const { config, logger } = getRuntime();
@@ -936,37 +1190,108 @@ function registerFileCommand(program) {
 
 // src/commands/lint.ts
 import * as path8 from "path";
-import { runCodelinter } from "@oniroproject/core";
+import {
+  detectCmdToolsFlavour,
+  detectRuntimeOs as detectRuntimeOs2,
+  getCmdToolsPath,
+  runCodelinter
+} from "@oniroproject/core";
+function lintTotals(result) {
+  if (result.summary) return result.summary;
+  const count = (s) => result.findings.filter((f) => f.severity === s).length;
+  return {
+    defects: result.findings.length,
+    errors: count("error"),
+    warnings: count("warning"),
+    suggestions: count("suggestion")
+  };
+}
+function lintExitCode(result) {
+  if (lintTotals(result).errors > 0) return 1;
+  const noReport = result.summary === null && result.findings.length === 0;
+  return noReport && result.code !== 0 ? result.code : 0;
+}
 function registerLintCommand(program) {
-  program.command("lint [project-dir]").description("Run the OpenHarmony codelinter on a project. Defaults to the current directory.").option("--files <globs...>", "Specific files/globs to lint (default: the whole project).").option("--json", "Emit findings as JSON.").action(async (projectDir, opts) => {
+  program.command("lint [project-dir]").description(
+    "Run the OpenHarmony codelinter on a project. Defaults to the current directory. Exits 1 on error-severity findings or when codelinter fails to run; warnings alone exit 0."
+  ).option("--files <globs...>", "Specific files/globs to lint (default: the whole project).").option("--json", "Emit the report (findings, summary, notices, incomplete) as JSON.").action(async (projectDir, opts) => {
     const { config, logger } = getRuntime();
     const dir = path8.resolve(projectDir ?? process.cwd());
     const result = await runCodelinter({ config, projectDir: dir, files: opts.files, logger });
+    const totals = lintTotals(result);
     if (opts.json) {
       process.stdout.write(`${JSON.stringify(result, null, 2)}
 `);
     } else {
       for (const f of result.findings) {
-        process.stdout.write(`${f.file}:${f.line} ${f.severity} ${f.message}${f.code ? ` [${f.code}]` : ""}
+        const at = `${f.file}:${f.line}${f.column ? `:${f.column}` : ""}`;
+        process.stdout.write(`${at} ${f.severity} ${f.message}${f.code ? ` [${f.code}]` : ""}
 `);
       }
-      if (result.findings.length === 0) process.stdout.write("No findings.\n");
+      process.stdout.write(
+        totals.defects === 0 ? "No defects found.\n" : `${totals.defects} defects: ${totals.errors} errors, ${totals.warnings} warnings, ${totals.suggestions} suggestions.
+`
+      );
+    }
+    if (result.summary === null && result.findings.length === 0 && result.code !== 0) {
+      logger.error(`codelinter exited ${result.code} without a report:
+${result.raw.trim().split("\n").slice(-15).join("\n")}`);
+    }
+    if (result.incomplete) {
+      for (const n of result.notices) logger.warn(`codelinter: ${n}`);
+      const cmdToolsPath = getCmdToolsPath(config);
+      const flavour = detectCmdToolsFlavour(cmdToolsPath);
+      const projectOs = detectRuntimeOs2(dir);
+      if (flavour !== projectOs) {
+        logger.warn(
+          `The command-line tools at ${cmdToolsPath} are the ${flavour} flavour, but the project targets ${projectOs} (runtimeOS in build-profile.json5), so codelinter skipped part of its checks: treat the counts as a lower bound. For a complete report, point ONIRO_CMD_TOOLS_PATH at ${projectOs} command-line tools. The build's ArkTS compiler checks are not affected.`
+        );
+      }
     }
-    if (result.code !== 0) process.exitCode = result.code;
+    process.exitCode = lintExitCode(result);
   });
 }
 
 // src/commands/input.ts
 import { Option as Option3 } from "commander";
-import { sendInput, sendGesture } from "@oniroproject/core";
-var INPUT_TYPES = ["click", "doubleClick", "longClick", "swipe", "drag", "fling", "keyEvent", "inputText"];
+import {
+  performInput,
+  sendGesture,
+  getDisplaySize,
+  describeLayoutNode as describeLayoutNode3
+} from "@oniroproject/core";
+var INPUT_TYPES = [
+  "click",
+  "doubleClick",
+  "longClick",
+  "swipe",
+  "drag",
+  "fling",
+  "keyEvent",
+  "inputText",
+  "clearText",
+  "hideKeyboard"
+];
 var num = (v) => v === void 0 ? void 0 : Number(v);
 function registerInputCommand(program) {
-  program.command("input").description("Inject a UI input event (pixel coordinates) via uitest uiInput.").addOption(new Option3("--type <type>", "Input type.").choices(INPUT_TYPES).makeOptionMandatory()).option("--x <px>", "X pixel (click/swipe start).").option("--y <px>", "Y pixel (click/swipe start).").option("--x2 <px>", "End X pixel (swipe/drag/fling).").option("--y2 <px>", "End Y pixel (swipe/drag/fling).").option("--speed <px-per-s>", "Velocity for swipe/drag/fling.").option("--key <key>", "Key id or symbolic name (Back/Home/Power) for keyEvent.").option("--text <text>", "Text for inputText.").option("--device <serial>", "Target device serial.").action(async (opts) => {
+  const input = program.command("input").description(
+    "Inject a UI input event via uitest uiInput. Position it with --target (an on-screen element), --fx/--fy (0-1 fractions of the display, as in `dump layout` and the screenshot grid), or --x/--y (pixels)."
+  ).addOption(new Option3("--type <type>", "Input type.").choices(INPUT_TYPES).makeOptionMandatory());
+  addTargetOptions(input, "Act on");
+  input.option("--fx <fraction>", "Start X as a 0-1 fraction of the display width.").option("--fy <fraction>", "Start Y as a 0-1 fraction of the display height.").option("--fx2 <fraction>", "End X fraction (swipe/drag/fling).").option("--fy2 <fraction>", "End Y fraction (swipe/drag/fling).").option("--x <px>", "X pixel (click/swipe start).").option("--y <px>", "Y pixel (click/swipe start).").option("--x2 <px>", "End X pixel (swipe/drag/fling).").option("--y2 <px>", "End Y pixel (swipe/drag/fling).").option("--speed <px-per-s>", "Velocity for swipe/drag/fling.").option(
+    "--key <key>",
+    "Key for keyEvent: Back/Home/Power, a name (Delete, Enter, Tab, Escape, MoveHome, MoveEnd, \u2026), a letter, a KeyCode id, or a combo like Ctrl+A."
+  ).option("--text <text>", "Text for inputText.").option("--clear", "inputText: clear the field (Ctrl+A, Delete) before typing.").option("--hide-keyboard", "Dismiss the soft keyboard afterwards, if it is up.").option("--device <serial>", "Target device serial.").action(async (opts) => {
     const { config, logger } = getRuntime();
-    await sendInput({
+    const result = await performInput({
       config,
       type: opts.type,
+      target: selectorFrom(opts),
+      targetIndex: targetIndexFrom(opts),
+      fx: num(opts.fx),
+      fy: num(opts.fy),
+      fx2: num(opts.fx2),
+      fy2: num(opts.fy2),
       pxX: num(opts.x),
       pxY: num(opts.y),
       pxX2: num(opts.x2),
@@ -974,14 +1299,31 @@ function registerInputCommand(program) {
       speed: num(opts.speed),
       key: opts.key,
       text: opts.text,
+      clear: opts.clear,
+      hideKeyboard: opts.hideKeyboard,
       deviceSerial: opts.device,
       logger
     });
-    logger.info(`Sent ${opts.type}.`);
+    if (opts.type === "hideKeyboard") {
+      logger.info(result.keyboardHidden ? "Dismissed the keyboard." : "The keyboard was not shown.");
+      return;
+    }
+    const at = result.x !== void 0 ? ` at ${result.x},${result.y}` : "";
+    const on = result.target ? ` on ${describeLayoutNode3(result.target)}` : "";
+    const kb = result.keyboardHidden ? " (dismissed the keyboard)" : "";
+    logger.info(`Sent ${opts.type}${at}${on}${kb}.`);
   });
-  program.command("gesture").description('Inject a multi-waypoint gesture. Waypoints are pixel JSON: [{"x":..,"y":..,"t":..}].').requiredOption("--waypoints <json>", "JSON array of {x,y,t} pixel waypoints (t = ms from start).").option("--hold-start <ms>", "Leading press-hold before moving (best-effort: uses `uitest drag`).").option("--hold-end <ms>", "Trailing hold before lifting (no uitest equivalent; ignored).").option("--device <serial>", "Target device serial.").action(async (opts) => {
+  program.command("gesture").description('Inject a multi-waypoint gesture. Waypoints are JSON: [{"x":..,"y":..,"t":..}] in pixels (or fractions with --fractions).').requiredOption("--waypoints <json>", "JSON array of {x,y,t} waypoints (t = ms from start).").option("--fractions", "Waypoint x/y are 0-1 fractions of the display instead of pixels.").option("--hold-start <ms>", "Leading press-hold before moving (best-effort: uses `uitest drag`).").option("--hold-end <ms>", "Trailing hold before lifting (no uitest equivalent; ignored).").option("--device <serial>", "Target device serial.").action(async (opts) => {
     const { config, logger } = getRuntime();
-    const waypoints = JSON.parse(opts.waypoints);
+    let waypoints = JSON.parse(opts.waypoints);
+    if (opts.fractions) {
+      const bad = waypoints.find((w) => !(w.x >= 0 && w.x <= 1 && w.y >= 0 && w.y <= 1));
+      if (bad) throw new Error(`With --fractions, waypoint x and y must be 0-1; got ${bad.x},${bad.y}.`);
+      const display = await getDisplaySize(config, { deviceSerial: opts.device, logger });
+      if (!display) throw new Error("Could not read the display size to convert fractions to pixels.");
+      const px = (f, size) => Math.min(size - 1, Math.round(f * size));
+      waypoints = waypoints.map((w) => ({ ...w, x: px(w.x, display.width), y: px(w.y, display.height) }));
+    }
     await sendGesture({
       config,
       waypoints,
@@ -994,12 +1336,70 @@ function registerInputCommand(program) {
   });
 }
 
+// src/commands/logs.ts
+import * as path9 from "path";
+import { captureLog } from "@oniroproject/core";
+function registerLogsCommand(program) {
+  program.command("logs").description(
+    "Capture hilog to a file for a whole session: the device's small log buffer wraps within seconds under chatty components, so a dump at the end loses lines. Runs until --for elapses or the process is interrupted; start it in the background, e.g. `oniro-app logs --clear -o hilog_full.txt &`. Every line is flushed as it arrives and the stream reconnects after a reboot."
+  ).requiredOption("-o, --output <file>", "File to append the lines to.").option("--for <ms>", "Stop after this many ms (default: run until interrupted).").option("--grep <regex>", "Keep only lines matching this regex (default: all).").option("--clear", "Clear the device log buffer first (hilog -r), so the file covers only this session.").option("--domain <domain>", "hilog domain filter (e.g. 0xD003900).").option("--device <serial>", "Target device serial.").action(async (opts) => {
+    const { config, logger } = getRuntime();
+    const file = path9.resolve(opts.output);
+    const abort = new AbortController();
+    const stop = () => abort.abort();
+    process.once("SIGINT", stop);
+    process.once("SIGTERM", stop);
+    logger.info(`Capturing hilog to ${file}${opts.for ? ` for ${opts.for} ms` : " until interrupted"}...`);
+    const result = await captureLog({
+      config,
+      file,
+      durationMs: opts.for !== void 0 ? Number(opts.for) : void 0,
+      pattern: opts.grep ? new RegExp(opts.grep) : void 0,
+      clear: opts.clear,
+      domain: opts.domain,
+      deviceSerial: opts.device,
+      abortSignal: abort.signal,
+      logger
+    });
+    logger.info(`Wrote ${result.lines} lines to ${result.file} (${result.reconnects} reconnects).`);
+    process.stdout.write(`${result.file}
+`);
+  });
+}
+
+// src/commands/hdc.ts
+import { getHdcPath, hdcTargetArgsFor, spawnCompat } from "@oniroproject/core";
+function hdcPassthroughArgv(args, device) {
+  return args[0] === "-t" ? [...args] : [...hdcTargetArgsFor(args, device), ...args];
+}
+function registerHdcCommand(program) {
+  program.command("hdc").description(
+    "Run the hdc binary oniro-app itself uses (see `cmdtools status`), addressed at --device or ONIRO_DEVICE_SERIAL, with stdio passed through. Exits with hdc's own code, which is 0 even for a `[Fail]` line. Example: oniro-app hdc shell param get const.ohos.apiversion"
+  ).argument("[args...]", "hdc arguments, passed through verbatim").option("--device <serial>", "Target device serial.").option("--path", "Print the hdc binary path and exit.").passThroughOptions().allowUnknownOption().action(async (args, opts) => {
+    const { config } = getRuntime();
+    const hdc = getHdcPath(config);
+    if (opts.path) {
+      process.stdout.write(`${hdc}
+`);
+      return;
+    }
+    await new Promise((resolve8, reject) => {
+      const child = spawnCompat(hdc, hdcPassthroughArgv(args, opts.device), { stdio: "inherit" });
+      child.on("error", (err) => reject(new Error(`Failed to run ${hdc}: ${err.message}`)));
+      child.on("close", (code) => {
+        process.exitCode = code ?? 1;
+        resolve8();
+      });
+    });
+  });
+}
+
 // src/bin/oniro-app.ts
-var CLI_VERSION = "0.12.0";
+var CLI_VERSION = "0.14.0";
 function buildProgram() {
   const program = new Command4().name("oniro-app").description(
     "Cross-platform CLI for Oniro/OpenHarmony app development.\n\nDesigned for non-interactive use (CI, scripts, agents): every command\ntakes explicit flags, results go to stdout, progress/logs go to stderr,\nand a non-zero exit code indicates failure."
-  ).version(CLI_VERSION).showHelpAfterError();
+  ).version(CLI_VERSION).showHelpAfterError().enablePositionalOptions();
   registerSdkCommand(program);
   registerCmdToolsCommand(program);
   registerEmulatorCommand(program);
@@ -1018,6 +1418,8 @@ function buildProgram() {
   registerFileCommand(program);
   registerLintCommand(program);
   registerInputCommand(program);
+  registerLogsCommand(program);
+  registerHdcCommand(program);
   return program;
 }
 async function main() {