@oniroproject/oniro-app 0.17.0 → 0.19.0

package/dist/oniro-app.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 
 // src/bin/oniro-app.ts
-import { Command as Command4 } from "commander";
-import { OniroError as OniroError3 } from "@oniroproject/core";
+import { Command as Command11, CommanderError } from "commander";
+import { OniroError as OniroError7 } from "@oniroproject/core";
 
 // src/commands/sdk.ts
 import * as fs from "fs";
@@ -12,6 +12,7 @@ import {
   OHOS_DAILY_BUILDS_URL,
   downloadAndInstallSdk,
   getOsFolder,
+  getHarmonyOsSdkListing,
   getSdkRootDir,
   getSupportedSdksForUi,
   installSdkFromArchive,
@@ -47,16 +48,16 @@ function createCliProgress() {
   let lastEmitted = -1;
   let lastMessage = "";
   return {
-    report({ message, increment }) {
+    report({ message: message2, increment }) {
       if (typeof increment === "number") total = Math.min(100, total + increment);
       const pct = total > 0 ? Math.round(total) : null;
-      const msg = message ?? lastMessage;
+      const msg = message2 ?? lastMessage;
       if (pct === lastEmitted && msg === lastMessage) return;
       const prefix = pct === null ? "[progress]" : `[progress ${pct}%]`;
       process.stderr.write(`${prefix} ${msg}
 `);
       lastEmitted = pct ?? lastEmitted;
-      if (message) lastMessage = message;
+      if (message2) lastMessage = message2;
     }
   };
 }
@@ -78,7 +79,9 @@ var ENV_VAR_BY_KEY = {
   applicationCertPath: "ONIRO_APPLICATION_CERT_PATH",
   harmonyosSdkPath: "ONIRO_HARMONYOS_SDK_PATH",
   harmonyosAuthDir: "ONIRO_HARMONYOS_AUTH_DIR",
-  harmonyosSigningDir: "ONIRO_HARMONYOS_SIGNING_DIR"
+  harmonyosSigningDir: "ONIRO_HARMONYOS_SIGNING_DIR",
+  cacheDir: "ONIRO_CACHE_DIR",
+  docsDir: "ONIRO_DOCS_DIR"
 };
 function createEnvConfig(env = process.env) {
   return {
@@ -106,9 +109,23 @@ function getRuntime() {
 }
 
 // src/commands/sdk.ts
+var HARMONYOS_SOURCE = {
+  cmdtools: "from the command-line tools",
+  "deveco-studio": "from DevEco Studio",
+  configured: "from ONIRO_HARMONYOS_SDK_PATH"
+};
+function formatHarmonyOsSdkNote(listing) {
+  const note = "HarmonyOS SDKs are not managed by `sdk`: they ship inside the HarmonyOS command-line tools (`oniro-app cmdtools`) or DevEco Studio.";
+  if (!listing) return `${note}
+No HarmonyOS SDK found; \`oniro-app cmdtools install\` installs one.`;
+  const name = listing.displayName ?? `HarmonyOS ${listing.version ?? ""}`.trim();
+  const from = listing.source ? `, ${HARMONYOS_SOURCE[listing.source]}` : "";
+  return `${note}
+*  ${name.padEnd(17)} api ${listing.api ?? "?"}  ${listing.path}${from}`;
+}
 var FULL_SDK_TIP = `Tip: the full SDK (with system APIs) is not on the release mirror. Download an ohos-sdk-full archive from the OpenHarmony daily builds, ${OHOS_DAILY_BUILDS_URL}, and install it with \`oniro-app sdk install --from-archive <archive>\`.`;
 function registerSdkCommand(program) {
-  const sdk = program.command("sdk").description("Manage OpenHarmony SDK installs.");
+  const sdk = program.command("sdk").description("Manage OpenHarmony SDK installs. HarmonyOS SDKs come with the command-line tools (`cmdtools`).");
   sdk.command("install [version]").description(
     "Download and install an OpenHarmony SDK (skips if already installed), or install one from a local archive with --from-archive."
   ).option(
@@ -166,16 +183,22 @@ ${FULL_SDK_TIP}`).action(async (version, opts) => {
     });
     logger.info("SDK installed.");
   });
-  sdk.command("list").description("List known SDK versions and whether they are installed on this machine.").option("--json", "Emit machine-readable JSON instead of a table.").action((opts) => {
+  sdk.command("list").description(
+    "List known OpenHarmony SDK versions and whether they are installed on this machine, then the HarmonyOS SDK, which comes with the command-line tools (`cmdtools`) or DevEco Studio, if one is found."
+  ).option("--json", "Emit machine-readable JSON instead of a table.").action((opts) => {
     const { config } = getRuntime();
     const sdks = getSupportedSdksForUi(config);
+    const harmonyOs = getHarmonyOsSdkListing(config);
     if (opts.json) {
-      process.stdout.write(`${JSON.stringify(sdks, null, 2)}
+      const rows2 = [...sdks.map((s) => ({ ...s, flavour: "OpenHarmony" })), ...harmonyOs ? [harmonyOs] : []];
+      process.stdout.write(`${JSON.stringify(rows2, null, 2)}
 `);
       return;
     }
     const rows = sdks.map((s) => `${s.installed ? "*" : " "}  ${s.version.padEnd(8)} api ${s.api}`);
     process.stdout.write(`${rows.join("\n")}
+
+${formatHarmonyOsSdkNote(harmonyOs)}
 `);
   });
   sdk.command("remove <api>").description("Remove an installed SDK by API level (e.g. 18, 20).").action((api) => {
@@ -190,24 +213,40 @@ ${FULL_SDK_TIP}`).action(async (version, opts) => {
 }
 
 // src/commands/cmdtools.ts
-import { getCmdToolsStatus, installCmdTools, isCmdToolsInstalled, removeCmdTools } from "@oniroproject/core";
+import {
+  describeCmdTools,
+  getCmdToolsStatus,
+  installCmdTools,
+  removeCmdTools
+} from "@oniroproject/core";
+function formatCmdToolsSdk(sdk) {
+  const name = [sdk.displayName, sdk.apiVersion ? `API ${sdk.apiVersion}` : void 0].filter(Boolean).join(", ");
+  return `${name || "SDK"}${sdk.build ? ` (${sdk.build})` : ""} at ${sdk.path}`;
+}
 function registerCmdToolsCommand(program) {
-  const cmdtools = program.command("cmdtools").description("Manage OpenHarmony command-line tools.");
-  cmdtools.command("install").description("Install the OpenHarmony command-line tools (hvigorw, ohpm, hdc). Skips if already installed.").option("--from-zip <path>", "Install from a local ZIP instead of downloading.").option("--force", "Reinstall even if the tools are already present.").option(
+  const cmdtools = program.command("cmdtools").description(
+    "Manage the command-line tools (hvigorw, ohpm, codelinter, hdc). Their HarmonyOS edition also supplies the HarmonyOS SDK, which `sdk` does not manage."
+  );
+  cmdtools.command("install").description(
+    "Install the command-line tools (hvigorw, ohpm, codelinter, hdc and, in the HarmonyOS edition, the HarmonyOS SDK). Skips if already installed."
+  ).option("--from-zip <path>", "Install from a local ZIP instead of downloading.").option("--force", "Reinstall even if the tools are already present.").option(
     "--tmp-dir <path>",
     "Directory for download/extract temporaries (default: ONIRO_TMP_DIR, else .oniro-tmp next to the install target). Use this when that filesystem is short on space."
   ).action(async (opts) => {
     const { config, logger, progress } = getRuntime();
-    if (isCmdToolsInstalled(config) && !opts.force) {
-      logger.info("Command-line tools already installed; pass --force to reinstall.");
+    const current = getCmdToolsStatus(config);
+    if (current.installed && !opts.force) {
+      logger.info(
+        `Command-line tools ${describeCmdTools(current)} already installed at ${current.path}; pass --force to replace them.`
+      );
       return;
     }
-    logger.info("Installing OpenHarmony command-line tools...");
-    await installCmdTools({ config, progress, logger, localZipPath: opts.fromZip, tmpDir: opts.tmpDir });
-    logger.info("Command-line tools installed.");
+    logger.info("Installing command-line tools...");
+    const result = await installCmdTools({ config, progress, logger, localZipPath: opts.fromZip, tmpDir: opts.tmpDir });
+    logger.info(`Command-line tools ${describeCmdTools(result.installed)} installed at ${result.path}.`);
   });
   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."
+    "Report whether the command-line tools are installed, their version, flavour (HarmonyOS or OpenHarmony), the SDK they bundle (name, API level), their tools' versions (hvigor, ohpm, ...), and the hdc binary every device command uses."
   ).option("--json", "Emit machine-readable JSON.").action((opts) => {
     const { config } = getRuntime();
     const status = getCmdToolsStatus(config);
@@ -216,11 +255,15 @@ function registerCmdToolsCommand(program) {
 `);
       return;
     }
-    process.stdout.write(`${status.status}
+    process.stdout.write(`${status.version ? `Installed ${describeCmdTools(status)}` : status.status}
 `);
     process.stdout.write(`path:    ${status.path}
 `);
     if (status.flavour) process.stdout.write(`flavour: ${status.flavour}
+`);
+    if (status.sdk) process.stdout.write(`sdk:     ${formatCmdToolsSdk(status.sdk)}
+`);
+    if (status.tools?.hvigor) process.stdout.write(`hvigor:  ${status.tools.hvigor}
 `);
     process.stdout.write(`hdc:     ${status.hdc.path}${status.hdc.exists ? "" : " (missing)"}
 `);
@@ -234,15 +277,56 @@ function registerCmdToolsCommand(program) {
 }
 
 // src/commands/emulator.ts
+import { InvalidArgumentError } from "commander";
 import {
+  MAX_POOL_INSTANCE,
+  POOL_DEFAULT_MEMORY,
+  POOL_DEFAULT_RESOLUTION,
+  POOL_DEFAULT_SMP,
+  DEFAULT_BOOT_TIMEOUT_SECONDS,
   attemptHdcConnection,
   getEmulatorStatus,
+  getPoolInstanceStatus,
   installEmulator,
   isEmulatorInstalled,
   removeEmulator,
   startEmulator,
-  stopEmulator
+  startPoolInstance,
+  stopEmulator,
+  stopPoolInstance
 } from "@oniroproject/core";
+function parseInstance(v) {
+  const n = Number(v);
+  if (!/^\d+$/.test(v) || n > MAX_POOL_INSTANCE) {
+    throw new InvalidArgumentError(`expected an integer from 0 to ${MAX_POOL_INSTANCE}.`);
+  }
+  return n;
+}
+function parseSeconds(v) {
+  if (!/^\d+$/.test(v)) throw new InvalidArgumentError("expected a whole number of seconds.");
+  return Number(v);
+}
+function parseSmp(v) {
+  if (!/^\d+$/.test(v) || Number(v) < 1) throw new InvalidArgumentError("expected a positive integer.");
+  return Number(v);
+}
+var ACCELS = ["auto", "kvm", "hvf", "whpx", "tcg"];
+function parseAccel(v) {
+  if (!ACCELS.includes(v)) throw new InvalidArgumentError(`expected one of ${ACCELS.join(", ")}.`);
+  return v;
+}
+function formatInstanceRow(i) {
+  const fields = [String(i.instance), i.state, `hdc=${i.address}`];
+  if (i.vncPort) fields.push(`vnc=127.0.0.1:${i.vncPort}`);
+  if (i.instance > 0 && i.serialPort) fields.push(`serial=127.0.0.1:${i.serialPort}`);
+  if (i.pid) fields.push(`pid=${i.pid}`);
+  if (i.smp) fields.push(`cpus=${i.smp}`);
+  if (i.memory) fields.push(`mem=${i.memory}`);
+  if (i.bootSeconds !== void 0) fields.push(`boot=${i.bootSeconds}s`);
+  return fields.join("	");
+}
+var POOL_ONLY_OPTIONS = ["memory", "smp", "resolution", "window", "fresh", "bootTimeout", "qemu", "accel", "json"];
+var flagName = (key) => `--${key.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`)}`;
 function registerEmulatorCommand(program) {
   const emu = program.command("emulator").description("Manage the Oniro emulator.");
   emu.command("install").description("Download and install the Oniro emulator (QEMU-based). Skips if already installed.").option("--force", "Reinstall even if the emulator is already present.").option(
@@ -258,24 +342,71 @@ function registerEmulatorCommand(program) {
     await installEmulator({ config, progress, logger, tmpDir: opts.tmpDir });
     logger.info("Emulator installed.");
   });
-  emu.command("start").description("Start the Oniro emulator via the bundled launcher (run.sh / run.bat). Detaches so the CLI can exit while the emulator keeps running.").option("--headless", "Launch headless (VNC + telnet serial, no local window). Required in CI.").option("--log <path>", "Redirect launcher stdout/stderr to this file. Defaults to discarding output.").option("--wait-for-hdc <seconds>", "Wait up to N seconds for hdc to connect. 0 = do not wait.", (v) => parseInt(v, 10), 0).option("--connect <host:port>", "Override the launcher's hdc port-forward bind address. Pass 0.0.0.0:55555 on hosts where QEMU refuses to bind 127.0.0.1 (some CI runners).").action(async (opts) => {
+  emu.command("start").description(
+    "Start the Oniro emulator and detach, so the CLI can exit while it keeps running. Without --instance (or with --instance 0) it runs the bundled launcher (run.sh / run.bat). --instance <n> (1..99) starts pool instance n instead: its own QEMU on copy-on-write overlays of the images, hdc on 127.0.0.1:55555+n, headless VNC on 127.0.0.1:5900+n, serial console on telnet 127.0.0.1:4444+n."
+  ).option("--instance <n>", "Pool instance number (1..99). 0 or unset: the default emulator via run.sh.", parseInstance).option("--headless", "Launch headless (VNC + telnet serial, no local window). Required in CI. Pool instances are headless unless --window.").option("--log <path>", "Redirect launcher stdout/stderr to this file. Defaults to discarding output (pool instances: <instance dir>/qemu.log).").option("--wait-for-hdc <seconds>", "Default emulator: wait up to N seconds for hdc to connect (restarts the hdc server). 0 = do not wait.", (v) => parseInt(v, 10), 0).option("--wait-ready <seconds>", "Wait up to N seconds until the guest reports bootevent.boot.completed=true. Connects with hdc tconn only, never restarting the hdc server.", parseSeconds).option("--connect <host:port>", "Default emulator: override the launcher's hdc port-forward bind address. Pass 0.0.0.0:55555 on hosts where QEMU refuses to bind 127.0.0.1 (some CI runners).").option("--memory <size>", `Pool: guest RAM in QEMU syntax (default ${POOL_DEFAULT_MEMORY}).`).option("--smp <n>", `Pool: virtual CPUs (default ${POOL_DEFAULT_SMP}).`, parseSmp).option("--resolution <WxH>", `Pool: display resolution (default ${POOL_DEFAULT_RESOLUTION}).`).option("--window", "Pool: show a local SDL window instead of VNC.").option("--fresh", "Pool: discard the instance's overlays first (factory reset).").option("--boot-timeout <seconds>", `Pool: seconds after launch past which a boot that has not completed is reported stuck (default ${DEFAULT_BOOT_TIMEOUT_SECONDS}).`, parseSeconds).option("--qemu <path>", "Pool: qemu-system-x86_64 binary (default QEMU_BIN, else PATH); qemu-img is looked up next to it.").option("--accel <kind>", `Pool: accelerator, one of ${ACCELS.join(", ")} (default auto: KVM on Linux, as run.sh).`, parseAccel).option("--json", "Pool: print the instance's status as JSON when done.").action(async (opts) => {
     const { config, logger } = getRuntime();
-    await startEmulator({
+    if (opts.instance === void 0 || opts.instance === 0) {
+      const poolOnly = POOL_ONLY_OPTIONS.filter((k) => opts[k] !== void 0);
+      if (poolOnly.length > 0) {
+        throw new InvalidArgumentError(
+          `${poolOnly.map(flagName).join(", ")} ${poolOnly.length > 1 ? "apply" : "applies"} only to pool instances (--instance 1..${MAX_POOL_INSTANCE}).`
+        );
+      }
+      await startEmulator({
+        config,
+        logger,
+        headless: opts.headless === true,
+        logFile: opts.log,
+        waitForHdcSeconds: opts.waitForHdc,
+        waitReadySeconds: opts.waitReady,
+        connect: opts.connect
+      });
+      logger.info("Emulator start command complete.");
+      return;
+    }
+    if (opts.connect || opts.waitForHdc > 0) {
+      throw new InvalidArgumentError(
+        "--connect and --wait-for-hdc apply to the default emulator only; a pool instance listens on 127.0.0.1:55555+n, wait with --wait-ready."
+      );
+    }
+    const status = await startPoolInstance({
       config,
       logger,
-      headless: opts.headless === true,
-      logFile: opts.log,
-      waitForHdcSeconds: opts.waitForHdc,
-      connect: opts.connect
+      instance: opts.instance,
+      memory: opts.memory,
+      smp: opts.smp,
+      resolution: opts.resolution,
+      headless: opts.window !== true,
+      fresh: opts.fresh === true,
+      waitReadySeconds: opts.waitReady,
+      bootTimeoutSeconds: opts.bootTimeout,
+      qemuBin: opts.qemu,
+      accel: opts.accel,
+      logFile: opts.log
     });
-    logger.info("Emulator start command complete.");
+    if (opts.json) process.stdout.write(`${JSON.stringify(status, null, 2)}
+`);
+    else logger.info(`Instance ${status.instance}: ${status.state} (${status.address}).`);
   });
   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) => {
+    "Report whether the Oniro emulator is installed, running, and connected to hdc, without starting it, and list every instance (the default emulator as 0, then each pool instance) with its health: stopped, booting, ready, hdc-lost or stuck. Exits 1 when the emulator is not installed."
+  ).option("--address <addr>", "hdc address the default emulator listens on", "127.0.0.1:55555").option("--instance <n>", "Report only this instance (0 = the default emulator).", parseInstance).option("--json", "Emit machine-readable JSON: `instances` lists every instance; with --instance, that instance alone.").action(async (opts) => {
     const { config, logger } = getRuntime();
+    const print = (one) => {
+      process.stdout.write(opts.json ? `${JSON.stringify(one, null, 2)}
+` : `${formatInstanceRow(one)}
+`);
+    };
+    if (opts.instance !== void 0 && opts.instance > 0) {
+      print(await getPoolInstanceStatus(config, opts.instance, { logger }));
+      if (!isEmulatorInstalled(config)) process.exitCode = 1;
+      return;
+    }
     const status = await getEmulatorStatus(config, { address: opts.address, logger });
-    if (opts.json) {
+    if (opts.instance === 0) {
+      print(status.instances[0]);
+    } else if (opts.json) {
       process.stdout.write(`${JSON.stringify(status, null, 2)}
 `);
     } else {
@@ -285,13 +416,26 @@ running:   ${status.running ? "yes" : "no"}
 connected: ${status.connected ? "yes" : "no"} (${status.address})
 `
       );
+      if (status.instances.length > 1) {
+        process.stdout.write(`instances:
+${status.instances.map((i) => `  ${formatInstanceRow(i)}`).join("\n")}
+`);
+      }
     }
     if (!status.installed) process.exitCode = 1;
   });
-  emu.command("stop").description("Kill running emulator processes.").action(async () => {
-    const { logger } = getRuntime();
-    await stopEmulator(logger);
-    logger.info("Emulator stopped.");
+  emu.command("stop").description(
+    "Without --instance: kill running emulator processes (every qemu-system-x86_64, pool instances included). With --instance <n>: stop only that pool instance's QEMU and drop its target from hdc."
+  ).option("--instance <n>", "Pool instance to stop (1..99).", parseInstance).option("--discard", "With --instance: also delete the instance's overlays, log and state.").action(async (opts) => {
+    const { config, logger } = getRuntime();
+    if (opts.instance === void 0 || opts.instance === 0) {
+      if (opts.discard) throw new InvalidArgumentError(`--discard needs --instance <n> (1..${MAX_POOL_INSTANCE}).`);
+      await stopEmulator(logger);
+      logger.info("Emulator stopped.");
+      return;
+    }
+    const stopped = await stopPoolInstance({ config, instance: opts.instance, discard: opts.discard === true, logger });
+    if (!stopped) logger.info(`Instance ${opts.instance} was not running.`);
   });
   emu.command("connect").description("Attempt to connect hdc to the emulator.").option("--address <addr>", "hdc address to connect to", "127.0.0.1:55555").action(async (opts) => {
     const { config, logger } = getRuntime();
@@ -311,45 +455,80 @@ connected: ${status.connected ? "yes" : "no"} (${status.address})
 
 // src/commands/build.ts
 import * as path2 from "path";
-import { SdkNotInstalledError, buildHap, downloadAndInstallSdk as downloadAndInstallSdk2 } from "@oniroproject/core";
+import {
+  OniroError,
+  buildWithDiagnostics,
+  downloadAndInstallSdk as downloadAndInstallSdk2
+} from "@oniroproject/core";
+async function runBuild(projectDir, opts) {
+  const { config, logger, progress } = getRuntime();
+  const dir = path2.resolve(projectDir ?? process.cwd());
+  logger.info(`Building project at ${dir}...`);
+  const build2 = () => buildWithDiagnostics({
+    config,
+    projectDir: dir,
+    product: opts.product,
+    module: opts.module,
+    mode: opts.mode,
+    task: opts.task,
+    autoInstallDeps: opts.deps,
+    parallel: opts.parallel,
+    logger,
+    // The logger already echoes spawn output; this hook is for streaming to other UIs.
+    onOutput: () => {
+    }
+  });
+  let report = await build2();
+  if (!report.ok && report.missingSdk?.version && opts.installSdk) {
+    const { version, api } = report.missingSdk;
+    logger.info(`Installing OpenHarmony SDK ${version} (api ${api}), which the project compiles against...`);
+    await downloadAndInstallSdk2({ config, version, api, progress, logger });
+    report = await build2();
+  }
+  return report;
+}
 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). 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 build = () => buildHap({
-      config,
-      projectDir: dir,
-      product: opts.product,
-      module: opts.module,
-      mode: opts.mode,
-      task: opts.task,
-      autoInstallDeps: opts.deps,
-      parallel: opts.parallel,
-      logger,
-      // The logger already echoes spawn output; this hook is for streaming to other UIs.
-      onOutput: () => {
-      }
-    });
-    let result;
+    '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. With --json, one result object is printed whether the build passes or fails; a failed build exits 1.'
+  ).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",
+    "print the result as JSON: ok, diagnostics (file, line, column, code, rule, message), summary, failedTask, discoveredHaps, warnings"
+  ).action(async (projectDir, opts) => {
+    const { logger } = getRuntime();
+    let report;
     try {
-      result = await build();
+      report = await runBuild(projectDir, opts);
     } 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();
+      if (opts.json) {
+        const error = err instanceof Error ? err.message : String(err);
+        process.stdout.write(`${JSON.stringify({ ok: false, exitCode: 1, error, diagnostics: [] }, null, 2)}
+`);
+      }
+      throw err;
     }
-    for (const w of result.warnings) logger.warn(w);
+    for (const w of report.warnings) logger.warn(w);
     if (opts.json) {
-      process.stdout.write(`${JSON.stringify(result, null, 2)}
+      process.stdout.write(`${JSON.stringify(report, null, 2)}
 `);
     }
+    if (!report.ok) {
+      const listed = formatDiagnostics(report.diagnostics);
+      if (listed) logger.error(`Build failed${report.failedTask ? ` in ${report.failedTask}` : ""}:
+${listed}`);
+      throw new OniroError(report.error ?? "Build failed.");
+    }
     logger.info("Build complete.");
   });
 }
+function formatDiagnostics(diagnostics, max = 20) {
+  const sorted = [...diagnostics].sort((a, b) => a.severity === b.severity ? 0 : a.severity === "error" ? -1 : 1);
+  const lines = sorted.slice(0, max).map((d) => {
+    const at = d.file ? `${d.file}${d.line ? `:${d.line}${d.column ? `:${d.column}` : ""}` : ""} ` : "";
+    return `  ${at}${d.severity} ${d.source}${d.code ? ` ${d.code}` : ""}: ${d.message}${d.rule ? ` (${d.rule})` : ""}`;
+  });
+  if (sorted.length > max) lines.push(`  \u2026 and ${sorted.length - max} more`);
+  return lines.join("\n");
+}
 
 // src/commands/sign.ts
 import { Option } from "commander";
@@ -357,7 +536,7 @@ import * as path3 from "path";
 import {
   APL_VALUES,
   APP_FEATURE_VALUES,
-  OniroError,
+  OniroError as OniroError2,
   createHarmonyOsSession,
   detectRuntimeOs,
   generateSigningConfigs,
@@ -365,8 +544,18 @@ import {
   harmonyOsSignHap,
   signOpenHarmonyHap,
   prepareSigning,
-  getOhosBaseSdkHome
+  getOhosBaseSdkHome,
+  describeProfileValidity,
+  describeSigningMaterial
 } from "@oniroproject/core";
+function profileSummary(result) {
+  const validity = describeProfileValidity({ type: result.profileType, notAfter: result.notAfter });
+  return [`profile names ${result.deviceIds.length} device(s)`, validity].filter(Boolean).join(", ");
+}
+function materialSuffix(summary) {
+  const text = describeSigningMaterial(summary);
+  return text ? ` (${text})` : "";
+}
 function parseAclsList(value) {
   return value.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
 }
@@ -379,7 +568,8 @@ function registerSignCommand(program) {
       "Overwrites the `signingConfigs` block in build-profile.json5 (other keys preserved).",
       "HarmonyOS projects need --harmonyos instead, which has AppGallery Connect issue the",
       "certificate and profile for a signed-in Huawei account (`oniro-app auth login`).",
-      "With --hap <file>, signs a prebuilt HAP instead of a project (with --harmonyos, for HarmonyOS)."
+      "With --hap <file>, signs a prebuilt HAP instead of a project (with --harmonyos, for HarmonyOS).",
+      "Ends by naming the profile type and expiry; `oniro-app app verify <hap>` checks what signed a built HAP."
     ].join(" ")
   ).addOption(
     new Option(
@@ -415,11 +605,11 @@ function registerSignCommand(program) {
       const { config, logger } = getRuntime();
       const dir = path3.resolve(projectDir ?? process.cwd());
       const passwords = opts.storePassword || opts.keyPassword ? { store: opts.storePassword ?? "123456", key: opts.keyPassword ?? "123456" } : void 0;
-      if (opts.out && !opts.hap) throw new OniroError("--out names where `--hap` writes the signed HAP; pass --hap too.");
+      if (opts.out && !opts.hap) throw new OniroError2("--out names where `--hap` writes the signed HAP; pass --hap too.");
       if (opts.hap) {
-        if (projectDir) throw new OniroError("Pass either a project directory or --hap, not both.");
+        if (projectDir) throw new OniroError2("Pass either a project directory or --hap, not both.");
         if (opts.product || opts.bootstrap) {
-          throw new OniroError(`--${opts.product ? "product" : "bootstrap"} applies to a project, not to --hap.`);
+          throw new OniroError2(`--${opts.product ? "product" : "bootstrap"} applies to a project, not to --hap.`);
         }
         const ignored = opts.harmonyos ? [
           opts.apl !== "normal" && "--apl",
@@ -430,7 +620,7 @@ function registerSignCommand(program) {
         ] : [opts.teamId && "--team-id", opts.force && "--force"];
         const unsupported = ignored.filter((flag) => typeof flag === "string");
         if (unsupported.length > 0) {
-          throw new OniroError(
+          throw new OniroError2(
             `${unsupported.join(", ")} ${unsupported.length > 1 ? "do" : "does"} not apply to ${opts.harmonyos ? "--harmonyos --hap" : "--hap without --harmonyos"}.`
           );
         }
@@ -447,7 +637,7 @@ function registerSignCommand(program) {
             applicationCertPath: config.get("applicationCertPath", "") || void 0,
             logger
           });
-          logger.info(`Signed ${result2.bundleName} into ${result2.outPath}.`);
+          logger.info(`Signed ${result2.bundleName} into ${result2.outPath}${materialSuffix(result2.material)}.`);
           return;
         }
         const result = await harmonyOsSignHap({
@@ -459,7 +649,7 @@ function registerSignCommand(program) {
           force: opts.force,
           logger
         });
-        logger.info(`Signed ${result.bundleName} into ${result.outPath} (profile names ${result.deviceIds.length} device(s)).`);
+        logger.info(`Signed ${result.bundleName} into ${result.outPath} (${profileSummary(result)}).`);
         return;
       }
       if (opts.harmonyos) {
@@ -472,11 +662,11 @@ function registerSignCommand(program) {
           force: opts.force,
           logger
         });
-        logger.info(`Signing configs ready for ${result.bundleName} (profile names ${result.deviceIds.length} device(s)).`);
+        logger.info(`Signing configs ready for ${result.bundleName} (${profileSummary(result)}).`);
         return;
       }
       if (detectRuntimeOs(dir, opts.product) === "HarmonyOS") {
-        throw new OniroError(
+        throw new OniroError2(
           `${dir} targets HarmonyOS, which needs a certificate from AppGallery Connect: run \`oniro-app auth login\` once, then \`oniro-app sign --harmonyos\`.`
         );
       }
@@ -496,7 +686,7 @@ function registerSignCommand(program) {
       }
       const sdkHome = getOhosBaseSdkHome(config);
       logger.info(`Generating signing configs in ${dir} using SDK at ${sdkHome}...`);
-      generateSigningConfigs({
+      const generated = generateSigningConfigs({
         projectDir: dir,
         sdkHome,
         apl: opts.apl,
@@ -506,32 +696,96 @@ function registerSignCommand(program) {
         passwords,
         logger
       });
-      logger.info("Signing configs generated.");
+      logger.info(`Signing configs generated${materialSuffix(generated)}.`);
     }
   );
 }
 
 // src/commands/auth.ts
+import { InvalidArgumentError as InvalidArgumentError2 } from "commander";
+import * as readline from "readline";
 import { HUAWEI_SITES, createHarmonyOsSession as createHarmonyOsSession2 } from "@oniroproject/core";
 function session() {
   const { config, logger } = getRuntime();
-  return createHarmonyOsSession2({
-    config,
-    logger,
-    onLoginUrl: (url) => process.stderr.write(`Opening the Huawei sign-in page. If no browser opens, visit:
+  return createHarmonyOsSession2({ config, logger });
+}
+function parsePort(value) {
+  const port = Number(value);
+  if (!/^\d+$/.test(value) || port < 1 || port > 65535) {
+    throw new InvalidArgumentError2("expected a port number from 1 to 65535.");
+  }
+  return port;
+}
+function browserInstructions(url) {
+  return `Opening the Huawei sign-in page. If no browser opens, visit:
   ${url}
-`)
-  });
+`;
+}
+function manualInstructions(url, callbackUrl, port) {
+  return [
+    "Open this address in a browser, on this machine or any other, and sign in:",
+    `  ${url}`,
+    `The browser is then sent to ${callbackUrl}?... If that page does not load (the browser is not on`,
+    "this machine), copy the whole address from its address bar, paste it here and press Enter.",
+    `(Or forward the port first, from the machine with the browser: ssh -L ${port}:127.0.0.1:${port} <this-host>.)`,
+    ""
+  ].join("\n");
 }
 function registerAuthCommand(program) {
   const auth = program.command("auth").description(
     "Sign in to a Huawei developer account, which HarmonyOS signing (`oniro-app sign --harmonyos`) needs. OpenHarmony signing needs no account. The token is stored encrypted under ONIRO_HARMONYOS_AUTH_DIR (default ~/.oniro/harmonyos)."
   );
-  auth.command("login").description("Sign in through the browser, which redirects back to a loopback port on this machine.").option("--timeout <seconds>", "How long to wait for the browser sign-in. Default 600.", (v) => Number(v)).action(async (opts) => {
-    const user = await session().login(opts.timeout ? { timeoutMs: Math.max(1, opts.timeout) * 1e3 } : void 0);
-    process.stdout.write(`${user.userName || user.userId}
+  auth.command("login").description(
+    "Sign in through the browser, which redirects back to a loopback port on this machine. With the browser on another machine, either pass --manual and paste the address the browser ends up on, or fix the port with --port and forward it with `ssh -L <port>:127.0.0.1:<port>`."
+  ).option("--timeout <seconds>", "How long to wait for the browser sign-in. Default 600.", (v) => Number(v)).option(
+    "--port <n>",
+    "Loopback port the sign-in page redirects to, instead of a random one, so an ssh tunnel can be set up beforehand: `ssh -L <n>:127.0.0.1:<n> <this-host>` from the machine with the browser (same port both ends).",
+    parsePort
+  ).option(
+    "--no-browser",
+    "Do not open a browser. Print the sign-in URL, then finish the sign-in from the callback address (`http://127.0.0.1:<port>/callback?...`, or just its query) pasted on stdin, or from the loopback port itself, whichever comes first."
+  ).option("--manual", "Same as --no-browser.").option("--print-url", "Also write the sign-in URL to stdout, alone on its line, before waiting.").option(
+    "--json",
+    'Write JSON lines to stdout: {"loginUrl","port","callbackUrl"} before waiting, then the account ({"userId","userName","site","tokenPath"}) once signed in.'
+  ).action(
+    async (opts) => {
+      const { config, logger } = getRuntime();
+      const manual = opts.manual || !opts.browser;
+      const s = createHarmonyOsSession2({
+        config,
+        logger,
+        onLoginUrl: (url, { port }) => {
+          const callbackUrl = `http://127.0.0.1:${port}/callback`;
+          if (opts.json) process.stdout.write(`${JSON.stringify({ loginUrl: url, port, callbackUrl })}
 `);
-  });
+          else if (opts.printUrl) process.stdout.write(`${url}
+`);
+          process.stderr.write(manual ? manualInstructions(url, callbackUrl, port) : browserInstructions(url));
+        }
+      });
+      const stdin = manual ? readline.createInterface({ input: process.stdin, terminal: false }) : void 0;
+      let user;
+      try {
+        user = await s.login({
+          timeoutMs: opts.timeout ? Math.max(1, opts.timeout) * 1e3 : void 0,
+          port: opts.port,
+          openBrowser: !manual,
+          pastedCallbacks: stdin
+        });
+      } finally {
+        stdin?.close();
+        if (stdin) process.stdin.destroy();
+      }
+      if (opts.json) {
+        const status = { userId: user.userId, userName: user.userName, site: user.siteCode, tokenPath: s.tokenPath };
+        process.stdout.write(`${JSON.stringify(status)}
+`);
+        return;
+      }
+      process.stdout.write(`${user.userName || user.userId}
+`);
+    }
+  );
   auth.command("logout").description("Sign out and delete the stored token.").action(async () => {
     const signedOut = await session().logout();
     getRuntime().logger.info(signedOut ? "Signed out." : "Not signed in; nothing to do.");
@@ -574,6 +828,7 @@ function registerAuthCommand(program) {
 }
 
 // src/commands/app.ts
+import * as os2 from "os";
 import * as path4 from "path";
 import {
   installApp,
@@ -584,164 +839,444 @@ import {
   existingHapOrUnsigned,
   getBundleName,
   readHapBundleName,
-  OniroError as OniroError2
-} 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-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 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."
-  ).option("--bundle <bundle>", "Launch an already-installed app by bundle name (no project needed).").option("--module <module>", "Module folder name (project mode).", "entry").option("--ability <name>", "Explicit ability to launch (defaults to the module mainElement in project mode, or the installed bundle main ability in --bundle mode).").option("--device <serial>", "Target device serial.").action(async (projectDir, opts) => {
-    const { config, logger } = getRuntime();
-    if (opts.bundle) {
-      logger.info(`Launching installed bundle ${opts.bundle}...`);
-      await launchApp({ config, bundleName: opts.bundle, abilityName: opts.ability, deviceSerial: opts.device, logger });
-    } else {
-      const dir = path4.resolve(projectDir ?? process.cwd());
-      logger.info(`Launching app from ${dir}...`);
-      await launchApp({ config, projectDir: dir, moduleName: opts.module, abilityName: opts.ability, deviceSerial: opts.device, logger });
-    }
-    logger.info("App launched.");
-  });
-  app.command("apply [project-dir-or-hap]").description(
-    "Install a HAP (a project dir, default the current one, or a .hap file) and verify the running process took the change. Refuses a HAP of another bundle. Handles sign-info mismatch, asset-cache invalidation, and persistent-bundle restart."
-  ).option(
-    "--bundle <bundle>",
-    "Bundle name to apply changes to. Defaults to the bundleName in the .hap file, else in the project AppScope/app.json5."
-  ).option("--module <module>", "Module to resolve the HAP from (multi-module projects).").option("--hap <path>", "Explicit .hap path (relative to project-dir or absolute).").option("--installed-hap <path>", "Local path to the currently-installed HAP, to enable the asset-cache reboot.").option("--system", "Treat as a persistent/system bundle (refuses uninstall on sign-info mismatch).").option("--allow-uninstall", "Permit uninstalling a system bundle on sign-info mismatch (dangerous).").option("--device <serial>", "Target device serial.").option("--json", "Emit the result as JSON.").action(async (target, opts) => {
-    const { config, logger } = getRuntime();
-    const isHap = target !== void 0 && /\.hap$/i.test(target);
-    if (isHap && opts.hap) throw new OniroError2("Pass the HAP either as the argument or with --hap, not both.");
-    const dir = isHap ? process.cwd() : path4.resolve(target ?? process.cwd());
-    const hapPath = isHap ? path4.resolve(target) : opts.hap;
-    let bundle = opts.bundle;
-    if (!bundle && isHap) {
-      const hap = existingHapOrUnsigned(hapPath);
-      if (!hap) throw new OniroError2(`HAP not found at ${hapPath}.`);
-      bundle = await readHapBundleName(hap.path).catch(() => null) ?? void 0;
-      if (!bundle) throw new OniroError2(`Could not read the bundle name from ${hap.path}. Pass --bundle.`);
-    }
-    bundle ??= getBundleName(dir);
-    const result = await applyChanges({
-      config,
-      bundle,
-      hapPath,
-      projectDir: dir,
-      module: opts.module,
-      installedHapPath: opts.installedHap,
-      isSystemBundle: opts.system,
-      allowUninstall: opts.allowUninstall,
-      deviceSerial: opts.device,
-      logger
-    });
-    if (opts.json) {
-      process.stdout.write(`${JSON.stringify(result, null, 2)}
-`);
-    } else {
-      logger.info(
-        `apply: method=${result.method} pid ${result.preInstallPid ?? "-"} -> ${result.postInstallPid ?? "-"}${result.cacheCleared ? " (cache cleared)" : ""}`
-      );
-    }
-  });
-  app.command("uninstall <bundle>").description("Uninstall an app by bundle name.").option("--device <serial>", "Target device serial.").action(async (bundle, opts) => {
-    const { config, logger } = getRuntime();
-    await uninstallApp({ config, bundle, deviceSerial: opts.device, logger });
-    logger.info(`Uninstalled ${bundle}.`);
-  });
-  app.command("stop <bundle>").description("Force-stop an app by bundle name.").option("--device <serial>", "Target device serial.").action(async (bundle, opts) => {
-    const { config, logger } = getRuntime();
-    await forceStop({ config, bundle, deviceSerial: opts.device, logger });
-    logger.info(`Stopped ${bundle}.`);
-  });
-}
-
-// src/commands/create.ts
-import * as path6 from "path";
-import {
-  ALL_SDKS as ALL_SDKS2,
-  createScaffold,
-  isValidBundleName,
-  isValidProjectName
+  smokeCheck,
+  latestCrash,
+  wakeAndUnlock,
+  DEFAULT_SMOKE_DELAY_MS,
+  OniroError as OniroError3
 } from "@oniroproject/core";
 
-// src/lib/templateRoot.ts
-import * as fs2 from "fs";
-import * as path5 from "path";
-import { fileURLToPath } from "url";
-function getBundledTemplateRoot() {
-  const here = path5.dirname(fileURLToPath(import.meta.url));
-  const candidates = [
-    path5.resolve(here, "../templates"),
-    // dist/oniro-app.js → ../templates
-    path5.resolve(here, "../../templates")
-    // src/bin/oniro-app.ts → ../../templates
-  ];
-  for (const c of candidates) {
-    if (fs2.existsSync(c)) return c;
+// src/lib/screenshotImage.ts
+import sharp from "sharp";
+import { compareImages } from "@oniroproject/core";
+function buildGridSvg(width, height) {
+  const lineColor = "rgba(255,80,80,0.55)";
+  const labelBg = "rgba(0,0,0,0.7)";
+  const labelFg = "#fff";
+  const fontSize = Math.max(10, Math.round(Math.min(width, height) / 60));
+  const padding = Math.round(fontSize * 0.4);
+  const labels = [];
+  const lines = [];
+  for (let i = 0; i <= 10; i++) {
+    const f = i / 10;
+    const x = Math.round(f * (width - 1));
+    const y = Math.round(f * (height - 1));
+    if (i > 0 && i < 10) {
+      lines.push(`<line x1="${x}" y1="0" x2="${x}" y2="${height}" stroke="${lineColor}" stroke-width="1"/>`);
+      lines.push(`<line x1="0" y1="${y}" x2="${width}" y2="${y}" stroke="${lineColor}" stroke-width="1"/>`);
+    }
+    const tag = f.toFixed(1);
+    const tx = i === 0 ? padding : i === 10 ? width - padding : x;
+    const anchorX = i === 0 ? "start" : i === 10 ? "end" : "middle";
+    labels.push(
+      `<text x="${tx}" y="${fontSize + padding}" font-family="monospace" font-size="${fontSize}" font-weight="bold" fill="${labelFg}" stroke="${labelBg}" stroke-width="3" paint-order="stroke" text-anchor="${anchorX}">${tag}</text>`
+    );
+    const ty = i === 0 ? fontSize + padding : i === 10 ? height - padding : y + fontSize / 3;
+    labels.push(
+      `<text x="${padding}" y="${ty}" font-family="monospace" font-size="${fontSize}" font-weight="bold" fill="${labelFg}" stroke="${labelBg}" stroke-width="3" paint-order="stroke" text-anchor="start">${tag}</text>`
+    );
   }
-  return candidates[0];
+  labels.push(
+    `<text x="${width / 2}" y="${fontSize * 2.4 + padding}" font-family="monospace" font-size="${fontSize}" font-weight="bold" fill="${labelFg}" stroke="${labelBg}" stroke-width="3" paint-order="stroke" text-anchor="middle">X \u2192</text>`
+  );
+  labels.push(
+    `<text x="${padding}" y="${fontSize * 2.6 + padding}" font-family="monospace" font-size="${fontSize}" font-weight="bold" fill="${labelFg}" stroke="${labelBg}" stroke-width="3" paint-order="stroke" text-anchor="start">Y \u2193</text>`
+  );
+  return `<svg width="${width}" height="${height}" xmlns="http://www.w3.org/2000/svg">${lines.join("")}${labels.join("")}</svg>`;
 }
-
-// src/commands/create.ts
-function registerCreateCommand(program) {
-  program.command("create").description("Scaffold a new Oniro/OpenHarmony or HarmonyOS app from a template. All flags are required (non-interactive).").requiredOption("--name <name>", "Project folder name (letters, digits, ._- only)").requiredOption("--bundle <bundleName>", "Bundle name in reverse-DNS form, e.g. com.example.myapp").requiredOption("--location <dir>", "Parent directory where the new project folder will be created").requiredOption("--sdk <api>", "Target SDK API level (e.g. 18, 20)").option("--template <id>", "Template id", "EmptyAbility").option("--module <name>", "Module folder name (defaults to the template default, usually `entry`)").option("--overwrite", "Replace the destination if it already exists").action(async (opts) => {
-    const { config, logger } = getRuntime();
-    if (!isValidProjectName(opts.name)) {
-      throw new Error(`Invalid --name '${opts.name}'. Use letters/numbers/._- and no slashes.`);
-    }
-    if (!isValidBundleName(opts.bundle)) {
-      throw new Error(`Invalid --bundle '${opts.bundle}'. Example: com.example.myapp`);
-    }
-    const sdkApi = Number(opts.sdk);
-    if (!Number.isFinite(sdkApi)) {
-      throw new Error(`--sdk must be a numeric api level. Known: ${ALL_SDKS2.map((s) => s.api).join(", ")}`);
-    }
-    const templateRoot = getBundledTemplateRoot();
-    const result = await createScaffold({
-      config,
-      templateId: opts.template,
-      projectName: opts.name,
-      bundleName: opts.bundle,
-      location: path6.resolve(opts.location),
-      sdkApi,
-      moduleName: opts.module,
-      templateRoot,
-      overwrite: opts.overwrite,
-      logger
-    });
-    logger.info(`Project created at ${result.projectDir}`);
-    process.stdout.write(`${result.projectDir}
-`);
-  });
+async function renderWithGrid(jpeg2, opts) {
+  const meta = await sharp(jpeg2).metadata();
+  const originalWidth = meta.width ?? 0;
+  const originalHeight = meta.height ?? 0;
+  const longest = Math.max(originalWidth, originalHeight) || 1;
+  const scale = Math.min(1, opts.maxDim / longest);
+  const width = Math.max(1, Math.round(originalWidth * scale));
+  const height = Math.max(1, Math.round(originalHeight * scale));
+  const resized = await sharp(jpeg2).resize(width, height).jpeg({ quality: 80 }).toBuffer();
+  if (!opts.grid) {
+    return { buf: resized, width, height, originalWidth, originalHeight };
+  }
+  const svg = buildGridSvg(width, height);
+  const buf = await sharp(resized).composite([{ input: Buffer.from(svg) }]).jpeg({ quality: 80 }).toBuffer();
+  return { buf, width, height, originalWidth, originalHeight };
 }
-
-// src/commands/templates.ts
-import { listTemplates } from "@oniroproject/core";
+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(jpeg2, rect, opts) {
+  const meta = await sharp(jpeg2).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(jpeg2).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);
+  let label = `#${idx}`;
+  if (typeof diff === "number") label += `  \u0394${diff.toFixed(2)}`;
+  const boxW = Math.round(label.length * fontSize * 0.62) + pad * 2;
+  const boxH = fontSize + pad * 2;
+  return `<svg width="${width}" height="${height}" xmlns="http://www.w3.org/2000/svg"><rect x="0" y="0" width="${boxW}" height="${boxH}" fill="rgba(0,0,0,0.6)"/><text x="${pad}" y="${fontSize + pad - 1}" font-family="monospace" font-size="${fontSize}" font-weight="bold" fill="#fff" stroke="rgba(0,0,0,0.85)" stroke-width="3" paint-order="stroke" text-anchor="start">${label}</text></svg>`;
+}
+async function buildContactSheet(frames, opts) {
+  if (frames.length === 0) throw new Error("buildContactSheet: no frames");
+  const count = frames.length;
+  const cols = Math.max(1, opts.cols ?? Math.ceil(Math.sqrt(count)));
+  const rows = Math.ceil(count / cols);
+  const gap = opts.gap ?? 8;
+  const meta0 = await sharp(frames[0]).metadata();
+  const fw = meta0.width ?? 1;
+  const fh = meta0.height ?? 1;
+  const longest = Math.max(fw, fh) || 1;
+  const tileScale = Math.min(1, opts.maxDim / cols / longest);
+  const tileWidth = Math.max(1, Math.round(fw * tileScale));
+  const tileHeight = Math.max(1, Math.round(fh * tileScale));
+  const tiles = await Promise.all(
+    frames.map((frame, i) => {
+      const label = Buffer.from(buildTileLabelSvg(tileWidth, tileHeight, i, opts.diffs?.[i]));
+      return sharp(frame).resize(tileWidth, tileHeight, { fit: "fill" }).composite([{ input: label, top: 0, left: 0 }]).png().toBuffer();
+    })
+  );
+  const width = cols * tileWidth + (cols + 1) * gap;
+  const height = rows * tileHeight + (rows + 1) * gap;
+  const placements = tiles.map((input2, i) => {
+    const r = Math.floor(i / cols);
+    const c = i % cols;
+    return { input: input2, left: gap + c * (tileWidth + gap), top: gap + r * (tileHeight + gap) };
+  });
+  const buf = await sharp({
+    create: { width, height, channels: 3, background: { r: 20, g: 20, b: 20 } }
+  }).composite(placements).jpeg({ quality: 80 }).toBuffer();
+  return { buf, width, height, cols, rows, tileWidth, tileHeight, count };
+}
+async function frameDiffs(frames, opts = {}) {
+  if (frames.length === 0) return [];
+  const sample = opts.sample ?? 32;
+  const thumbs = await Promise.all(
+    frames.map((f) => sharp(f).greyscale().resize(sample, sample, { fit: "fill" }).raw().toBuffer())
+  );
+  const out = [0];
+  for (let i = 1; i < thumbs.length; i++) {
+    const a = thumbs[i - 1];
+    const b = thumbs[i];
+    if (!a || !b) {
+      out.push(0);
+      continue;
+    }
+    const n = Math.min(a.length, b.length) || 1;
+    let s = 0;
+    for (let k = 0; k < n; k++) s += Math.abs((a[k] ?? 0) - (b[k] ?? 0));
+    out.push(+(s / n / 255).toFixed(4));
+  }
+  return out;
+}
+async function decodeGreyscale(jpeg2, maxDim = 512) {
+  const { data, info } = await sharp(jpeg2).greyscale().resize(maxDim, maxDim, { fit: "inside", withoutEnlargement: true }).raw().toBuffer({ resolveWithObject: true });
+  const n = info.width * info.height;
+  const grey = new Uint8Array(n);
+  for (let i = 0; i < n; i++) grey[i] = data[i * info.channels];
+  return { width: info.width, height: info.height, data: grey };
+}
+async function diffScreenshots(baseline, current) {
+  const [a, b] = await Promise.all([decodeGreyscale(baseline), decodeGreyscale(current)]);
+  const [, meanDiff] = await frameDiffs([baseline, current]);
+  return { ...compareImages(a, b), meanDiff: meanDiff ?? 0 };
+}
+
+// src/commands/appVerify.ts
+import { formatHapVerification, verifyHap, verifyHapExitCode } from "@oniroproject/core";
+function registerAppVerifyCommand(app) {
+  app.command("verify <hap>").description(
+    "Verify a HAP's signature with the SDK's hap-sign-tool (`verify-app`), then report what signed it: the certificate chain and its root, whether it is OpenHarmony development material or a HarmonyOS certificate from AppGallery Connect (root Huawei CBG Root CA G2), and the provisioning profile: type, bundle name, apl, app-feature, devices, validity and days left. Exits 0 when valid, 1 when unsigned, invalid, expired or mismatched, 2 when it could not verify (no java or hap-sign-tool.jar). Needs java."
+  ).option("--json", "Emit the result as JSON.").action(async (hap, opts) => {
+    const { config, logger } = getRuntime();
+    const result = await verifyHap({ hapPath: hap, config, logger });
+    process.stdout.write(opts.json ? `${JSON.stringify(result, null, 2)}
+` : formatHapVerification(result));
+    process.exitCode = verifyHapExitCode(result);
+  });
+}
+
+// src/commands/app.ts
+function addSmokeOptions(cmd) {
+  return cmd.option(
+    "--smoke",
+    "After launch, wait for the process, take a screenshot after --smoke-delay, and fail (exit 1) when the process died or the screen is blank."
+  ).option("--smoke-delay <ms>", "With --smoke: wait between the process appearing and the screenshot.", String(DEFAULT_SMOKE_DELAY_MS)).option("--smoke-screenshot <file>", "With --smoke: where to write the screenshot (default: a file in the system temp dir).");
+}
+function smokeDelayFrom(raw) {
+  const n = Number(raw);
+  if (!Number.isFinite(n) || n < 0) throw new OniroError3(`--smoke-delay expects a number of milliseconds; got "${raw}".`);
+  return Math.round(n);
+}
+async function wakeForSmoke(config, logger, device) {
+  const screen = await wakeAndUnlock({ config, deviceSerial: device, logger }).catch((err) => {
+    logger.warn(`Could not wake the screen: ${err.message}`);
+    return null;
+  });
+  if (screen?.locked) logger.warn("The lock screen asks for a credential; the smoke screenshot will show it.");
+}
+var CRASH_CLOCK_SLACK_MS = 2e3;
+var CRASH_WAIT_MS = 15e3;
+function runSmoke(config, logger, bundle, since, opts) {
+  const screenshotPath = opts.smokeScreenshot ? path4.resolve(opts.smokeScreenshot) : path4.join(os2.tmpdir(), `oniro-smoke-${bundle}-${since.getTime()}.jpeg`);
+  return smokeCheck({
+    config,
+    bundle,
+    since,
+    delayMs: smokeDelayFrom(opts.smokeDelay),
+    screenshotPath,
+    decodeGreyscale: (jpeg2) => decodeGreyscale(jpeg2),
+    crashProbe: (probe) => latestCrash({
+      config: probe.config,
+      bundle: probe.bundle,
+      // Faultlog times are the device's clock, which need not agree with the host's:
+      // ask for "as long ago as the launch" on the device's clock, plus a little slack.
+      since: (Date.now() - probe.since.getTime() + CRASH_CLOCK_SLACK_MS) / 1e3,
+      // hiview writes the faultlog seconds after a death; a live app is looked up once.
+      waitMs: probe.alive ? 0 : CRASH_WAIT_MS,
+      deviceSerial: probe.deviceSerial,
+      logger: probe.logger
+    }),
+    deviceSerial: opts.device,
+    logger
+  });
+}
+function formatSmoke(s) {
+  const parts = [
+    s.pid === null ? "no process" : `pid ${s.pid} ${s.alive ? "alive" : "died"}`,
+    s.blankScreen === null ? "blank check skipped" : `${s.blankScreen ? "blank" : "not blank"} (score ${s.blankScore})`
+  ];
+  if (s.crash) {
+    const where = s.crash.file ? ` at ${s.crash.file}:${s.crash.line ?? "?"}` : "";
+    parts.push(`${s.crash.kind ?? "crash"}${s.crash.reason ? ` (${s.crash.reason})` : ""}${where}`);
+  }
+  if (s.screenshot) parts.push(`screenshot ${s.screenshot}`);
+  return `smoke: ${s.passed ? "passed" : `FAILED (${s.failures.join("; ")})`}: ${parts.join(", ")}`;
+}
+async function launchWithSmoke(rt2, p) {
+  const { config, logger } = rt2;
+  const smokeDelay = p.smokeDelay ?? DEFAULT_SMOKE_DELAY_MS;
+  if (p.smoke) {
+    smokeDelayFrom(smokeDelay);
+    await wakeForSmoke(config, logger, p.device);
+  }
+  const since = /* @__PURE__ */ new Date();
+  let bundle;
+  if (p.bundle) {
+    bundle = p.bundle;
+    logger.info(`Launching installed bundle ${p.bundle}...`);
+    await launchApp({ config, bundleName: p.bundle, abilityName: p.ability, deviceSerial: p.device, logger });
+  } else {
+    const dir = path4.resolve(p.projectDir ?? process.cwd());
+    bundle = getBundleName(dir);
+    logger.info(`Launching app from ${dir}...`);
+    await launchApp({
+      config,
+      projectDir: dir,
+      moduleName: p.module ?? "entry",
+      abilityName: p.ability,
+      deviceSerial: p.device,
+      logger
+    });
+  }
+  logger.info("App launched.");
+  if (!p.smoke) return { bundle };
+  const smoke = await runSmoke(config, logger, bundle, since, { ...p, smokeDelay });
+  return { bundle, smoke };
+}
+async function applyWithSmoke(rt2, p) {
+  const { config, logger } = rt2;
+  const smokeDelay = p.smokeDelay ?? DEFAULT_SMOKE_DELAY_MS;
+  if (p.smoke) smokeDelayFrom(smokeDelay);
+  const target = p.target;
+  const isHap = target !== void 0 && /\.hap$/i.test(target);
+  if (isHap && p.hap) throw new OniroError3("Pass the HAP either as the argument or with --hap, not both.");
+  const dir = isHap ? process.cwd() : path4.resolve(target ?? process.cwd());
+  const hapPath = isHap ? path4.resolve(target) : p.hap;
+  let bundle = p.bundle;
+  if (!bundle && isHap) {
+    const hap = existingHapOrUnsigned(hapPath);
+    if (!hap) throw new OniroError3(`HAP not found at ${hapPath}.`);
+    bundle = await readHapBundleName(hap.path).catch(() => null) ?? void 0;
+    if (!bundle) throw new OniroError3(`Could not read the bundle name from ${hap.path}. Pass --bundle.`);
+  }
+  bundle ??= getBundleName(dir);
+  const result = await applyChanges({
+    config,
+    bundle,
+    hapPath,
+    projectDir: dir,
+    module: p.module,
+    installedHapPath: p.installedHap,
+    isSystemBundle: p.system,
+    allowUninstall: p.allowUninstall,
+    deviceSerial: p.device,
+    logger
+  });
+  if (!p.smoke) return result;
+  await wakeForSmoke(config, logger, p.device);
+  const since = /* @__PURE__ */ new Date();
+  logger.info(`Launching ${bundle} for the smoke check...`);
+  await launchApp({ config, bundleName: bundle, deviceSerial: p.device, logger });
+  const smoke = await runSmoke(config, logger, bundle, since, { ...p, smokeDelay });
+  return { ...result, smoke };
+}
+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-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 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}.`);
+  });
+  const launch2 = 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."
+  ).option("--bundle <bundle>", "Launch an already-installed app by bundle name (no project needed).").option("--module <module>", "Module folder name (project mode).", "entry").option("--ability <name>", "Explicit ability to launch (defaults to the module mainElement in project mode, or the installed bundle main ability in --bundle mode).").option("--device <serial>", "Target device serial.");
+  addSmokeOptions(launch2).option("--json", "With --smoke: emit `{ bundle, smoke }` as JSON.").action(async (projectDir, opts) => {
+    const { config, logger } = getRuntime();
+    const { bundle, smoke } = await launchWithSmoke({ config, logger }, { ...opts, projectDir });
+    if (!smoke) return;
+    if (opts.json) process.stdout.write(`${JSON.stringify({ bundle, smoke }, null, 2)}
+`);
+    else process.stdout.write(`${formatSmoke(smoke)}
+`);
+    if (!smoke.passed) process.exitCode = 1;
+  });
+  const apply2 = app.command("apply [project-dir-or-hap]").description(
+    "Install a HAP (a project dir, default the current one, or a .hap file) and verify the running process took the change. Refuses a HAP of another bundle. Handles sign-info mismatch, asset-cache invalidation, and persistent-bundle restart."
+  ).option(
+    "--bundle <bundle>",
+    "Bundle name to apply changes to. Defaults to the bundleName in the .hap file, else in the project AppScope/app.json5."
+  ).option("--module <module>", "Module to resolve the HAP from (multi-module projects).").option("--hap <path>", "Explicit .hap path (relative to project-dir or absolute).").option("--installed-hap <path>", "Local path to the currently-installed HAP, to enable the asset-cache reboot.").option("--system", "Treat as a persistent/system bundle (refuses uninstall on sign-info mismatch).").option("--allow-uninstall", "Permit uninstalling a system bundle on sign-info mismatch (dangerous).").option("--device <serial>", "Target device serial.").option("--json", "Emit the result as JSON (with --smoke, plus a `smoke` object).");
+  addSmokeOptions(apply2).action(async (target, opts) => {
+    const { config, logger } = getRuntime();
+    const report = await applyWithSmoke({ config, logger }, { ...opts, target });
+    const { smoke, ...result } = report;
+    if (opts.json) {
+      process.stdout.write(`${JSON.stringify(report, null, 2)}
+`);
+    } else {
+      logger.info(
+        `apply: method=${result.method} pid ${result.preInstallPid ?? "-"} -> ${result.postInstallPid ?? "-"}${result.cacheCleared ? " (cache cleared)" : ""}`
+      );
+      if (smoke) process.stdout.write(`${formatSmoke(smoke)}
+`);
+    }
+    if (smoke && !smoke.passed) process.exitCode = 1;
+  });
+  app.command("uninstall <bundle>").description("Uninstall an app by bundle name.").option("--device <serial>", "Target device serial.").action(async (bundle, opts) => {
+    const { config, logger } = getRuntime();
+    await uninstallApp({ config, bundle, deviceSerial: opts.device, logger });
+    logger.info(`Uninstalled ${bundle}.`);
+  });
+  app.command("stop <bundle>").description("Force-stop an app by bundle name.").option("--device <serial>", "Target device serial.").action(async (bundle, opts) => {
+    const { config, logger } = getRuntime();
+    await forceStop({ config, bundle, deviceSerial: opts.device, logger });
+    logger.info(`Stopped ${bundle}.`);
+  });
+  registerAppVerifyCommand(app);
+}
+
+// src/commands/create.ts
+import * as path6 from "path";
+import {
+  ALL_SDKS as ALL_SDKS2,
+  createScaffold,
+  isValidBundleName,
+  isValidProjectName
+} from "@oniroproject/core";
+
+// src/lib/templateRoot.ts
+import * as fs2 from "fs";
+import * as path5 from "path";
+import { fileURLToPath } from "url";
+function getBundledTemplateRoot() {
+  const here = path5.dirname(fileURLToPath(import.meta.url));
+  const candidates = [
+    path5.resolve(here, "../templates"),
+    // dist/oniro-app.js → ../templates
+    path5.resolve(here, "../../templates")
+    // src/bin/oniro-app.ts → ../../templates
+  ];
+  for (const c of candidates) {
+    if (fs2.existsSync(c)) return c;
+  }
+  return candidates[0];
+}
+
+// src/commands/create.ts
+function registerCreateCommand(program) {
+  program.command("create").description("Scaffold a new Oniro/OpenHarmony or HarmonyOS app from a template. All flags are required (non-interactive).").requiredOption("--name <name>", "Project folder name (letters, digits, ._- only)").requiredOption("--bundle <bundleName>", "Bundle name in reverse-DNS form, e.g. com.example.myapp").requiredOption("--location <dir>", "Parent directory where the new project folder will be created").requiredOption("--sdk <api>", "Target SDK API level (e.g. 18, 20)").option("--template <id>", "Template id", "EmptyAbility").option("--module <name>", "Module folder name (defaults to the template default, usually `entry`)").option("--overwrite", "Replace the destination if it already exists").action(async (opts) => {
+    const { config, logger } = getRuntime();
+    if (!isValidProjectName(opts.name)) {
+      throw new Error(`Invalid --name '${opts.name}'. Use letters/numbers/._- and no slashes.`);
+    }
+    if (!isValidBundleName(opts.bundle)) {
+      throw new Error(`Invalid --bundle '${opts.bundle}'. Example: com.example.myapp`);
+    }
+    const sdkApi = Number(opts.sdk);
+    if (!Number.isFinite(sdkApi)) {
+      throw new Error(`--sdk must be a numeric api level. Known: ${ALL_SDKS2.map((s) => s.api).join(", ")}`);
+    }
+    const templateRoot = getBundledTemplateRoot();
+    const result = await createScaffold({
+      config,
+      templateId: opts.template,
+      projectName: opts.name,
+      bundleName: opts.bundle,
+      location: path6.resolve(opts.location),
+      sdkApi,
+      moduleName: opts.module,
+      templateRoot,
+      overwrite: opts.overwrite,
+      logger
+    });
+    logger.info(`Project created at ${result.projectDir}`);
+    process.stdout.write(`${result.projectDir}
+`);
+  });
+}
+
+// src/commands/templates.ts
+import { listTemplates } from "@oniroproject/core";
 function registerTemplatesCommand(program) {
   const templates = program.command("templates").description("Inspect the templates bundled with this CLI.");
   templates.command("list").description("List available project templates.").option("--json", "Emit machine-readable JSON.").action((opts) => {
     const root = getBundledTemplateRoot();
-    const list = listTemplates(root);
+    const list2 = listTemplates(root);
     if (opts.json) {
-      process.stdout.write(`${JSON.stringify(list, null, 2)}
+      process.stdout.write(`${JSON.stringify(list2, null, 2)}
 `);
       return;
     }
-    if (list.length === 0) {
+    if (list2.length === 0) {
       process.stdout.write("No templates available.\n");
       return;
     }
-    const rows = list.map((t) => `${t.id.padEnd(20)} ${t.label.padEnd(24)} ${t.description}`);
+    const rows = list2.map((t) => `${t.id.padEnd(20)} ${t.label.padEnd(24)} ${t.description}`);
     process.stdout.write(`${rows.join("\n")}
 `);
   });
@@ -774,6 +1309,9 @@ function registerRebootCommand(program) {
 import { waitForLog, waitForBoot, waitForBundle, waitForTarget, describeLayoutNode } from "@oniroproject/core";
 
 // src/lib/target.ts
+import { parseSelector } from "@oniroproject/core";
+var SELECTOR_HELP = `An attribute selector such as "type=Button,text*=Sign" (keys text, desc, hint, id, key, type, enabled, focused, checked, selected, visible, clickable, longClickable, checkable, scrollable; operators = *= ^= $= /=regex; a [n] suffix picks the n-th match, 0-based, [-1] or [last] the last), or "xpath=//Button[@text='OK']".`;
+var WINDOW_HELP = "Restrict to one window: a window id from `dump layout --flat` ([window <id> \u2026]) or `dump windows`.";
 function addTargetOptions(cmd, verb, opts = {}) {
   cmd.option(
     "--target <text>",
@@ -782,10 +1320,20 @@ function addTargetOptions(cmd, verb, opts = {}) {
   if (opts.index !== false) {
     cmd.option("--target-index <n>", "Pick the n-th (0-based) of several matching elements.");
   }
+  cmd.option("--selector <expr>", `Instead of --target*: ${SELECTOR_HELP}`).option("--window <id>", WINDOW_HELP);
   return cmd;
 }
+function parseSelectorOption(raw) {
+  return raw === void 0 ? void 0 : parseSelector(raw);
+}
 function selectorFrom(opts) {
-  if (opts.target === void 0 && opts.targetId === void 0 && opts.targetType === void 0) return void 0;
+  const plain = opts.target !== void 0 || opts.targetId !== void 0 || opts.targetType !== void 0;
+  if (opts.selector !== void 0) {
+    if (plain) throw new Error("Use either --selector or --target / --target-id / --target-type, not both.");
+    if (opts.targetIndex !== void 0) throw new Error("--target-index does not apply to --selector; append [n] to the selector.");
+    return parseSelector(opts.selector);
+  }
+  if (!plain) return void 0;
   return { text: opts.target, id: opts.targetId, type: opts.targetType };
 }
 function targetIndexFrom(opts) {
@@ -794,6 +1342,12 @@ function targetIndexFrom(opts) {
   if (!Number.isInteger(n) || n < 0) throw new Error(`--target-index must be a non-negative integer; got ${opts.targetIndex}.`);
   return n;
 }
+function windowIdFrom(opts) {
+  if (opts.window === void 0) return void 0;
+  const n = Number(opts.window);
+  if (!Number.isInteger(n) || n < 0) throw new Error(`--window must be a window id (a non-negative integer); got ${opts.window}.`);
+  return n;
+}
 
 // src/lib/logSince.ts
 function parseSince(value) {
@@ -808,18 +1362,20 @@ function parseSince(value) {
 
 // src/commands/wait.ts
 function registerWaitCommand(program) {
-  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)."
+  const wait2 = 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, or --selector)."
   ).option("--log <pattern>", "Resolve when a hilog line (tag: message) logged after the command starts matches this regex.").option(
     "--since <seconds>",
     'With --log: also match lines logged up to N seconds before the command started, measured on the device clock; "all" matches everything still in the device log buffer.'
   ).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) => {
+  addTargetOptions(wait2, "Resolve when", { index: false });
+  wait2.option("--gone", "With --target* or --selector: resolve when no uncovered element matches any more.").option("--interval <ms>", "With --target* or --selector: 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, --target* or --selector: emit the matched entry/element as JSON.").action(async (opts) => {
     const { config, logger } = getRuntime();
     const timeoutMs = Number(opts.timeout);
     const selector = selectorFrom(opts);
+    const windowId = windowIdFrom(opts);
     if (opts.since !== void 0 && !opts.log) throw new Error("--since applies only to --log.");
+    if (windowId !== void 0 && !selector) throw new Error("--window applies only to --target* and --selector.");
     if (opts.log) {
       const entry = await waitForLog({
         config,
@@ -846,6 +1402,7 @@ function registerWaitCommand(program) {
         config,
         selector,
         gone: opts.gone,
+        windowId,
         timeoutMs,
         pollMs: Number(opts.interval) || 500,
         deviceSerial: opts.device,
@@ -865,7 +1422,9 @@ function registerWaitCommand(program) {
       logger.info(`Bundle ${opts.bundle} is running.`);
       return;
     }
-    throw new Error("Specify one of --log <pattern>, --boot, --bundle <bundle>, or --target <text> (or --target-id / --target-type).");
+    throw new Error(
+      "Specify one of --log <pattern>, --boot, --bundle <bundle>, --target <text> (or --target-id / --target-type), or --selector <expr>."
+    );
   });
 }
 
@@ -902,150 +1461,7 @@ function registerWatchCommand(program) {
 // src/commands/screenshot.ts
 import * as fs3 from "fs";
 import * as path7 from "path";
-import { takeScreenshot, captureBurst, locateTarget, describeLayoutNode as describeLayoutNode2 } from "@oniroproject/core";
-
-// src/lib/screenshotImage.ts
-import sharp from "sharp";
-function buildGridSvg(width, height) {
-  const lineColor = "rgba(255,80,80,0.55)";
-  const labelBg = "rgba(0,0,0,0.7)";
-  const labelFg = "#fff";
-  const fontSize = Math.max(10, Math.round(Math.min(width, height) / 60));
-  const padding = Math.round(fontSize * 0.4);
-  const labels = [];
-  const lines = [];
-  for (let i = 0; i <= 10; i++) {
-    const f = i / 10;
-    const x = Math.round(f * (width - 1));
-    const y = Math.round(f * (height - 1));
-    if (i > 0 && i < 10) {
-      lines.push(`<line x1="${x}" y1="0" x2="${x}" y2="${height}" stroke="${lineColor}" stroke-width="1"/>`);
-      lines.push(`<line x1="0" y1="${y}" x2="${width}" y2="${y}" stroke="${lineColor}" stroke-width="1"/>`);
-    }
-    const tag = f.toFixed(1);
-    const tx = i === 0 ? padding : i === 10 ? width - padding : x;
-    const anchorX = i === 0 ? "start" : i === 10 ? "end" : "middle";
-    labels.push(
-      `<text x="${tx}" y="${fontSize + padding}" font-family="monospace" font-size="${fontSize}" font-weight="bold" fill="${labelFg}" stroke="${labelBg}" stroke-width="3" paint-order="stroke" text-anchor="${anchorX}">${tag}</text>`
-    );
-    const ty = i === 0 ? fontSize + padding : i === 10 ? height - padding : y + fontSize / 3;
-    labels.push(
-      `<text x="${padding}" y="${ty}" font-family="monospace" font-size="${fontSize}" font-weight="bold" fill="${labelFg}" stroke="${labelBg}" stroke-width="3" paint-order="stroke" text-anchor="start">${tag}</text>`
-    );
-  }
-  labels.push(
-    `<text x="${width / 2}" y="${fontSize * 2.4 + padding}" font-family="monospace" font-size="${fontSize}" font-weight="bold" fill="${labelFg}" stroke="${labelBg}" stroke-width="3" paint-order="stroke" text-anchor="middle">X \u2192</text>`
-  );
-  labels.push(
-    `<text x="${padding}" y="${fontSize * 2.6 + padding}" font-family="monospace" font-size="${fontSize}" font-weight="bold" fill="${labelFg}" stroke="${labelBg}" stroke-width="3" paint-order="stroke" text-anchor="start">Y \u2193</text>`
-  );
-  return `<svg width="${width}" height="${height}" xmlns="http://www.w3.org/2000/svg">${lines.join("")}${labels.join("")}</svg>`;
-}
-async function renderWithGrid(jpeg, opts) {
-  const meta = await sharp(jpeg).metadata();
-  const originalWidth = meta.width ?? 0;
-  const originalHeight = meta.height ?? 0;
-  const longest = Math.max(originalWidth, originalHeight) || 1;
-  const scale = Math.min(1, opts.maxDim / longest);
-  const width = Math.max(1, Math.round(originalWidth * scale));
-  const height = Math.max(1, Math.round(originalHeight * scale));
-  const resized = await sharp(jpeg).resize(width, height).jpeg({ quality: 80 }).toBuffer();
-  if (!opts.grid) {
-    return { buf: resized, width, height, originalWidth, originalHeight };
-  }
-  const svg = buildGridSvg(width, height);
-  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);
-  let label = `#${idx}`;
-  if (typeof diff === "number") label += `  \u0394${diff.toFixed(2)}`;
-  const boxW = Math.round(label.length * fontSize * 0.62) + pad * 2;
-  const boxH = fontSize + pad * 2;
-  return `<svg width="${width}" height="${height}" xmlns="http://www.w3.org/2000/svg"><rect x="0" y="0" width="${boxW}" height="${boxH}" fill="rgba(0,0,0,0.6)"/><text x="${pad}" y="${fontSize + pad - 1}" font-family="monospace" font-size="${fontSize}" font-weight="bold" fill="#fff" stroke="rgba(0,0,0,0.85)" stroke-width="3" paint-order="stroke" text-anchor="start">${label}</text></svg>`;
-}
-async function buildContactSheet(frames, opts) {
-  if (frames.length === 0) throw new Error("buildContactSheet: no frames");
-  const count = frames.length;
-  const cols = Math.max(1, opts.cols ?? Math.ceil(Math.sqrt(count)));
-  const rows = Math.ceil(count / cols);
-  const gap = opts.gap ?? 8;
-  const meta0 = await sharp(frames[0]).metadata();
-  const fw = meta0.width ?? 1;
-  const fh = meta0.height ?? 1;
-  const longest = Math.max(fw, fh) || 1;
-  const tileScale = Math.min(1, opts.maxDim / cols / longest);
-  const tileWidth = Math.max(1, Math.round(fw * tileScale));
-  const tileHeight = Math.max(1, Math.round(fh * tileScale));
-  const tiles = await Promise.all(
-    frames.map((frame, i) => {
-      const label = Buffer.from(buildTileLabelSvg(tileWidth, tileHeight, i, opts.diffs?.[i]));
-      return sharp(frame).resize(tileWidth, tileHeight, { fit: "fill" }).composite([{ input: label, top: 0, left: 0 }]).png().toBuffer();
-    })
-  );
-  const width = cols * tileWidth + (cols + 1) * gap;
-  const height = rows * tileHeight + (rows + 1) * gap;
-  const placements = tiles.map((input, i) => {
-    const r = Math.floor(i / cols);
-    const c = i % cols;
-    return { input, left: gap + c * (tileWidth + gap), top: gap + r * (tileHeight + gap) };
-  });
-  const buf = await sharp({
-    create: { width, height, channels: 3, background: { r: 20, g: 20, b: 20 } }
-  }).composite(placements).jpeg({ quality: 80 }).toBuffer();
-  return { buf, width, height, cols, rows, tileWidth, tileHeight, count };
-}
-async function frameDiffs(frames, opts = {}) {
-  if (frames.length === 0) return [];
-  const sample = opts.sample ?? 32;
-  const thumbs = await Promise.all(
-    frames.map((f) => sharp(f).greyscale().resize(sample, sample, { fit: "fill" }).raw().toBuffer())
-  );
-  const out = [0];
-  for (let i = 1; i < thumbs.length; i++) {
-    const a = thumbs[i - 1];
-    const b = thumbs[i];
-    if (!a || !b) {
-      out.push(0);
-      continue;
-    }
-    const n = Math.min(a.length, b.length) || 1;
-    let s = 0;
-    for (let k = 0; k < n; k++) s += Math.abs((a[k] ?? 0) - (b[k] ?? 0));
-    out.push(+(s / n / 255).toFixed(4));
-  }
-  return out;
-}
-
-// src/commands/screenshot.ts
+import { takeScreenshot, captureBurst, locateTarget, describeLayoutNode as describeLayoutNode2, dumpLayout, listLayoutWindows } from "@oniroproject/core";
 var DEFAULT_CONTACT_SHEET_FRAMES = 8;
 var TARGET_CROP_PAD = 0.02;
 function clampMaxDim(raw) {
@@ -1054,19 +1470,53 @@ function clampMaxDim(raw) {
   return Math.max(256, Math.min(4096, Math.round(n)));
 }
 function registerScreenshotCommand(program) {
-  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."
+  const screenshot2 = 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 / --selector / --window: a full-resolution crop of one region, element or window, for checking detail cheaply. --contact-sheet: capture a burst and tile it into one image with per-frame change diffs. --diff: compare the screen with a baseline JPEG (perceptual-hash distance, pixel-change ratio)."
   ).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) => {
+  addTargetOptions(screenshot2, "Crop to");
+  screenshot2.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(
+    "--diff <baseline.jpeg>",
+    "Capture the screen (written to --output) and compare it with this baseline: pHash and dHash distance, pixel-change ratio, mean change."
+  ).option("--json", "Emit the full result object as JSON on stdout (with --contact-sheet or --diff).").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.");
+    const windowId = windowIdFrom(opts);
+    if (opts.diff !== void 0) {
+      if (opts.crop !== void 0 || selector || windowId !== void 0 || opts.grid || opts.contactSheet || opts.burst) {
+        throw new Error(
+          "--diff cannot be combined with --crop, --target* / --selector / --window, --grid, --contact-sheet, or --burst."
+        );
+      }
+      let baseline;
+      try {
+        baseline = fs3.readFileSync(opts.diff);
+      } catch (err) {
+        throw new Error(`Cannot read the baseline ${opts.diff}: ${err.message}`);
+      }
+      const shot2 = await takeScreenshot({ config, deviceSerial: opts.device, logger });
+      fs3.writeFileSync(opts.output, shot2.pixels);
+      const diff = await diffScreenshots(baseline, shot2.pixels);
+      const result = { baseline: opts.diff, current: opts.output, ...diff };
+      if (opts.json) {
+        process.stdout.write(`${JSON.stringify(result, null, 2)}
+`);
+      } else {
+        process.stdout.write(
+          `${diff.same ? "same" : "different"}: pHash ${diff.phashDistance}/64, dHash ${diff.dhashDistance}/64, ${(diff.pixelChangeRatio * 100).toFixed(2)}% of pixels changed, mean change ${diff.meanDiff.toFixed(4)}${diff.sizeMismatch ? " (sizes differ)" : ""}
+`
+        );
+      }
+      logger.info(`Wrote ${opts.output} (${shot2.width}x${shot2.height}).`);
+      return;
+    }
+    if (opts.crop !== void 0 || selector || windowId !== void 0) {
+      if (opts.crop !== void 0 && (selector || windowId !== void 0)) {
+        throw new Error("Use either --crop or --target* / --selector / --window, not both.");
+      }
       if (opts.grid || opts.contactSheet || opts.burst) {
-        throw new Error("--crop / --target cannot be combined with --grid, --contact-sheet, or --burst.");
+        throw new Error("--crop / --target / --selector / --window cannot be combined with --grid, --contact-sheet, or --burst.");
       }
       let rect;
       let label;
@@ -1075,6 +1525,7 @@ function registerScreenshotCommand(program) {
           config,
           selector,
           index: targetIndexFrom(opts),
+          windowId,
           hideKeyboard: false,
           deviceSerial: opts.device,
           logger
@@ -1082,6 +1533,12 @@ function registerScreenshotCommand(program) {
         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 if (windowId !== void 0) {
+        const { tree } = await dumpLayout({ config, windowId, deviceSerial: opts.device, logger });
+        const win = listLayoutWindows(tree).find((w) => w.windowId === windowId);
+        if (!win?.b) throw new Error(`Window ${windowId} has no bounds to crop to.`);
+        rect = win.b;
+        label = `window ${windowId}${win.bundle ? ` (${win.bundle})` : ""}`;
       } else {
         rect = parseCropRect(opts.crop);
         label = rect.map((n) => n.toFixed(3)).join(",");
@@ -1164,7 +1621,16 @@ function registerScreenshotCommand(program) {
 }
 
 // src/commands/dump.ts
-import { dumpLayout } from "@oniroproject/core";
+import * as fs4 from "fs";
+import {
+  diffLayouts,
+  dumpLayout as dumpLayout2,
+  findLayoutNodes,
+  listWindows,
+  parseLayoutBaseline,
+  selectableTree,
+  summarizeLayout
+} from "@oniroproject/core";
 
 // src/lib/layoutText.ts
 import { flattenLayout } from "@oniroproject/core";
@@ -1182,6 +1648,7 @@ function flags(n) {
   if (n.sel) out.push("selected");
   if (n.focus) out.push("focus");
   if (n.disabled) out.push("disabled");
+  if (n.hidden) out.push("hidden");
   if (n.covered) out.push("covered");
   return out;
 }
@@ -1200,6 +1667,9 @@ 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 windowLabel(windowId, bundle) {
+  return [windowId, bundle].filter((x) => x !== void 0).join(" ");
+}
 function formatFlatLayout(result) {
   const lines = [];
   const d = result.display;
@@ -1208,13 +1678,15 @@ function formatFlatLayout(result) {
   );
   const keyboardBundle = result.keyboard?.shown ? result.keyboard.bundle : void 0;
   let window;
+  let windowId;
   for (const n of flattenLayout(result.tree)) {
-    if (n.window !== window) {
+    if (n.window !== window || n.windowId !== windowId) {
       window = n.window;
+      windowId = n.windowId;
       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}]`);
+        lines.push(`[keyboard ${windowLabel(windowId, window)}] up \u2014 dismiss with input --type hideKeyboard`);
+      } else if (window !== void 0 || windowId !== void 0) {
+        lines.push(`[window ${windowLabel(windowId, window)}]`);
       }
     }
     if (window !== void 0 && window === keyboardBundle) continue;
@@ -1224,26 +1696,98 @@ function formatFlatLayout(result) {
   return `${lines.join("\n")}
 `;
 }
+function formatSelectorMatches(display, selector, matches) {
+  const lines = [
+    `# display ${display ? `${display.width}x${display.height}` : "unknown"}; ${matches.length} element(s) match ${JSON.stringify(selector)}${matches.length > 1 ? "; append [n] to the selector to act on one" : ""}`
+  ];
+  matches.forEach((n, i) => {
+    const win = windowLabel(n.windowId, n.window);
+    lines.push(`[${i}] ${formatLayoutLine(n)}${win ? ` (window ${win})` : ""}`);
+  });
+  return `${lines.join("\n")}
+`;
+}
 
 // src/commands/dump.ts
+function readBaseline(file) {
+  let text;
+  try {
+    text = fs4.readFileSync(file, "utf8");
+  } catch (err) {
+    throw new Error(`Cannot read the layout baseline ${file}: ${err.message}`);
+  }
+  try {
+    return parseLayoutBaseline(JSON.parse(text));
+  } catch (err) {
+    throw new Error(`${file} is not a saved \`dump layout\` JSON: ${err.message}`);
+  }
+}
+function formatWindows(windows) {
+  const lines = ["# id name pid type z-order [x y w h]; z-order -1 = not shown; `--window <id>` restricts dump/input/wait/screenshot"];
+  for (const w of windows) {
+    const rect = w.rect ? ` [${w.rect.join(" ")}]` : "";
+    lines.push(`${w.id} ${w.name} pid=${w.pid} type=${w.type} z=${w.zOrder}${rect}${w.focused ? " focused" : ""}`);
+  }
+  return `${lines.join("\n")}
+`;
+}
 function registerDumpCommand(program) {
   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) => {
+    "Dump device state. `dump layout` (the default target): JSON by default, or one line per element with --flat; --selector lists only the matching elements, --summary counts elements per window, --diff compares the live layout with one saved earlier. `dump windows`: the window list (ids for --window)."
+  ).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("--summary", "Per window: element, content, clickable and text-node counts (JSON).").option(
+    "--diff <baseline.json>",
+    "Compare with a saved `dump layout` JSON: matched elements with IoU, missing, extra, and a 0-1 similarity (JSON)."
+  ).option("--selector <expr>", `List only the elements matching this expression, numbered for its [n] suffix. ${SELECTOR_HELP}`).option("--window <id>", WINDOW_HELP).option("--json", "dump windows: print JSON instead of one line per window.").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 (what === "windows") {
+      const windows = await listWindows({ config, deviceSerial: opts.device, logger });
+      process.stdout.write(opts.json ? `${JSON.stringify(windows, null, 2)}
+` : formatWindows(windows));
+      return;
+    }
+    if (what !== "layout") throw new Error(`Unknown dump target "${what}". Supported: layout, windows.`);
     if (opts.raw && opts.flat) throw new Error("--raw and --flat cannot be combined.");
-    const result = await dumpLayout({
+    const selector = parseSelectorOption(opts.selector);
+    if (selector && opts.raw) throw new Error("--selector matches the pruned layout; it cannot be combined with --raw.");
+    const modes = [opts.flat && "--flat", opts.summary && "--summary", opts.diff !== void 0 && "--diff"].filter(Boolean);
+    if (modes.length > 1) throw new Error(`${modes.join(" and ")} cannot be combined.`);
+    if (opts.raw && modes.length > 0) throw new Error(`--raw cannot be combined with ${modes[0]}.`);
+    if (selector && (opts.summary || opts.diff !== void 0)) {
+      throw new Error(`--selector cannot be combined with ${opts.summary ? "--summary" : "--diff"}.`);
+    }
+    const baseline = opts.diff !== void 0 ? readBaseline(opts.diff) : void 0;
+    const result = await dumpLayout2({
       config,
       bundleName: opts.bundle,
+      windowId: windowIdFrom(opts),
       prune: !opts.raw,
       detectKeyboard: !opts.raw,
       deviceSerial: opts.device,
       logger
     });
-    process.stdout.write(opts.flat ? formatFlatLayout(result) : `${JSON.stringify(result, null, 2)}
-`);
+    if (selector) {
+      const matches = findLayoutNodes(selectableTree(result, windowIdFrom(opts)), selector);
+      process.stdout.write(
+        opts.flat ? formatSelectorMatches(result.display, selector.raw, matches) : `${JSON.stringify({ display: result.display, selector: selector.raw, matches }, null, 2)}
+`
+      );
+      return;
+    }
+    let out;
+    if (opts.flat) out = formatFlatLayout(result);
+    else if (opts.summary) out = `${JSON.stringify(summarizeLayout(result), null, 2)}
+`;
+    else if (baseline) {
+      const diff = diffLayouts(baseline, result);
+      logger.info(
+        `layout similarity ${diff.similarity.toFixed(3)}: ${diff.matched.length} matched (${diff.moved} moved, ${diff.changed} changed), ${diff.missing.length} missing, ${diff.extra.length} extra.`
+      );
+      out = `${JSON.stringify(diff, null, 2)}
+`;
+    } else out = `${JSON.stringify(result, null, 2)}
+`;
+    process.stdout.write(out);
   });
 }
 
@@ -1252,9 +1796,9 @@ import { getDeviceInfo, listDevices } from "@oniroproject/core";
 function formatLongDevice(d, info) {
   const head = `${d.serial}	${d.connection ?? ""}	${d.status}`;
   if (!info) return head;
-  const os3 = [info.osFamily, info.osFamily === "HarmonyOS" ? info.osDistVersion : void 0].filter(Boolean).join(" ");
+  const os5 = [info.osFamily, info.osFamily === "HarmonyOS" ? info.osDistVersion : void 0].filter(Boolean).join(" ");
   const fields = [
-    ["os", os3 || void 0],
+    ["os", os5 || void 0],
     ["api", info.sdkApiVersion],
     ["abi", info.abi],
     ["type", info.deviceType],
@@ -1264,34 +1808,40 @@ function formatLongDevice(d, info) {
   const rest = fields.filter(([, v]) => v).map(([k, v]) => `${k}=${/\s/.test(v) ? JSON.stringify(v) : v}`);
   return [head, ...rest].join("	");
 }
+async function queryDevices(long) {
+  const { config, logger } = getRuntime();
+  const devices2 = await listDevices(config);
+  const infos = /* @__PURE__ */ new Map();
+  if (long) {
+    for (const d of devices2.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}`);
+      }
+    }
+  }
+  return { devices: devices2, infos };
+}
+function devicesJson(devices2, infos, long) {
+  return long ? devices2.map((d) => ({ ...d, info: infos.get(d.serial) ?? null })) : devices2;
+}
 function registerDevicesCommand(program) {
   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}`);
-        }
-      }
-    }
+    const { devices: devices2, infos } = await queryDevices(!!opts.long);
     if (opts.json) {
-      const out = opts.long ? devices.map((d) => ({ ...d, info: infos.get(d.serial) ?? null })) : devices;
-      process.stdout.write(`${JSON.stringify(out, null, 2)}
+      process.stdout.write(`${JSON.stringify(devicesJson(devices2, infos, !!opts.long), null, 2)}
 `);
       return;
     }
-    if (devices.length === 0) {
+    if (devices2.length === 0) {
       process.stdout.write("(no devices)\n");
       return;
     }
-    for (const d of devices) {
+    for (const d of devices2) {
       process.stdout.write(`${opts.long ? formatLongDevice(d, infos.get(d.serial)) : `${d.serial}	${d.connection ?? ""}	${d.status}`}
 `);
     }
@@ -1319,7 +1869,8 @@ function registerFileCommand(program) {
 }
 
 // src/commands/lint.ts
-import * as path8 from "path";
+import { InvalidArgumentError as InvalidArgumentError3 } from "commander";
+import * as path9 from "path";
 import {
   detectCmdToolsFlavour,
   detectRuntimeOs as detectRuntimeOs2,
@@ -1327,6 +1878,76 @@ import {
   missingProjectRootFiles,
   runCodelinter
 } from "@oniroproject/core";
+
+// src/commands/check.ts
+import * as path8 from "path";
+import { checkArkts } from "@oniroproject/core";
+function arktsCheckExitCode(report) {
+  if (!report.completed) return 2;
+  return report.ok ? 0 : 1;
+}
+function arktsCheckSummaryLine(report) {
+  const s = report.summary;
+  const fixed = s.fixed ? `, ${s.fixed} fixed` : "";
+  return `${s.errors} errors, ${s.warnings} warnings${fixed} in ${s.files} files (${(report.durationMs / 1e3).toFixed(1)} s).`;
+}
+async function arktsCheckOrError(projectDir, opts) {
+  const { config, logger } = getRuntime();
+  const dir = path8.resolve(projectDir ?? process.cwd());
+  try {
+    return await checkArkts({ config, projectDir: dir, files: opts.files, fix: opts.fix, sdkDir: opts.sdk, logger });
+  } catch (err) {
+    return { ok: false, completed: false, error: err instanceof Error ? err.message : String(err), diagnostics: [] };
+  }
+}
+async function runArktsCheckCommand(projectDir, opts) {
+  const { logger } = getRuntime();
+  const report = await arktsCheckOrError(projectDir, opts);
+  if (!("summary" in report)) {
+    if (opts.json) process.stdout.write(`${JSON.stringify(report, null, 2)}
+`);
+    logger.error(report.error);
+    return 2;
+  }
+  if (opts.json) {
+    process.stdout.write(`${JSON.stringify(report, null, 2)}
+`);
+  } else if (report.completed) {
+    if (report.diagnostics.length) process.stdout.write(`${formatDiagnostics(report.diagnostics, Infinity)}
+`);
+    for (const d of report.fixed) {
+      process.stdout.write(`  fixed ${d.file}:${d.line}:${d.column} ${d.message}
+`);
+    }
+    if (report.alsoModified.length) {
+      process.stdout.write(`--fix also edited: ${report.alsoModified.join(", ")}
+`);
+    }
+    process.stdout.write(`${arktsCheckSummaryLine(report)}
+`);
+  }
+  if (!report.completed) logger.error(report.error ?? "The ArkTS checker did not complete, so nothing was checked.");
+  return arktsCheckExitCode(report);
+}
+function registerCheckCommand(program) {
+  const check = program.command("check").description("Static checks that need no build and no device.");
+  check.command("arkts [project-dir]").description(
+    "Type-check and lint ArkTS with the SDK's own ArkTS checker (what the build's CompileArkTS runs), plus the ArkUI component-model and project-config rules the build enforces later (V1/V2 decorators, @Entry root, route maps, resources, permissions), in seconds and without a build. Uses the SDK the project compiles with. Exits 0 when clean, 1 on an error, 2 when the checker could not run (then nothing is known)."
+  ).option(
+    "--files <files...>",
+    "Check only these .ets files (project-wide rules such as main_pages.json and module.json5 are then skipped)."
+  ).option(
+    "--fix",
+    "Apply the fixes the checker can verify (the compiler's `Did you mean` suggestions, import paths, a missing `export`, the @Component/@ComponentV2 decorator), re-check, and revert any fix that adds an error."
+  ).option("--sdk <dir>", "SDK directory to check against (holding ets/), instead of the one compileSdkVersion names.").option(
+    "--json",
+    "Print the report as JSON: ok, completed, diagnostics (severity, source, rule, message, file, line, column), fixed, alsoModified, summary, sdk, durationMs, error."
+  ).action(async (projectDir, opts) => {
+    process.exitCode = await runArktsCheckCommand(projectDir, opts);
+  });
+}
+
+// src/commands/lint.ts
 function lintTotals(result) {
   if (result.summary) return result.summary;
   const count = (s) => result.findings.filter((f) => f.severity === s).length;
@@ -1337,19 +1958,34 @@ function lintTotals(result) {
     suggestions: count("suggestion")
   };
 }
-function lintExitCode(result) {
+function lintExitCode(result, allowIncomplete = false) {
   if (lintTotals(result).errors > 0) return 1;
-  return lintFailed(result) ? result.code : 0;
+  if (lintFailed(result)) return result.code;
+  return result.incomplete && !allowIncomplete ? 2 : 0;
 }
 function lintFailed(result) {
   return result.summary === null && result.findings.length === 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. 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) => {
+    "Run the OpenHarmony codelinter on a project. Defaults to the current directory. Exits 1 on error-severity findings or when codelinter fails to run, 2 when codelinter reports that it skipped checks (incomplete), 0 otherwise; warnings alone exit 0. `--engine arkts` runs `check arkts` instead."
+  ).option("--files <globs...>", "Specific files/globs to lint (default: the whole project).").option("--json", "Emit the report (findings, summary, notices, incomplete) as JSON.").option(
+    "--engine <engine>",
+    "`codelinter`, or `arkts` for the ArkTS checker of `check arkts` (same options, report and exit codes).",
+    "codelinter"
+  ).option(
+    "--allow-incomplete",
+    "Exit 0 rather than 2 when codelinter reports that it skipped checks (e.g. the tools flavour differs from runtimeOS)."
+  ).action(async (projectDir, opts) => {
+    if (opts.engine === "arkts") {
+      process.exitCode = await runArktsCheckCommand(projectDir, { files: opts.files, json: opts.json });
+      return;
+    }
+    if (opts.engine !== "codelinter") {
+      throw new InvalidArgumentError3(`Unknown --engine ${opts.engine}: use codelinter or arkts.`);
+    }
     const { config, logger } = getRuntime();
-    const dir = path8.resolve(projectDir ?? process.cwd());
+    const dir = path9.resolve(projectDir ?? process.cwd());
     const result = await runCodelinter({ config, projectDir: dir, files: opts.files, logger });
     const totals = lintTotals(result);
     const failed = lintFailed(result);
@@ -1386,65 +2022,272 @@ function registerLintCommand(program) {
         );
       }
     }
-    process.exitCode = lintExitCode(result);
+    if (result.incomplete && !opts.allowIncomplete && lintTotals(result).errors === 0 && !failed) {
+      logger.error(
+        "codelinter reported an incomplete run, so a clean result is not evidence the code is clean: exiting 2. Pass --allow-incomplete to exit 0, or use `oniro-app check arkts`, which does not depend on codelinter."
+      );
+    }
+    process.exitCode = lintExitCode(result, opts.allowIncomplete);
   });
 }
 
-// src/commands/input.ts
-import { Option as Option3 } from "commander";
-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) {
-  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) => {
+// src/commands/test.ts
+import { InvalidArgumentError as InvalidArgumentError4 } from "commander";
+import * as path10 from "path";
+import { runTests } from "@oniroproject/core";
+function positiveMs(raw) {
+  const n = Number(raw);
+  if (!Number.isFinite(n) || n <= 0) throw new InvalidArgumentError4("Expected a positive number of milliseconds.");
+  return Math.floor(n);
+}
+function testExitCode(report) {
+  return report.outcome === "passed" ? 0 : report.outcome === "failed" ? 1 : 2;
+}
+function projectFrame(stack) {
+  for (const line of stack?.split("\n") ?? []) {
+    if (/oh_modules|@ohos\/hypium/.test(line)) continue;
+    const m = /\(([^()]+:\d+:\d+)\)\s*$/.exec(line.trim());
+    if (m) return m[1];
+  }
+  return void 0;
+}
+function formatTestCase(t) {
+  const label = { pass: "PASS", fail: "FAIL", error: "ERROR", ignore: "SKIP", unknown: `CODE ${t.statusCode}` }[t.status];
+  const time = t.durationMs !== void 0 ? ` (${t.durationMs} ms)` : "";
+  let line = `${label} ${t.suite} > ${t.name}${time}`;
+  if (t.status !== "pass" && t.message) line += `
+    ${t.message}`;
+  const at = t.status !== "pass" ? projectFrame(t.stack) : void 0;
+  if (at) line += `
+    at ${at}`;
+  return line;
+}
+function registerTestCommand(program) {
+  program.command("test [project-dir]").description(
+    "Build a module's main and ohosTest HAPs, install both on the device, run the suite with `aa test` (Hypium, OpenHarmonyTestRunner) and report each case. Defaults to the current directory. Exits 0 when every case passed, 1 when a case failed or threw, 2 when the run did not complete (build failed, test module not found, timeout, no device). The test module is left installed."
+  ).option("--module <module>", "Module whose src/ohosTest suite runs.", "entry").option("--product <product>", "hvigor product name.", "default").option("--class <filter>", "Run only these cases: `Suite`, `Suite#case`, or several joined by commas.").option("--timeout <ms>", "Per-case timeout passed to the runner.", positiveMs, 15e3).option("--run-timeout <ms>", "Wall-clock limit for the whole run; aa test can hang when the app dies.", positiveMs, 6e5).option("--no-build", "Use the HAPs already built instead of building them.").option("--no-wake", "Leave the screen as it is (by default it is turned on, a lock screen without a credential is swiped away, and it is kept on during the run).").option("--mode <mode>", "hvigor build mode (e.g. debug).").option("--no-deps", "Skip the automatic `ohpm install --all` when oh_modules/ is missing.").option("--device <serial>", "Target device serial.").option(
+    "--json",
+    "Print the report as JSON: ok, outcome, tests (suite, name, status, statusCode, durationMs, message, stack), summary, resultCode, haps, log, error."
+  ).action(async (projectDir, opts) => {
     const { config, logger } = getRuntime();
-    const result = await performInput({
+    const dir = path10.resolve(projectDir ?? process.cwd());
+    const report = await runTests({
       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),
-      pxY2: num(opts.y2),
-      speed: num(opts.speed),
-      key: opts.key,
-      text: opts.text,
-      clear: opts.clear,
-      hideKeyboard: opts.hideKeyboard,
+      projectDir: dir,
+      module: opts.module,
+      product: opts.product,
+      testClass: opts.class,
+      caseTimeoutMs: opts.timeout,
+      runTimeoutMs: opts.runTimeout,
+      build: opts.build,
+      wakeScreen: opts.wake,
+      mode: opts.mode,
+      autoInstallDeps: opts.deps,
       deviceSerial: opts.device,
       logger
     });
-    if (opts.type === "hideKeyboard") {
-      logger.info(result.keyboardHidden ? "Dismissed the keyboard." : "The keyboard was not shown.");
-      return;
+    if (opts.json) {
+      process.stdout.write(`${JSON.stringify(report, null, 2)}
+`);
+    } else {
+      for (const t of report.tests) process.stdout.write(`${formatTestCase(t)}
+`);
+      const s = report.summary;
+      if (report.tests.length || report.outcome !== "runner-error") {
+        process.stdout.write(
+          `${s.run} run: ${s.pass} passed, ${s.fail} failed, ${s.error} errors, ${s.ignore} ignored.
+`
+        );
+      }
+    }
+    for (const w of report.warnings) logger.warn(w);
+    if (report.error) {
+      const listed = report.diagnostics ? formatDiagnostics(report.diagnostics) : "";
+      logger.error(`${report.error}${listed ? `
+${listed}` : ""}`);
+    }
+    process.exitCode = testExitCode(report);
+  });
+}
+
+// src/commands/doctor.ts
+import * as fs5 from "fs";
+import * as path11 from "path";
+import { runDoctor } from "@oniroproject/core";
+function formatDoctorCheck(c) {
+  const line = `${c.status.padEnd(5)} ${c.id.padEnd(16)} ${c.detail}${c.fixed ? " (fixed)" : ""}`;
+  return c.fix && c.status !== "ok" && c.status !== "skip" ? `${line}
+${" ".repeat(23)}fix: ${c.fix}` : line;
+}
+function doctorExitCode(report) {
+  return report.ok ? 0 : 1;
+}
+function registerDoctorCommand(program) {
+  program.command("doctor [project-dir]").description(
+    "Check that this machine can build, check, sign, install and test: node, java, the SDK the project compiles with, the command-line tools (complete, their version, their flavour against runtimeOS), a `check arkts` self-test, hdc and a reachable device at the project's API, signing material, free disk space. Each check is ok, warn, fail or skip, with a fix. Uses the project in the current directory when there is one. Exits 1 when any check fails."
+  ).option("--json", "Print the report as JSON: ok, checks (id, status, detail, fix, fixed), project, versions.").option("--fix", "Install the project's missing OpenHarmony SDK.").option("--no-device", "Skip the device check (for a machine that only builds).").option("--serial <serial>", "The device to check, when several are connected.").option("--no-arkts-check", "Skip the `check arkts` self-test.").action(async (projectDir, opts) => {
+    const { config, logger, progress } = getRuntime();
+    let dir;
+    if (projectDir) {
+      dir = path11.resolve(projectDir);
+    } else if (fs5.existsSync(path11.join(process.cwd(), "build-profile.json5"))) {
+      dir = process.cwd();
+    }
+    const report = await runDoctor({
+      config,
+      projectDir: dir,
+      fix: opts.fix,
+      device: opts.device,
+      deviceSerial: opts.serial,
+      arktsSelfTest: opts.arktsCheck,
+      logger,
+      progress
+    });
+    if (opts.json) {
+      process.stdout.write(`${JSON.stringify(report, null, 2)}
+`);
+    } else {
+      if (report.project) process.stdout.write(`Project ${report.project.dir} (${report.project.runtimeOS})
+`);
+      for (const c of report.checks) process.stdout.write(`${formatDoctorCheck(c)}
+`);
+      const failed = report.checks.filter((c) => c.status === "fail").length;
+      process.stdout.write(failed ? `${failed} check(s) failed.
+` : "No check failed.\n");
+    }
+    process.exitCode = doctorExitCode(report);
+  });
+}
+
+// src/commands/screens.ts
+import * as path12 from "path";
+import { inventoryScreens } from "@oniroproject/core";
+function formatTable(header, rows) {
+  const widths = header.map((h, i) => Math.max(h.length, ...rows.map((r) => (r[i] ?? "").length)));
+  const line = (cells) => cells.map((c, i) => i === cells.length - 1 ? c : c.padEnd(widths[i] ?? 0)).join("  ").trimEnd();
+  return [line(header), ...rows.map(line)].join("\n");
+}
+function formatScreens(inv) {
+  const out = [];
+  const multiModule = inv.modules.length > 1;
+  out.push(`Pages (${inv.pages.length})`);
+  if (inv.pages.length) {
+    out.push(
+      formatTable(
+        ["NAME", ...multiModule ? ["MODULE"] : [], "KIND", "COMPONENT", "NODES", "ROUTES OUT", "FILE"],
+        inv.pages.map((p) => [
+          p.registered ? p.name : `${p.name} (unregistered)`,
+          ...multiModule ? [p.module] : [],
+          p.kind,
+          p.component ?? "-",
+          String(p.contentNodes),
+          p.routesOut.join(", ") || "-",
+          `${p.file}:${p.line}`
+        ])
+      )
+    );
+  }
+  out.push("", `Routes (${inv.routes.length})`);
+  if (inv.routes.length) {
+    out.push(
+      formatTable(
+        ["FROM", "TO", "VIA", "FILE"],
+        inv.routes.map((r) => [r.from, r.dynamic ? `${r.to} (dynamic)` : r.to, r.via, `${r.file}:${r.line}`])
+      )
+    );
+  }
+  out.push("", `Placeholders (${inv.placeholders.length})`);
+  if (inv.placeholders.length) {
+    out.push(formatTable(["FILE", "KIND", "TEXT"], inv.placeholders.map((p) => [`${p.file}:${p.line}`, p.kind, p.text])));
+  }
+  if (inv.warnings.length) {
+    out.push("", `Warnings (${inv.warnings.length})`);
+    for (const w of inv.warnings) out.push(w);
+  }
+  return out.join("\n");
+}
+function registerScreensCommand(program) {
+  program.command("screens [project-dir]").description(
+    "Static inventory of the pages and routes of a project, from its sources, without a build or a device: @Entry pages (main_pages.json, @Entry({ routeName })), NavDestination pages (route maps and .navDestination() builders that dispatch on the route name), the router.pushUrl/replaceUrl/pushNamedRoute and NavPathStack.pushPath*/replacePath*/pushDestination* call sites, the content nodes each page renders (component calls through its custom components and @Builders, layout containers excluded), and placeholder markers (TODO/FIXME, placeholder-like text, empty build()). Reads every module in build-profile.json5. Exits 0 (it is an inventory, not a gate) unless the project cannot be read."
+  ).option(
+    "--json",
+    "Print the inventory as JSON: pages (name, module, file, line, component, entry, kind, registered, contentNodes, routesOut), routes (from, to, file, line, via, dynamic), placeholders (file, line, text, kind), warnings, modules, projectDir."
+  ).action((projectDir, opts) => {
+    const { logger } = getRuntime();
+    const dir = path12.resolve(projectDir ?? process.cwd());
+    let inv;
+    try {
+      inv = inventoryScreens({ projectDir: dir });
+    } catch (err) {
+      const error = err instanceof Error ? err.message : String(err);
+      if (opts.json) process.stdout.write(`${JSON.stringify({ error }, null, 2)}
+`);
+      logger.error(error);
+      process.exitCode = 1;
+      return;
+    }
+    process.stdout.write(opts.json ? `${JSON.stringify(inv, null, 2)}
+` : `${formatScreens(inv)}
+`);
+  });
+}
+
+// src/commands/input.ts
+import { Option as Option3 } from "commander";
+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) {
+  const input2 = program.command("input").description(
+    "Inject a UI input event via uitest uiInput. Position it with --target or --selector (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(input2, "Act on");
+  input2.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();
+    const result = await performInput({
+      config,
+      type: opts.type,
+      target: selectorFrom(opts),
+      targetIndex: targetIndexFrom(opts),
+      windowId: windowIdFrom(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),
+      pxY2: num(opts.y2),
+      speed: num(opts.speed),
+      key: opts.key,
+      text: opts.text,
+      clear: opts.clear,
+      hideKeyboard: opts.hideKeyboard,
+      deviceSerial: opts.device,
+      logger
+    });
+    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)}` : "";
@@ -1475,13 +2318,14 @@ function registerInputCommand(program) {
 }
 
 // src/commands/logs.ts
-import * as os2 from "os";
-import * as path10 from "path";
-import { captureLog } from "@oniroproject/core";
+import * as fs8 from "fs/promises";
+import * as os3 from "os";
+import * as path15 from "path";
+import { analyzeFaultLog, captureLog, latestCrash as latestCrash2 } from "@oniroproject/core";
 
 // src/lib/logBundle.ts
-import * as fs4 from "fs/promises";
-import * as path9 from "path";
+import * as fs6 from "fs/promises";
+import * as path13 from "path";
 import { deflateRawSync } from "zlib";
 import {
   VERSION,
@@ -1514,7 +2358,7 @@ function validateDate(date, time) {
   const value = new Date(Date.UTC(2e3, Number(monthText) - 1, Number(dayText), Number(hourText), Number(minuteText), Number(secondText), Number(millisecondText)));
   return value.getUTCMonth() === Number(monthText) - 1 && value.getUTCDate() === Number(dayText) && Number(hourText) < 24 && Number(minuteText) < 60 && Number(secondText) < 60;
 }
-function filterHilog(input, filters) {
+function filterHilog(input2, filters) {
   const criteria = {};
   if (filters.pid) criteria.pid = filters.pid.replace(/^0+(?=\d)/, "");
   if (filters.tag) criteria.tag = filters.tag;
@@ -1523,7 +2367,7 @@ function filterHilog(input, filters) {
   let sawRecord = false;
   let keep = false;
   let output = "";
-  for (const line of input.match(/[^\n]*\n|[^\n]+$/g) ?? []) {
+  for (const line of input2.match(/[^\n]*\n|[^\n]+$/g) ?? []) {
     const content = line.replace(/[\r\n]+$/, "");
     const match = HILOG_RECORD.exec(content);
     if (match?.groups) {
@@ -1576,34 +2420,34 @@ function decodeText(data, relativePath) {
   return text;
 }
 async function redactTree(source, destination, serials, boundedHilog) {
-  await fs4.mkdir(destination, { recursive: false, mode: 448 });
+  await fs6.mkdir(destination, { recursive: false, mode: 448 });
   try {
     const visit = async (directory) => {
-      for (const entry of await fs4.readdir(directory, { withFileTypes: true })) {
-        const sourcePath = path9.join(directory, entry.name);
-        const relative2 = path9.relative(source, sourcePath);
-        const portableRelative = relative2.split(path9.sep).join("/");
-        const destinationPath = path9.join(destination, relative2);
+      for (const entry of await fs6.readdir(directory, { withFileTypes: true })) {
+        const sourcePath = path13.join(directory, entry.name);
+        const relative2 = path13.relative(source, sourcePath);
+        const portableRelative = relative2.split(path13.sep).join("/");
+        const destinationPath = path13.join(destination, relative2);
         if (entry.isDirectory()) {
-          await fs4.mkdir(destinationPath, { recursive: true, mode: 448 });
+          await fs6.mkdir(destinationPath, { recursive: true, mode: 448 });
           await visit(sourcePath);
         } else if (entry.isFile()) {
           if (portableRelative === "logs/hilog.txt") {
             const text2 = boundedHilog ?? "HiLog omitted from this archive because the requested duration could not be reliably applied.\n";
-            await fs4.mkdir(path9.dirname(destinationPath), { recursive: true, mode: 448 });
-            await fs4.writeFile(destinationPath, redactLogText(text2, serials), { encoding: "utf8", mode: 384 });
+            await fs6.mkdir(path13.dirname(destinationPath), { recursive: true, mode: 448 });
+            await fs6.writeFile(destinationPath, redactLogText(text2, serials), { encoding: "utf8", mode: 384 });
             continue;
           }
           if (portableRelative === "logs/hilog-filtered.txt" && boundedHilog === null) continue;
-          const text = decodeText(await fs4.readFile(sourcePath), relative2);
-          await fs4.mkdir(path9.dirname(destinationPath), { recursive: true, mode: 448 });
-          await fs4.writeFile(destinationPath, redactLogText(text, serials), { encoding: "utf8", mode: 384 });
+          const text = decodeText(await fs6.readFile(sourcePath), relative2);
+          await fs6.mkdir(path13.dirname(destinationPath), { recursive: true, mode: 448 });
+          await fs6.writeFile(destinationPath, redactLogText(text, serials), { encoding: "utf8", mode: 384 });
         }
       }
     };
     await visit(source);
   } catch (error) {
-    await fs4.rm(destination, { recursive: true, force: true });
+    await fs6.rm(destination, { recursive: true, force: true });
     throw error;
   }
 }
@@ -1628,8 +2472,8 @@ function dosDateTime(date) {
 async function writeZip(source, archivePath) {
   const files = [];
   const visit = async (directory) => {
-    for (const entry of await fs4.readdir(directory, { withFileTypes: true })) {
-      const filePath = path9.join(directory, entry.name);
+    for (const entry of await fs6.readdir(directory, { withFileTypes: true })) {
+      const filePath = path13.join(directory, entry.name);
       if (entry.isDirectory()) await visit(filePath);
       else if (entry.isFile()) files.push(filePath);
     }
@@ -1640,8 +2484,8 @@ async function writeZip(source, archivePath) {
   let offset = 0;
   const stamp = dosDateTime(/* @__PURE__ */ new Date());
   for (const filePath of files) {
-    const name = Buffer.from(path9.relative(source, filePath).split(path9.sep).join("/"), "utf8");
-    const data = await fs4.readFile(filePath);
+    const name = Buffer.from(path13.relative(source, filePath).split(path13.sep).join("/"), "utf8");
+    const data = await fs6.readFile(filePath);
     const compressed = deflateRawSync(data);
     const checksum = crc32(data);
     const local = Buffer.alloc(30);
@@ -1688,7 +2532,7 @@ async function writeZip(source, archivePath) {
   end.writeUInt32LE(centralDirectory.length, 12);
   end.writeUInt32LE(offset, 16);
   end.writeUInt16LE(0, 20);
-  await fs4.writeFile(archivePath, Buffer.concat([...localParts, centralDirectory, end]), { flag: "wx", mode: 384 });
+  await fs6.writeFile(archivePath, Buffer.concat([...localParts, centralDirectory, end]), { flag: "wx", mode: 384 });
 }
 function commandFailure(result) {
   if (result.code !== 0) return `hdc exited with code ${result.code}`;
@@ -1700,12 +2544,12 @@ function errorMessage(error) {
   return error instanceof Error ? error.message : String(error);
 }
 async function uniqueBundleDirectory(outputDirectory, stamp) {
-  await fs4.mkdir(outputDirectory, { recursive: true, mode: 448 });
+  await fs6.mkdir(outputDirectory, { recursive: true, mode: 448 });
   for (let suffix = 0; ; suffix++) {
     const name = `incident-${stamp}${suffix ? `-${suffix}` : ""}`;
-    const directory = path9.join(outputDirectory, name);
+    const directory = path13.join(outputDirectory, name);
     try {
-      await fs4.mkdir(directory, { mode: 448 });
+      await fs6.mkdir(directory, { mode: 448 });
       return directory;
     } catch (error) {
       if (error.code !== "EEXIST") throw error;
@@ -1725,7 +2569,7 @@ async function collectLogBundle(options) {
   }
   const started = /* @__PURE__ */ new Date();
   const stamp = started.toISOString().replace(/[-:]/g, "").replace(/\.\d{3}Z$/, "Z");
-  const bundleDirectory = await uniqueBundleDirectory(path9.resolve(options.outputDirectory), stamp);
+  const bundleDirectory = await uniqueBundleDirectory(path13.resolve(options.outputDirectory), stamp);
   const records = [];
   const serials = [];
   let replacementWarning = false;
@@ -1766,14 +2610,14 @@ async function collectLogBundle(options) {
     ]
   };
   const run = async (name, relativeOutput, args, deviceSerial) => {
-    const outputPath = path9.join(bundleDirectory, relativeOutput);
-    await fs4.mkdir(path9.dirname(outputPath), { recursive: true, mode: 448 });
+    const outputPath = path13.join(bundleDirectory, relativeOutput);
+    await fs6.mkdir(path13.dirname(outputPath), { recursive: true, mode: 448 });
     let result = null;
     let failure = null;
     try {
       result = await execute(args, deviceSerial);
-      await fs4.writeFile(outputPath, result.stdout, { encoding: "utf8", mode: 384 });
-      if (result.stderr) await fs4.writeFile(`${outputPath}.stderr.txt`, result.stderr, { encoding: "utf8", mode: 384 });
+      await fs6.writeFile(outputPath, result.stdout, { encoding: "utf8", mode: 384 });
+      if (result.stderr) await fs6.writeFile(`${outputPath}.stderr.txt`, result.stderr, { encoding: "utf8", mode: 384 });
       if (result.stdout.includes("\uFFFD") || result.stderr.includes("\uFFFD")) {
         replacementWarning = true;
         manifest.notes.push(`${name} output contains Unicode replacement characters; review the redacted evidence before sharing.`);
@@ -1781,7 +2625,7 @@ async function collectLogBundle(options) {
       failure = commandFailure(result);
     } catch (error) {
       failure = errorMessage(error);
-      await fs4.writeFile(outputPath, "", { encoding: "utf8", mode: 384 });
+      await fs6.writeFile(outputPath, "", { encoding: "utf8", mode: 384 });
     }
     const record = {
       name,
@@ -1795,7 +2639,7 @@ async function collectLogBundle(options) {
     return record;
   };
   const targetRecord = await run("list-targets", "device/targets.txt", ["list", "targets", "-v"]);
-  const targetOutput = await fs4.readFile(path9.join(bundleDirectory, "device/targets.txt"), "utf8").catch(() => "");
+  const targetOutput = await fs6.readFile(path13.join(bundleDirectory, "device/targets.txt"), "utf8").catch(() => "");
   const targets = parseDeviceList(targetOutput).filter((target) => target.status === "Connected" || target.status === "Unknown");
   serials.push(...parseDeviceList(targetOutput).map((target) => target.serial));
   const requestedDevice = resolveDeviceSerial(options.deviceSerial);
@@ -1837,9 +2681,9 @@ async function collectLogBundle(options) {
     const hostElapsedMs = Date.now() - captureStartedHostMs;
     if (deviceTimeBefore.status === "success" && hilog.status === "success" && deviceTimeAfter.status === "success") {
       const [beforeText, afterText, fullHilog] = await Promise.all([
-        fs4.readFile(path9.join(bundleDirectory, "device/device-time-before.txt"), "utf8"),
-        fs4.readFile(path9.join(bundleDirectory, "device/device-time-after.txt"), "utf8"),
-        fs4.readFile(path9.join(bundleDirectory, "logs/hilog.txt"), "utf8")
+        fs6.readFile(path13.join(bundleDirectory, "device/device-time-before.txt"), "utf8"),
+        fs6.readFile(path13.join(bundleDirectory, "device/device-time-after.txt"), "utf8"),
+        fs6.readFile(path13.join(bundleDirectory, "logs/hilog.txt"), "utf8")
       ]);
       const window = filterHilogWindow(fullHilog, beforeText, afterText, durationSeconds, hostElapsedMs);
       if (window.text === null) durationFailureReason = window.reason;
@@ -1867,7 +2711,7 @@ async function collectLogBundle(options) {
     } else if (boundedHilog !== null && (options.pid || options.tag || options.level)) {
       const filtered = filterHilog(boundedHilog, { pid: options.pid, tag: options.tag, level: options.level });
       if (filtered) {
-        await fs4.writeFile(path9.join(bundleDirectory, "logs/hilog-filtered.txt"), filtered.text, { encoding: "utf8", mode: 384 });
+        await fs6.writeFile(path13.join(bundleDirectory, "logs/hilog-filtered.txt"), filtered.text, { encoding: "utf8", mode: 384 });
         const status = manifest.filterStatus;
         for (const key of filtered.applied) status[key] = "applied";
       } else {
@@ -1883,11 +2727,11 @@ async function collectLogBundle(options) {
   manifest.collectionEndUtc = ended.toISOString();
   const files = records.flatMap((record) => [record.output, record.stderr].filter((file) => Boolean(file)));
   files.push("manifest.json", "notes.txt");
-  if (await fs4.access(path9.join(bundleDirectory, "logs/hilog-filtered.txt")).then(() => true, () => false)) {
+  if (await fs6.access(path13.join(bundleDirectory, "logs/hilog-filtered.txt")).then(() => true, () => false)) {
     files.push("logs/hilog-filtered.txt");
   }
   manifest.files = files;
-  await fs4.writeFile(path9.join(bundleDirectory, "notes.txt"), "Add reproduction steps and precise event timestamps here.\n", { encoding: "utf8", mode: 384 });
+  await fs6.writeFile(path13.join(bundleDirectory, "notes.txt"), "Add reproduction steps and precise event timestamps here.\n", { encoding: "utf8", mode: 384 });
   const durationFailure = !durationApplied;
   const criticalFailure = Boolean(targetError) || records.some((record) => record.name === "hilog-snapshot" && record.status !== "success");
   const anyCommandFailure = records.some((record) => record.status !== "success");
@@ -1898,16 +2742,16 @@ async function collectLogBundle(options) {
     if (options.redact) {
       redactedDirectory = `${bundleDirectory}-redacted`;
       manifest.redactionStatus = replacementWarning ? "review-required" : "success";
-      manifest.archiveStatus = { status: "success", path: `${path9.basename(redactedDirectory)}.zip` };
-      await fs4.writeFile(path9.join(bundleDirectory, "manifest.json"), `${JSON.stringify(manifest, null, 2)}
+      manifest.archiveStatus = { status: "success", path: `${path13.basename(redactedDirectory)}.zip` };
+      await fs6.writeFile(path13.join(bundleDirectory, "manifest.json"), `${JSON.stringify(manifest, null, 2)}
 `, { encoding: "utf8", mode: 384 });
       await redactTree(bundleDirectory, redactedDirectory, serials, boundedHilog);
       archivePath = `${redactedDirectory}.zip`;
       await writeZip(redactedDirectory, archivePath);
     } else {
       archivePath = `${bundleDirectory}.zip`;
-      manifest.archiveStatus = { status: "success", path: path9.basename(archivePath) };
-      await fs4.writeFile(path9.join(bundleDirectory, "manifest.json"), `${JSON.stringify(manifest, null, 2)}
+      manifest.archiveStatus = { status: "success", path: path13.basename(archivePath) };
+      await fs6.writeFile(path13.join(bundleDirectory, "manifest.json"), `${JSON.stringify(manifest, null, 2)}
 `, { encoding: "utf8", mode: 384 });
       await writeZip(bundleDirectory, archivePath);
     }
@@ -1917,9 +2761,9 @@ async function collectLogBundle(options) {
     manifest.redactionStatus = options.redact ? "failed" : "not-requested";
     manifest.archiveStatus = { status: "failed", path: null };
     manifest.notes.push(bundleError);
-    await fs4.rm(`${redactedDirectory ?? bundleDirectory}.zip`, { force: true }).catch(() => void 0);
-    if (redactedDirectory) await fs4.rm(redactedDirectory, { recursive: true, force: true }).catch(() => void 0);
-    await fs4.writeFile(path9.join(bundleDirectory, "manifest.json"), `${JSON.stringify(manifest, null, 2)}
+    await fs6.rm(`${redactedDirectory ?? bundleDirectory}.zip`, { force: true }).catch(() => void 0);
+    if (redactedDirectory) await fs6.rm(redactedDirectory, { recursive: true, force: true }).catch(() => void 0);
+    await fs6.writeFile(path13.join(bundleDirectory, "manifest.json"), `${JSON.stringify(manifest, null, 2)}
 `, { encoding: "utf8", mode: 384 });
     redactedDirectory = null;
   }
@@ -1951,7 +2795,7 @@ function parseHilogTimestamp(datePart, timePart, referenceMs) {
   const closest = candidates[0];
   return closest !== void 0 && closest <= referenceMs + 2e3 ? closest : null;
 }
-function filterHilogWindow(input, deviceClockBefore, deviceClockAfter, durationSeconds, hostElapsedMs) {
+function filterHilogWindow(input2, deviceClockBefore, deviceClockAfter, durationSeconds, hostElapsedMs) {
   if (!Number.isSafeInteger(durationSeconds) || durationSeconds < 1 || durationSeconds > 31536e3) {
     return { text: null, reason: "requested duration is invalid" };
   }
@@ -1967,7 +2811,7 @@ function filterHilogWindow(input, deviceClockBefore, deviceClockAfter, durationS
   let sawRecord = false;
   let keep = false;
   let output = "";
-  for (const line of input.match(/[^\n]*\n|[^\n]+$/g) ?? []) {
+  for (const line of input2.match(/[^\n]*\n|[^\n]+$/g) ?? []) {
     const content = line.replace(/[\r\n]+$/, "");
     const match = HILOG_RECORD.exec(content);
     if (match?.groups) {
@@ -1992,6 +2836,53 @@ function filterHilogWindow(input, deviceClockBefore, deviceClockAfter, durationS
   return sawRecord ? { text: output } : { text: null, reason: "no recognized timestamped HiLog records were found" };
 }
 
+// src/lib/crashReport.ts
+import * as fs7 from "fs";
+import * as path14 from "path";
+import { getBundleName as getBundleName2 } from "@oniroproject/core";
+function parseCrashSince(value) {
+  if (value === void 0) return void 0;
+  const trimmed = value.trim();
+  if (/^\d+(?:\.\d+)?$/.test(trimmed)) return Number(trimmed);
+  if (/^\d{4}-\d{2}-\d{2}/.test(trimmed)) {
+    const date = new Date(trimmed);
+    if (!Number.isNaN(date.getTime())) return date;
+  }
+  throw new Error(`--since takes a number of seconds or an ISO 8601 time (2026-11-05T12:30:00+01:00), not "${value}".`);
+}
+function projectBundle(dir) {
+  if (!fs7.existsSync(path14.join(dir, "AppScope", "app.json5"))) return void 0;
+  try {
+    return getBundleName2(dir);
+  } catch {
+    return void 0;
+  }
+}
+function formatCrashVerdict(v) {
+  const lines = [];
+  const kind = v.subtype ? `${v.kind} (${v.subtype})` : v.kind;
+  const who = [v.bundle ?? v.process, v.pid !== null ? `pid ${v.pid}` : null].filter(Boolean).join(" ");
+  lines.push(`${v.crashed ? "CRASH" : "NO CRASH"} ${kind}, ${v.confidence} confidence${who ? `: ${who}` : ""}${v.time ? ` at ${v.time}` : ""}`);
+  if (v.jsError) lines.push(`${v.jsError.name}: ${v.jsError.message}`);
+  else if (v.reason) lines.push(`Reason: ${v.reason}`);
+  if (v.lastFatalMessage) lines.push(`Last fatal message: ${v.lastFatalMessage}`);
+  if (v.file) lines.push(`At ${v.file}:${v.line}:${v.column}`);
+  if (v.topFrame) lines.push(`Top frame: ${v.topFrame}`);
+  if (v.projectFrame && v.projectFrame !== v.topFrame) lines.push(`Project frame: ${v.projectFrame}`);
+  const shown = v.stack.slice(0, 12);
+  if (shown.length > 0) lines.push("Stack:", ...shown.map((f) => `  ${f}`));
+  if (v.stack.length > shown.length) lines.push(`  \u2026 ${v.stack.length - shown.length} more`);
+  for (const edge of v.binderChain) {
+    lines.push(`Binder: ${edge.from} -> ${edge.to} waits ${edge.waitSeconds.toFixed(2)} s${edge.frzState ? ` frz_state:${edge.frzState}` : ""}`);
+  }
+  for (const cycle of v.deadlocks) lines.push(`Binder deadlock: ${cycle}`);
+  for (const note of v.notes) lines.push(`Note: ${note}`);
+  if (v.path) lines.push(`Faultlog: ${v.path}`);
+  if (v.rawPath && v.rawPath !== v.path) lines.push(`Saved to: ${v.rawPath}`);
+  return `${lines.join("\n")}
+`;
+}
+
 // src/commands/logs.ts
 function registerLogsCommand(program) {
   const logs = program.command("logs").description(
@@ -1999,7 +2890,7 @@ function registerLogsCommand(program) {
   ).option("-o, --output <file>", "File to append the lines to (required).").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) => {
     if (!opts.output) logs.error("error: required option '-o, --output <file>' not specified");
     const { config, logger } = getRuntime();
-    const file = path10.resolve(opts.output);
+    const file = path15.resolve(opts.output);
     const abort = new AbortController();
     const stop = () => abort.abort();
     process.once("SIGINT", stop);
@@ -2020,7 +2911,7 @@ function registerLogsCommand(program) {
     process.stdout.write(`${result.file}
 `);
   });
-  logs.command("collect").description("Create a diagnostic bundle from a connected device.").allowExcessArguments(false).option("-o, --output <directory>", "Parent directory for incident bundles.", path10.join(os2.homedir(), ".oniro", "incident-bundles")).option("--device <serial>", "Target device serial.").option("--package <bundle>", "Collect faultlog entries for this application bundle.").option("--pid <pid>", "Create a filtered HiLog view for this process.").option("--tag <tag>", "Create a filtered HiLog view for this tag.").option("--level <level>", "Create a filtered HiLog view for this level (V/D/I/W/E/F).").option("--duration <seconds>", "Keep HiLog records from the last N seconds (default 600).", "600").option("--redact", "Redact sensitive values and archive only the redacted bundle.").option("--json", "Emit bundle paths and status as JSON.").action(async (opts) => {
+  logs.command("collect").description("Create a diagnostic bundle from a connected device.").allowExcessArguments(false).option("-o, --output <directory>", "Parent directory for incident bundles.", path15.join(os3.homedir(), ".oniro", "incident-bundles")).option("--device <serial>", "Target device serial.").option("--package <bundle>", "Collect faultlog entries for this application bundle.").option("--pid <pid>", "Create a filtered HiLog view for this process.").option("--tag <tag>", "Create a filtered HiLog view for this tag.").option("--level <level>", "Create a filtered HiLog view for this level (V/D/I/W/E/F).").option("--duration <seconds>", "Keep HiLog records from the last N seconds (default 600).", "600").option("--redact", "Redact sensitive values and archive only the redacted bundle.").option("--json", "Emit bundle paths and status as JSON.").action(async (opts) => {
     const { config } = getRuntime();
     const result = await collectLogBundle({
       config,
@@ -2041,6 +2932,34 @@ function registerLogsCommand(program) {
       throw new Error(`Bundle is partial; inspect manifest.json. ${result.error ?? "One or more collectors failed."}`);
     }
   });
+  logs.command("crash").description(
+    "Fetch the newest faultlog of an app from the device and say what happened: a native crash (cpp_crash), an uncaught ArkTS/JS error (js_crash), a freeze (app_freeze), or none. Reports the reason, the top frame, the first frame in the project's own code with file:line:column, the JS error and its stack, the native frames and, for a freeze, the binder chain. The bundle defaults to the project in the current directory, else any app. Lists through `hidumper -s 1201 -a \"-p Faultlogger\"`, and also reads faultloggerd's native crash records that hiview did not turn into a faultlog. Exits 0 whether or not there was a crash; check `crashed`."
+  ).allowExcessArguments(false).option("--bundle <bundle>", "App to look for (default: the bundleName of the project in the current directory, else any process).").option("--since <s|ISO>", "Only faults from the last N seconds (device clock), or since an ISO 8601 time.").option("--wait <ms>", "Keep looking this long when there is no fault yet; hiview writes the faultlog a few seconds after the process dies (default: look once).").option("--path <file>", "Analyse this local faultlog (or faultloggerd .json crash record) instead of fetching one.").option("-o, --output <directory>", "Where to save the fetched faultlog.", path15.join(os3.homedir(), ".oniro", "faultlogs")).option("--device <serial>", "Target device serial.").option(
+    "--json",
+    "Print the verdict as JSON: crashed, kind, subtype, confidence, bundle, pid, time, reason, topFrame, projectFrame, file, line, column, jsError {name, message, stack}, stack, nativeFrames, jsFrames, binderChain, deadlocks, notes, name, path, rawPath."
+  ).action(async (opts) => {
+    const since = parseCrashSince(opts.since);
+    const waitMs = opts.wait !== void 0 ? Number(opts.wait) : 0;
+    if (!Number.isFinite(waitMs) || waitMs < 0) throw new Error(`--wait takes a number of milliseconds, not "${opts.wait}".`);
+    let verdict;
+    const bundle = opts.bundle ?? (opts.path ? void 0 : projectBundle(process.cwd()));
+    if (opts.path) {
+      const file = path15.resolve(opts.path);
+      verdict = analyzeFaultLog(await fs8.readFile(file, "utf8"), { name: path15.basename(file), path: file, rawPath: file });
+    } else {
+      const { config, logger } = getRuntime();
+      logger.info(`Looking for the newest fault of ${bundle ?? "any process"}${opts.since ? ` since ${opts.since}` : ""}...`);
+      verdict = await latestCrash2({ config, bundle, since, waitMs, deviceSerial: opts.device, saveDir: opts.output, logger });
+    }
+    if (opts.json) {
+      const none = { crashed: false, kind: null, bundle: bundle ?? null, since: since instanceof Date ? since.toISOString() : since ?? null };
+      process.stdout.write(`${JSON.stringify(verdict ?? none, null, 2)}
+`);
+    } else {
+      process.stdout.write(verdict ? formatCrashVerdict(verdict) : `No fault for ${bundle ?? "any process"}${opts.since ? ` since ${opts.since}` : ""}.
+`);
+    }
+  });
 }
 
 // src/commands/hdc.ts
@@ -2059,58 +2978,2030 @@ function registerHdcCommand(program) {
 `);
       return;
     }
-    await new Promise((resolve10, reject) => {
+    await new Promise((resolve20, 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;
-        resolve10();
+        resolve20();
       });
     });
   });
 }
 
-// src/bin/oniro-app.ts
-var CLI_VERSION = "0.17.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().enablePositionalOptions();
-  registerSdkCommand(program);
-  registerCmdToolsCommand(program);
-  registerEmulatorCommand(program);
-  registerBuildCommand(program);
-  registerSignCommand(program);
-  registerAuthCommand(program);
-  registerAppCommand(program);
-  registerCreateCommand(program);
-  registerTemplatesCommand(program);
-  registerRebootCommand(program);
-  registerWaitCommand(program);
-  registerWatchCommand(program);
-  registerScreenshotCommand(program);
-  registerDumpCommand(program);
-  registerDevicesCommand(program);
-  registerFileCommand(program);
-  registerLintCommand(program);
-  registerInputCommand(program);
-  registerLogsCommand(program);
-  registerHdcCommand(program);
-  return program;
+// src/commands/api.ts
+import * as path16 from "path";
+import {
+  findApiInOtherSdks,
+  getApiIndexCacheDir,
+  loadApiIndex,
+  resolveApiSdk,
+  searchApi,
+  showApi,
+  suggestApiSymbols,
+  OniroError as OniroError4
+} from "@oniroproject/core";
+var KINDS = [
+  "namespace",
+  "class",
+  "interface",
+  "enum",
+  "enumMember",
+  "type",
+  "function",
+  "method",
+  "constructor",
+  "property",
+  "variable",
+  "component",
+  "decorator",
+  "macro",
+  "typedef",
+  "struct"
+];
+function parseApi(value) {
+  if (value === void 0) return void 0;
+  const n = Number(value);
+  if (!Number.isInteger(n) || n <= 0) throw new OniroError4(`--api expects an API level such as 20, got "${value}".`);
+  return n;
 }
-async function main() {
-  const program = buildProgram();
+function parseKinds(values) {
+  if (!values?.length) return void 0;
+  const out = [];
+  for (const v of values.flatMap((x) => x.split(","))) {
+    const k = KINDS.find((kind) => kind.toLowerCase() === v.trim().toLowerCase());
+    if (!k) throw new OniroError4(`Unknown --kind "${v}". Kinds: ${KINDS.join(", ")}.`);
+    out.push(k);
+  }
+  return out;
+}
+function selectSdk(opts) {
+  const { config, logger } = getRuntime();
+  const selection = resolveApiSdk(config, {
+    sdkDir: opts.sdk,
+    api: parseApi(opts.api),
+    projectDir: opts.project ? path16.resolve(opts.project) : process.cwd()
+  });
+  if (selection.note) logger.warn(selection.note);
+  return selection;
+}
+function openIndex(sdkDir, rebuild) {
+  const { config, logger } = getRuntime();
+  return loadApiIndex(sdkDir, { cacheDir: getApiIndexCacheDir(config), rebuild, logger });
+}
+function describeIndex(index) {
+  const api = index.api !== void 0 ? `API ${index.api}` : index.sdkDir;
+  return index.sdkVersion ? `${api} (${index.sdkVersion})` : api;
+}
+function apiEntryFacts(e) {
+  const parts = [e.kind];
+  if (e.kit) parts.push(e.kit);
+  if (e.since !== void 0) parts.push(`since ${e.sinceText ?? e.since}`);
+  if (e.deprecated !== void 0) {
+    const dep = e.deprecated ? `deprecated ${e.deprecated}` : "deprecated";
+    parts.push(e.useInstead ? `${dep}, use ${e.useInstead}` : dep);
+  }
+  if (e.systemApi) parts.push("systemapi");
+  return parts.join("  ");
+}
+function formatApiEntry(e, sdkDir) {
+  const lines = [`${e.qualifiedName}  ${apiEntryFacts(e)}`];
+  lines.push(`  ${e.signature}${e.overloads ? `   (+${e.overloads} overload${e.overloads > 1 ? "s" : ""})` : ""}`);
+  if (e.doc) lines.push(`  ${e.doc}`);
+  const where = [`${path16.join(sdkDir, e.file)}:${e.line}`, e.module];
+  if (e.import) where.push(e.import);
+  else if (e.global) where.push("global, no import");
+  if (e.syscap) where.push(e.syscap);
+  lines.push(`  ${where.join("  ")}`);
+  return lines.join("\n");
+}
+function jsonEntry(e, sdkDir) {
+  return { ...e, path: path16.join(sdkDir, e.file) };
+}
+function sdkJson(index, sel) {
+  return { dir: index.sdkDir, api: index.api, version: index.sdkVersion, source: sel.source };
+}
+function runApiSearch(query, opts) {
+  const sel = selectSdk(opts);
+  const { index } = openIndex(sel.sdkDir, opts.rebuild);
+  const lang = opts.lang?.toLowerCase();
+  if (lang && lang !== "arkts" && lang !== "c") throw new OniroError4(`--lang expects arkts or c, got "${opts.lang}".`);
+  const limit = Number(opts.limit ?? 20);
+  if (!Number.isInteger(limit) || limit <= 0) throw new OniroError4(`--limit expects a positive number, got "${opts.limit}".`);
+  const result = searchApi(index, query, {
+    kit: opts.kit,
+    kinds: parseKinds(opts.kind),
+    language: lang,
+    noDeprecated: opts.deprecated === false,
+    noSystemApi: opts.systemapi === false,
+    limit
+  });
+  const json = {
+    sdk: sdkJson(index, sel),
+    query: result.query,
+    total: result.total,
+    hits: result.hits.map((h) => jsonEntry(h, index.sdkDir))
+  };
+  return { json, index, hits: result.hits, total: result.total };
+}
+function runApiShow(symbol, opts) {
+  const sel = selectSdk(opts);
+  const { index } = openIndex(sel.sdkDir, opts.rebuild);
+  const r = showApi(index, symbol, { kit: opts.kit });
+  let alsoIn = [];
+  let suggestions = [];
+  if (!r.found) {
+    const { config, logger } = getRuntime();
+    if (opts.otherSdks !== false) {
+      alsoIn = findApiInOtherSdks(config, symbol, index.sdkDir, {
+        cacheDir: getApiIndexCacheDir(config),
+        kit: opts.kit,
+        logger
+      });
+    }
+    suggestions = suggestApiSymbols(index, symbol);
+  }
+  const json = {
+    sdk: sdkJson(index, sel),
+    symbol,
+    found: r.found,
+    entries: r.entries.map((e) => jsonEntry(e, index.sdkDir))
+  };
+  if (!r.found) {
+    json.alsoIn = alsoIn;
+    json.suggestions = suggestions;
+  }
+  return { json, index, found: r.found, entries: r.entries, alsoIn, suggestions };
+}
+function registerApiCommand(program) {
+  const api = program.command("api").description(
+    "Look up the SDK's declarations: the ArkTS API (`ets/api`, `ets/arkts`, the ArkUI components in `ets/component`, with the kit that exports each symbol) and the Node-API C headers, at one API level. The index is built on first use (a few seconds) and cached under ~/.oniro/cache (ONIRO_CACHE_DIR)."
+  );
+  const sdkOptions = (cmd) => cmd.option(
+    "--api <level>",
+    "The SDK API level to read. Default: the project's compileSdkVersion (from the current directory or --project), else the newest installed SDK."
+  ).option("--sdk <dir>", "An SDK API directory (holding ets/) to read instead.").option("--project <dir>", "The project whose compileSdkVersion picks the SDK (default: the current directory).").option("--rebuild", "Rebuild the index even if the cached one is current.");
+  sdkOptions(
+    api.command("search <query...>").description(
+      "Ranked search: every word must match a symbol name (exact name > prefix > camelCase part > substring) or its doc line. A dotted word matches qualified names (`router.pushUrl`); a leading @ is ignored (`@Local`)."
+    )
+  ).option("--kit <name>", "Only symbols this kit exports (`ArkUI` or `@kit.ArkUI`).").option("--kind <kinds...>", `Only these kinds: ${KINDS.join(", ")}.`).option("--lang <lang>", "Only `arkts` declarations or `c` (Node-API headers).").option("--limit <n>", "At most n hits.", "20").option("--no-deprecated", "Leave out @deprecated symbols.").option("--no-systemapi", "Leave out @systemapi symbols (system apps only).").option(
+    "--json",
+    "Print JSON: sdk (dir, api, version, source), query, total, hits (name, qualifiedName, kind, kit, import, module, since, deprecated, deprecatedSince, useInstead, syscap, systemApi, file, path, line, signature, doc, overloads, score)."
+  ).action((words, opts) => {
+    const { json, index, hits, total } = runApiSearch(words.join(" "), opts);
+    if (opts.json) {
+      process.stdout.write(`${JSON.stringify(json, null, 2)}
+`);
+    } else {
+      for (const h of hits) process.stdout.write(`${formatApiEntry(h, index.sdkDir)}
+
+`);
+      const shown = hits.length < total ? `${hits.length} of ${total}` : `${total}`;
+      process.stdout.write(`${shown} match${total === 1 ? "" : "es"} in ${describeIndex(index)}.
+`);
+    }
+    process.exitCode = total ? 0 : 1;
+  });
+  sdkOptions(
+    api.command("show <symbol>").description(
+      "Exact lookup: is `symbol` declared at this API level? Takes a qualified name (`NavPathStack.pushPathByName`, `router.pushUrl`, `Column`, `@Local`, `napi_create_threadsafe_function`); when none matches, names that end with it (`Preferences.get`). Prints every declaration (overloads included). Exits 1 when it is not declared, naming the other installed SDKs that declare it and close matches."
+    )
+  ).option("--kit <name>", "Only declarations this kit exports.").option("--no-other-sdks", "On a miss, do not look in the other installed SDKs.").option(
+    "--json",
+    "Print JSON: sdk, symbol, found, entries (the `search` hit fields), and on a miss alsoIn ([{api, since}]) and suggestions (qualified names)."
+  ).action((symbol, opts) => {
+    const { json, index, found, entries, alsoIn, suggestions } = runApiShow(symbol, opts);
+    if (opts.json) {
+      process.stdout.write(`${JSON.stringify(json, null, 2)}
+`);
+    } else if (found) {
+      for (const e of entries) process.stdout.write(`${formatApiEntry(e, index.sdkDir)}
+
+`);
+      process.stdout.write(
+        `${symbol} is declared in ${describeIndex(index)} (${entries.length} declaration${entries.length === 1 ? "" : "s"}).
+`
+      );
+    } else {
+      process.stdout.write(`${symbol} is not declared in ${describeIndex(index)}.
+`);
+      for (const a of alsoIn) {
+        process.stdout.write(`  declared in the installed API ${a.api} SDK${a.since !== void 0 ? ` (@since ${a.since})` : ""}
+`);
+      }
+      if (suggestions.length) process.stdout.write(`  close matches: ${suggestions.join(", ")}
+`);
+    }
+    process.exitCode = found ? 0 : 1;
+  });
+  sdkOptions(
+    api.command("index").description("Build (or refresh) the index of one SDK and print its size, for warming a cache.")
+  ).option("--json", "Print JSON: sdk, entries, files, buildMs, cached, cachePath, loadMs.").action((opts) => {
+    const sel = selectSdk(opts);
+    const loaded = openIndex(sel.sdkDir, opts.rebuild);
+    const { index } = loaded;
+    if (opts.json) {
+      const out = {
+        sdk: { dir: index.sdkDir, api: index.api, version: index.sdkVersion, source: sel.source },
+        entries: index.entries.length,
+        files: index.files,
+        buildMs: index.buildMs,
+        builtAt: index.builtAt,
+        cached: loaded.cached,
+        cachePath: loaded.cachePath,
+        loadMs: loaded.loadMs
+      };
+      process.stdout.write(`${JSON.stringify(out, null, 2)}
+`);
+    } else {
+      process.stdout.write(
+        `${describeIndex(index)}: ${index.entries.length} declarations from ${index.files} files, ${loaded.cached ? `cached (built ${index.builtAt})` : `built in ${index.buildMs} ms`}, ${loaded.cachePath}
+`
+      );
+    }
+  });
+}
+
+// src/commands/docs.ts
+import {
+  DocsIndex,
+  docsDirFor,
+  docsRefFor,
+  docsTree,
+  readSdkRelease,
+  syncDocs,
+  OniroError as OniroError5
+} from "@oniroproject/core";
+function selectDocs(opts) {
+  const { config, logger } = getRuntime();
+  if (opts.ref) return { ref: opts.ref, dir: docsDirFor(config, opts.ref) };
+  const api = opts.api !== void 0 ? Number(opts.api) : void 0;
+  let sel;
   try {
-    await program.parseAsync(process.argv);
+    sel = selectSdk(opts);
   } catch (err) {
-    const message = err instanceof OniroError3 ? err.message : err instanceof Error ? err.message : String(err);
-    process.stderr.write(`[error] ${message}
+    if (api === void 0 || !Number.isInteger(api) || api <= 0) throw err;
+    const ref2 = docsRefFor({ api });
+    logger.warn(`The API ${api} SDK is not installed; taking the ${ref2} docs for it.`);
+    return { ref: ref2, dir: docsDirFor(config, ref2), sdk: { api } };
+  }
+  const release = readSdkRelease(sel.sdkDir);
+  const ref = docsRefFor({ api: release.api ?? sel.api, version: release.version });
+  return { ref, dir: docsDirFor(config, ref), sdk: { dir: sel.sdkDir, api: release.api ?? sel.api, version: release.version } };
+}
+function docsJson(sel, tree) {
+  return { ref: sel.ref, dir: sel.dir, tree, sdk: sel.sdk };
+}
+function openDocs(sel) {
+  const tree = docsTree(sel.dir);
+  if (!tree) {
+    const flag = sel.sdk?.api !== void 0 ? ` --api ${sel.sdk.api}` : sel.ref ? ` --ref ${sel.ref}` : "";
+    throw new OniroError5(
+      `The ${sel.ref} docs are not synced (no ${sel.dir}). Run \`oniro-app docs sync${flag}\` first (a partial clone of gitcode.com/openharmony/docs, about 100 MB).`
+    );
+  }
+  return { tree, index: DocsIndex.load(tree) };
+}
+function runDocsSearch(query, opts) {
+  const sel = selectDocs(opts);
+  const { tree, index } = openDocs(sel);
+  const limit = opts.limit !== void 0 ? Number(opts.limit) : void 0;
+  if (limit !== void 0 && (!Number.isInteger(limit) || limit <= 0)) {
+    throw new OniroError5(`--limit expects a positive number, got "${opts.limit}".`);
+  }
+  const result = index.search(query, { limit, section: opts.section });
+  return { json: { docs: docsJson(sel, tree), ...result }, result, tree };
+}
+function runDocsShow(docPath, opts) {
+  const sel = selectDocs(opts);
+  const { tree, index } = openDocs(sel);
+  const maxLines = opts.lines !== void 0 ? Number(opts.lines) : void 0;
+  if (maxLines !== void 0 && (!Number.isInteger(maxLines) || maxLines <= 0)) {
+    throw new OniroError5(`--lines expects a positive number, got "${opts.lines}".`);
+  }
+  const result = index.show(docPath, { heading: opts.heading, maxLines });
+  return { json: { docs: docsJson(sel, tree), ...result }, result, tree };
+}
+async function runDocsSync(opts) {
+  const { logger } = getRuntime();
+  const sel = selectDocs(opts);
+  const result = await syncDocs({ ref: sel.ref, dir: sel.dir, logger });
+  const tree = docsTree(sel.dir);
+  if (tree) DocsIndex.forget(tree);
+  return { json: { docs: docsJson(sel, tree ?? sel.dir), sdk: sel.sdk, ...result }, result, sel };
+}
+function formatDocHit(h) {
+  const lines = [`${h.path}  \u2014  ${h.title}`];
+  if (h.headings.length) lines.push(`  sections: ${h.headings.map((x) => `"${x.text}" (line ${x.line})`).join(", ")}`);
+  if (h.snippet) lines.push(`  ${h.snippet}`);
+  return lines.join("\n");
+}
+function registerDocsCommand(program) {
+  const docs = program.command("docs").description(
+    "Search the OpenHarmony application-development documentation (gitcode.com/openharmony/docs, `en/application-dev`) of the release matching the SDK: usage guides, kit API prose, business error codes and platform behaviour, which the SDK typings behind `api search` do not say. `docs sync` clones the release's tree once (a partial, sparse clone without figures, about 100 MB) under <sdkRootDir>/docs (ONIRO_DOCS_DIR)."
+  );
+  const docsOptions = (cmd) => cmd.option(
+    "--api <level>",
+    "The SDK API level whose release picks the docs. Default: the project's compileSdkVersion (from the current directory or --project), else the newest installed SDK."
+  ).option("--sdk <dir>", "An SDK API directory (holding ets/) whose version picks the docs.").option("--project <dir>", "The project whose compileSdkVersion picks the SDK (default: the current directory).").option("--ref <branch>", "A docs branch or tag (`OpenHarmony-6.1-Release`, `master`) instead of the SDK-chosen one.");
+  docsOptions(
+    docs.command("sync").description(
+      "Clone the docs of the release matching the SDK (6.1.0.x \u2192 OpenHarmony-6.1-Release), or bring an existing clone up to date. Needs git."
+    )
+  ).option("--json", "Print JSON: docs (ref, dir, tree, sdk), files, updated, commit.").action(async (opts) => {
+    const { json, result, sel } = await runDocsSync(opts);
+    if (opts.json) process.stdout.write(`${JSON.stringify(json, null, 2)}
+`);
+    else {
+      process.stdout.write(
+        `${result.updated ? "Updated" : "Cloned"} the ${sel.ref} docs${result.commit ? ` (${result.commit})` : ""}: ${result.files} documents in ${result.dir}
+`
+      );
+    }
+  });
+  docsOptions(
+    docs.command("search <query...>").description(
+      "Ranked search: documents containing every word (any word when none does), scored by where the words occur (title, headings, path, body); a camelCase or dotted identifier also matches by its parts. Each hit names the sections that match, to read with `docs show`. Exits 1 when nothing matches."
+    )
+  ).option("--limit <n>", "At most n hits.", "8").option("--section <dir>", "Only documents under this subtree: `ui`, `database`, `reference/errorcodes`, `application-models`.").option("--json", "Print JSON: docs (ref, dir, tree, sdk), query, terms, total, hits (path, title, score, headings, snippet).").action((words, opts) => {
+    const { json, result, tree } = runDocsSearch(words.join(" "), opts);
+    if (opts.json) {
+      process.stdout.write(`${JSON.stringify(json, null, 2)}
+`);
+    } else {
+      for (const h of result.hits) process.stdout.write(`${formatDocHit(h)}
+
+`);
+      const shown = result.hits.length < result.total ? `${result.hits.length} of ${result.total}` : `${result.total}`;
+      process.stdout.write(
+        result.total ? `${shown} document${result.total === 1 ? "" : "s"} match; paths are relative to ${tree}.
+` : "No document matches; try fewer or different words (component or kit names, decorators, an error code).\n"
+      );
+    }
+    process.exitCode = result.total ? 0 : 1;
+  });
+  docsOptions(
+    docs.command("show <path>").description(
+      "One document (a path `docs search` printed, relative to en/application-dev), or one section of it by heading. Images and inline HTML are dropped; long documents are cut at --lines with a list of their sections. Exits 1 when the document or heading does not exist, suggesting close paths or the headings."
+    )
+  ).option("--heading <text>", "A heading (or a distinctive part of it, case-insensitive): only that section.").option("--lines <n>", "At most n lines (default 250).").option(
+    "--json",
+    "Print JSON: docs (ref, dir, tree, sdk), found, path, text, truncated, lines, headings; on a miss error and suggestions."
+  ).action((docPath, opts) => {
+    const { json, result } = runDocsShow(docPath, opts);
+    if (opts.json) {
+      process.stdout.write(`${JSON.stringify(json, null, 2)}
 `);
-    if (process.env.ONIRO_DEBUG === "1" && err instanceof Error && err.stack) {
-      process.stderr.write(`${err.stack}
+    } else if (result.found) {
+      process.stdout.write(`${result.text}
+`);
+      if (!opts.heading && result.headings.length) {
+        process.stdout.write(`
+[sections: ${result.headings.slice(0, 40).map((h) => h.text).join(" | ")}]
+`);
+      }
+    } else {
+      process.stdout.write(`${result.error}
 `);
+      if (result.suggestions.length) {
+        process.stdout.write(`  ${opts.heading ? "headings" : "close paths"}: ${result.suggestions.join(" | ")}
+`);
+      }
+    }
+    process.exitCode = result.found ? 0 : 1;
+  });
+}
+
+// src/commands/serve.ts
+import * as fs10 from "fs";
+import * as path19 from "path";
+import { OniroError as OniroError6 } from "@oniroproject/core";
+
+// src/mcp/protocol.ts
+import * as readline2 from "readline";
+
+// src/mcp/schema.ts
+function typeOk(type, v) {
+  switch (type) {
+    case void 0:
+      return true;
+    case "object":
+      return typeof v === "object" && v !== null && !Array.isArray(v);
+    case "array":
+      return Array.isArray(v);
+    case "integer":
+      return typeof v === "number" && Number.isInteger(v);
+    case "number":
+      return typeof v === "number" && Number.isFinite(v);
+    default:
+      return typeof v === type;
+  }
+}
+function validateArgs(schema, value, at = "") {
+  const where = at || "arguments";
+  if (!typeOk(schema.type, value)) return [`${where} must be ${schema.type === "integer" ? "an integer" : `a ${schema.type}`}`];
+  const out = [];
+  if (schema.enum && !schema.enum.includes(value)) {
+    out.push(`${where} must be one of ${schema.enum.map((e) => JSON.stringify(e)).join(", ")}`);
+  }
+  if (typeof value === "number") {
+    if (schema.minimum !== void 0 && value < schema.minimum) out.push(`${where} must be >= ${schema.minimum}`);
+    if (schema.maximum !== void 0 && value > schema.maximum) out.push(`${where} must be <= ${schema.maximum}`);
+  }
+  if (Array.isArray(value)) {
+    if (schema.minItems !== void 0 && value.length < schema.minItems) {
+      out.push(`${where} needs at least ${schema.minItems} item${schema.minItems === 1 ? "" : "s"}`);
+    }
+    if (schema.items) value.forEach((item, i) => out.push(...validateArgs(schema.items, item, `${where}[${i}]`)));
+  }
+  if (schema.type === "object" && typeof value === "object" && value !== null) {
+    const obj = value;
+    const props = schema.properties ?? {};
+    for (const key of schema.required ?? []) {
+      if (obj[key] === void 0 || obj[key] === null) out.push(`${at ? `${at}.` : ""}${key} is required`);
+    }
+    for (const [key, v] of Object.entries(obj)) {
+      const prop = props[key];
+      if (!prop) {
+        if (schema.additionalProperties === false) {
+          out.push(`unknown property ${at ? `${at}.` : ""}${key} (expected: ${Object.keys(props).join(", ") || "none"})`);
+        }
+        continue;
+      }
+      if (v === void 0 || v === null) continue;
+      out.push(...validateArgs(prop, v, `${at ? `${at}.` : ""}${key}`));
+    }
+  }
+  return out;
+}
+function applyDefaults(schema, args) {
+  const out = {};
+  for (const [key, v] of Object.entries(args)) if (v !== null && v !== void 0) out[key] = v;
+  for (const [key, prop] of Object.entries(schema.properties ?? {})) {
+    if (out[key] === void 0 && prop.default !== void 0) out[key] = prop.default;
+  }
+  return out;
+}
+
+// src/mcp/protocol.ts
+var SUPPORTED_PROTOCOL_VERSIONS = ["2025-11-25", "2025-06-18", "2025-03-26", "2024-11-05"];
+var STRUCTURED_CONTENT_SINCE = "2025-06-18";
+var RPC_PARSE_ERROR = -32700;
+var RPC_INVALID_REQUEST = -32600;
+var RPC_METHOD_NOT_FOUND = -32601;
+var RPC_INVALID_PARAMS = -32602;
+var RPC_INTERNAL_ERROR = -32603;
+function rpcError(id, code, message2) {
+  return { jsonrpc: "2.0", id, error: { code, message: message2 } };
+}
+function isObject(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function errorResult(message2, structured) {
+  return {
+    content: [{ type: "text", text: message2 }],
+    ...structured ? { structuredContent: structured } : {},
+    isError: true
+  };
+}
+var McpServer = class {
+  constructor(opts) {
+    this.opts = opts;
+    for (const t of opts.tools) this.tools.set(t.name, t);
+  }
+  opts;
+  tools = /* @__PURE__ */ new Map();
+  protocolVersion;
+  /** The version agreed in `initialize`, or undefined before it. */
+  get negotiatedVersion() {
+    return this.protocolVersion;
+  }
+  /**
+   * Handle one parsed JSON-RPC message (or a batch, which the 2025-03-26
+   * revision allows). Returns the response to send, or undefined for a
+   * notification.
+   */
+  async handle(message2) {
+    if (Array.isArray(message2)) {
+      if (message2.length === 0) return rpcError(null, RPC_INVALID_REQUEST, "Empty batch.");
+      const out = (await Promise.all(message2.map((m) => this.handleOne(m)))).filter(
+        (r) => r !== void 0
+      );
+      return out.length ? out : void 0;
+    }
+    return this.handleOne(message2);
+  }
+  async handleOne(msg) {
+    if (!isObject(msg) || msg.jsonrpc !== "2.0") {
+      return rpcError(isObject(msg) && isId(msg.id) ? msg.id : null, RPC_INVALID_REQUEST, "Not a JSON-RPC 2.0 message.");
+    }
+    const hasId = "id" in msg;
+    if (typeof msg.method !== "string") {
+      if (hasId && ("result" in msg || "error" in msg)) return void 0;
+      return rpcError(isId(msg.id) ? msg.id : null, RPC_INVALID_REQUEST, "Missing method.");
+    }
+    if (!hasId) {
+      this.onNotification(msg.method);
+      return void 0;
+    }
+    if (!isId(msg.id) || msg.id === null) return rpcError(null, RPC_INVALID_REQUEST, "The id must be a string or a number.");
+    const id = msg.id;
+    const params = msg.params === void 0 ? {} : msg.params;
+    if (!isObject(params)) return rpcError(id, RPC_INVALID_PARAMS, "params must be an object.");
+    try {
+      return await this.dispatch(id, msg.method, params);
+    } catch (err) {
+      this.opts.logger.error(`mcp: ${msg.method} failed: ${err.stack ?? String(err)}`);
+      return rpcError(id, RPC_INTERNAL_ERROR, err instanceof Error ? err.message : String(err));
+    }
+  }
+  onNotification(method) {
+    if (method === "notifications/initialized") this.opts.logger.debug("mcp: client initialized");
+  }
+  async dispatch(id, method, params) {
+    const ok = (result) => ({ jsonrpc: "2.0", id, result });
+    if (method === "initialize") return ok(this.initialize(params));
+    if (method === "ping") return ok({});
+    if (this.protocolVersion === void 0) {
+      return rpcError(id, RPC_INVALID_REQUEST, `Received ${method} before initialize.`);
+    }
+    if (method === "tools/list") {
+      return ok({
+        tools: [...this.tools.values()].map((t) => ({
+          name: t.name,
+          ...t.title ? { title: t.title } : {},
+          description: t.description,
+          inputSchema: t.inputSchema,
+          ...t.annotations ? { annotations: t.annotations } : {}
+        }))
+      });
+    }
+    if (method === "tools/call") {
+      const name = params.name;
+      if (typeof name !== "string") return rpcError(id, RPC_INVALID_PARAMS, "tools/call needs a tool name.");
+      const tool = this.tools.get(name);
+      if (!tool) return rpcError(id, RPC_INVALID_PARAMS, `Unknown tool: ${name}. Tools: ${[...this.tools.keys()].join(", ")}.`);
+      return ok(this.shape(await this.callTool(tool, params.arguments)));
+    }
+    return rpcError(id, RPC_METHOD_NOT_FOUND, `Method not found: ${method}`);
+  }
+  initialize(params) {
+    const asked = typeof params.protocolVersion === "string" ? params.protocolVersion : void 0;
+    const version = asked && SUPPORTED_PROTOCOL_VERSIONS.includes(asked) ? asked : SUPPORTED_PROTOCOL_VERSIONS[0];
+    this.protocolVersion = version;
+    const client = isObject(params.clientInfo) ? `${params.clientInfo.name ?? "?"} ${params.clientInfo.version ?? ""}` : "client";
+    this.opts.logger.info(`mcp: ${client.trim()} connected (protocol ${version}, asked ${asked ?? "none"})`);
+    return {
+      protocolVersion: version,
+      capabilities: { tools: { listChanged: false } },
+      serverInfo: { name: this.opts.name, version: this.opts.version },
+      ...this.opts.instructions ? { instructions: this.opts.instructions } : {}
+    };
+  }
+  /** Validate, fill defaults, run. A tool that throws or gets bad arguments yields an `isError` result, not an RPC error. */
+  async callTool(tool, rawArgs) {
+    const args = rawArgs === void 0 || rawArgs === null ? {} : rawArgs;
+    if (!isObject(args)) return errorResult(`Invalid arguments for ${tool.name}: arguments must be an object.`);
+    const problems = validateArgs(tool.inputSchema, args);
+    if (problems.length) return errorResult(`Invalid arguments for ${tool.name}: ${problems.join("; ")}.`);
+    const started = Date.now();
+    this.opts.logger.info(`mcp: ${tool.name} ${JSON.stringify(args)}`);
+    try {
+      const result = await tool.call(applyDefaults(tool.inputSchema, args), this.opts.context);
+      this.opts.logger.info(`mcp: ${tool.name} ${result.isError ? "failed" : "done"} in ${Date.now() - started} ms`);
+      return result;
+    } catch (err) {
+      const message2 = err instanceof Error ? err.message : String(err);
+      this.opts.logger.info(`mcp: ${tool.name} threw in ${Date.now() - started} ms: ${message2}`);
+      if (process.env.ONIRO_DEBUG === "1" && err instanceof Error && err.stack) this.opts.logger.debug(err.stack);
+      return errorResult(message2, { error: message2 });
+    }
+  }
+  /** Clients before 2025-06-18 know no `structuredContent`; the text block carries the same JSON. */
+  shape(result) {
+    if (result.structuredContent && (this.protocolVersion ?? "") < STRUCTURED_CONTENT_SINCE) {
+      const { structuredContent: _dropped, ...rest } = result;
+      return rest;
+    }
+    return result;
+  }
+};
+function isId(v) {
+  return typeof v === "string" || typeof v === "number" || v === null;
+}
+async function serveStdio(server, opts = {}) {
+  const input2 = opts.input ?? process.stdin;
+  const write = opts.write ?? ((line) => void process.stdout.write(line));
+  const send = (msg) => write(`${JSON.stringify(msg)}
+`);
+  const pending = /* @__PURE__ */ new Set();
+  const rl = readline2.createInterface({ input: input2, crlfDelay: Infinity, terminal: false });
+  for await (const line of rl) {
+    const text = line.trim();
+    if (!text) continue;
+    let message2;
+    try {
+      message2 = JSON.parse(text);
+    } catch {
+      send(rpcError(null, RPC_PARSE_ERROR, "Parse error: each line must be one JSON-RPC message."));
+      continue;
+    }
+    const p = server.handle(message2).then(
+      (response) => {
+        if (response !== void 0) send(response);
+      },
+      () => {
+      }
+    );
+    pending.add(p);
+    void p.finally(() => pending.delete(p));
+  }
+  await Promise.all(pending);
+}
+
+// src/mcp/tools.ts
+import * as fs9 from "fs";
+import * as os4 from "os";
+import * as path18 from "path";
+import {
+  analyzeFaultLog as analyzeFaultLog2,
+  captureBurst as captureBurst2,
+  describeLayoutNode as describeLayoutNode4,
+  findLayoutNodes as findLayoutNodes2,
+  listLayoutWindows as listLayoutWindows2,
+  selectableTree as selectableTree2,
+  diffLayouts as diffLayouts2,
+  dumpLayout as dumpLayout3,
+  inventoryScreens as inventoryScreens2,
+  latestCrash as latestCrash3,
+  locateTarget as locateTarget2,
+  parseLayoutBaseline as parseLayoutBaseline2,
+  parseSelector as parseSelector2,
+  performInput as performInput2,
+  runDoctor as runDoctor2,
+  runTests as runTests2,
+  summarizeLayout as summarizeLayout2,
+  takeScreenshot as takeScreenshot2,
+  waitForBoot as waitForBoot2,
+  waitForBundle as waitForBundle2,
+  waitForLog as waitForLog2,
+  waitForTarget as waitForTarget2,
+  DEFAULT_SMOKE_DELAY_MS as DEFAULT_SMOKE_DELAY_MS2,
+  DEFAULT_TRACE_BUFFER_KB as DEFAULT_TRACE_BUFFER_KB2,
+  DEFAULT_TRACE_CATEGORIES as DEFAULT_TRACE_CATEGORIES2,
+  evaluatePerfGate as evaluatePerfGate2,
+  perfTrace as perfTrace2,
+  readFlowFile as readFlowFile2
+} from "@oniroproject/core";
+
+// src/commands/perf.ts
+import { InvalidArgumentError as InvalidArgumentError5 } from "commander";
+import * as path17 from "path";
+import {
+  DEFAULT_PERF_FLOW_TAIL_MS,
+  DEFAULT_PERF_FOR_MS,
+  DEFAULT_TRACE_BUFFER_KB,
+  DEFAULT_TRACE_CATEGORIES,
+  evaluatePerfGate,
+  parseTraceFile,
+  perfSliceFilter,
+  perfTrace,
+  readFlowFile,
+  summarizeTrace
+} from "@oniroproject/core";
+
+// src/lib/interrupt.ts
+async function withInterrupt(logger, what, fn) {
+  const controller = new AbortController();
+  const onSigint = () => {
+    if (controller.signal.aborted) process.exit(130);
+    logger.info(`${what}\u2026 (Ctrl+C again to quit at once)`);
+    controller.abort();
+  };
+  process.on("SIGINT", onSigint);
+  try {
+    return await fn(controller.signal);
+  } finally {
+    process.off("SIGINT", onSigint);
+  }
+}
+
+// src/commands/perf.ts
+function positiveMs2(raw) {
+  const n = Number(raw);
+  if (!Number.isFinite(n) || n <= 0) throw new InvalidArgumentError5("Expected a positive number of milliseconds.");
+  return Math.floor(n);
+}
+function rate(raw) {
+  const n = Number(raw);
+  if (!Number.isFinite(n) || n < 0 || n > 1) throw new InvalidArgumentError5("Expected a rate between 0 and 1, e.g. 0.05.");
+  return n;
+}
+function positiveInt(raw) {
+  const n = Number(raw);
+  if (!Number.isInteger(n) || n <= 0) throw new InvalidArgumentError5("Expected a positive integer.");
+  return n;
+}
+function positiveNumber(raw) {
+  const n = Number(raw);
+  if (!Number.isFinite(n) || n <= 0) throw new InvalidArgumentError5("Expected a positive number.");
+  return n;
+}
+function list(raw) {
+  return raw.split(/[,\s]+/).filter(Boolean);
+}
+function perfExitCode(report, gate) {
+  if (!report.ok) return 2;
+  return gate.passed ? 0 : 1;
+}
+var ms = (n) => `${Math.round(n * 10) / 10} ms`;
+function formatPerfReport(r, gate) {
+  const lines = [
+    `${r.bundle}${r.pid !== null ? ` (pid ${r.pid})` : ""}: ${(r.durationMs / 1e3).toFixed(1)} s captured` + (r.refreshRateHz ? `, display ${r.refreshRateHz} Hz (${ms(1e3 / r.refreshRateHz)} per frame)` : "")
+  ];
+  const f = r.frames;
+  if (f) {
+    lines.push(
+      `  frames: ${f.total}, janky ${f.janky} (${(f.jankRate * 100).toFixed(1)}%), p50 ${ms(f.p50Ms)}, p95 ${ms(f.p95Ms)}, max ${ms(f.maxMs)}, ${f.missedVsyncs} vsync(s) missed`
+    );
+    if (f.longest.length) lines.push(`  longest: ${f.longest.map((l) => `${ms(l.ms)} at +${(l.atMs / 1e3).toFixed(2)} s`).join(", ")}`);
+  }
+  if (r.startup) {
+    const s = r.startup;
+    lines.push(
+      `  startup: cold ${ms(s.coldMs)} (${s.from} \u2192 ${s.to})` + (s.processMs !== null ? `, process up after ${ms(s.processMs)}` : "") + (s.firstFrameMs !== null ? `, first frame ${ms(s.firstFrameMs)}` : "")
+    );
+  }
+  if (r.mainThread) {
+    lines.push(`  main thread: ${ms(r.mainThread.busyMs)} in traced work${r.mainThread.cpuMs !== null ? `, ${ms(r.mainThread.cpuMs)} on CPU` : ""}`);
+  }
+  for (const s of r.scenes) {
+    const parts = [
+      s.maxFrameMs !== void 0 ? `max frame ${s.maxFrameMs} ms` : "",
+      s.maxHitchMs !== void 0 ? `max hitch ${s.maxHitchMs} ms` : "",
+      s.hitchMsPerS !== void 0 ? `hitch ${Math.round(s.hitchMsPerS * 10) / 10} ms/s` : "",
+      s.responseMs !== void 0 ? `response ${s.responseMs} ms` : ""
+    ].filter(Boolean);
+    lines.push(`  RenderService ${s.scene}${s.page ? ` ${s.page}` : ""}: ${parts.join(", ")}`);
+  }
+  if (r.flow) {
+    lines.push(
+      r.flow.outcome === "passed" ? `  flow: passed (${r.flow.steps.length} step(s))` : `  flow: ${r.flow.outcome} at step ${r.flow.failedStep ?? "?"} (${r.flow.reason ?? r.flow.error ?? ""}): ${r.flow.message ?? ""}`
+    );
+  }
+  if (r.hiperf) {
+    if ("error" in r.hiperf) lines.push(`  hiperf: ${r.hiperf.error}`);
+    else {
+      lines.push(`  hiperf: ${r.hiperf.samples} sample(s)${r.hiperf.event ? ` of ${r.hiperf.event}` : ""}${r.hiperf.data ? `, data ${r.hiperf.data}` : ""}`);
+      for (const t of r.hiperf.top.slice(0, 10)) lines.push(`    ${t.percent.toFixed(2).padStart(6)}%  ${t.func}  (${t.dso})`);
+    }
+  }
+  if (r.trace) lines.push(`  trace: ${r.trace}`);
+  for (const n of r.notes) lines.push(`  note: ${n}`);
+  if (gate && !gate.passed) for (const fail of gate.failures) lines.push(`GATE FAILED: ${fail}`);
+  return lines.join("\n");
+}
+function registerPerfCommand(program) {
+  const perf = program.command("perf").description("Measure app performance on the device: frames, jank and startup from a hitrace capture.");
+  perf.command("trace").description(
+    "Capture a hitrace trace while the app cold-launches (--launch), a flow is replayed (--flow), or for a fixed time (--for); pull it and summarise it for the bundle: its UI frames (janky when one takes longer than the display's refresh interval, from its vsync to done), p50/p95/max frame time, cold-start time (launch request to the first frame composited), main-thread load and RenderService jank reports. Exits 0 when the capture completed, 1 when --max-jank-rate or --max-startup-ms is exceeded (or the flow diverged), 2 when it could not capture."
+  ).option("--flow <file>", "Replay this flow file (see `replay`) while tracing; its bundle is the default --bundle.").option("--launch", "Force-stop the app, start tracing, then cold-launch it and report its startup time.").option(
+    "--for <ms>",
+    `Without --flow: how long to capture (after the launch with --launch), default ${DEFAULT_PERF_FOR_MS}. With --flow: how long to keep capturing after it, default ${DEFAULT_PERF_FLOW_TAIL_MS}.`,
+    positiveMs2
+  ).option("--bundle <bundle>", "The app to measure (default: the flow's bundle, else the project in the current directory).").option("--ability <name>", "Ability --launch starts (default: the main ability).").option("--out <file>", "Where to save the trace (default: a file in the system temp dir).").option("--categories <list>", `hitrace categories, comma-separated (default ${DEFAULT_TRACE_CATEGORIES.join(",")}; add sched for main-thread CPU time).`, list).option("--buffer-kb <kb>", "hitrace buffer size in KB.", positiveInt, DEFAULT_TRACE_BUFFER_KB).option("--hiperf", "Also sample the app's process with hiperf during the capture and list its top functions.").option("--max-jank-rate <r>", "Exit 1 when the share of janky frames is above this (0..1).", rate).option("--max-startup-ms <ms>", "Exit 1 when the cold start takes longer than this (needs --launch).", positiveMs2).option("--step-timeout <ms>", "With --flow: how long to wait for a step's selector and expect.", positiveMs2).option("--fallback", "With --flow: act on a step's fallback point when its selector is not found.").option("--no-wake", "Leave the screen as it is (by default, with --launch or --flow, it is woken, a credential-less lock screen swiped away, and kept on).").option("--device <serial>", "Target device serial.").option("--json", "Print the report as JSON: ok, bundle, durationMs, trace, refreshRateHz, frames, startup, flow, pid, mainThread, scenes, hiperf, notes, gate, error.").action(async (opts) => {
+    const { config, logger } = getRuntime();
+    const thresholds = { maxJankRate: opts.maxJankRate, maxStartupMs: opts.maxStartupMs };
+    let report;
+    try {
+      const flow = opts.flow ? readFlowFile(path17.resolve(opts.flow)) : void 0;
+      report = await withInterrupt(logger, "stopping the trace", (abortSignal) => perfTrace({
+        config,
+        logger,
+        abortSignal,
+        deviceSerial: opts.device,
+        bundle: opts.bundle ?? flow?.bundle ?? projectBundle(process.cwd()),
+        ability: opts.ability,
+        launch: opts.launch,
+        flow,
+        replay: {
+          stepTimeoutMs: opts.stepTimeout,
+          fallback: opts.fallback,
+          onStep: opts.json ? void 0 : (s) => logger.info(`flow step ${s.index} ${s.action} ${s.ok ? "ok" : "FAILED"}`)
+        },
+        forMs: opts.for,
+        out: opts.out ? path17.resolve(opts.out) : void 0,
+        categories: opts.categories,
+        bufferKb: opts.bufferKb,
+        hiperf: opts.hiperf,
+        wake: opts.wake
+      }));
+    } catch (err) {
+      report = emptyReport(opts.bundle ?? "", err.message);
+    }
+    const gate = evaluatePerfGate(report, thresholds);
+    if (opts.json) process.stdout.write(`${JSON.stringify({ ...report, gate }, null, 2)}
+`);
+    else if (report.ok) process.stdout.write(`${formatPerfReport(report, gate)}
+`);
+    if (report.error) logger.error(report.error);
+    process.exitCode = perfExitCode(report, gate);
+  });
+  perf.command("summary <trace>").description(
+    "Summarise a hitrace text trace taken earlier (by `perf trace --out`, or `hitrace -o` by hand) for a bundle, the same way `perf trace` does. Exit codes as `perf trace`."
+  ).option("--bundle <bundle>", "The app to summarise (default: the project in the current directory).").option("--launched", "The trace holds a cold launch: report startup and leave the first frame out of the frame stats.").option("--pid <pid>", "The app's pid, when the trace holds several of its processes.", positiveInt).option("--refresh-rate <hz>", "Refresh rate to use when the trace has no vsync period.", positiveNumber).option("--max-jank-rate <r>", "Exit 1 when the share of janky frames is above this (0..1).", rate).option("--max-startup-ms <ms>", "Exit 1 when the cold start takes longer than this.", positiveMs2).option("--json", "Print the summary as JSON.").action(async (trace, opts) => {
+    const { logger } = getRuntime();
+    const bundle = opts.bundle ?? projectBundle(process.cwd());
+    const file = path17.resolve(trace);
+    let report;
+    if (!bundle) report = emptyReport("", "No bundle to summarise: pass --bundle.");
+    else {
+      try {
+        const model = await parseTraceFile(file, { keepSlice: perfSliceFilter });
+        const s = summarizeTrace(model, { bundle, launched: opts.launched, pid: opts.pid, refreshRateHz: opts.refreshRate });
+        report = { ...emptyReport(bundle), ...s, ok: true, trace: file };
+      } catch (err) {
+        report = emptyReport(bundle, `Could not read ${file}: ${err.message}`);
+      }
+    }
+    const gate = evaluatePerfGate(report, { maxJankRate: opts.maxJankRate, maxStartupMs: opts.maxStartupMs });
+    if (opts.json) process.stdout.write(`${JSON.stringify({ ...report, gate }, null, 2)}
+`);
+    else if (report.ok) process.stdout.write(`${formatPerfReport(report, gate)}
+`);
+    if (report.error) logger.error(report.error);
+    process.exitCode = perfExitCode(report, gate);
+  });
+}
+function emptyReport(bundle, error) {
+  return {
+    ok: false,
+    bundle,
+    durationMs: 0,
+    trace: null,
+    refreshRateHz: null,
+    frames: null,
+    startup: null,
+    flow: null,
+    pid: null,
+    mainThread: null,
+    scenes: [],
+    categories: [],
+    notes: [],
+    ...error ? { error } : {}
+  };
+}
+
+// src/mcp/target.ts
+function targetProperties(verb, opts = {}) {
+  const props = {
+    target: {
+      type: "string",
+      description: `${verb} the element whose text, description, or placeholder matches (case-insensitive; exact matches win, else substring). Covered elements are skipped.`
+    },
+    targetId: { type: "string", description: "Match the element by its id or key." },
+    targetType: { type: "string", description: "Restrict the match to a component type (e.g. Button, TextInput)." },
+    selector: {
+      type: "string",
+      description: 'Instead of target*: an exact selector. Attributes as comma-separated key<op>value clauses (keys text, desc, hint, id, key, type, enabled, focused, checked, selected, visible, clickable, scrollable; ops = *= ^= $= /=regex) with an optional [n] index, e.g. "type=Button,text*=Sign[1]"; or "xpath=//Button[@text=\\"OK\\"]".'
+    },
+    window: windowProperty
+  };
+  if (opts.index !== false) {
+    props.targetIndex = { type: "integer", minimum: 0, description: "Pick the n-th (0-based) of several matching elements." };
+  }
+  return props;
+}
+var windowProperty = {
+  type: "integer",
+  minimum: 0,
+  description: "Only this window (an id from `dump windows`, or the [window <id> ...] header of a flat dump)."
+};
+function selectorFromArgs(args) {
+  return selectorFrom({
+    target: args.target,
+    targetId: args.targetId,
+    targetType: args.targetType,
+    targetIndex: args.targetIndex === void 0 ? void 0 : String(args.targetIndex),
+    selector: args.selector
+  });
+}
+function targetIndexFromArgs(args) {
+  return args.targetIndex;
+}
+function windowFromArgs(args) {
+  return windowIdFrom({ window: args.window === void 0 ? void 0 : String(args.window) });
+}
+
+// src/mcp/tools.ts
+var str = (description, extra = {}) => ({ type: "string", description, ...extra });
+var bool = (description, dflt) => ({
+  type: "boolean",
+  description,
+  ...dflt !== void 0 ? { default: dflt } : {}
+});
+var num2 = (description, extra = {}) => ({ type: "number", description, ...extra });
+var int = (description, extra = {}) => ({ type: "integer", description, ...extra });
+var PROJECT = {
+  project: str("Project directory; a relative path resolves against the server's --project (default: the server's --project).")
+};
+var DEVICE = {
+  device: str("Target device serial (default: the server's --device, else the only connected device).")
+};
+function object(properties, required = []) {
+  return { type: "object", properties, ...required.length ? { required } : {}, additionalProperties: false };
+}
+function projectOf(a, ctx) {
+  return typeof a.project === "string" ? path18.resolve(ctx.projectDir, a.project) : ctx.projectDir;
+}
+function deviceOf(a, ctx) {
+  return a.device ?? ctx.deviceSerial;
+}
+function pathArg(a, key, ctx) {
+  const v = a[key];
+  return typeof v === "string" ? path18.resolve(projectOf(a, ctx), v) : void 0;
+}
+function jsonResult(json, isError = false, extra = []) {
+  return {
+    content: [{ type: "text", text: JSON.stringify(json) }, ...extra],
+    structuredContent: json,
+    ...isError ? { isError: true } : {}
+  };
+}
+function message(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+function jpeg(buf) {
+  return { type: "image", data: buf.toString("base64"), mimeType: "image/jpeg" };
+}
+function rt() {
+  const { config, logger } = getRuntime();
+  return { config, logger };
+}
+var SMOKE = {
+  smoke: bool(
+    "After launch, wait for the process, take a screenshot after smokeDelay, and fail (isError) when the process died or the screen is blank; a crash is reported from the faultlog.",
+    false
+  ),
+  smokeDelay: int("With smoke: wait between the process appearing and the screenshot, ms.", {
+    minimum: 0,
+    default: DEFAULT_SMOKE_DELAY_MS2
+  }),
+  smokeScreenshot: str("With smoke: where to write the screenshot (default: a file in the system temp dir).")
+};
+var INPUT_TYPES2 = [
+  "click",
+  "doubleClick",
+  "longClick",
+  "swipe",
+  "drag",
+  "fling",
+  "keyEvent",
+  "inputText",
+  "clearText",
+  "hideKeyboard"
+];
+var build = {
+  name: "build",
+  title: "Build the app",
+  description: "Build an OpenHarmony or HarmonyOS app via hvigorw (`oniro-app build --json`). Returns ok, exitCode, durationMs, failedTask, diagnostics (severity, source, code, rule, message, file, line, column, task), summary, discoveredHaps, warnings, error and rawTail. An OpenHarmony project fails early, naming the release to install, when the SDK for its compileSdkVersion is missing. isError when the build fails.",
+  inputSchema: object({
+    ...PROJECT,
+    product: str("hvigor product name.", { default: "default" }),
+    module: str("Restrict the build to a specific module."),
+    mode: str("hvigor build mode (e.g. release, debug)."),
+    task: str("hvigor task to run.", { default: "assembleHap" }),
+    deps: bool("Run `ohpm install --all` when oh_modules/ is missing (false = --no-deps).", true),
+    parallel: bool("Build modules in parallel (false = --no-parallel).", true),
+    installSdk: bool("Install the OpenHarmony SDK the project compiles against when it is missing, then build.", false)
+  }),
+  annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+  changesDevice: false,
+  async call(a, ctx) {
+    try {
+      const report = await runBuild(projectOf(a, ctx), {
+        product: a.product,
+        module: a.module,
+        mode: a.mode,
+        task: a.task,
+        deps: a.deps,
+        parallel: a.parallel,
+        installSdk: a.installSdk
+      });
+      return jsonResult(report, !report.ok);
+    } catch (err) {
+      return jsonResult({ ok: false, exitCode: 1, error: message(err), diagnostics: [] }, true);
+    }
+  }
+};
+var checkArktsTool = {
+  name: "check_arkts",
+  title: "Check ArkTS",
+  description: "Type-check and lint ArkTS with the SDK's own ArkTS checker (what the build's CompileArkTS runs), plus the ArkUI component-model and project-config rules the build enforces later (V1/V2 decorators, @Entry root, route maps, resources, permissions), in seconds and without a build (`oniro-app check arkts --json`). Returns ok, completed, diagnostics (severity, source, rule, message, file, line, column), fixed, alsoModified, summary, sdk, durationMs, error. isError when it found an error or could not run (completed: false means nothing is known).",
+  inputSchema: object({
+    ...PROJECT,
+    files: {
+      type: "array",
+      items: { type: "string" },
+      minItems: 1,
+      description: "Check only these .ets files (project-wide rules such as main_pages.json and module.json5 are then skipped)."
+    },
+    fix: bool(
+      "Apply the fixes the checker can verify (the compiler's `Did you mean` suggestions, import paths, a missing `export`, the @Component/@ComponentV2 decorator), re-check, and revert any fix that adds an error.",
+      false
+    ),
+    sdk: str("SDK directory to check against (holding ets/), instead of the one compileSdkVersion names.")
+  }),
+  annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+  changesDevice: false,
+  async call(a, ctx) {
+    const report = await arktsCheckOrError(projectOf(a, ctx), {
+      files: a.files,
+      fix: a.fix,
+      sdk: pathArg(a, "sdk", ctx)
+    });
+    return jsonResult(report, arktsCheckExitCode(report) !== 0);
+  }
+};
+var test = {
+  name: "test",
+  title: "Run the ohosTest suite",
+  description: "Build a module's main and ohosTest HAPs, install both on the device, run the suite with `aa test` (Hypium) and report each case (`oniro-app test --json`). Returns ok, outcome, tests (suite, name, status, statusCode, durationMs, message, stack), summary, resultCode, haps, log, error. isError when a case failed or the run did not complete. Installs on the device; the test module is left installed.",
+  inputSchema: object({
+    ...PROJECT,
+    module: str("Module whose src/ohosTest suite runs.", { default: "entry" }),
+    product: str("hvigor product name.", { default: "default" }),
+    class: str("Run only these cases: `Suite`, `Suite#case`, or several joined by commas."),
+    timeout: int("Per-case timeout passed to the runner, ms.", { minimum: 1, default: 15e3 }),
+    runTimeout: int("Wall-clock limit for the whole run, ms; aa test can hang when the app dies.", { minimum: 1, default: 6e5 }),
+    build: bool("Build the HAPs first (false = --no-build: use the HAPs already built).", true),
+    wake: bool(
+      "Turn the screen on, swipe a credential-less lock screen away and keep it on during the run (false = --no-wake).",
+      true
+    ),
+    mode: str("hvigor build mode (e.g. debug)."),
+    deps: bool("Run `ohpm install --all` when oh_modules/ is missing (false = --no-deps).", true),
+    ...DEVICE
+  }),
+  annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false },
+  changesDevice: true,
+  async call(a, ctx) {
+    const { config, logger } = rt();
+    const report = await runTests2({
+      config,
+      projectDir: projectOf(a, ctx),
+      module: a.module,
+      product: a.product,
+      testClass: a.class,
+      caseTimeoutMs: a.timeout,
+      runTimeoutMs: a.runTimeout,
+      build: a.build,
+      wakeScreen: a.wake,
+      mode: a.mode,
+      autoInstallDeps: a.deps,
+      deviceSerial: deviceOf(a, ctx),
+      logger
+    });
+    return jsonResult(report, testExitCode(report) !== 0);
+  }
+};
+var apply = {
+  name: "apply",
+  title: "Install and apply a HAP",
+  description: "Install the HAP of the project (or `hap`) and verify the running process took the change (`oniro-app app apply --json`). Refuses a HAP of another bundle. Handles sign-info mismatch, asset-cache invalidation, and persistent-bundle restart. Returns method, preInstallPid, postInstallPid, replaced, cacheCleared, and with smoke a `smoke` verdict (passed, failures, pid, alive, blankScreen, blankScore, crash, screenshot). isError when the smoke check fails.",
+  inputSchema: object({
+    ...PROJECT,
+    hap: str(
+      "An explicit .hap file (relative to the project); its own bundleName is the one applied unless `bundle` is given."
+    ),
+    bundle: str("Bundle name to apply changes to. Defaults to the bundleName in the .hap file, else in the project AppScope/app.json5."),
+    module: str("Module to resolve the HAP from (multi-module projects)."),
+    installedHap: str("Local path to the currently-installed HAP, to enable the asset-cache reboot."),
+    system: bool("Treat as a persistent/system bundle (refuses uninstall on sign-info mismatch).", false),
+    allowUninstall: bool("Permit uninstalling a system bundle on sign-info mismatch (dangerous).", false),
+    ...SMOKE,
+    ...DEVICE
+  }),
+  annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false },
+  changesDevice: true,
+  async call(a, ctx) {
+    const hap = pathArg(a, "hap", ctx);
+    const report = await applyWithSmoke(rt(), {
+      // A HAP goes in as the command's positional .hap, so its own bundle name is the one applied.
+      target: hap ?? projectOf(a, ctx),
+      bundle: a.bundle,
+      module: a.module,
+      installedHap: pathArg(a, "installedHap", ctx),
+      system: a.system,
+      allowUninstall: a.allowUninstall,
+      smoke: a.smoke,
+      smokeDelay: a.smokeDelay,
+      smokeScreenshot: pathArg(a, "smokeScreenshot", ctx),
+      device: deviceOf(a, ctx)
+    });
+    return jsonResult(report, report.smoke ? !report.smoke.passed : false);
+  }
+};
+var launch = {
+  name: "launch",
+  title: "Launch the app",
+  description: "Launch an app on the device (`oniro-app app launch --json`). Project mode (default) resolves the bundle and main ability from the project; bundle mode (`bundle`) launches an already-installed app. With smoke, waits for the process, takes a screenshot and reports whether it died, crashed (from the faultlog) or shows a blank screen. Returns bundle and, with smoke, `smoke` (passed, failures, pid, alive, blankScreen, blankScore, crash, screenshot). isError when the smoke check fails.",
+  inputSchema: object({
+    ...PROJECT,
+    bundle: str("Launch an already-installed app by bundle name (no project needed)."),
+    module: str("Module folder name (project mode).", { default: "entry" }),
+    ability: str(
+      "Explicit ability to launch (defaults to the module mainElement in project mode, or the installed bundle main ability in bundle mode)."
+    ),
+    ...SMOKE,
+    ...DEVICE
+  }),
+  annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+  changesDevice: true,
+  async call(a, ctx) {
+    const report = await launchWithSmoke(rt(), {
+      projectDir: projectOf(a, ctx),
+      bundle: a.bundle,
+      module: a.module,
+      ability: a.ability,
+      smoke: a.smoke,
+      smokeDelay: a.smokeDelay,
+      smokeScreenshot: pathArg(a, "smokeScreenshot", ctx),
+      device: deviceOf(a, ctx)
+    });
+    return jsonResult(report, report.smoke ? !report.smoke.passed : false);
+  }
+};
+function readLayoutBaseline(file) {
+  let text;
+  try {
+    text = fs9.readFileSync(file, "utf8");
+  } catch (err) {
+    throw new Error(`Cannot read the layout baseline ${file}: ${message(err)}`);
+  }
+  try {
+    return parseLayoutBaseline2(JSON.parse(text));
+  } catch (err) {
+    throw new Error(`${file} is not a saved \`dump layout\` JSON: ${message(err)}`);
+  }
+}
+var dumpLayoutTool = {
+  name: "dump_layout",
+  title: "Dump the UI layout",
+  description: "Dump the on-screen UI layout (`oniro-app dump layout`). Default: the pruned JSON tree (large; prefer flat or summary). flat: one line per labelled or interactive element (type, label, center as 0-1 fractions, flags), as text. summary: per window element, content, clickable and text-node counts. diff: compare with a layout saved earlier (via `output`): matched elements with IoU, missing, extra, and a 0-1 similarity.",
+  inputSchema: object({
+    bundle: str("Filter the layout to a single window/bundle."),
+    raw: bool("Return the unpruned layout tree.", false),
+    flat: bool("One line per element (type, label, center as 0-1 fractions, flags) instead of a JSON tree.", false),
+    summary: bool("Per window: element, content, clickable and text-node counts (JSON).", false),
+    diff: str(
+      "Compare with a saved `dump layout` JSON (relative to the project): matched elements with IoU, missing, extra, and a 0-1 similarity (JSON)."
+    ),
+    output: str("Also write what is returned (the JSON, or the flat text) to this file, e.g. as a later diff baseline."),
+    selector: str(
+      "Return only the elements matching this selector (attribute clauses or xpath=..., as in input), numbered for its [n] suffix: { display, selector, matches }."
+    ),
+    window: windowProperty,
+    ...PROJECT,
+    ...DEVICE
+  }),
+  annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+  changesDevice: false,
+  async call(a, ctx) {
+    const { config, logger } = rt();
+    if (a.raw && a.flat) throw new Error("raw and flat cannot be combined.");
+    const modes = [a.flat && "flat", a.summary && "summary", a.diff !== void 0 && "diff"].filter(Boolean);
+    if (modes.length > 1) throw new Error(`${modes.join(" and ")} cannot be combined.`);
+    if (a.raw && modes.length > 0) throw new Error(`raw cannot be combined with ${modes[0]}.`);
+    const selector = a.selector === void 0 ? void 0 : parseSelector2(a.selector);
+    if (selector && (a.raw || a.summary || a.diff !== void 0)) {
+      throw new Error("selector cannot be combined with raw, summary or diff.");
+    }
+    const windowId = windowFromArgs(a);
+    const diffPath = pathArg(a, "diff", ctx);
+    const baseline = diffPath !== void 0 ? readLayoutBaseline(diffPath) : void 0;
+    const result = await dumpLayout3({
+      config,
+      bundleName: a.bundle,
+      windowId,
+      prune: !a.raw,
+      detectKeyboard: !a.raw,
+      deviceSerial: deviceOf(a, ctx),
+      logger
+    });
+    const output = pathArg(a, "output", ctx);
+    if (selector) {
+      const matches = findLayoutNodes2(selectableTree2(result, windowId), selector);
+      const json2 = { display: result.display, selector: selector.raw, matches };
+      if (output) fs9.writeFileSync(output, `${JSON.stringify(json2, null, 2)}
+`);
+      return jsonResult(json2);
+    }
+    if (a.flat) {
+      const text = formatFlatLayout(result);
+      if (output) fs9.writeFileSync(output, text);
+      return { content: [{ type: "text", text }] };
+    }
+    let json;
+    if (a.summary) json = summarizeLayout2(result);
+    else if (baseline) json = diffLayouts2(baseline, result);
+    else json = result;
+    if (output) fs9.writeFileSync(output, `${JSON.stringify(json, null, 2)}
+`);
+    return jsonResult(json);
+  }
+};
+var input = {
+  name: "input",
+  title: "Send a UI input",
+  description: "Inject a UI input event via uitest uiInput (`oniro-app input`). Position it with target/targetId/targetType (an on-screen element), fx/fy (0-1 fractions of the display, as in dump_layout flat and the screenshot grid), or x/y (pixels). Returns x, y (the resolved start point in pixels), target (the element it resolved to) and keyboardHidden.",
+  inputSchema: object(
+    {
+      type: { type: "string", enum: INPUT_TYPES2, description: "Input type." },
+      ...targetProperties("Act on"),
+      fx: num2("Start X as a 0-1 fraction of the display width.", { minimum: 0, maximum: 1 }),
+      fy: num2("Start Y as a 0-1 fraction of the display height.", { minimum: 0, maximum: 1 }),
+      fx2: num2("End X fraction (swipe/drag/fling).", { minimum: 0, maximum: 1 }),
+      fy2: num2("End Y fraction (swipe/drag/fling).", { minimum: 0, maximum: 1 }),
+      x: num2("X pixel (click/swipe start)."),
+      y: num2("Y pixel (click/swipe start)."),
+      x2: num2("End X pixel (swipe/drag/fling)."),
+      y2: num2("End Y pixel (swipe/drag/fling)."),
+      speed: num2("Velocity for swipe/drag/fling, px/s."),
+      key: str(
+        "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."
+      ),
+      text: str("Text for inputText."),
+      clear: bool("inputText: clear the field (Ctrl+A, Delete) before typing.", false),
+      hideKeyboard: bool("Dismiss the soft keyboard afterwards, if it is up.", false),
+      ...DEVICE
+    },
+    ["type"]
+  ),
+  annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false },
+  changesDevice: true,
+  async call(a, ctx) {
+    const { config, logger } = rt();
+    const result = await performInput2({
+      config,
+      type: a.type,
+      target: selectorFromArgs(a),
+      targetIndex: targetIndexFromArgs(a),
+      windowId: windowFromArgs(a),
+      fx: a.fx,
+      fy: a.fy,
+      fx2: a.fx2,
+      fy2: a.fy2,
+      pxX: a.x,
+      pxY: a.y,
+      pxX2: a.x2,
+      pxY2: a.y2,
+      speed: a.speed,
+      key: a.key,
+      text: a.text,
+      clear: a.clear,
+      hideKeyboard: a.hideKeyboard,
+      deviceSerial: deviceOf(a, ctx),
+      logger
+    });
+    return jsonResult(result);
+  }
+};
+var DEFAULT_CONTACT_SHEET_FRAMES2 = 8;
+var TARGET_CROP_PAD2 = 0.02;
+var screenshot = {
+  name: "screenshot",
+  title: "Take a screenshot",
+  description: "Capture the screen and return it as an image, downscaled so its longest side is at most maxDim (`oniro-app screenshot --max-dim`). grid: overlay a 10x10 grid (axes 0.0-1.0) for picking fx/fy tap coordinates. crop / target*: a full-resolution crop of one region or element, for checking detail cheaply. contactSheet: capture a burst and tile it into one image with per-frame change diffs. diff: compare the screen with a baseline JPEG (pHash/dHash distance, pixel-change ratio, mean change). output: also write the image to a file (with diff: the full-resolution capture, usable as a later baseline).",
+  inputSchema: object({
+    output: str("Also write the image to this file (relative to the project)."),
+    grid: bool("Overlay a 10x10 coordinate grid.", false),
+    maxDim: int("Longest-side cap of the returned image, px.", { minimum: 256, maximum: 4096, default: 1024 }),
+    crop: str('Crop to this region, given as 0-1 fractions of the screen: "x1,y1,x2,y2".'),
+    ...targetProperties("Crop to"),
+    contactSheet: bool("Capture a burst and composite it into one tiled contact sheet.", false),
+    burst: int("With contactSheet: the number of frames.", { minimum: 1, default: DEFAULT_CONTACT_SHEET_FRAMES2 }),
+    interval: int("With contactSheet: delay between frames, ms.", { minimum: 0, default: 50 }),
+    diff: str(
+      "Compare the screen with this baseline JPEG (relative to the project): pHash and dHash distance, pixel-change ratio, mean change."
+    ),
+    ...PROJECT,
+    ...DEVICE
+  }),
+  annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+  changesDevice: false,
+  async call(a, ctx) {
+    const { config, logger } = rt();
+    const deviceSerial = deviceOf(a, ctx);
+    const maxDim = a.maxDim;
+    const output = pathArg(a, "output", ctx);
+    const selector = selectorFromArgs(a);
+    const windowId = windowFromArgs(a);
+    if (a.diff !== void 0) {
+      if (a.crop !== void 0 || selector || windowId !== void 0 || a.grid || a.contactSheet) {
+        throw new Error("diff cannot be combined with crop, target* / selector / window, grid, or contactSheet.");
+      }
+      const baselinePath = pathArg(a, "diff", ctx);
+      let baseline;
+      try {
+        baseline = fs9.readFileSync(baselinePath);
+      } catch (err) {
+        throw new Error(`Cannot read the baseline ${baselinePath}: ${message(err)}`);
+      }
+      const shot2 = await takeScreenshot2({ config, deviceSerial, logger });
+      if (output) fs9.writeFileSync(output, shot2.pixels);
+      const diff = await diffScreenshots(baseline, shot2.pixels);
+      const shown = await renderWithGrid(shot2.pixels, { maxDim });
+      return jsonResult({ baseline: baselinePath, current: output ?? null, ...diff }, false, [jpeg(shown.buf)]);
+    }
+    if (a.crop !== void 0 || selector || windowId !== void 0) {
+      if (a.crop !== void 0 && (selector || windowId !== void 0)) {
+        throw new Error("Use either crop or target* / selector / window, not both.");
+      }
+      if (a.grid || a.contactSheet) throw new Error("crop / target cannot be combined with grid or contactSheet.");
+      let rect;
+      let label;
+      if (selector) {
+        const located = await locateTarget2({
+          config,
+          selector,
+          index: targetIndexFromArgs(a),
+          windowId,
+          hideKeyboard: false,
+          deviceSerial,
+          logger
+        });
+        if (!located.node.b) throw new Error(`${describeLayoutNode4(located.node)} has no bounds to crop to.`);
+        rect = padCropRect(located.node.b, TARGET_CROP_PAD2);
+        label = describeLayoutNode4(located.node);
+      } else if (windowId !== void 0) {
+        const { tree } = await dumpLayout3({ config, windowId, deviceSerial, logger });
+        const win = listLayoutWindows2(tree).find((w) => w.windowId === windowId);
+        if (!win?.b) throw new Error(`Window ${windowId} has no bounds to crop to.`);
+        rect = win.b;
+        label = `window ${windowId}${win.bundle ? ` (${win.bundle})` : ""}`;
+      } else {
+        rect = parseCropRect(a.crop);
+        label = rect.map((n) => n.toFixed(3)).join(",");
+      }
+      const shot2 = await takeScreenshot2({ config, deviceSerial, logger });
+      const cropped = await cropImage(shot2.pixels, rect, { maxDim });
+      if (output) fs9.writeFileSync(output, cropped.buf);
+      const { buf: buf2, ...dims2 } = cropped;
+      return jsonResult({ output: output ?? null, region: label, ...dims2 }, false, [jpeg(buf2)]);
+    }
+    if (a.contactSheet) {
+      const intervalMs = a.interval;
+      const frames = await captureBurst2({ config, count: a.burst, intervalMs, deviceSerial, logger });
+      const diffs = await frameDiffs(frames);
+      const sheet = await buildContactSheet(frames, { maxDim, diffs });
+      if (output) fs9.writeFileSync(output, sheet.buf);
+      const json = {
+        sheet: output ?? null,
+        frameCount: frames.length,
+        cols: sheet.cols,
+        rows: sheet.rows,
+        intervalMs,
+        note: "t_ms is nominal (idx*interval); diffVsPrev is 0..1 mean greyscale diff vs the previous frame.",
+        frames: frames.map((_, i) => ({ idx: i, t_ms: i * intervalMs, diffVsPrev: diffs[i] ?? 0 }))
+      };
+      return jsonResult(json, false, [jpeg(sheet.buf)]);
+    }
+    const shot = await takeScreenshot2({ config, deviceSerial, logger });
+    const rendered = await renderWithGrid(shot.pixels, { maxDim, grid: !!a.grid });
+    if (output) fs9.writeFileSync(output, rendered.buf);
+    const { buf, ...dims } = rendered;
+    return jsonResult({ output: output ?? null, grid: !!a.grid, ...dims }, false, [jpeg(buf)]);
+  }
+};
+var wait = {
+  name: "wait",
+  title: "Wait for a device condition",
+  description: "Wait for a device condition (`oniro-app wait --json`): a hilog line (log), boot (boot), a bundle to start (bundle), or an on-screen element (target / targetId / targetType or selector, optionally in one window, or its absence with gone). Returns the matched log entry or element, or {booted}, {gone}, {bundle, running}. isError on timeout.",
+  inputSchema: object({
+    log: str("Resolve when a hilog line (tag: message) logged after the call starts matches this regex."),
+    since: str(
+      'With log: also match lines logged up to N seconds before the call started, measured on the device clock; "all" matches everything still in the device log buffer.'
+    ),
+    boot: bool("Resolve when the device is reachable (optionally also pidOf).", false),
+    bundle: str("With log: filter to this bundle. Alone: wait until this bundle is running."),
+    pidOf: str("With boot: also require this process to have a pid."),
+    domain: str("With log: hilog domain filter (e.g. 0xD003900)."),
+    ...targetProperties("Resolve when", { index: false }),
+    gone: bool("With target*: resolve when no uncovered element matches any more.", false),
+    interval: int("With target*: poll interval, ms (each poll is a layout dump).", { minimum: 1, default: 500 }),
+    timeout: int("Max wait, ms.", { minimum: 0, default: 3e4 }),
+    ...DEVICE
+  }),
+  annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+  changesDevice: false,
+  async call(a, ctx) {
+    const { config, logger } = rt();
+    const deviceSerial = deviceOf(a, ctx);
+    const timeoutMs = a.timeout;
+    const selector = selectorFromArgs(a);
+    const windowId = windowFromArgs(a);
+    if (windowId !== void 0 && !selector) throw new Error("window applies only to target* and selector.");
+    if (a.since !== void 0 && !a.log) throw new Error("since applies only to log.");
+    if (a.log) {
+      const entry = await waitForLog2({
+        config,
+        pattern: new RegExp(a.log),
+        timeoutMs,
+        bundle: a.bundle,
+        domain: a.domain,
+        deviceSerial,
+        lookbackMs: parseSince(a.since),
+        logger
+      });
+      return jsonResult(entry);
+    }
+    if (a.boot) {
+      await waitForBoot2({ config, untilPidOf: a.pidOf, timeoutMs, deviceSerial, logger });
+      return jsonResult({ booted: true });
+    }
+    if (selector) {
+      const node = await waitForTarget2({
+        config,
+        selector,
+        gone: a.gone,
+        windowId,
+        timeoutMs,
+        pollMs: a.interval,
+        deviceSerial,
+        logger
+      });
+      return jsonResult(node ? node : { gone: true });
+    }
+    if (a.bundle) {
+      await waitForBundle2({ config, bundle: a.bundle, timeoutMs, deviceSerial, logger });
+      return jsonResult({ bundle: a.bundle, running: true });
+    }
+    throw new Error("Specify one of log, boot, bundle, target (or targetId / targetType), or selector.");
+  }
+};
+var logsCrash = {
+  name: "logs_crash",
+  title: "Explain the last crash",
+  description: "Fetch the newest faultlog of an app from the device and say what happened (`oniro-app logs crash --json`): a native crash (cpp_crash), an uncaught ArkTS/JS error (js_crash), a freeze (app_freeze), or none. Returns crashed, kind, subtype, confidence, bundle, pid, time, reason, topFrame, projectFrame, file, line, column, jsError, stack, nativeFrames, jsFrames, binderChain, deadlocks, notes, path, rawPath; `{crashed: false, kind: null}` when there is no fault. Not an error when there was no crash: check `crashed`.",
+  inputSchema: object({
+    bundle: str("App to look for (default: the bundleName of the project, else any process)."),
+    since: str("Only faults from the last N seconds (device clock), or since an ISO 8601 time."),
+    wait: int(
+      "Keep looking this long when there is no fault yet, ms; hiview writes the faultlog a few seconds after the process dies.",
+      { minimum: 0, default: 0 }
+    ),
+    path: str("Analyse this local faultlog (or faultloggerd .json crash record) instead of fetching one."),
+    output: str("Where to save the fetched faultlog.", { default: path18.join(os4.homedir(), ".oniro", "faultlogs") }),
+    ...PROJECT,
+    ...DEVICE
+  }),
+  annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+  changesDevice: false,
+  async call(a, ctx) {
+    const since = parseCrashSince(a.since);
+    const local = pathArg(a, "path", ctx);
+    const bundle = a.bundle ?? (local ? void 0 : projectBundle(projectOf(a, ctx)));
+    let verdict;
+    if (local) {
+      verdict = analyzeFaultLog2(fs9.readFileSync(local, "utf8"), { name: path18.basename(local), path: local, rawPath: local });
+    } else {
+      const { config, logger } = rt();
+      verdict = await latestCrash3({
+        config,
+        bundle,
+        since,
+        waitMs: a.wait,
+        deviceSerial: deviceOf(a, ctx),
+        saveDir: pathArg(a, "output", ctx),
+        logger
+      });
+    }
+    const none = { crashed: false, kind: null, bundle: bundle ?? null, since: since instanceof Date ? since.toISOString() : since ?? null };
+    return jsonResult(verdict ?? none);
+  }
+};
+var perfTraceTool = {
+  name: "perf_trace",
+  title: "Measure frames, jank and startup",
+  description: "Capture a hitrace trace while the app cold-launches (`launch`), a flow file is replayed (`flow`), or for a fixed time (`for`), and summarise it (`oniro-app perf trace --json`). Returns ok, bundle, durationMs, trace (local path), refreshRateHz, frames (total, janky, jankRate, p50Ms, p95Ms, maxMs, missedVsyncs, longest), startup (coldMs, firstFrameMs, processMs, from, to) or null, flow (the replay report) or null, pid, mainThread, scenes (RenderService's own jank reports), hiperf, notes, gate (passed, failures), error. isError when the capture failed or a threshold (maxJankRate, maxStartupMs) or the flow failed. Launching force-stops the app first.",
+  inputSchema: object({
+    bundle: str("The app to measure (default: the flow's bundle, else the bundleName of the project)."),
+    launch: bool("Force-stop the app, start tracing, then cold-launch it and report its startup time.", false),
+    flow: str("A flow file (as for `replay`) to replay while tracing; relative to the project."),
+    for: int("Without flow: how long to capture (after the launch with launch), ms. With flow: how long to keep capturing after it.", {
+      minimum: 1
+    }),
+    ability: str("Ability `launch` starts (default: the main ability)."),
+    out: str("Where to save the trace (default: a file in the system temp dir)."),
+    categories: { type: "array", items: { type: "string" }, description: `hitrace categories (default ${DEFAULT_TRACE_CATEGORIES2.join(", ")}).` },
+    bufferKb: int("hitrace buffer size, KB.", { minimum: 1, default: DEFAULT_TRACE_BUFFER_KB2 }),
+    hiperf: bool("Also sample the app's process with hiperf and list its top functions.", false),
+    maxJankRate: num2("Fail (isError) when the share of janky frames is above this.", { minimum: 0, maximum: 1 }),
+    maxStartupMs: int("Fail (isError) when the cold start takes longer than this, ms (needs launch).", { minimum: 1 }),
+    stepTimeout: int("With flow: how long to wait for a step's selector and expect, ms.", { minimum: 1 }),
+    fallback: bool("With flow: act on a step's fallback point when its selector is not found.", false),
+    wake: bool("With launch or flow: wake the screen and swipe a credential-less lock screen away (false = --no-wake).", true),
+    ...PROJECT,
+    ...DEVICE
+  }),
+  annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false },
+  // It force-stops and launches the app, and a flow taps and swipes.
+  changesDevice: true,
+  async call(a, ctx) {
+    const { config, logger } = rt();
+    const flowFile = pathArg(a, "flow", ctx);
+    const flow = flowFile ? readFlowFile2(flowFile) : void 0;
+    const report = await perfTrace2({
+      config,
+      logger,
+      deviceSerial: deviceOf(a, ctx),
+      bundle: a.bundle ?? flow?.bundle ?? projectBundle(projectOf(a, ctx)),
+      ability: a.ability,
+      launch: a.launch,
+      flow,
+      replay: { stepTimeoutMs: a.stepTimeout, fallback: a.fallback },
+      forMs: a.for,
+      out: pathArg(a, "out", ctx),
+      categories: a.categories,
+      bufferKb: a.bufferKb,
+      hiperf: a.hiperf,
+      wake: a.wake
+    });
+    const gate = evaluatePerfGate2(report, { maxJankRate: a.maxJankRate, maxStartupMs: a.maxStartupMs });
+    return jsonResult({ ...report, gate }, perfExitCode(report, gate) !== 0);
+  }
+};
+var screens = {
+  name: "screens",
+  title: "Inventory pages and routes",
+  description: "Static inventory of the pages and routes of a project, from its sources, without a build or a device (`oniro-app screens --json`): @Entry and NavDestination pages, the router/NavPathStack call sites between them, the content nodes each page renders, and placeholder markers (TODO/FIXME, placeholder-like text, empty build()). Returns pages (name, module, file, line, component, entry, kind, registered, contentNodes, routesOut), routes (from, to, file, line, via, dynamic), placeholders (file, line, text, kind), warnings, modules, projectDir.",
+  inputSchema: object({ ...PROJECT }),
+  annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+  changesDevice: false,
+  async call(a, ctx) {
+    try {
+      return jsonResult(inventoryScreens2({ projectDir: projectOf(a, ctx) }));
+    } catch (err) {
+      return jsonResult({ error: message(err) }, true);
+    }
+  }
+};
+var SDK_PROPS = {
+  api: int(
+    "The SDK API level to read. Default: the project's compileSdkVersion, else the newest installed SDK.",
+    { minimum: 1 }
+  ),
+  sdk: str("An SDK API directory (holding ets/) to read instead."),
+  project: str("The project whose compileSdkVersion picks the SDK (default: the server's --project)."),
+  rebuild: bool("Rebuild the index even if the cached one is current.", false)
+};
+var API_KINDS = [
+  "namespace",
+  "class",
+  "interface",
+  "enum",
+  "enumMember",
+  "type",
+  "function",
+  "method",
+  "constructor",
+  "property",
+  "variable",
+  "component",
+  "decorator",
+  "macro",
+  "typedef",
+  "struct"
+];
+function sdkOpts(a, ctx) {
+  return {
+    api: a.api !== void 0 ? String(a.api) : void 0,
+    sdk: pathArg(a, "sdk", ctx),
+    project: projectOf(a, ctx),
+    rebuild: a.rebuild
+  };
+}
+var apiSearch = {
+  name: "api_search",
+  title: "Search the SDK API",
+  description: "Ranked search of the SDK's declarations at one API level (`oniro-app api search --json`): the ArkTS API, the ArkUI components and decorators, and the Node-API C headers. Every word must match a symbol name (exact > prefix > camelCase part > substring) or its doc line; a dotted word matches qualified names (`router.pushUrl`). Returns sdk, query, total, hits (name, qualifiedName, kind, kit, import, module, since, deprecated, useInstead, syscap, systemApi, file, path, line, signature, doc, overloads, score). isError when nothing matches.",
+  inputSchema: object(
+    {
+      query: str('The search words, e.g. "navigation push" or "router.pushUrl".'),
+      kit: str("Only symbols this kit exports (`ArkUI` or `@kit.ArkUI`)."),
+      kind: { type: "array", items: { type: "string", enum: API_KINDS }, description: "Only these kinds." },
+      lang: { type: "string", enum: ["arkts", "c"], description: "Only `arkts` declarations or `c` (Node-API headers)." },
+      limit: int("At most n hits.", { minimum: 1, default: 20 }),
+      deprecated: bool("Include @deprecated symbols (false = --no-deprecated).", true),
+      systemapi: bool("Include @systemapi symbols, for system apps only (false = --no-systemapi).", true),
+      ...SDK_PROPS
+    },
+    ["query"]
+  ),
+  annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+  changesDevice: false,
+  async call(a, ctx) {
+    const run = runApiSearch(a.query, {
+      ...sdkOpts(a, ctx),
+      kit: a.kit,
+      kind: a.kind,
+      lang: a.lang,
+      limit: String(a.limit),
+      deprecated: a.deprecated,
+      systemapi: a.systemapi
+    });
+    return jsonResult(run.json, run.total === 0);
+  }
+};
+var apiShow = {
+  name: "api_show",
+  title: "Look up one SDK symbol",
+  description: "Exact lookup (`oniro-app api show --json`): is `symbol` declared at this API level? Takes a qualified name (`NavPathStack.pushPathByName`, `router.pushUrl`, `Column`, `@Local`, `napi_create_threadsafe_function`); when none matches, names that end with it. Returns sdk, symbol, found, entries (the api_search hit fields, every overload), and on a miss alsoIn ([{api, since}], the other installed SDKs that declare it) and suggestions. isError when it is not declared.",
+  inputSchema: object(
+    {
+      symbol: str("The symbol, e.g. `NavPathStack.pushPathByName`."),
+      kit: str("Only declarations this kit exports."),
+      otherSdks: bool("On a miss, look in the other installed SDKs (false = --no-other-sdks).", true),
+      ...SDK_PROPS
+    },
+    ["symbol"]
+  ),
+  annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+  changesDevice: false,
+  async call(a, ctx) {
+    const run = runApiShow(a.symbol, {
+      ...sdkOpts(a, ctx),
+      kit: a.kit,
+      otherSdks: a.otherSdks
+    });
+    return jsonResult(run.json, !run.found);
+  }
+};
+var DOCS_PROPS = {
+  api: int("The SDK API level whose release picks the docs (default: the project's compileSdkVersion, else the newest installed SDK)."),
+  sdk: str("An SDK API directory (holding ets/) whose version picks the docs."),
+  ref: str("A docs branch or tag (`OpenHarmony-6.1-Release`, `master`) instead of the SDK-chosen one."),
+  ...PROJECT
+};
+function docsOpts(a, ctx) {
+  return {
+    api: a.api !== void 0 ? String(a.api) : void 0,
+    sdk: pathArg(a, "sdk", ctx),
+    ref: a.ref,
+    project: projectOf(a, ctx)
+  };
+}
+var docsSearch = {
+  name: "docs_search",
+  title: "Search the OpenHarmony docs",
+  description: "Ranked search of the OpenHarmony application-development documentation of the release matching the SDK (`oniro-app docs search --json`): usage guides (ArkUI components, navigation, state management, data storage, abilities), kit API prose, business error codes and platform behaviour, which the SDK typings behind api_search do not say. Documents containing every word rank by where the words occur (title, headings, path, body); each hit names the matching sections, to read with docs_show. Use domain words (a component, kit or decorator name, an error code), not sentences. Returns docs (ref, dir, tree, sdk), query, terms, total, hits (path, title, score, headings [{line, text}], snippet). isError when nothing matches, or when the docs are not synced (`oniro-app docs sync`).",
+  inputSchema: object(
+    {
+      query: str('The search words, e.g. "LazyForEach reuse", "relationalStore insert", "14800011".'),
+      limit: int("At most n hits.", { minimum: 1, maximum: 30, default: 8 }),
+      section: str("Only documents under this subtree: `ui`, `database`, `reference/errorcodes`, `application-models`."),
+      ...DOCS_PROPS
+    },
+    ["query"]
+  ),
+  annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+  changesDevice: false,
+  async call(a, ctx) {
+    try {
+      const run = runDocsSearch(a.query, {
+        ...docsOpts(a, ctx),
+        limit: a.limit !== void 0 ? String(a.limit) : void 0,
+        section: a.section
+      });
+      return jsonResult(run.json, run.result.total === 0);
+    } catch (err) {
+      return errorResult(message(err));
+    }
+  }
+};
+var docsShow = {
+  name: "docs_show",
+  title: "Read one OpenHarmony doc",
+  description: "One documentation file (a path docs_search returned, relative to en/application-dev), or one section of it by heading (`oniro-app docs show --json`). Images and inline HTML are dropped; a long document is cut at maxLines with the list of its sections, so ask for a heading rather than the whole file. Returns docs, found, path, text, truncated, lines, headings; isError with suggestions (close paths, or the headings when the heading did not match).",
+  inputSchema: object(
+    {
+      path: str("The document path, e.g. `ui/arkts-navigation-jump.md`."),
+      heading: str("A heading (or a distinctive part of it, case-insensitive): only that section."),
+      maxLines: int("At most n lines.", { minimum: 20, maximum: 1200, default: 250 }),
+      ...DOCS_PROPS
+    },
+    ["path"]
+  ),
+  annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+  changesDevice: false,
+  async call(a, ctx) {
+    try {
+      const run = runDocsShow(a.path, {
+        ...docsOpts(a, ctx),
+        heading: a.heading,
+        lines: a.maxLines !== void 0 ? String(a.maxLines) : void 0
+      });
+      return jsonResult(run.json, !run.result.found);
+    } catch (err) {
+      return errorResult(message(err));
+    }
+  }
+};
+var doctor = {
+  name: "doctor",
+  title: "Check the toolchain",
+  description: "Check that this machine can build, check, sign, install and test (`oniro-app doctor --json`): node, java, the SDK the project compiles with, the command-line tools, a `check arkts` self-test, hdc and a reachable device at the project's API, signing material, free disk space. Returns ok, checks (id, status ok/warn/fail/skip, detail, fix, fixed), project, versions. isError when a check fails.",
+  inputSchema: object({
+    project: str("Project directory (default: the server's --project when it holds build-profile.json5)."),
+    fix: bool("Install the project's missing OpenHarmony SDK.", false),
+    device: bool("Check the device (false = --no-device, for a machine that only builds).", true),
+    serial: str("The device to check, when several are connected (default: the server's --device)."),
+    arktsCheck: bool("Run the `check arkts` self-test (false = --no-arkts-check).", true)
+  }),
+  annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+  changesDevice: false,
+  async call(a, ctx) {
+    const { config, logger, progress } = getRuntime();
+    let dir;
+    if (typeof a.project === "string") dir = projectOf(a, ctx);
+    else if (fs9.existsSync(path18.join(ctx.projectDir, "build-profile.json5"))) dir = ctx.projectDir;
+    const report = await runDoctor2({
+      config,
+      projectDir: dir,
+      fix: a.fix,
+      device: a.device,
+      deviceSerial: a.serial ?? ctx.deviceSerial,
+      arktsSelfTest: a.arktsCheck,
+      logger,
+      progress
+    });
+    return jsonResult(report, doctorExitCode(report) !== 0);
+  }
+};
+var devices = {
+  name: "devices",
+  title: "List devices",
+  description: "List the connected hdc devices (`oniro-app devices --json`), as `{devices: [{serial, connection, status}]}`. long: also ask each connected device for its OS family, version, API level, CPU ABI, device type and model (`info`).",
+  inputSchema: object({
+    long: bool(
+      "Also ask each connected device for its OS family (HarmonyOS / OpenHarmony), version, API level, CPU ABI, device type and model.",
+      false
+    )
+  }),
+  annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+  changesDevice: false,
+  async call(a) {
+    const long = a.long;
+    const { devices: list2, infos } = await queryDevices(long);
+    return jsonResult({ devices: devicesJson(list2, infos, long) });
+  }
+};
+var ALL_TOOLS = [
+  build,
+  checkArktsTool,
+  test,
+  apply,
+  launch,
+  dumpLayoutTool,
+  input,
+  screenshot,
+  wait,
+  logsCrash,
+  perfTraceTool,
+  screens,
+  apiSearch,
+  apiShow,
+  docsSearch,
+  docsShow,
+  doctor,
+  devices
+];
+var TOOL_NAMES = ALL_TOOLS.map((t) => t.name);
+function selectTools(names, readOnly) {
+  if (names) {
+    const unknown = names.filter((n) => !TOOL_NAMES.includes(n));
+    if (unknown.length) throw new Error(`Unknown tool${unknown.length > 1 ? "s" : ""} ${unknown.join(", ")}. Tools: ${TOOL_NAMES.join(", ")}.`);
+  }
+  return ALL_TOOLS.filter((t) => (!names || names.includes(t.name)) && !(readOnly && t.changesDevice));
+}
+
+// src/commands/serve.ts
+function parseToolList(raw) {
+  if (raw === void 0) return void 0;
+  const names = raw.split(",").map((s) => s.trim()).filter(Boolean);
+  if (!names.length) throw new OniroError6("--tools needs at least one tool name.");
+  return names;
+}
+function instructions(ctx, toolCount) {
+  return `oniro-app: build, check, test, deploy and inspect the OpenHarmony/HarmonyOS app in ${ctx.projectDir}${ctx.deviceSerial ? ` on device ${ctx.deviceSerial}` : ""} (${toolCount} tools). Each tool runs the matching \`oniro-app\` command and returns its \`--json\` object, as structured content and as JSON text; isError is true when the command would exit non-zero (a failed build, check, test or smoke check, a missing symbol) or could not run. Relative paths resolve against the project. A typical round: check_arkts on the changed files, build, apply with smoke, then screenshot and dump_layout (flat) to see the result, input to drive it, logs_crash when it died.`;
+}
+function registerServeCommand(program) {
+  const serve = program.command("serve").description("Serve oniro-app to other programs.");
+  serve.command("mcp").description(
+    `A Model Context Protocol server on stdio (newline-delimited JSON-RPC 2.0) exposing the gate commands as typed tools for agents: ${TOOL_NAMES.join(", ")}. Each tool returns the JSON the command's --json prints. stdout carries only the protocol; logs go to stderr. Register it with Claude Code: \`claude mcp add oniro-app -- oniro-app serve mcp --project <dir>\`.`
+  ).allowExcessArguments(false).option("--project <dir>", "Project the tools work on unless a call names another (default: the current directory).").option("--device <serial>", "Device the tools target unless a call names another (default: the only connected one).").option("--tools <list>", `Expose only these tools, comma-separated (of ${TOOL_NAMES.join(", ")}).`).option("--read-only", "Leave out the tools that change the device: apply, launch, input, test.").action(async (opts) => {
+    const { logger } = getRuntime();
+    const projectDir = path19.resolve(opts.project ?? process.cwd());
+    if (!fs10.existsSync(projectDir)) throw new OniroError6(`--project ${projectDir} does not exist.`);
+    const tools = selectTools(parseToolList(opts.tools), !!opts.readOnly);
+    if (!tools.length) throw new OniroError6("No tool left to serve: --read-only removed every tool --tools named.");
+    const context = { projectDir, deviceSerial: opts.device };
+    const server = new McpServer({
+      name: "oniro-app",
+      version: program.version() ?? "0.0.0",
+      tools,
+      context,
+      instructions: instructions(context, tools.length),
+      logger
+    });
+    const protocolWrite = process.stdout.write.bind(process.stdout);
+    process.stdout.write = ((chunk, ...rest) => process.stderr.write(chunk, ...rest));
+    process.stdout.on("error", () => process.exit(0));
+    logger.info(`oniro-app MCP server on stdio: project ${projectDir}, tools ${tools.map((t) => t.name).join(", ")}`);
+    await serveStdio(server, { write: (line) => void protocolWrite(line) });
+    logger.info("stdin closed; MCP server exiting.");
+    protocolWrite("", () => process.exit(0));
+  });
+}
+
+// src/commands/record.ts
+import { InvalidArgumentError as InvalidArgumentError6 } from "commander";
+import * as fs11 from "fs";
+import * as path20 from "path";
+import { formatFlow, recordFlow } from "@oniroproject/core";
+function positiveMs3(raw) {
+  const n = Number(raw);
+  if (!Number.isFinite(n) || n <= 0) throw new InvalidArgumentError6("Expected a positive number of milliseconds.");
+  return Math.floor(n);
+}
+function registerRecordCommand(program) {
+  program.command("record").description(
+    "Record what is done on the device into a flow file for `replay`. Runs uitest's recorder (`uitest uiRecord record -l`), which logs every tap, swipe and key with the widget under the finger and dumps the layout after each one; each event becomes a step with the most specific stable selector for that widget in the layout on screen when it happened, a fallback point, and an `expect` element that appeared after it. Typing collapses into one inputText step per field. Stops on Ctrl+C or after --for."
+  ).requiredOption("--out <file>", "Where to write the flow (JSON).").option("--for <ms>", "Stop after this long instead of waiting for Ctrl+C.", positiveMs3).option("--bundle <bundle>", "The app being recorded (default: the foreground app when recording starts).").option("--no-wake", "Leave the screen as it is (by default it is turned on, a lock screen without a credential is swiped away, and it is kept on while recording).").option("--raw <dir>", "Also keep uitest's raw recording (events, layouts, touch times) in this directory, for bug reports.").option("--device <serial>", "Target device serial.").option("--json", "Print {out, steps, events, warnings} as JSON.").action(async (opts) => {
+    const { config, logger } = getRuntime();
+    await withInterrupt(logger, "stopping the recorder", async (abortSignal) => {
+      const result = await recordFlow({
+        config,
+        durationMs: opts.for,
+        abortSignal,
+        bundle: opts.bundle,
+        wake: opts.wake,
+        rawDir: opts.raw,
+        deviceSerial: opts.device,
+        logger,
+        onEvents: (n) => logger.info(`${n} event line(s) recorded`)
+      });
+      const out = path20.resolve(opts.out);
+      fs11.mkdirSync(path20.dirname(out), { recursive: true });
+      fs11.writeFileSync(out, formatFlow(result.flow));
+      for (const w of result.warnings) logger.warn(w);
+      if (opts.json) {
+        process.stdout.write(
+          `${JSON.stringify({ out, steps: result.flow.steps.length, events: result.events, warnings: result.warnings }, null, 2)}
+`
+        );
+      } else {
+        process.stdout.write(`Wrote ${result.flow.steps.length} step(s) to ${out}.
+`);
+      }
+    });
+  });
+}
+
+// src/commands/replay.ts
+import { InvalidArgumentError as InvalidArgumentError7 } from "commander";
+import * as path21 from "path";
+import { readFlowFile as readFlowFile3, replayFlow } from "@oniroproject/core";
+function stepIndex(raw) {
+  const n = Number(raw);
+  if (!Number.isInteger(n) || n < 0) throw new InvalidArgumentError7("Expected a step index (0-based).");
+  return n;
+}
+function positiveMs4(raw) {
+  const n = Number(raw);
+  if (!Number.isFinite(n) || n <= 0) throw new InvalidArgumentError7("Expected a positive number of milliseconds.");
+  return Math.floor(n);
+}
+function replayExitCode(report) {
+  return report.outcome === "passed" ? 0 : report.outcome === "diverged" ? 1 : 2;
+}
+function formatReplayStep(s) {
+  const what = s.selector ? ` ${s.selector}` : "";
+  const how = s.usedFallback ? " (at the recorded point)" : "";
+  return `[${s.index}] ${s.action}${what}${how}  ${s.ok ? "ok" : "FAILED"}  ${(s.durationMs / 1e3).toFixed(1)} s`;
+}
+function formatDivergence(r) {
+  const lines = [`Diverged at step ${r.failedStep} (${r.reason}): ${r.message}`];
+  if (r.screenshot) lines.push(`  screenshot: ${r.screenshot}`);
+  for (const n of r.nearMatches ?? []) lines.push(`  near match: ${n.element} (differs in ${n.differs})`);
+  if (r.layout) {
+    const where = r.layout.appOnScreen ? `on screen in ${r.bundle}` : "on screen";
+    lines.push(`  ${where} (${r.layout.elementCount} element(s)${r.layout.keyboard ? ", keyboard up" : ""}):`);
+    for (const e of r.layout.elements) lines.push(`    ${e}`);
+    if (r.layout.elementCount > r.layout.elements.length) lines.push(`    \u2026 ${r.layout.elementCount - r.layout.elements.length} more`);
+  }
+  return lines.join("\n");
+}
+function registerReplayCommand(program) {
+  program.command("replay <flow>").description(
+    "Replay a flow file (written by `record` or by hand) on the device: for each step, wait for its selector, act on it the way `input --selector` does, then wait for its `expect`. Stops at the first step that fails and reports the step, why (not-found, expect-not-found, wrong-screen, ambiguous, covered, action-failed), a screenshot and what was on screen. Exits 0 when every step ran, 1 when the flow diverged, 2 when it could not run (invalid flow file, no device)."
+  ).option("--from <i>", "First step to run (0-based).", stepIndex).option("--to <i>", "Last step to run (0-based, inclusive).", stepIndex).option("--step-timeout <ms>", "How long to wait for a step's selector and its expect (a step's timeoutMs overrides it).", positiveMs4, 1e4).option("--screenshots <dir>", "Save a screenshot after every step (step-<i>.jpeg), and the divergence screenshot, here.").option("--fallback", "When a step's selector is not found, act on its recorded fallback point instead of stopping.").option("--launch", "Force-stop and start the flow's app (its bundle and ability) before the first step.").option("--no-wake", "Leave the screen as it is (by default it is turned on, a lock screen without a credential is swiped away, and it is kept on during the run).").option("--device <serial>", "Target device serial.").option(
+    "--json",
+    "Print the report as JSON: ok, outcome, steps, failedStep, reason, message, selector, screenshot, layout, nearMatches, error, warnings."
+  ).action(async (flowPath, opts) => {
+    const { config, logger } = getRuntime();
+    let report;
+    try {
+      const flow = readFlowFile3(path21.resolve(flowPath));
+      report = await withInterrupt(logger, "stopping the replay", (abortSignal) => replayFlow({
+        config,
+        flow,
+        abortSignal,
+        from: opts.from,
+        to: opts.to,
+        stepTimeoutMs: opts.stepTimeout,
+        screenshotsDir: opts.screenshots,
+        fallback: opts.fallback,
+        launch: opts.launch,
+        wake: opts.wake,
+        deviceSerial: opts.device,
+        logger,
+        onStep: opts.json ? void 0 : (s) => process.stdout.write(`${formatReplayStep(s)}
+`)
+      }));
+    } catch (err) {
+      report = { ok: false, outcome: "error", range: [0, 0], steps: [], error: err.message, warnings: [] };
+    }
+    if (opts.json) {
+      process.stdout.write(`${JSON.stringify(report, null, 2)}
+`);
+    } else if (report.outcome === "passed") {
+      process.stdout.write(`Flow passed: ${report.steps.length} step(s).
+`);
+    } else if (report.outcome === "diverged") {
+      process.stdout.write(`${formatDivergence(report)}
+`);
+    }
+    for (const w of report.warnings) logger.warn(w);
+    if (report.error) logger.error(report.error);
+    process.exitCode = replayExitCode(report);
+  });
+}
+
+// src/bin/oniro-app.ts
+var CLI_VERSION = "0.19.0";
+function buildProgram() {
+  const program = new Command11().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().enablePositionalOptions().exitOverride();
+  registerSdkCommand(program);
+  registerCmdToolsCommand(program);
+  registerEmulatorCommand(program);
+  registerBuildCommand(program);
+  registerSignCommand(program);
+  registerAuthCommand(program);
+  registerAppCommand(program);
+  registerCreateCommand(program);
+  registerTemplatesCommand(program);
+  registerRebootCommand(program);
+  registerWaitCommand(program);
+  registerWatchCommand(program);
+  registerScreenshotCommand(program);
+  registerDumpCommand(program);
+  registerDevicesCommand(program);
+  registerFileCommand(program);
+  registerLintCommand(program);
+  registerCheckCommand(program);
+  registerDoctorCommand(program);
+  registerScreensCommand(program);
+  registerApiCommand(program);
+  registerDocsCommand(program);
+  registerTestCommand(program);
+  registerInputCommand(program);
+  registerRecordCommand(program);
+  registerReplayCommand(program);
+  registerPerfCommand(program);
+  registerLogsCommand(program);
+  registerHdcCommand(program);
+  registerServeCommand(program);
+  return program;
+}
+async function main() {
+  const program = buildProgram();
+  try {
+    await program.parseAsync(process.argv);
+  } catch (err) {
+    if (err instanceof CommanderError) {
+      process.exitCode = err.exitCode;
+      return;
     }
-    process.exit(1);
+    const message2 = err instanceof OniroError7 ? err.message : err instanceof Error ? err.message : String(err);
+    const stack = process.env.ONIRO_DEBUG === "1" && err instanceof Error && err.stack ? `${err.stack}
+` : "";
+    process.stderr.write(`[error] ${message2}
+${stack}`, () => process.exit(1));
   }
 }
 void main();