@oniroproject/core 0.17.0 → 0.18.0

package/dist/index.js

@@ -599,14 +599,14 @@ var pipelineAsync = promisify(pipeline);
 async function downloadFile(opts) {
   const { url, dest, progress, abortSignal } = opts;
   const proto = url.startsWith("https") ? https : http;
-  return new Promise((resolve21, reject) => {
+  return new Promise((resolve22, reject) => {
     const s = Math.max(0, Math.min(100, opts.start ?? 0));
     const r = Math.max(0, Math.min(100 - s, opts.range ?? 100));
     let settled = false;
     const done = (err) => {
       if (settled) return;
       settled = true;
-      err ? reject(err) : resolve21();
+      err ? reject(err) : resolve22();
     };
     if (abortSignal?.aborted) {
       done(new CancelledError("Download cancelled before start."));
@@ -787,10 +787,10 @@ async function extractTarball(tarPath, dest, strip = 0, filter) {
 var SIGNED_HAP_CHUNK_SIZE = 128 * 1024;
 async function withHapZip(zipPath, use) {
   const zip = new StreamZip({ file: zipPath, chunkSize: SIGNED_HAP_CHUNK_SIZE, storeEntries: true });
-  const close = () => new Promise((resolve21) => zip.close(() => resolve21()));
+  const close = () => new Promise((resolve22) => zip.close(() => resolve22()));
   try {
-    await new Promise((resolve21, reject) => {
-      zip.once("ready", () => resolve21());
+    await new Promise((resolve22, reject) => {
+      zip.once("ready", () => resolve22());
       zip.once("error", (err) => reject(err));
     });
     return await use({ entries: () => zip.entries(), entryData: (name) => zip.entryDataSync(name) });
@@ -2280,7 +2280,7 @@ function runProcess(opts) {
   const { command, args, cwd, env, onOutput } = opts;
   const timeoutMs = opts.timeoutMs ?? 6e4;
   const { abortSignal } = opts;
-  return new Promise((resolve21, reject) => {
+  return new Promise((resolve22, reject) => {
     if (abortSignal?.aborted) {
       reject(new CancelledError(`Command aborted before start: ${command}`));
       return;
@@ -2353,7 +2353,7 @@ ${stderr.trim()}` : "")
         );
         return;
       }
-      resolve21({ code: code ?? -1, stdout, stderr });
+      resolve22({ code: code ?? -1, stdout, stderr });
     });
   });
 }
@@ -3004,11 +3004,11 @@ async function getDefaultInstanceStatus(config, opts) {
   };
 }
 function isTcpPortFree(port, host = "127.0.0.1") {
-  return new Promise((resolve21) => {
+  return new Promise((resolve22) => {
     const srv = net.createServer();
-    srv.once("error", () => resolve21(false));
+    srv.once("error", () => resolve22(false));
     srv.listen({ port, host, exclusive: true }, () => {
-      srv.close(() => resolve21(true));
+      srv.close(() => resolve22(true));
     });
   });
 }
@@ -3169,9 +3169,9 @@ async function startPoolInstance(opts) {
   } finally {
     fs22.closeSync(logFd);
   }
-  const earlyExit = new Promise((resolve21) => {
-    child.once("exit", (code) => resolve21(code));
-    child.once("error", () => resolve21(-1));
+  const earlyExit = new Promise((resolve22) => {
+    child.once("exit", (code) => resolve22(code));
+    child.once("error", () => resolve22(-1));
   });
   if (!child.pid) {
     await earlyExit;
@@ -3381,11 +3381,11 @@ async function startEmulator(opts) {
   fs23.writeFileSync(DEFAULT_EMULATOR_PID_FILE, String(child.pid));
   child.unref();
   logger.info(`Emulator launched (PID ${child.pid}). Logs: ${logPath}`);
-  const earlyExit = new Promise((resolve21) => {
-    child.once("exit", (code) => resolve21(code));
-    child.once("error", () => resolve21(-1));
+  const earlyExit = new Promise((resolve22) => {
+    child.once("exit", (code) => resolve22(code));
+    child.once("error", () => resolve22(-1));
   });
-  const liveness = new Promise((resolve21) => setTimeout(() => resolve21("alive"), 2e3));
+  const liveness = new Promise((resolve22) => setTimeout(() => resolve22("alive"), 2e3));
   const outcome = await Promise.race([earlyExit, liveness]);
   if (outcome !== "alive") {
     const tail = readTail(logPath, 4e3);
@@ -3714,7 +3714,7 @@ async function getDisplaySize(config, opts = {}) {
 
 // src/hdc/wait.ts
 function delay(ms, signal) {
-  return new Promise((resolve21, reject) => {
+  return new Promise((resolve22, reject) => {
     if (signal?.aborted) {
       reject(new CancelledError("Wait cancelled."));
       return;
@@ -3729,7 +3729,7 @@ function delay(ms, signal) {
     };
     const timer = setTimeout(() => {
       cleanup();
-      resolve21();
+      resolve22();
     }, ms);
     signal?.addEventListener("abort", onAbort, { once: true });
   });
@@ -3904,8 +3904,8 @@ async function resolveInstallHap(opts, logger) {
     return hap;
   };
   const configured = opts.hapPath ?? opts.config.get("hapPath", "");
-  const relative7 = configured || defaultPaths.hapPath;
-  const hapPath = path26.isAbsolute(relative7) ? relative7 : path26.join(opts.projectDir, relative7);
+  const relative8 = configured || defaultPaths.hapPath;
+  const hapPath = path26.isAbsolute(relative8) ? relative8 : path26.join(opts.projectDir, relative8);
   if (configured) {
     const hap = existingHapOrUnsigned(hapPath);
     if (!hap) throw new OniroError(`HAP file not found at: ${hapPath}. Build the app first.`);
@@ -4022,7 +4022,7 @@ function listRunningProcesses(config, options = {}) {
   const logger = options.logger ?? noopLogger;
   const timeoutMs = options.timeoutMs ?? 1e3;
   const hdc = getHdcPath(config);
-  return new Promise((resolve21, reject) => {
+  return new Promise((resolve22, reject) => {
     let proc;
     try {
       proc = spawnCompat(hdc, [...hdcTargetArgs(options.deviceSerial), "track-jpid"]);
@@ -4042,7 +4042,7 @@ function listRunningProcesses(config, options = {}) {
         if (options.targetProcessName && name === options.targetProcessName && !resolved) {
           resolved = true;
           killProcessTree(proc);
-          resolve21(pid);
+          resolve22(pid);
           return;
         }
       }
@@ -4063,7 +4063,7 @@ function listRunningProcesses(config, options = {}) {
       if (options.targetProcessName) {
         reject(new OniroError(`Could not find process for bundle: ${options.targetProcessName}`));
       } else {
-        resolve21(processes);
+        resolve22(processes);
       }
     }, timeoutMs);
     proc.on("close", () => {
@@ -4073,7 +4073,7 @@ function listRunningProcesses(config, options = {}) {
       if (options.targetProcessName) {
         reject(new OniroError(`Could not find process for bundle: ${options.targetProcessName}`));
       } else {
-        resolve21(processes);
+        resolve22(processes);
       }
     });
   });
@@ -4697,9 +4697,9 @@ var Parser = class {
     return tok2.t === "name" && tok2.v === v;
   }
   parseTop() {
-    const path60 = this.parsePath();
+    const path62 = this.parsePath();
     if (this.peek().t !== "eof") this.fail("unexpected trailing input");
-    return path60;
+    return path62;
   }
   parsePath() {
     const startTok = this.peek();
@@ -4714,10 +4714,10 @@ var Parser = class {
     }
     const steps = [];
     for (; ; ) {
-      const sep6 = this.peek();
-      if (sep6.t !== "/" && sep6.t !== "//") break;
+      const sep7 = this.peek();
+      if (sep7.t !== "/" && sep7.t !== "//") break;
       this.next();
-      steps.push(this.parseStep(sep6.t === "//"));
+      steps.push(this.parseStep(sep7.t === "//"));
     }
     if (start === "root" && steps.length === 0) this.fail("expected a step");
     return { source: this.src, start, steps };
@@ -5567,7 +5567,7 @@ async function listWindows(opts) {
 // src/hdc/uiActions.ts
 var FOCUS_SETTLE_MS = 400;
 var KEYBOARD_SETTLE_MS = 400;
-var sleep = (ms) => new Promise((resolve21) => setTimeout(resolve21, ms));
+var sleep = (ms) => new Promise((resolve22) => setTimeout(resolve22, ms));
 function selectableTree(layout, windowId) {
   const kb = layout.keyboard;
   return kb?.shown && kb.bundle && windowId === void 0 ? withoutWindow(layout.tree, kb.bundle) : layout.tree;
@@ -5733,7 +5733,7 @@ import * as fs29 from "fs";
 function setHilogLevel(opts) {
   const logger = opts.logger ?? noopLogger;
   const hdc = getHdcPath(opts.config);
-  return new Promise((resolve21, reject) => {
+  return new Promise((resolve22, reject) => {
     let child;
     try {
       child = spawnCompat(hdc, [...hdcTargetArgs(opts.deviceSerial), "shell", "hilog", "-b", opts.level]);
@@ -5753,7 +5753,7 @@ function setHilogLevel(opts) {
     });
     child.once("close", (code) => {
       if (code === 0) {
-        resolve21();
+        resolve22();
       } else {
         const msg = stderr.trim() || `hdc shell hilog -b ${opts.level} exited with code ${code}`;
         logger.error(`[hilog] ${msg}`);
@@ -5855,7 +5855,7 @@ async function recentEntryFilter(opts) {
   };
 }
 function waitForLog(opts) {
-  return new Promise((resolve21, reject) => {
+  return new Promise((resolve22, reject) => {
     const deadline = Date.now() + opts.timeoutMs;
     let settled = false;
     let child = null;
@@ -5876,7 +5876,7 @@ function waitForLog(opts) {
       if (settled) return;
       settled = true;
       cleanup();
-      resolve21(entry);
+      resolve22(entry);
     };
     const fail = (err) => {
       if (settled) return;
@@ -5931,7 +5931,7 @@ function waitForLog(opts) {
   });
 }
 function watchLog(opts) {
-  return new Promise((resolve21, reject) => {
+  return new Promise((resolve22, reject) => {
     const matches = [];
     let settled = false;
     let child = null;
@@ -5950,7 +5950,7 @@ function watchLog(opts) {
       if (settled) return;
       settled = true;
       cleanup();
-      resolve21(opts.dedup === false ? matches : dedupEntries(matches));
+      resolve22(opts.dedup === false ? matches : dedupEntries(matches));
     };
     const onAbort = () => {
       if (settled) return;
@@ -5999,7 +5999,7 @@ async function captureLog(opts) {
   let lines = 0;
   let reconnects = 0;
   try {
-    await new Promise((resolve21, reject) => {
+    await new Promise((resolve22, reject) => {
       const deadline = opts.durationMs !== void 0 ? Date.now() + opts.durationMs : Infinity;
       let settled = false;
       let child = null;
@@ -6029,7 +6029,7 @@ async function captureLog(opts) {
         if (settled) return;
         settled = true;
         cleanup();
-        resolve21();
+        resolve22();
       }
       const fail = (err) => {
         if (settled) return;
@@ -6476,7 +6476,7 @@ function analyzeBlank(img) {
 var DEFAULT_SMOKE_DELAY_MS = 2e3;
 var DEFAULT_SMOKE_PID_TIMEOUT_MS = 1e4;
 var PID_POLL_MS = 500;
-var sleep2 = (ms) => new Promise((resolve21) => setTimeout(resolve21, ms));
+var sleep2 = (ms) => new Promise((resolve22) => setTimeout(resolve22, ms));
 async function pidOf(opts) {
   const proc = await findRunningProcess({ config: opts.config, bundle: opts.bundle, deviceSerial: opts.deviceSerial });
   return proc ? Number(proc.pid) : null;
@@ -6629,7 +6629,7 @@ function runHvigorw(opts) {
     }
   }
   const env = { ...process.env, ...sdkEnv };
-  return new Promise((resolve21, reject) => {
+  return new Promise((resolve22, reject) => {
     if (opts.abortSignal?.aborted) {
       reject(new CancelledError("hvigorw build cancelled."));
       return;
@@ -6673,7 +6673,7 @@ function runHvigorw(opts) {
       settled = true;
       cleanup();
       const exitCode = code ?? 1;
-      if (exitCode === 0) resolve21({ exitCode });
+      if (exitCode === 0) resolve22({ exitCode });
       else reject(new OniroError(`hvigorw exited with code ${exitCode}`));
     });
   });
@@ -7057,17 +7057,17 @@ function sdkTooOldDiagnostic(diagnostics, sdkHome, projectApi) {
   } catch {
     return null;
   }
-  const cache = /* @__PURE__ */ new Map();
+  const cache2 = /* @__PURE__ */ new Map();
   const declares = (api2, s) => {
     const file = moduleDeclarationFile(path33.join(sdkHome, String(api2)), s.module);
-    if (!cache.has(file)) {
+    if (!cache2.has(file)) {
       try {
-        cache.set(file, fs35.readFileSync(file, "utf8"));
+        cache2.set(file, fs35.readFileSync(file, "utf8"));
       } catch {
-        cache.set(file, null);
+        cache2.set(file, null);
       }
     }
-    const text = cache.get(file);
+    const text = cache2.get(file);
     return !!text && new RegExp(`\\b${s.symbol.replace(/\$/g, "\\$")}\\b`).test(text);
   };
   const api = apis.find((a) => missing.every((s) => declares(a, s)));
@@ -8169,8 +8169,8 @@ async function startCallbackServer(opts) {
   }
   let resolveCallback;
   let rejectCallback;
-  const callback = new Promise((resolve21, reject) => {
-    resolveCallback = resolve21;
+  const callback = new Promise((resolve22, reject) => {
+    resolveCallback = resolve22;
     rejectCallback = reject;
   });
   callback.catch(() => {
@@ -8222,12 +8222,12 @@ async function startCallbackServer(opts) {
     }
   });
   server.keepAliveTimeout = 1;
-  await new Promise((resolve21, reject) => {
+  await new Promise((resolve22, reject) => {
     server.once("error", (err) => {
       const why = err.code === "EADDRINUSE" ? `port ${requested} is already in use on 127.0.0.1; pick another with --port` : err.code === "EACCES" ? `this user may not listen on port ${requested}; pick one above 1023` : err.message;
       reject(new OniroError(`Failed to start the local login callback server: ${why}.`, err));
     });
-    server.listen(requested, "127.0.0.1", resolve21);
+    server.listen(requested, "127.0.0.1", resolve22);
   });
   const port = server.address().port;
   return {
@@ -8249,12 +8249,12 @@ async function startCallbackServer(opts) {
       return { accepted: true };
     },
     stop() {
-      return new Promise((resolve21) => {
+      return new Promise((resolve22) => {
         server.closeAllConnections?.();
-        const timer = setTimeout(resolve21, 100);
+        const timer = setTimeout(resolve22, 100);
         server.close(() => {
           clearTimeout(timer);
-          resolve21();
+          resolve22();
         });
       });
     }
@@ -8286,11 +8286,11 @@ function openBrowser(url) {
     windowsHide: true
   });
   child.unref();
-  return new Promise((resolve21, reject) => {
+  return new Promise((resolve22, reject) => {
     child.on("error", (err) => reject(new OniroError(`Failed to open a browser (${command}).`, err)));
     child.on(
       "exit",
-      (code) => code === 0 ? resolve21() : reject(new OniroError(`Browser launcher '${command}' exited with code ${code}.`))
+      (code) => code === 0 ? resolve22() : reject(new OniroError(`Browser launcher '${command}' exited with code ${code}.`))
     );
   });
 }
@@ -12699,13 +12699,13 @@ function cycleFrom(start, g) {
     const node = queue.shift();
     for (const n of g.out.get(key2(node)) ?? []) {
       if (same(n, start)) {
-        const path60 = [];
+        const path62 = [];
         let cursor = node;
         while (cursor && !same(cursor, start)) {
-          path60.push(cursor);
+          path62.push(cursor);
           cursor = parent.get(key2(cursor));
         }
-        return cursor ? [start, ...path60.reverse()] : null;
+        return cursor ? [start, ...path62.reverse()] : null;
       }
       const k = key2(n);
       if (!seen.has(k) && g.out.has(k)) {
@@ -13237,7 +13237,7 @@ async function latestCrash(opts) {
       return verdict;
     }
     if (Date.now() >= deadline) return null;
-    await new Promise((resolve21) => setTimeout(resolve21, Math.min(opts.pollMs ?? 1e3, Math.max(0, deadline - Date.now()))));
+    await new Promise((resolve22) => setTimeout(resolve22, Math.min(opts.pollMs ?? 1e3, Math.max(0, deadline - Date.now()))));
   }
 }
 
@@ -13792,12 +13792,12 @@ var UI_RECORD_CSV = "/data/local/tmp/record.csv";
 var RECORD_CONSOLE = "/data/local/tmp/oniro_record_console.txt";
 var MMI_SERVER_DOMAIN = "0xD002801";
 function sleep3(ms, signal) {
-  return new Promise((resolve21) => {
-    if (signal?.aborted) return resolve21();
+  return new Promise((resolve22) => {
+    if (signal?.aborted) return resolve22();
     const done = () => {
       clearTimeout(t);
       signal?.removeEventListener("abort", done);
-      resolve21();
+      resolve22();
     };
     const t = setTimeout(done, ms);
     signal?.addEventListener("abort", done, { once: true });
@@ -14661,11 +14661,11 @@ function parseActiveRefreshRate(hidumper) {
   const m = /activeMode:[^\n]*?refreshRate=(\d+(?:\.\d+)?)/.exec(hidumper);
   return m ? Number(m[1]) : null;
 }
-var sleep5 = (ms, signal) => new Promise((resolve21, reject) => {
+var sleep5 = (ms, signal) => new Promise((resolve22, reject) => {
   if (signal?.aborted) return reject(new CancelledError("Capture cancelled."));
   const t = setTimeout(() => {
     signal?.removeEventListener("abort", onAbort);
-    resolve21();
+    resolve22();
   }, ms);
   const onAbort = () => {
     clearTimeout(t);
@@ -14851,8 +14851,394 @@ async function collectHiperf(run, device, remotePerf, localPerf) {
   return { ...parsed, data };
 }
 
+// src/docs/search.ts
+import * as fs63 from "fs";
+import * as path60 from "path";
+var SKIP_DIRS = /* @__PURE__ */ new Set(["figures", "figure", "images", "image", "public_sys-resources"]);
+function listMarkdown(tree) {
+  const out = [];
+  const walk3 = (dir) => {
+    let entries;
+    try {
+      entries = fs63.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      if (e.isDirectory()) {
+        if (!SKIP_DIRS.has(e.name)) walk3(path60.join(dir, e.name));
+      } else if (e.isFile() && e.name.endsWith(".md")) {
+        out.push(path60.join(dir, e.name));
+      }
+    }
+  };
+  walk3(tree);
+  return out.sort();
+}
+var WORD = /[a-z0-9_@.]+/g;
+function docTokens(text) {
+  const out = [];
+  for (const m of text.toLowerCase().matchAll(WORD)) {
+    const w = m[0].replace(/^[.@]+|[.@]+$/g, "");
+    if (w.length >= 2 && w.length <= 40 && !/^\d{13,}$/.test(w)) out.push(w);
+  }
+  return out;
+}
+function docQueryTerms(query) {
+  const out = /* @__PURE__ */ new Map();
+  const add = (t, w) => {
+    if (t.length >= 2 && (out.get(t) ?? 0) < w) out.set(t, w);
+  };
+  for (const w of docTokens(query)) {
+    add(w, 1);
+    for (const p of w.split(/[._]/)) if (p.length >= 3 && p !== w) add(p, 0.4);
+  }
+  for (const m of query.matchAll(/[A-Z][a-z]+|[a-z]+|[A-Z]+(?![a-z])|[0-9]+/g)) {
+    if (m[0].length >= 3) add(m[0].toLowerCase(), 0.4);
+  }
+  return [...out].map(([term, weight]) => ({ term, weight }));
+}
+function wordIn(text, term) {
+  let i = text.indexOf(term);
+  while (i >= 0) {
+    const before = i === 0 ? "" : text[i - 1] ?? "";
+    const after = text[i + term.length] ?? "";
+    if (!/[a-z0-9]/.test(before) && !/[a-z]/.test(after)) return true;
+    i = text.indexOf(term, i + 1);
+  }
+  return false;
+}
+var flat = (s) => Buffer.from(s, "utf8").toString("utf8");
+function stripMd(line) {
+  return line.replace(/!\[[^\]]*\]\([^)]*\)/g, "").replace(/<[^>]+>/g, "").replace(/\[([^\]]*)\]\([^)]*\)/g, "$1").replace(/[`*_]/g, "").trim();
+}
+function parseDoc(rel, text) {
+  const lines = text.split("\n");
+  let title = "";
+  const headings = [];
+  for (let i = 0; i < lines.length; i++) {
+    const m = /^(#{1,4})\s+(.+?)\s*#*\s*$/.exec(lines[i] ?? "");
+    if (!m) continue;
+    const level = (m[1] ?? "#").length;
+    const text2 = flat(stripMd(m[2] ?? ""));
+    if (level === 1 && !title) title = text2;
+    else headings.push({ line: i + 1, level, text: text2 });
+  }
+  if (!title) title = path60.basename(rel, ".md");
+  return { path: rel, title, headings, bytes: text.length };
+}
+function docWords(rel, text) {
+  const words = /* @__PURE__ */ new Set();
+  const add = (w) => {
+    words.add(w);
+    const stem = /^([a-z_]{3,})\d{1,2}$/.exec(w)?.[1];
+    if (stem !== void 0) words.add(stem);
+  };
+  for (const w of docTokens(text)) {
+    add(w);
+    if (w.includes(".")) {
+      for (const p of w.split(".")) if (p.length >= 3) add(p);
+    }
+  }
+  for (const w of docTokens(rel.replace(/[-/]/g, " "))) words.add(w);
+  return words;
+}
+var cache = /* @__PURE__ */ new Map();
+var DocsIndex = class _DocsIndex {
+  constructor(tree, docs, words, buildMs) {
+    this.tree = tree;
+    this.docs = docs;
+    this.buildMs = buildMs;
+    const lists = /* @__PURE__ */ new Map();
+    let id = 0;
+    for (const set of words) {
+      for (const w of set) {
+        const list = lists.get(w);
+        if (list) list.push(id);
+        else lists.set(flat(w), [id]);
+      }
+      id++;
+    }
+    for (const [w, list] of lists) this.postings.set(w, Int32Array.from(list));
+  }
+  tree;
+  docs;
+  buildMs;
+  /** word → ascending document ids (packed: 4 bytes per occurrence). */
+  postings = /* @__PURE__ */ new Map();
+  /** The index of a tree, built on the first call of a process and kept. */
+  static load(tree) {
+    const key3 = path60.resolve(tree);
+    const hit = cache.get(key3);
+    if (hit) return hit;
+    const started = Date.now();
+    const docs = [];
+    const words = [];
+    for (const abs of listMarkdown(key3)) {
+      const rel = path60.relative(key3, abs).split(path60.sep).join("/");
+      const text = fs63.readFileSync(abs, "utf8");
+      docs.push(parseDoc(rel, text));
+      words.push(docWords(rel, text));
+    }
+    const idx = new _DocsIndex(key3, docs, words, Date.now() - started);
+    cache.set(key3, idx);
+    return idx;
+  }
+  /** An index over in-memory documents (tests). `tree` is used by `show` for reading files. */
+  static fromDocs(tree, docs) {
+    return new _DocsIndex(
+      tree,
+      docs.map((d) => parseDoc(d.path, d.text)),
+      docs.map((d) => docWords(d.path, d.text)),
+      0
+    );
+  }
+  /** Forget the cached index of a tree (after a sync). */
+  static forget(tree) {
+    cache.delete(path60.resolve(tree));
+  }
+  get size() {
+    return this.docs.length;
+  }
+  has(term) {
+    return this.postings.get(term) ?? [];
+  }
+  /**
+   * Documents containing every word of the query (any of them when none does), scored by
+   * where the words occur: title, headings, path, body; a document whose title is exactly a
+   * query word, or that contains the whole query in a title or heading, ranks higher; the
+   * generated API reference ranks a little below the guides, system-API pages and tables of
+   * contents below everything.
+   */
+  search(query, o = {}) {
+    const terms = docQueryTerms(query);
+    const full = terms.filter((t) => t.weight === 1);
+    const result = { query, terms: terms.map((t) => t.term), total: 0, hits: [] };
+    if (!terms.length) return result;
+    const limit = Math.max(1, Math.min(o.limit ?? 8, 30));
+    const section = o.section?.replace(/^\/+|\/+$/g, "").toLowerCase();
+    const inScope = (d) => !section || d.path.toLowerCase().startsWith(`${section}/`) || d.path.toLowerCase().includes(`/${section}/`);
+    const phrase = query.trim().toLowerCase();
+    const presentBy = /* @__PURE__ */ new Map();
+    for (const t of terms) {
+      for (const id of this.has(t.term)) {
+        const l = presentBy.get(id);
+        if (l) l.push(t);
+        else presentBy.set(id, [t]);
+      }
+    }
+    const scored = (requireAll) => {
+      const out = [];
+      for (const [id, present] of presentBy) {
+        const d = this.docs[id];
+        if (!d) continue;
+        const fullPresent = present.filter((t) => t.weight === 1).length;
+        if (!inScope(d) || requireAll && fullPresent < full.length) continue;
+        const title = d.title.toLowerCase();
+        const p = d.path.toLowerCase();
+        let score = 0;
+        const headingHits = [];
+        for (const h of d.headings) {
+          const ht = h.text.toLowerCase();
+          const n = present.reduce((a, t) => a + (wordIn(ht, t.term) ? t.weight : 0), 0);
+          if (n) headingHits.push({ line: h.line, text: h.text, n });
+        }
+        for (const t of present) {
+          if (wordIn(title, t.term)) score += 8 * t.weight;
+          if (wordIn(p, t.term)) score += 3 * t.weight;
+          score += t.weight;
+        }
+        if (full.some((t) => title === t.term || title.replace(/\s*\(.*\)$/, "") === t.term)) score += 6;
+        if (headingHits.length) score += Math.min(12, headingHits.reduce((a, h) => a + h.n * 2, 0));
+        if (phrase.length > 3) {
+          if (title.includes(phrase)) score += 20;
+          else if (headingHits.some((h) => h.text.toLowerCase().includes(phrase))) score += 10;
+        }
+        if (p.startsWith("reference/apis-")) score -= 2;
+        if (/-sys\.md$/.test(p) || /\(system api\)/i.test(title)) score -= 12;
+        if (/\/(readme|summary)\.md$/i.test(p) || /^readme/i.test(p)) score -= 6;
+        if (fullPresent === full.length) score += 4;
+        headingHits.sort((a, b) => b.n - a.n || a.line - b.line);
+        out.push({
+          d,
+          score: Math.round(score * 10) / 10,
+          headings: headingHits.slice(0, 6).map(({ line, text }) => ({ line, text }))
+        });
+      }
+      return out;
+    };
+    let hits = scored(true);
+    if (!hits.length) hits = scored(false);
+    hits.sort((a, b) => b.score - a.score || a.d.path.localeCompare(b.d.path));
+    result.total = hits.length;
+    result.hits = hits.slice(0, limit).map(({ d, score, headings }) => ({
+      path: d.path,
+      title: d.title,
+      score,
+      headings,
+      snippet: this.snippet(d)
+    }));
+    return result;
+  }
+  snippet(d) {
+    let text;
+    try {
+      text = fs63.readFileSync(path60.join(this.tree, d.path), "utf8");
+    } catch {
+      return "";
+    }
+    const lines = text.split("\n");
+    for (let i = lines.findIndex((l) => /^#\s/.test(l)) + 1; i < lines.length; i++) {
+      const s = stripMd(lines[i] ?? "");
+      if (s && !/^[#>|<-]/.test(s)) return s.length > 220 ? `${s.slice(0, 217)}\u2026` : s;
+    }
+    return "";
+  }
+  /**
+   * A document, or one of its sections: from the heading that matches `heading`
+   * (exactly, else by substring, case-insensitive) to the next heading of the same or a
+   * higher level. Image lines and inline HTML are dropped; the text is cut at `maxLines`
+   * with a note of what was left out.
+   */
+  show(rel, o = {}) {
+    const clean2 = rel.replace(/\\/g, "/").replace(/^\/+/, "").replace(/^en\/application-dev\//, "");
+    const abs = path60.resolve(this.tree, clean2);
+    const inside = abs.startsWith(this.tree + path60.sep);
+    if (!inside || !fs63.existsSync(abs) || !fs63.statSync(abs).isFile()) {
+      const base = path60.basename(clean2, ".md").toLowerCase();
+      let suggestions = this.docs.filter((d) => d.path.toLowerCase().includes(base)).slice(0, 5).map((d) => d.path);
+      if (!suggestions.length) suggestions = this.search(base.replace(/[-_]/g, " "), { limit: 5 }).hits.map((h) => h.path);
+      return { found: false, path: clean2, error: `No document at ${clean2}.`, suggestions };
+    }
+    const text = fs63.readFileSync(abs, "utf8");
+    const entry = this.docs.find((d) => d.path === clean2) ?? parseDoc(clean2, text);
+    const lines = text.split("\n");
+    let from = 0;
+    let to = lines.length;
+    if (o.heading) {
+      const needle = o.heading.toLowerCase().replace(/^#+\s*/, "").trim();
+      const h = entry.headings.find((x2) => x2.text.toLowerCase() === needle) ?? entry.headings.find((x2) => x2.text.toLowerCase().includes(needle));
+      if (!h) {
+        return {
+          found: false,
+          path: clean2,
+          error: `No heading matching "${o.heading}" in ${clean2}.`,
+          suggestions: entry.headings.slice(0, 30).map((x2) => x2.text)
+        };
+      }
+      from = h.line - 1;
+      const next2 = entry.headings.find((x2) => x2.line > h.line && x2.level <= h.level);
+      to = next2 ? next2.line - 1 : lines.length;
+    }
+    const max = Math.max(20, Math.min(o.maxLines ?? 250, 1200));
+    const body = lines.slice(from, to).filter((l) => !/^\s*!\[[^\]]*\]\([^)]*\)\s*$/.test(l) && !/^\s*<img\b/i.test(l)).map((l) => l.replace(/<br\s*\/?>/gi, " ").replace(/<\/?(p|div|span|b|i|em|strong|sup|sub)>/gi, ""));
+    const truncated = body.length > max;
+    const shown = body.slice(0, max).join("\n") + (truncated ? `
+
+[\u2026 ${body.length - max} more lines; ask for one section with heading]` : "");
+    return {
+      found: true,
+      path: clean2,
+      text: shown,
+      truncated,
+      lines: body.length,
+      headings: entry.headings.filter((h) => h.line > from && h.line <= to).map(({ line, text: t }) => ({ line, text: t }))
+    };
+  }
+};
+
+// src/docs/sync.ts
+import * as fs64 from "fs";
+import * as path61 from "path";
+var DOCS_REPO = "https://gitcode.com/openharmony/docs";
+var DOCS_SPARSE_PATH = "en/application-dev";
+var DOCS_SPARSE_PATTERNS = [
+  `/${DOCS_SPARSE_PATH}/`,
+  "!**/figures/",
+  "!**/*.png",
+  "!**/*.gif",
+  "!**/*.jpg",
+  "!**/*.jpeg"
+];
+function docsRefFor(sdk) {
+  const m = sdk.version ? /^(\d+)\.(\d+)\.(\d+)/.exec(sdk.version) : null;
+  if (m) {
+    const [, major, minor, patch] = m;
+    return `OpenHarmony-${Number(major) >= 6 ? `${major}.${minor}` : `${major}.${minor}.${patch}`}-Release`;
+  }
+  const api = sdk.api;
+  if (api === void 0) return "master";
+  if (api <= 18) return "OpenHarmony-5.1.0-Release";
+  if (api <= 20) return "OpenHarmony-6.0-Release";
+  if (api <= 23) return "OpenHarmony-6.1-Release";
+  if (api <= 26) return "OpenHarmony-7.0-Release";
+  return "master";
+}
+function readSdkRelease(sdkDir) {
+  try {
+    const pkg = JSON.parse(fs64.readFileSync(path61.join(sdkDir, "ets", "oh-uni-package.json"), "utf8"));
+    const api = Number(pkg.apiVersion);
+    return { api: Number.isFinite(api) ? api : void 0, version: typeof pkg.version === "string" ? pkg.version : void 0 };
+  } catch {
+    return {};
+  }
+}
+function getDocsRootDir(config) {
+  return config.get("docsDir", path61.join(getSdkRootDir(config), "docs"));
+}
+function docsDirFor(config, ref) {
+  return path61.join(getDocsRootDir(config), ref);
+}
+function docsTree(docsDir) {
+  const tree = path61.join(docsDir, DOCS_SPARSE_PATH);
+  return fs64.existsSync(tree) ? tree : null;
+}
+async function syncDocs(opts) {
+  const { ref, dir } = opts;
+  const repo = opts.repo ?? DOCS_REPO;
+  const logger = opts.logger;
+  const git = async (args, cwd) => {
+    const r = await runProcess({
+      command: "git",
+      args,
+      cwd,
+      timeoutMs: opts.timeoutMs ?? 6e5,
+      abortSignal: opts.abortSignal,
+      onOutput: (chunk) => {
+        for (const line of chunk.split(/\r?\n/)) if (line.trim()) logger?.debug(`git: ${line.trim()}`);
+      }
+    }).catch((err) => {
+      const msg = err instanceof Error ? err.message : String(err);
+      throw new OniroError(/ENOENT/.test(msg) ? "git is not installed or not on the PATH; `docs sync` needs it." : msg);
+    });
+    if (r.code !== 0) {
+      const tail = (r.stderr || r.stdout).trim().split("\n").filter(Boolean).slice(-3).join(" | ");
+      throw new OniroError(`git ${args[0]} failed (exit ${r.code}): ${tail}`);
+    }
+    return r.stdout;
+  };
+  const exists = fs64.existsSync(path61.join(dir, ".git"));
+  if (exists) {
+    logger?.info(`Updating the ${ref} docs in ${dir}`);
+    await git(["fetch", "--depth", "1", "origin", ref], dir);
+    await git(["sparse-checkout", "set", "--no-cone", ...DOCS_SPARSE_PATTERNS], dir);
+    await git(["reset", "--hard", "FETCH_HEAD"], dir);
+  } else {
+    logger?.info(`Cloning the ${ref} docs (${DOCS_SPARSE_PATH} only) into ${dir}`);
+    fs64.mkdirSync(path61.dirname(dir), { recursive: true });
+    await git(["clone", "--depth", "1", "--filter=blob:none", "--no-checkout", "--branch", ref, repo, dir]);
+    await git(["sparse-checkout", "set", "--no-cone", ...DOCS_SPARSE_PATTERNS], dir);
+    await git(["checkout", ref], dir);
+  }
+  const commit = (await git(["rev-parse", "--short", "HEAD"], dir)).trim() || void 0;
+  const tree = docsTree(dir);
+  const files = tree ? listMarkdown(tree).length : 0;
+  if (!files) throw new OniroError(`The ${ref} clone at ${dir} holds no Markdown under ${DOCS_SPARSE_PATH}.`);
+  return { dir, ref, files, updated: exists, commit };
+}
+
 // src/index.ts
-var VERSION = "0.17.0";
+var VERSION = "0.18.0";
 export {
   ALL_SDKS,
   API_INDEX_FORMAT,
@@ -14876,6 +15262,10 @@ export {
   DEFAULT_SMOKE_PID_TIMEOUT_MS,
   DEFAULT_TRACE_BUFFER_KB,
   DEFAULT_TRACE_CATEGORIES,
+  DOCS_REPO,
+  DOCS_SPARSE_PATH,
+  DOCS_SPARSE_PATTERNS,
+  DocsIndex,
   EMULATOR_KERNEL_APPEND,
   FAULTLOG_DIR,
   FAULTLOG_TEMP_DIR,
@@ -14998,6 +15388,12 @@ export {
   diffHapAssets,
   diffLayouts,
   discoverHaps,
+  docQueryTerms,
+  docTokens,
+  docWords,
+  docsDirFor,
+  docsRefFor,
+  docsTree,
   downloadAndInstallSdk,
   downloadFile,
   dumpLayout,
@@ -15058,6 +15454,7 @@ export {
   getDefaultInstanceStatus,
   getDeviceInfo,
   getDisplaySize,
+  getDocsRootDir,
   getEmulatorDir,
   getEmulatorStatus,
   getFreeSpaceBytes,
@@ -15121,6 +15518,7 @@ export {
   listDevices,
   listFaultLogs,
   listLayoutWindows,
+  listMarkdown,
   listModules,
   listPoolInstanceNumbers,
   listPoolInstanceStatuses,
@@ -15161,6 +15559,7 @@ export {
   parseCrashRecordHeads,
   parseDeviceList,
   parseDeviceTime,
+  parseDoc,
   parseDocBlock,
   parseFaultLogList,
   parseFaultLogName,
@@ -15217,6 +15616,7 @@ export {
   readPoolState,
   readProvisionProfile,
   readSdkPkg,
+  readSdkRelease,
   readTestModuleName,
   readZipEntry,
   reboot,
@@ -15279,6 +15679,7 @@ export {
   summarizeDivergenceLayout,
   summarizeLayout,
   summarizeTrace,
+  syncDocs,
   takeScreenshot,
   testHapPath,
   toLongPath,
@@ -15302,6 +15703,7 @@ export {
   windowSubtree,
   withHapZip,
   withoutWindow,
+  wordIn,
   writeJson5File,
   writeJsonFile,
   writePoolState