@yinsen/deveco-cli-docs-zh 1.3.1

package/dist/engine/index.js

@@ -0,0 +1,2575 @@
+// src/data-dir.ts
+import * as fs from "fs";
+import * as path from "path";
+var CacheDirError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "CacheDirError";
+  }
+};
+var _cacheDir = null;
+function setCacheDir(dir) {
+  _cacheDir = path.resolve(dir);
+}
+function getCacheDir() {
+  if (_cacheDir === null) {
+    throw new CacheDirError(
+      "Cache directory not initialized. Call createDocsEngine first."
+    );
+  }
+  return _cacheDir;
+}
+async function assertCacheDirSafe() {
+  const dataDir = getCacheDir();
+  await fs.promises.mkdir(dataDir, { recursive: true });
+  const realDir = await fs.promises.realpath(dataDir);
+  const stat2 = await fs.promises.stat(realDir);
+  if (!stat2.isDirectory()) {
+    throw new CacheDirError("Cache directory must be a writable directory.");
+  }
+  return realDir;
+}
+function isPathInside(child, parent) {
+  const relative2 = path.relative(parent, child);
+  return relative2 === "" || !path.isAbsolute(relative2) && !relative2.startsWith(`..${path.sep}`) && relative2 !== "..";
+}
+function resolveCanonicalPath(value) {
+  const resolved = path.resolve(value);
+  const missing = [];
+  let current = resolved;
+  for (; ; ) {
+    try {
+      const real = fs.realpathSync(current);
+      return missing.length === 0 ? real : path.join(real, ...missing.reverse());
+    } catch (error) {
+      if (error.code !== "ENOENT") {
+        throw error;
+      }
+      const parent = path.dirname(current);
+      if (parent === current) {
+        return resolved;
+      }
+      missing.push(path.basename(current));
+      current = parent;
+    }
+  }
+}
+function resolvePathInsideRoot(child, root) {
+  const realRoot = resolveCanonicalPath(root);
+  const realChild = resolveCanonicalPath(child);
+  return isPathInside(realChild, realRoot) ? realChild : null;
+}
+
+// src/init/doc-initializer.ts
+import * as fs9 from "fs";
+import lockfile from "proper-lockfile";
+import ora from "ora";
+
+// src/doc-index/index-state.ts
+import * as fs8 from "fs";
+import * as path7 from "path";
+
+// src/portal/catalog.ts
+var CATALOG_NAMES = [
+  "harmonyos-guides",
+  "harmonyos-references",
+  "best-practices",
+  "harmonyos-faqs",
+  "harmonyos-releases",
+  "harmonyos-roadmap"
+];
+var CATALOG_TITLES = {
+  "harmonyos-guides": "\u5F00\u53D1\u6307\u5357",
+  "harmonyos-references": "API\u53C2\u8003",
+  "best-practices": "\u6700\u4F73\u5B9E\u8DF5",
+  "harmonyos-faqs": "FAQ",
+  "harmonyos-releases": "\u7248\u672C\u8BF4\u660E",
+  "harmonyos-roadmap": "\u53D8\u66F4\u9884\u544A"
+};
+
+// src/doc-index/constants.ts
+var INDEX_VERSION = "1.9.1";
+var INDEX_DB_MAX_BYTES = 48 * 1024 * 1024;
+var QUERY_MAX_RAW_CHARS = 200;
+var QUERY_MAX_FTS_TOKENS = 12;
+var QUERY_AND_MAX_TOKENS = 4;
+var SYNONYM_EXPAND_MAX_PARTS = 8;
+var CATALOG_RERANK_POOL_FACTOR = 6;
+var DOC_SEARCH_TEXT_MAX_CHARS = 1320;
+var DOC_SEARCH_BUDGET_TITLE = 120;
+var DOC_SEARCH_BUDGET_API_SYMBOLS = 450;
+var DOC_SEARCH_BUDGET_HEADINGS = 250;
+var DOC_SEARCH_BUDGET_BODY = 500;
+var DOC_SECTION_SEARCH_TEXT_MAX_CHARS = 480;
+var DOC_SECTION_BUDGET_TITLE = 80;
+var DOC_SECTION_BUDGET_API_SYMBOLS = 200;
+var DOC_SECTION_BUDGET_HEADINGS = 60;
+var DOC_SECTION_BUDGET_BODY = 200;
+var DOC_SNIPPET_MAX_CHARS = 200;
+var DOC_SNIPPET_CONTEXT_CHARS = 40;
+var INSERT_BATCH_SIZE = 500;
+var CATALOG_TITLE_TO_ID = Object.fromEntries(
+  CATALOG_NAMES.map((name, index) => [CATALOG_TITLES[name], index])
+);
+var CATALOG_NAME_TO_ID = Object.fromEntries(
+  CATALOG_NAMES.map((name, index) => [name, index])
+);
+
+// src/doc-index/doc-paths.ts
+import * as fs2 from "fs";
+import * as path2 from "path";
+import { fileURLToPath } from "url";
+var DOCS_DIR_NAME = "docs";
+function getDocsDir() {
+  return path2.join(getCacheDir(), DOCS_DIR_NAME);
+}
+function getIndexDir() {
+  return path2.join(getDocsDir(), ".index");
+}
+function getBuildLockFile() {
+  return path2.join(getIndexDir(), "build.lock");
+}
+function getBuildStatusFile() {
+  return path2.join(getIndexDir(), "build-status.json");
+}
+function getBuildMetaFile() {
+  return path2.join(getIndexDir(), "build-meta.json");
+}
+function getSearchDbFile() {
+  return path2.join(getIndexDir(), "search.db");
+}
+function getIndexTmpDir() {
+  return path2.join(getIndexDir(), ".tmp");
+}
+function getDistDir(currentFilePath, currentDir) {
+  let dir = currentDir;
+  while (!dir.endsWith(`${path2.sep}dist`) && dir !== path2.dirname(dir)) {
+    dir = path2.dirname(dir);
+  }
+  return dir;
+}
+function getPackageRootFromDist(currentFilePath, currentDir) {
+  return path2.dirname(getDistDir(currentFilePath, currentDir));
+}
+function getPackageRoot() {
+  const currentFilePath = fileURLToPath(import.meta.url);
+  const currentDir = path2.dirname(currentFilePath);
+  if (currentFilePath.includes(`${path2.sep}dist${path2.sep}`)) {
+    return getPackageRootFromDist(currentFilePath, currentDir);
+  }
+  return path2.join(currentDir, "..", "..", "..");
+}
+function resolvePackageRelativePath(...segments) {
+  const currentFilePath = fileURLToPath(import.meta.url);
+  const currentDir = path2.dirname(currentFilePath);
+  if (currentFilePath.includes(`${path2.sep}dist${path2.sep}`)) {
+    return [
+      path2.join(
+        getPackageRootFromDist(currentFilePath, currentDir),
+        ...segments
+      )
+    ];
+  }
+  return [path2.join(currentDir, "..", "..", "..", ...segments)];
+}
+function findBundledAsset(...segments) {
+  const packageRoot = getPackageRoot();
+  const realPackageRoot = fs2.realpathSync(packageRoot);
+  for (const candidate of resolvePackageRelativePath(...segments)) {
+    try {
+      const entry = fs2.lstatSync(candidate);
+      if (entry.isSymbolicLink() || !entry.isFile()) {
+        throw new Error(
+          `Unsafe documentation package asset: ${segments.join("/")} must be a regular file.`
+        );
+      }
+      const realCandidate = fs2.realpathSync(candidate);
+      if (!isPathInside(realCandidate, realPackageRoot)) {
+        throw new Error(
+          `Unsafe documentation package asset: ${segments.join("/")} is outside the package.`
+        );
+      }
+      return realCandidate;
+    } catch (error) {
+      if (error.code !== "ENOENT") {
+        throw error;
+      }
+    }
+  }
+  return null;
+}
+function findDocsZip() {
+  return findBundledAsset("docs.zip");
+}
+function findBundledIndexZip() {
+  return findBundledAsset("index.zip");
+}
+function getBuildLexiconDir() {
+  return path2.join(getPackageRoot(), "index", "data");
+}
+
+// src/doc-index/lexicon.ts
+import * as fs3 from "fs";
+import * as path3 from "path";
+var INDEX_LEXICON_FILES = [
+  "harmonyos-terms.txt",
+  "harmonyos-synonyms.json",
+  "harmonyos-stopwords.txt"
+];
+var LexiconNotFoundError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "LexiconNotFoundError";
+  }
+};
+var lexiconDirOverride = null;
+function resolveLexiconSourceDir() {
+  if (lexiconDirOverride) {
+    return lexiconDirOverride;
+  }
+  const indexDir = getIndexDir();
+  const fromIndex = INDEX_LEXICON_FILES.every(
+    (name) => fs3.existsSync(path3.join(indexDir, name))
+  );
+  if (fromIndex) {
+    return indexDir;
+  }
+  const buildDir = getBuildLexiconDir();
+  const fromBuild = INDEX_LEXICON_FILES.every(
+    (name) => fs3.existsSync(path3.join(buildDir, name))
+  );
+  if (fromBuild) {
+    return buildDir;
+  }
+  throw new LexiconNotFoundError(
+    "Lexicon files not found. Install the documentation index first (index.zip)."
+  );
+}
+function readIndexLexiconFile(name) {
+  const filePath = path3.join(resolveLexiconSourceDir(), name);
+  return fs3.readFileSync(filePath, "utf-8");
+}
+function readBuildLexiconFile(name, lexiconDir) {
+  return fs3.readFileSync(path3.join(lexiconDir, name), "utf-8");
+}
+
+// src/doc-index/docs-zip-reader.ts
+import * as fs4 from "fs";
+import * as path4 from "path";
+import * as yauzl from "yauzl";
+var docsZipCache = null;
+function openZip(zipPath) {
+  return new Promise((resolve3, reject) => {
+    yauzl.open(
+      zipPath,
+      { lazyEntries: true, decodeStrings: false, autoClose: false },
+      (error, zipfile) => {
+        if (error || !zipfile) {
+          reject(error ?? new Error(`Failed to open zip: ${zipPath}`));
+          return;
+        }
+        resolve3(zipfile);
+      }
+    );
+  });
+}
+function normalizeEntryFileName(entry) {
+  const rawFileName = entry.fileName;
+  const fileName = Buffer.isBuffer(rawFileName) ? rawFileName.toString("utf-8") : String(rawFileName);
+  return fileName.replace(/\\/g, "/");
+}
+function loadEntryIndex(zipfile) {
+  const entries = /* @__PURE__ */ new Map();
+  return new Promise((resolve3, reject) => {
+    zipfile.readEntry();
+    zipfile.on("entry", (entry) => {
+      const fileName = normalizeEntryFileName(entry);
+      if (!fileName.endsWith("/")) {
+        entries.set(fileName, entry);
+      }
+      zipfile.readEntry();
+    });
+    zipfile.on("end", () => {
+      resolve3(entries);
+    });
+    zipfile.on("error", reject);
+  });
+}
+function closeDocsZipCache() {
+  docsZipCache?.zipfile.close();
+  docsZipCache = null;
+}
+async function getDocsZipCache(zipPath) {
+  const resolvedPath = path4.resolve(zipPath);
+  const stat2 = await fs4.promises.stat(resolvedPath);
+  const cached = docsZipCache;
+  if (cached && cached.zipPath === resolvedPath && cached.mtimeMs === stat2.mtimeMs && cached.size === stat2.size) {
+    return cached;
+  }
+  closeDocsZipCache();
+  const zipfile = await openZip(resolvedPath);
+  let entries;
+  try {
+    entries = await loadEntryIndex(zipfile);
+  } catch (error) {
+    zipfile.close();
+    throw new Error(`Failed to read entries from zip: ${resolvedPath}`, { cause: error });
+  }
+  docsZipCache = {
+    zipPath: resolvedPath,
+    mtimeMs: stat2.mtimeMs,
+    size: stat2.size,
+    zipfile,
+    entries,
+    readChain: Promise.resolve()
+  };
+  return docsZipCache;
+}
+function readEntryStream(zipfile, entry) {
+  return new Promise((resolve3, reject) => {
+    zipfile.openReadStream(entry, (error, stream) => {
+      if (error || !stream) {
+        reject(
+          error ?? new Error(`Failed to read zip entry: ${entry.fileName}`)
+        );
+        return;
+      }
+      const chunks = [];
+      stream.on("data", (chunk) => {
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+      });
+      stream.on("end", () => {
+        resolve3(Buffer.concat(chunks));
+      });
+      stream.on("error", reject);
+    });
+  });
+}
+async function readEntryWithLock(cache, entry) {
+  const previous = cache.readChain;
+  let release;
+  cache.readChain = new Promise((resolve3) => {
+    release = resolve3;
+  });
+  await previous;
+  try {
+    return await readEntryStream(cache.zipfile, entry);
+  } finally {
+    release();
+  }
+}
+function documentIdToZipEntries(documentId) {
+  const normalized = documentId.replace(/\\/g, "/").replace(/\.md$/, "");
+  if (normalized.split("/").includes("..")) {
+    throw new Error("Invalid document ID: path traversal is not allowed.");
+  }
+  return [
+    `docs/${normalized}.md`,
+    `${normalized}.md`,
+    `docs/${normalized}`,
+    normalized
+  ];
+}
+function lookupEntry(entries, entryNames) {
+  for (const name of entryNames) {
+    const entry = entries.get(name.replace(/\\/g, "/"));
+    if (entry) {
+      return entry;
+    }
+  }
+  return null;
+}
+async function readMarkdownFromDocsZip(documentId) {
+  const zipPath = findDocsZip();
+  if (!zipPath) {
+    throw new Error("docs.zip not found");
+  }
+  const cache = await getDocsZipCache(zipPath);
+  const entry = lookupEntry(cache.entries, documentIdToZipEntries(documentId));
+  if (!entry) {
+    throw new Error(`Document not found: ${documentId}`);
+  }
+  const buffer = await readEntryWithLock(cache, entry);
+  return buffer.toString("utf-8");
+}
+function isDocsZipAvailable() {
+  const zipPath = findDocsZip();
+  return zipPath !== null && fs4.existsSync(zipPath);
+}
+function resetDocsZipReaderCache() {
+  closeDocsZipCache();
+}
+
+// src/doc-index/index-bundle.ts
+import * as fs6 from "fs";
+import * as path6 from "path";
+import AdmZip from "adm-zip";
+
+// src/doc-index/path-safety.ts
+import * as fs5 from "fs";
+import * as path5 from "path";
+var DocPathSafetyError = class extends Error {
+  constructor(message) {
+    super(`Unsafe documentation path: ${message}`);
+    this.name = "DocPathSafetyError";
+  }
+};
+function isDocStorageError(error) {
+  return error instanceof CacheDirError || error instanceof DocPathSafetyError || error instanceof Error && (error.name === "CacheDirError" || error.name === "DocPathSafetyError");
+}
+function unsafePath(message) {
+  return new DocPathSafetyError(message);
+}
+function dataRootForContainment() {
+  return resolveCanonicalPath(getCacheDir());
+}
+function assertInsideDataRoot(target, dataRoot, label) {
+  const realTarget = resolvePathInsideRoot(target, dataRoot);
+  if (realTarget === null) {
+    throw unsafePath(`${label} resolves outside the data directory.`);
+  }
+  return realTarget;
+}
+async function assertSafeDirectory(directory, dataRoot) {
+  await fs5.promises.mkdir(directory, { recursive: true });
+  const realDir = assertInsideDataRoot(directory, dataRoot, "directory");
+  const entry = await fs5.promises.stat(realDir);
+  if (!entry.isDirectory()) {
+    throw unsafePath("path must be a directory.");
+  }
+}
+function assertSafeRegularFile(filePath) {
+  const dataRoot = dataRootForContainment();
+  try {
+    const realFile = assertInsideDataRoot(filePath, dataRoot, "file");
+    if (!fs5.statSync(realFile).isFile()) {
+      throw unsafePath("path must be a regular file.");
+    }
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      assertInsideDataRoot(path5.dirname(filePath), dataRoot, "file parent");
+      return;
+    }
+    throw error;
+  }
+}
+async function assertDocStorageSafe(options = {}) {
+  const mode = options.mode ?? "write";
+  const dataRoot = await assertCacheDirSafe();
+  await assertSafeDirectory(getDocsDir(), dataRoot);
+  await assertSafeDirectory(getIndexDir(), dataRoot);
+  if (mode === "write") {
+    await assertSafeDirectory(getIndexTmpDir(), dataRoot);
+  }
+  for (const filePath of [
+    getSearchDbFile(),
+    getBuildMetaFile(),
+    getBuildStatusFile(),
+    getBuildLockFile(),
+    ...INDEX_LEXICON_FILES.map((name) => path5.join(getIndexDir(), name))
+  ]) {
+    assertSafeRegularFile(filePath);
+  }
+}
+
+// src/doc-index/index-bundle.ts
+var BUNDLE_FILES = [
+  "search.db",
+  "build-meta.json",
+  ...INDEX_LEXICON_FILES
+];
+var LEGACY_INDEX_FILES = [
+  "corpus.json",
+  "corpus-offsets.json",
+  "orama.dpack"
+];
+async function cleanLegacyIndexArtifacts(indexDir) {
+  for (const name of LEGACY_INDEX_FILES) {
+    await fs6.promises.rm(path6.join(indexDir, name), { force: true });
+  }
+}
+function readBundleMetaFromZip(indexZipPath) {
+  const zip = new AdmZip(indexZipPath);
+  const entry = zip.getEntry("build-meta.json");
+  if (!entry) {
+    throw new Error("index.zip is missing build-meta.json");
+  }
+  return JSON.parse(entry.getData().toString("utf-8"));
+}
+async function commitBundleFiles(tmpDir) {
+  const indexDir = getIndexDir();
+  await fs6.promises.mkdir(indexDir, { recursive: true });
+  for (const file of BUNDLE_FILES) {
+    const target = path6.join(indexDir, file);
+    await fs6.promises.rm(target, { force: true });
+    await fs6.promises.rename(path6.join(tmpDir, file), target);
+  }
+  await cleanLegacyIndexArtifacts(indexDir);
+  await fs6.promises.rm(getIndexTmpDir(), { recursive: true, force: true });
+}
+function isBundledIndexUsable(docsZipSha256) {
+  const bundlePath = findBundledIndexZip();
+  if (!bundlePath) {
+    return false;
+  }
+  try {
+    const meta = readBundleMetaFromZip(bundlePath);
+    return meta.indexVersion === INDEX_VERSION && meta.docsZipSha256 === docsZipSha256 && meta.segmentCount > 0;
+  } catch {
+    return false;
+  }
+}
+async function installBundledIndex(docsZipSha256) {
+  await assertDocStorageSafe({ mode: "write" });
+  const bundlePath = findBundledIndexZip();
+  if (!bundlePath) {
+    throw new Error("index.zip not found");
+  }
+  const bundleMeta = readBundleMetaFromZip(bundlePath);
+  if (bundleMeta.docsZipSha256 !== docsZipSha256) {
+    throw new Error(
+      "Bundled index.zip does not match docs.zip. Rebuild index.zip with npm run build:index."
+    );
+  }
+  if (bundleMeta.segmentCount <= 0) {
+    throw new Error("Bundled index.zip is empty");
+  }
+  const tmpDir = getIndexTmpDir();
+  await fs6.promises.rm(tmpDir, { recursive: true, force: true });
+  await fs6.promises.mkdir(tmpDir, { recursive: true });
+  const zip = new AdmZip(bundlePath);
+  for (const file of BUNDLE_FILES) {
+    const entry = zip.getEntry(file);
+    if (!entry) {
+      throw new Error(`index.zip is missing ${file}`);
+    }
+    await fs6.promises.writeFile(path6.join(tmpDir, file), entry.getData());
+  }
+  const installedMeta = JSON.parse(
+    await fs6.promises.readFile(path6.join(tmpDir, "build-meta.json"), "utf-8")
+  );
+  if (!fs6.existsSync(path6.join(tmpDir, "search.db"))) {
+    throw new Error("index.zip is missing search.db");
+  }
+  await commitBundleFiles(tmpDir);
+  return installedMeta;
+}
+async function resetBundledInstallScratch() {
+  await fs6.promises.rm(getIndexTmpDir(), { recursive: true, force: true });
+  const indexDir = getIndexDir();
+  for (const file of BUNDLE_FILES) {
+    await fs6.promises.rm(path6.join(indexDir, file), { force: true });
+  }
+}
+
+// src/doc-index/hash-utils.ts
+import { createHash } from "crypto";
+import * as fs7 from "fs";
+async function sha256File(filePath) {
+  return new Promise((resolve3, reject) => {
+    const hash = createHash("sha256");
+    const stream = fs7.createReadStream(filePath);
+    stream.on("data", (chunk) => hash.update(chunk));
+    stream.on("error", reject);
+    stream.on("end", () => resolve3(hash.digest("hex")));
+  });
+}
+function sha256Text(text) {
+  return createHash("sha256").update(text, "utf8").digest("hex");
+}
+
+// src/doc-index/query-rewriter.ts
+var synonymMap = null;
+function loadSynonymGroups() {
+  const raw = readIndexLexiconFile("harmonyos-synonyms.json");
+  return JSON.parse(raw);
+}
+function buildSynonymIndex(groups) {
+  const idx = /* @__PURE__ */ new Map();
+  for (const group of groups) {
+    const normalized = group.map((item) => item.trim()).filter(Boolean);
+    for (const term of normalized) {
+      const others = normalized.filter((item) => item !== term);
+      idx.set(term.toLowerCase(), others);
+      if (term !== term.toLowerCase()) {
+        idx.set(term, others);
+      }
+    }
+  }
+  return idx;
+}
+function buildSynonymMap() {
+  const idx = buildSynonymIndex(loadSynonymGroups());
+  const map = /* @__PURE__ */ new Map();
+  for (const [key, others] of idx) {
+    map.set(key, new Set(others));
+  }
+  return map;
+}
+function getSynonymMap() {
+  if (!synonymMap) {
+    synonymMap = buildSynonymMap();
+  }
+  return synonymMap;
+}
+function expandSynonymsLimited(query, maxParts) {
+  const map = getSynonymMap();
+  const parts = query.split(/\s+/).filter(Boolean);
+  const expanded = /* @__PURE__ */ new Set();
+  const limit = Number.isFinite(maxParts) ? maxParts : parts.length;
+  for (let index = 0; index < parts.length && expanded.size < limit; index += 1) {
+    const part = parts[index];
+    expanded.add(part);
+    const synonyms = map.get(part) ?? map.get(part.toLowerCase());
+    if (!synonyms) {
+      continue;
+    }
+    for (const synonym of synonyms) {
+      if (expanded.size >= limit) {
+        break;
+      }
+      expanded.add(synonym);
+    }
+  }
+  return [...expanded].join(" ");
+}
+function hashLexiconFile(name, lexiconDir) {
+  const content = lexiconDir ? readBuildLexiconFile(name, lexiconDir) : readIndexLexiconFile(name);
+  return sha256Text(content);
+}
+function getSynonymsHash(lexiconDir) {
+  return hashLexiconFile("harmonyos-synonyms.json", lexiconDir);
+}
+function getTermsHash(lexiconDir) {
+  return hashLexiconFile("harmonyos-terms.txt", lexiconDir);
+}
+
+// src/doc-index/index-state.ts
+var DEFAULT_STATUS = {
+  state: "idle",
+  phase: 0,
+  phaseLabel: "Idle",
+  current: 0,
+  total: 0,
+  message: "",
+  startedAt: 0,
+  updatedAt: 0,
+  error: null
+};
+async function readBuildStatus() {
+  try {
+    const raw = await fs8.promises.readFile(getBuildStatusFile(), "utf-8");
+    return JSON.parse(raw);
+  } catch {
+    return { ...DEFAULT_STATUS };
+  }
+}
+async function writeBuildStatus(status) {
+  const filePath = getBuildStatusFile();
+  await fs8.promises.mkdir(path7.dirname(filePath), { recursive: true });
+  await fs8.promises.writeFile(filePath, JSON.stringify(status, null, 2));
+}
+function createInitialStatus(message) {
+  const now = Date.now();
+  return {
+    state: "installing",
+    phase: 1,
+    phaseLabel: "Preparing documentation index",
+    current: 0,
+    total: 0,
+    message,
+    startedAt: now,
+    updatedAt: now,
+    error: null
+  };
+}
+async function updateBuildStatus(partial) {
+  const current = await readBuildStatus();
+  const next = {
+    ...current,
+    ...partial,
+    updatedAt: Date.now()
+  };
+  await writeBuildStatus(next);
+  return next;
+}
+async function getBundledDocsZipSha256() {
+  const zipPath = findDocsZip();
+  if (!zipPath) {
+    return null;
+  }
+  return sha256File(zipPath);
+}
+async function readBuildMeta() {
+  try {
+    const raw = await fs8.promises.readFile(getBuildMetaFile(), "utf-8");
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+async function needsRebuildIndex(force = false) {
+  if (force) {
+    return "no-index";
+  }
+  const meta = await readBuildMeta();
+  if (!meta || meta.segmentCount === 0) {
+    return "no-index";
+  }
+  const bundled = await getBundledDocsZipSha256();
+  if (bundled && meta.docsZipSha256 !== bundled) {
+    return "docs-changed";
+  }
+  if (meta.indexVersion !== INDEX_VERSION) {
+    return "engine-upgraded";
+  }
+  if (meta.termsHash !== getTermsHash()) {
+    return "terms-changed";
+  }
+  if (meta.synonymsHash !== getSynonymsHash()) {
+    return "synonyms-changed";
+  }
+  return null;
+}
+function isIndexReady() {
+  if (!isDocsZipAvailable()) {
+    return false;
+  }
+  if (!fs8.existsSync(getSearchDbFile()) || !fs8.existsSync(getBuildMetaFile())) {
+    return false;
+  }
+  const indexDir = path7.dirname(getSearchDbFile());
+  if (!INDEX_LEXICON_FILES.every(
+    (name) => fs8.existsSync(path7.join(indexDir, name))
+  )) {
+    return false;
+  }
+  try {
+    const raw = fs8.readFileSync(getBuildMetaFile(), "utf-8");
+    const meta = JSON.parse(raw);
+    return meta.segmentCount > 0;
+  } catch {
+    return false;
+  }
+}
+async function needsIndexInstall(force = false) {
+  if (force) {
+    return true;
+  }
+  if (!isDocsZipAvailable()) {
+    return false;
+  }
+  if (!isIndexReady()) {
+    return true;
+  }
+  return await needsRebuildIndex() !== null;
+}
+async function isBuildInProgress() {
+  const status = await readBuildStatus();
+  return ["installing", "indexing", "persisting"].includes(status.state);
+}
+
+// src/doc-index/api-suffixes.ts
+var API_COMPOUND_SUFFIXES = /* @__PURE__ */ new Set([
+  // Selectors — cameraPicker, @ohos.file.picker, DatePicker, DocumentViewPicker, avCastPicker
+  "picker",
+  // Overlays — AlertDialog, ActionSheet, bindSheet, …
+  "dialog",
+  "sheet",
+  "panel",
+  "popup",
+  "menu",
+  // ArkUI structure / motion — Navigation, GestureRecognizer, PageTransition, …
+  "layout",
+  "view",
+  "gesture",
+  "animation",
+  "transition",
+  "recognizer",
+  // @ohos.*Manager modules users describe as "wifi manager", "notification manager", …
+  "manager",
+  // Kit-oriented queries — "camera kit", "location kit" (maps to *Kit docs / symbols)
+  "kit"
+]);
+var MANAGER_REFERENCE_MERGE_FIRST_WORDS = /* @__PURE__ */ new Set([
+  "wifi",
+  "wlan",
+  "notification",
+  "bluetooth",
+  "location",
+  "sensor",
+  "power",
+  "battery",
+  "account",
+  "pasteboard",
+  "calendar",
+  "telephony",
+  "contact"
+]);
+var COMPOUND_FIRST_BLOCKLIST = /* @__PURE__ */ new Set([
+  "a",
+  "an",
+  "and",
+  "api",
+  "app",
+  "application",
+  "arkts",
+  "arkui",
+  "for",
+  "get",
+  "harmonyos",
+  "how",
+  "in",
+  "oh",
+  "ohos",
+  "on",
+  "or",
+  "set",
+  "the",
+  "to",
+  "use",
+  "using",
+  "what",
+  "when",
+  "where",
+  "which",
+  "with",
+  "without",
+  // Generic nouns that precede real APIs but should not auto-merge
+  "data",
+  "file",
+  "main",
+  "model",
+  "name",
+  "network",
+  "stage",
+  "system",
+  "type",
+  "user"
+]);
+var COMPOUND_SECOND_BLOCKLIST = /* @__PURE__ */ new Set([
+  "ability",
+  "extension",
+  "module",
+  "service",
+  "context",
+  "options",
+  "config",
+  "info",
+  "event",
+  "code",
+  "state",
+  "type",
+  "data",
+  "request",
+  "response",
+  "client",
+  "server",
+  "handler",
+  "helper",
+  "utils",
+  "factory",
+  "builder",
+  "listener",
+  "callback",
+  "observer",
+  "provider",
+  "consumer",
+  "delegate",
+  "adapter",
+  "driver",
+  "buffer",
+  "stream",
+  "channel",
+  "session",
+  "task",
+  "worker",
+  "controller",
+  "component",
+  "container",
+  "attribute",
+  "descriptor",
+  "modifier",
+  "validator",
+  "parser",
+  "formatter",
+  "encoder",
+  "decoder",
+  "filter",
+  "converter",
+  "generator",
+  "iterator",
+  "dispatcher",
+  "resolver",
+  "scanner",
+  "tracker",
+  "monitor",
+  "scheduler",
+  "renderer",
+  "loader",
+  "subscriber",
+  "proxy",
+  "button",
+  "surface",
+  "stack",
+  "heap",
+  "map",
+  "set",
+  "array",
+  "list"
+]);
+
+// src/doc-index/api-identifiers.ts
+var OHOS_MODULE_RE = /@ohos\.[a-z][a-zA-Z0-9.]+/gi;
+var CAMEL_CASE_API_RE = /\b[a-z][a-z0-9]*[A-Z][a-zA-Z0-9]+\b/g;
+var PASCAL_CASE_API_RE = /[A-Z][a-zA-Z0-9]{2,}/g;
+var DECORATOR_TOKEN_RE = /@[A-Z][a-zA-Z0-9]*/g;
+var QUALIFIED_SYMBOL_RE = /[a-z][a-zA-Z0-9]*\.[a-zA-Z][a-zA-Z0-9]+/g;
+var CAMEL_CASE_MIN_LEN = 6;
+var IDENTIFIER_PART_RE = /^[a-z][a-z0-9]{2,}$/;
+var SPLIT_API_QUERY_RE = /^([a-z][a-z0-9]{2,})\s+([a-z][a-z0-9]{2,})$/;
+var OHOS_MODULE_QUERY_RE = /^@ohos\.[a-z][a-zA-Z0-9.]+$/i;
+var SINGLE_CAMEL_CASE_QUERY_RE = /^[a-z][a-z0-9]*[A-Z][a-zA-Z0-9]+$/;
+var SINGLE_PASCAL_CASE_QUERY_RE = /^[A-Z][a-zA-Z0-9]+$/;
+function escapeFtsToken(token) {
+  return `"${token.replace(/"/g, '""')}"`;
+}
+function buildFtsMatch(tokens, operator) {
+  const unique = [...new Set(tokens.filter(Boolean))];
+  if (unique.length === 0) {
+    return '""';
+  }
+  return unique.map(escapeFtsToken).join(` ${operator} `);
+}
+function buildFtsOrMatch(tokens) {
+  return buildFtsMatch(tokens, "OR");
+}
+function buildSplitApiAndMatch(left, right) {
+  const l = [...new Set(left.filter(Boolean))];
+  const r = [...new Set(right.filter(Boolean))];
+  if (l.length === 0 || r.length === 0) {
+    return buildFtsOrMatch([...l, ...r]);
+  }
+  return `(${buildFtsOrMatch(l)}) AND (${buildFtsOrMatch(r)})`;
+}
+function isOhosModuleQuery(trimmed) {
+  return OHOS_MODULE_QUERY_RE.test(trimmed);
+}
+function isSingleCamelCaseApiQuery(trimmed) {
+  return SINGLE_CAMEL_CASE_QUERY_RE.test(trimmed) && trimmed.length >= CAMEL_CASE_MIN_LEN;
+}
+function isSinglePascalCaseApiQuery(trimmed) {
+  return SINGLE_PASCAL_CASE_QUERY_RE.test(trimmed);
+}
+function isSingleApiLikeQuery(trimmed) {
+  return isOhosModuleQuery(trimmed) || isSingleCamelCaseApiQuery(trimmed) || isSinglePascalCaseApiQuery(trimmed);
+}
+function isApiCompoundSuffix(word) {
+  const lower = word.trim().toLowerCase();
+  if (COMPOUND_SECOND_BLOCKLIST.has(lower)) {
+    return false;
+  }
+  return API_COMPOUND_SUFFIXES.has(lower);
+}
+function buildCamelCaseCompound(first, second) {
+  const head = second.trim().charAt(0).toUpperCase();
+  const tail = second.trim().slice(1).toLowerCase();
+  return `${first.trim().toLowerCase()}${head}${tail}`;
+}
+function ohosModuleLastSegment(modulePath) {
+  const body = modulePath.replace(/^@ohos\./i, "");
+  const parts = body.split(".").filter(Boolean);
+  const last = parts[parts.length - 1]?.trim();
+  return last || void 0;
+}
+function extractOhosModules(text) {
+  return [...text.matchAll(OHOS_MODULE_RE)].map((match) => match[0]);
+}
+function extractCamelCaseIdentifiers(text, minLen = CAMEL_CASE_MIN_LEN) {
+  const out = [];
+  for (const match of text.matchAll(CAMEL_CASE_API_RE)) {
+    if (match[0].length >= minLen) {
+      out.push(match[0]);
+    }
+  }
+  return out;
+}
+function filterSubsumedTokens(tokens) {
+  return tokens.filter((token) => {
+    const lower = token.toLowerCase();
+    return !tokens.some((other) => {
+      if (other === token) {
+        return false;
+      }
+      const otherLower = other.toLowerCase();
+      return otherLower.length > lower.length && otherLower.endsWith(lower) && lower.length >= 4;
+    });
+  });
+}
+function appendSymbolVariants(target, symbol) {
+  const trimmed = symbol.trim();
+  if (!trimmed) {
+    return;
+  }
+  target.add(trimmed);
+  const lower = trimmed.toLowerCase();
+  if (lower !== trimmed) {
+    target.add(lower);
+  }
+}
+function buildOhosModuleQueryTokens(modulePath) {
+  const tokens = /* @__PURE__ */ new Set();
+  appendSymbolVariants(tokens, modulePath);
+  const last = ohosModuleLastSegment(modulePath);
+  if (last) {
+    appendSymbolVariants(tokens, last);
+  }
+  return filterSubsumedTokens([...tokens]);
+}
+function buildSingleApiQueryTokens(trimmed) {
+  if (isOhosModuleQuery(trimmed)) {
+    return buildOhosModuleQueryTokens(trimmed);
+  }
+  const tokens = /* @__PURE__ */ new Set();
+  appendSymbolVariants(tokens, trimmed);
+  return filterSubsumedTokens([...tokens]);
+}
+function parseSplitApiPhraseQuery(raw) {
+  const trimmed = raw.trim();
+  if (/[A-Z]/.test(trimmed)) {
+    return null;
+  }
+  const match = trimmed.match(SPLIT_API_QUERY_RE);
+  if (!match) {
+    return null;
+  }
+  const first = match[1].toLowerCase();
+  const second = match[2].toLowerCase();
+  if (!IDENTIFIER_PART_RE.test(first) || COMPOUND_FIRST_BLOCKLIST.has(first)) {
+    return null;
+  }
+  if (!isApiCompoundSuffix(second)) {
+    return null;
+  }
+  const camelCase = buildCamelCaseCompound(first, second);
+  return { first, second, camelCase, lower: camelCase.toLowerCase() };
+}
+function getManagerSplitApiCompound(rawQuery) {
+  const split = parseSplitApiPhraseQuery(rawQuery.trim());
+  if (!split || split.second !== "manager") {
+    return null;
+  }
+  return split;
+}
+function managerMergeFirstWord(camelCase) {
+  const match = camelCase.match(/^([a-z][a-z0-9]*)Manager$/i);
+  if (!match) {
+    return null;
+  }
+  return match[1].toLowerCase();
+}
+function shouldReferencesFirstForManagerQuery(rawQuery) {
+  const trimmed = rawQuery.trim();
+  const split = getManagerSplitApiCompound(trimmed);
+  if (split && MANAGER_REFERENCE_MERGE_FIRST_WORDS.has(split.first)) {
+    return true;
+  }
+  if (isSingleCamelCaseApiQuery(trimmed)) {
+    const first = managerMergeFirstWord(trimmed);
+    return first !== null && MANAGER_REFERENCE_MERGE_FIRST_WORDS.has(first);
+  }
+  return false;
+}
+function rowMatchesManagerApiModule(docTitle, sectionTitle, compoundCamel) {
+  const compoundLower = compoundCamel.toLowerCase();
+  const ohosModuleRe = new RegExp(`@ohos\\.[^\\s(]*${compoundCamel}`, "i");
+  for (const field of [docTitle, sectionTitle]) {
+    if (!field) {
+      continue;
+    }
+    if (field.toLowerCase().includes(compoundLower)) {
+      return true;
+    }
+    if (ohosModuleRe.test(field)) {
+      return true;
+    }
+  }
+  return false;
+}
+function extractPriorityApiTokens(text) {
+  const trimmed = text.trim();
+  if (isSingleApiLikeQuery(trimmed)) {
+    return buildSingleApiQueryTokens(trimmed);
+  }
+  const tokens = /* @__PURE__ */ new Set();
+  for (const modulePath of extractOhosModules(text)) {
+    appendSymbolVariants(tokens, modulePath);
+    const last = ohosModuleLastSegment(modulePath);
+    if (last) {
+      appendSymbolVariants(tokens, last);
+    }
+  }
+  for (const camel of extractCamelCaseIdentifiers(text)) {
+    appendSymbolVariants(tokens, camel);
+  }
+  for (const match of text.matchAll(DECORATOR_TOKEN_RE)) {
+    tokens.add(match[0]);
+  }
+  for (const match of text.matchAll(QUALIFIED_SYMBOL_RE)) {
+    tokens.add(match[0]);
+  }
+  for (const match of text.matchAll(PASCAL_CASE_API_RE)) {
+    if (match[0].length >= 4) {
+      tokens.add(match[0]);
+    }
+  }
+  return filterSubsumedTokens([...tokens]);
+}
+function extractQueryApiSymbolTokens(rawQuery) {
+  const trimmed = rawQuery.trim();
+  if (isSingleApiLikeQuery(trimmed)) {
+    return buildSingleApiQueryTokens(trimmed);
+  }
+  const tokens = /* @__PURE__ */ new Set();
+  const split = parseSplitApiPhraseQuery(trimmed);
+  if (split) {
+    appendSymbolVariants(tokens, split.camelCase);
+  }
+  for (const token of extractPriorityApiTokens(trimmed)) {
+    tokens.add(token);
+  }
+  for (const match of trimmed.matchAll(/\b[a-z][a-zA-Z0-9]{3,}\b/g)) {
+    const value = match[0];
+    if (value !== value.toLowerCase()) {
+      tokens.add(value);
+    }
+  }
+  return filterSubsumedTokens([...tokens]);
+}
+function shouldSkipSynonymExpansion(trimmed) {
+  return isSingleApiLikeQuery(trimmed);
+}
+
+// src/doc-index/query-named-rules.ts
+var NAMED_QUERY_RE = {
+  pureApiSymbol: /^[A-Z][a-zA-Z0-9]+$/,
+  stageModelExact: /^Stage\s*模型$/i,
+  /** English alias for Stage 模型 (exact two-word query only). */
+  stageModelEnglishExact: /^stage\s+model$/i,
+  stageModel: /Stage\s*模型/i,
+  stageModelEntryPage: /Stage\s*模型.*EntryAbility.*(页面|新页面)/,
+  declarePermissionBoost: /声明.*权限|应用权限.*声明|如何声明应用权限/,
+  declarePermissionCatalog: /如何声明应用权限/,
+  declarePermissionTokens: /如何声明应用权限|声明应用权限/,
+  uiAbilityLifecycleBoost: /UIAbility.*生命周期|生命周期.*UIAbility|UIAblity/i,
+  uiAbilityLifecycleCatalog: /UIAblity.*生命周期|UIAbility.*生命周期/i,
+  entryAbilityPage: /EntryAbility.*(页面|启动|跳转|新页面)/,
+  stateDecoratorBoost: /@State|@Prop|@Link|@Provide|@Consume/,
+  stateDecoratorCatalog: /@State\s*装饰器|@Prop\s*装饰器|@Link\s*装饰器/,
+  stateManagement: /状态管理原理/,
+  routerRoute: /Router\s+路由/,
+  dialogPopupExact: /^Dialog\s+弹窗$/,
+  dialogPopupBoost: /Dialog\s+弹窗/
+};
+function isPureApiSymbolQuery(rawQuery) {
+  return NAMED_QUERY_RE.pureApiSymbol.test(rawQuery.trim());
+}
+function isStageModelExactQuery(rawQuery) {
+  const trimmed = rawQuery.trim();
+  return NAMED_QUERY_RE.stageModelExact.test(trimmed) || NAMED_QUERY_RE.stageModelEnglishExact.test(trimmed);
+}
+function extractNamedConceptTokens(text) {
+  const tokens = [];
+  if (isStageModelExactQuery(text.trim())) {
+    tokens.push("Stage\u6A21\u578B", "Stage\u6A21\u578B\u5F00\u53D1\u6982\u8FF0");
+  }
+  if (NAMED_QUERY_RE.declarePermissionTokens.test(text)) {
+    tokens.push("\u58F0\u660E\u6743\u9650");
+  }
+  if (NAMED_QUERY_RE.stageModelEntryPage.test(text)) {
+    tokens.push("\u9875\u9762\u8DEF\u7531", "pushUrl");
+  }
+  if (/UIAblity|UIAbility/.test(text) && /生命周期/.test(text)) {
+    tokens.push("UIAbility\u7EC4\u4EF6\u751F\u547D\u5468\u671F");
+  }
+  return tokens;
+}
+function getStageModelPreparedOverride(trimmedRawQuery) {
+  if (!isStageModelExactQuery(trimmedRawQuery)) {
+    return null;
+  }
+  return {
+    expandedQuery: "Stage\u6A21\u578B\u5F00\u53D1\u6982\u8FF0",
+    tokens: ["Stage\u6A21\u578B\u5F00\u53D1\u6982\u8FF0", "Stage\u6A21\u578B"]
+  };
+}
+var NAMED_CONCEPT_BOOST_RULES = [
+  {
+    matches: (q) => NAMED_QUERY_RE.uiAbilityLifecycleBoost.test(q),
+    weights: [
+      { catalog: "harmonyos-guides", multiplier: 1.85 },
+      { catalog: "harmonyos-references", multiplier: 0.65 },
+      { catalog: "harmonyos-faqs", multiplier: 0.82 }
+    ]
+  },
+  {
+    matches: (q) => isStageModelExactQuery(q),
+    weights: [
+      { catalog: "harmonyos-guides", multiplier: 1.85 },
+      { catalog: "harmonyos-references", multiplier: 0.55 },
+      { catalog: "harmonyos-faqs", multiplier: 0.85 }
+    ]
+  },
+  {
+    matches: (q) => !isStageModelExactQuery(q) && NAMED_QUERY_RE.stageModel.test(q),
+    weights: [
+      { catalog: "harmonyos-guides", multiplier: 1.65 },
+      { catalog: "harmonyos-references", multiplier: 0.65 }
+    ]
+  },
+  {
+    matches: (q) => NAMED_QUERY_RE.entryAbilityPage.test(q),
+    weights: [
+      { catalog: "harmonyos-guides", multiplier: 1.75 },
+      { catalog: "harmonyos-references", multiplier: 0.48 }
+    ]
+  },
+  {
+    matches: (q) => NAMED_QUERY_RE.declarePermissionBoost.test(q),
+    weights: [
+      { catalog: "harmonyos-guides", multiplier: 1.65 },
+      { catalog: "best-practices", multiplier: 0.68 }
+    ]
+  },
+  {
+    matches: (q) => NAMED_QUERY_RE.stateDecoratorBoost.test(q),
+    weights: [
+      { catalog: "harmonyos-guides", multiplier: 1.75 },
+      { catalog: "harmonyos-references", multiplier: 0.42 }
+    ]
+  },
+  {
+    matches: (q) => NAMED_QUERY_RE.stateManagement.test(q),
+    weights: [
+      { catalog: "harmonyos-guides", multiplier: 1.6 },
+      { catalog: "best-practices", multiplier: 0.78 }
+    ]
+  },
+  {
+    matches: (q) => NAMED_QUERY_RE.routerRoute.test(q),
+    weights: [
+      { catalog: "harmonyos-guides", multiplier: 1.65 },
+      { catalog: "harmonyos-references", multiplier: 1.4 },
+      { catalog: "harmonyos-faqs", multiplier: 0.72 },
+      { catalog: "best-practices", multiplier: 0.72 }
+    ]
+  },
+  {
+    matches: (q) => NAMED_QUERY_RE.dialogPopupBoost.test(q),
+    weights: [
+      { catalog: "harmonyos-guides", multiplier: 1.65 },
+      { catalog: "harmonyos-faqs", multiplier: 0.72 },
+      { catalog: "best-practices", multiplier: 0.72 }
+    ]
+  }
+];
+function applyWeights(boosts, weights) {
+  for (const { catalog, multiplier } of weights) {
+    const catalogId = CATALOG_NAME_TO_ID[catalog];
+    boosts.set(catalogId, (boosts.get(catalogId) ?? 1) * multiplier);
+  }
+}
+function applyNamedConceptBoosts(rawQuery, boosts) {
+  for (const rule of NAMED_CONCEPT_BOOST_RULES) {
+    if (rule.matches(rawQuery)) {
+      applyWeights(boosts, rule.weights);
+    }
+  }
+}
+function shouldMergeReferencesWithGlobalFallback(rawQuery, explicitCatalog) {
+  if (explicitCatalog !== void 0) {
+    return false;
+  }
+  const trimmed = rawQuery.trim();
+  return isOhosModuleQuery(trimmed) || NAMED_QUERY_RE.pureApiSymbol.test(trimmed) || shouldReferencesFirstForManagerQuery(trimmed);
+}
+function inferNamedSearchCatalog(rawQuery) {
+  const trimmed = rawQuery.trim();
+  if (isOhosModuleQuery(trimmed) || NAMED_QUERY_RE.pureApiSymbol.test(trimmed)) {
+    return "harmonyos-references";
+  }
+  if (isStageModelExactQuery(trimmed)) {
+    return "harmonyos-guides";
+  }
+  if (NAMED_QUERY_RE.uiAbilityLifecycleCatalog.test(trimmed)) {
+    return "harmonyos-guides";
+  }
+  if (NAMED_QUERY_RE.stateDecoratorCatalog.test(trimmed)) {
+    return "harmonyos-guides";
+  }
+  if (NAMED_QUERY_RE.stateManagement.test(trimmed)) {
+    return "harmonyos-guides";
+  }
+  if (NAMED_QUERY_RE.declarePermissionCatalog.test(trimmed)) {
+    return "harmonyos-guides";
+  }
+  if (NAMED_QUERY_RE.stageModelEntryPage.test(trimmed)) {
+    return "harmonyos-guides";
+  }
+  if (NAMED_QUERY_RE.routerRoute.test(trimmed)) {
+    return "harmonyos-guides";
+  }
+  if (NAMED_QUERY_RE.dialogPopupExact.test(trimmed)) {
+    return "harmonyos-guides";
+  }
+  return void 0;
+}
+
+// src/doc-index/tokenizer.ts
+import { createRequire } from "module";
+
+// src/logger.ts
+function debugLog(message) {
+  if (process.env.DEVECO_CLI_DEBUG) {
+    const msg = typeof message === "function" ? message() : message;
+    console.log(`[DEBUG] ${msg}`);
+  }
+}
+
+// src/doc-index/tokenizer.ts
+var require2 = createRequire(import.meta.url);
+var stopWords = null;
+var jiebaInstance = null;
+var initPromise = null;
+function loadStopWords() {
+  if (stopWords) {
+    return stopWords;
+  }
+  const raw = readIndexLexiconFile("harmonyos-stopwords.txt");
+  stopWords = new Set(
+    raw.split("\n").map((line) => line.trim()).filter(Boolean)
+  );
+  return stopWords;
+}
+function mergeDecoratorTokens(tokens) {
+  const merged = [];
+  for (let i = 0; i < tokens.length; i++) {
+    const current = tokens[i]?.trim();
+    if (!current) {
+      continue;
+    }
+    const next = tokens[i + 1]?.trim();
+    if (current === "@" && next && /^[A-Z][a-zA-Z0-9]*$/.test(next)) {
+      merged.push(`@${next}`);
+      i += 1;
+      continue;
+    }
+    merged.push(current);
+  }
+  return merged;
+}
+function normalizeTokens(tokens) {
+  const stops = loadStopWords();
+  const out = [];
+  for (const raw of mergeDecoratorTokens(tokens)) {
+    const token = raw.trim();
+    if (!token || stops.has(token)) {
+      continue;
+    }
+    out.push(token.toLowerCase());
+    if (/[A-Z]/.test(token) && /[a-zA-Z]/.test(token)) {
+      out.push(token);
+    }
+  }
+  return out;
+}
+async function createJieba() {
+  const { cut, cut_for_search, with_dict } = require2("jieba-wasm");
+  const userDict = readIndexLexiconFile("harmonyos-terms.txt");
+  with_dict(userDict);
+  debugLog("doc-index: using jieba-wasm backend");
+  return {
+    cut: (text, hmm) => cut(text, hmm),
+    cutForSearch: (text, hmm) => cut_for_search(text, hmm)
+  };
+}
+async function getJieba() {
+  if (jiebaInstance) {
+    return jiebaInstance;
+  }
+  if (!initPromise) {
+    initPromise = createJieba().then((instance) => {
+      jiebaInstance = instance;
+      return instance;
+    });
+  }
+  return initPromise;
+}
+async function tokenizeForIndex(text) {
+  const jieba = await getJieba();
+  return normalizeTokens(jieba.cutForSearch(text, true));
+}
+async function tokenizeForQuery(text) {
+  const jieba = await getJieba();
+  return normalizeTokens(jieba.cut(text, true));
+}
+async function tokenizeAndCap(text, maxChars) {
+  const trimmed = text.trim();
+  if (!trimmed || maxChars <= 0) {
+    return "";
+  }
+  const joined = (await tokenizeForIndex(trimmed)).join(" ");
+  if (joined.length <= maxChars) {
+    return joined;
+  }
+  return joined.slice(0, maxChars);
+}
+async function capApiSymbolsForIndex(symbols, maxChars) {
+  const tokens = [];
+  for (const symbol of symbols) {
+    const trimmed = symbol.trim();
+    if (!trimmed) {
+      continue;
+    }
+    tokens.push(trimmed.toLowerCase());
+    if (/[A-Z]/.test(trimmed)) {
+      tokens.push(trimmed);
+    }
+  }
+  const joined = [...new Set(tokens)].join(" ");
+  if (joined.length <= maxChars) {
+    return joined;
+  }
+  return joined.slice(0, maxChars);
+}
+async function buildDocumentSearchText(source) {
+  const isSectionRow = Boolean(source.sectionTitle.trim());
+  const titleRaw = source.titleTokens.trim();
+  const maxChars = isSectionRow ? DOC_SECTION_SEARCH_TEXT_MAX_CHARS : DOC_SEARCH_TEXT_MAX_CHARS;
+  const apiBudget = isSectionRow ? DOC_SECTION_BUDGET_API_SYMBOLS : DOC_SEARCH_BUDGET_API_SYMBOLS;
+  const apiText = isSectionRow ? await capApiSymbolsForIndex(source.apiSymbols, apiBudget) : await tokenizeAndCap(source.apiSymbols.join(" "), apiBudget);
+  const parts = await Promise.all([
+    tokenizeAndCap(
+      titleRaw,
+      isSectionRow ? DOC_SECTION_BUDGET_TITLE : DOC_SEARCH_BUDGET_TITLE
+    ),
+    Promise.resolve(apiText),
+    tokenizeAndCap(
+      source.headingsText,
+      isSectionRow ? DOC_SECTION_BUDGET_HEADINGS : DOC_SEARCH_BUDGET_HEADINGS
+    ),
+    tokenizeAndCap(
+      source.bodySample,
+      isSectionRow ? DOC_SECTION_BUDGET_BODY : DOC_SEARCH_BUDGET_BODY
+    )
+  ]);
+  const joined = parts.filter(Boolean).join(" ");
+  if (joined.length <= maxChars) {
+    return joined;
+  }
+  return joined.slice(0, maxChars);
+}
+
+// src/doc-index/query-normalizer.ts
+function normalizeSearchInput(keywords) {
+  return keywords.join(" ").replace(/\s+/g, " ").trim().slice(0, QUERY_MAX_RAW_CHARS);
+}
+function capTokens(priority, general) {
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  for (const token of [...priority, ...general]) {
+    const key = token.toLowerCase();
+    if (!token || seen.has(key)) {
+      continue;
+    }
+    seen.add(key);
+    out.push(token);
+    if (out.length >= QUERY_MAX_FTS_TOKENS) {
+      break;
+    }
+  }
+  return out;
+}
+function shouldPreferAndMatch(tokens) {
+  return tokens.length >= 2 && tokens.length <= QUERY_AND_MAX_TOKENS;
+}
+function buildSplitApiPrepared(rawQuery, split) {
+  const expandedQuery = expandSynonymsLimited(
+    rawQuery,
+    SYNONYM_EXPAND_MAX_PARTS
+  );
+  const synonymParts = expandedQuery.split(/\s+/).filter(Boolean);
+  const left = [
+    split.first,
+    ...synonymParts.filter((part) => part !== split.second),
+    split.lower,
+    split.camelCase
+  ];
+  const right = [split.second, split.lower, split.camelCase];
+  const tokens = capTokens(left, right);
+  return {
+    rawQuery,
+    expandedQuery,
+    tokens,
+    preferAnd: false,
+    ftsMatch: buildSplitApiAndMatch(left, right)
+  };
+}
+function buildSingleApiPrepared(rawQuery, trimmed) {
+  const tokens = capTokens(buildSingleApiQueryTokens(trimmed), []);
+  return {
+    rawQuery,
+    expandedQuery: rawQuery,
+    tokens,
+    preferAnd: false,
+    ftsMatch: buildFtsOrMatch(tokens)
+  };
+}
+async function prepareSearchQuery(keywords) {
+  const rawQuery = normalizeSearchInput(keywords);
+  const trimmed = rawQuery.trim();
+  const stageOverride = getStageModelPreparedOverride(trimmed);
+  if (stageOverride) {
+    return {
+      rawQuery,
+      expandedQuery: stageOverride.expandedQuery,
+      tokens: stageOverride.tokens,
+      preferAnd: false
+    };
+  }
+  const splitApi = parseSplitApiPhraseQuery(trimmed);
+  if (splitApi) {
+    return buildSplitApiPrepared(rawQuery, splitApi);
+  }
+  if (isSingleApiLikeQuery(trimmed)) {
+    return buildSingleApiPrepared(rawQuery, trimmed);
+  }
+  const conceptPriority = extractNamedConceptTokens(rawQuery);
+  const priorityTokens = [
+    ...extractPriorityApiTokens(rawQuery),
+    ...conceptPriority
+  ];
+  const skipSynonyms = shouldSkipSynonymExpansion(trimmed);
+  const expandedQuery = skipSynonyms ? rawQuery : expandSynonymsLimited(rawQuery, SYNONYM_EXPAND_MAX_PARTS);
+  const generalTokens = await tokenizeForQuery(expandedQuery);
+  const tokens = capTokens(priorityTokens, generalTokens);
+  return {
+    rawQuery,
+    expandedQuery,
+    tokens,
+    preferAnd: conceptPriority.length === 0 && shouldPreferAndMatch(tokens)
+  };
+}
+
+// src/doc-index/catalog-routing.ts
+var TAIL_SEARCH_CATALOGS = [
+  "harmonyos-releases",
+  "harmonyos-roadmap"
+];
+var TAIL_CATALOG_IDS = new Set(
+  TAIL_SEARCH_CATALOGS.map((name) => CATALOG_NAME_TO_ID[name])
+);
+var TAIL_CATALOG_DOCUMENT_PREFIXES = TAIL_SEARCH_CATALOGS.map(
+  (name) => `${CATALOG_TITLES[name]}/`
+);
+function isTailSearchCatalogId(catalogId) {
+  return TAIL_CATALOG_IDS.has(catalogId);
+}
+function isTailCatalogDocumentId(documentId) {
+  return TAIL_CATALOG_DOCUMENT_PREFIXES.some(
+    (prefix) => documentId.startsWith(prefix)
+  );
+}
+function orderRowsWithTailCatalogsLast(rows) {
+  const head = [];
+  const tail = [];
+  for (const row of rows) {
+    if (isTailSearchCatalogId(row.catalog_id)) {
+      tail.push(row);
+    } else {
+      head.push(row);
+    }
+  }
+  return [...head, ...tail];
+}
+function orderLocalResultsWithTailCatalogsLast(results) {
+  const head = [];
+  const tail = [];
+  for (const row of results) {
+    if (isTailCatalogDocumentId(row.documentId)) {
+      tail.push(row);
+    } else {
+      head.push(row);
+    }
+  }
+  return [...head, ...tail];
+}
+var CATALOG_ROUTING_RULES = [
+  { pattern: /@ohos\./i, catalog: "harmonyos-references", multiplier: 1.5 },
+  { pattern: /@[A-Z][a-zA-Z]+/, catalog: "harmonyos-guides", multiplier: 1.35 },
+  {
+    pattern: /(如何|怎么|怎样|步骤)/,
+    catalog: "harmonyos-guides",
+    multiplier: 1.45
+  },
+  {
+    pattern: /(生命周期|原理|概述|什么是|模型|介绍)/,
+    catalog: "harmonyos-guides",
+    multiplier: 1.35
+  },
+  {
+    pattern: /(报错|失败|错误|异常|排查)/,
+    catalog: "harmonyos-guides",
+    multiplier: 1.25
+  },
+  {
+    pattern: /(报错|失败|FAQ)/i,
+    catalog: "harmonyos-faqs",
+    multiplier: 1.2
+  },
+  {
+    pattern: /(构建|签名|打包|发布|上架|应用市场|hvigor|ohpm)/i,
+    catalog: "harmonyos-guides",
+    multiplier: 1.3
+  },
+  {
+    pattern: /(行为变更|changelog|升级|适配|版本说明)/i,
+    catalog: "harmonyos-releases",
+    multiplier: 1.3
+  },
+  {
+    pattern: /(路由|弹窗|手势|页面|权限|装饰器)/,
+    catalog: "harmonyos-guides",
+    multiplier: 1.25,
+    skipForPureApiSymbol: true
+  }
+];
+function applyCatalogWeight(boosts, catalog, multiplier) {
+  const catalogId = CATALOG_NAME_TO_ID[catalog];
+  boosts.set(catalogId, (boosts.get(catalogId) ?? 1) * multiplier);
+}
+function applyQueryShapeHeuristics(rawQuery, boosts) {
+  const trimmed = rawQuery.trim();
+  const hasChinese = /[\u4e00-\u9fff]/.test(trimmed);
+  const hasPascalApi = /\b[A-Z][a-zA-Z0-9]{2,}\b/.test(trimmed);
+  const hasCamelApi = /\b[a-z][a-zA-Z0-9]{3,}\b/.test(trimmed);
+  if (hasChinese && (hasPascalApi || hasCamelApi)) {
+    applyCatalogWeight(boosts, "harmonyos-guides", 1.45);
+    applyCatalogWeight(boosts, "harmonyos-references", 1.35);
+    return;
+  }
+  if (hasPascalApi || hasCamelApi) {
+    applyCatalogWeight(boosts, "harmonyos-references", 1.55);
+  }
+  if (/\b[A-Z][a-zA-Z]*(Gesture|Dialog|Sheet|Transition|Recognizer)\b/.test(
+    trimmed
+  )) {
+    applyCatalogWeight(boosts, "harmonyos-references", 1.75);
+  }
+}
+function inferCatalogBoosts(rawQuery) {
+  const boosts = /* @__PURE__ */ new Map();
+  const trimmed = rawQuery.trim();
+  if (!trimmed) {
+    return boosts;
+  }
+  const pureApiSymbol = isPureApiSymbolQuery(trimmed);
+  applyQueryShapeHeuristics(trimmed, boosts);
+  applyNamedConceptBoosts(trimmed, boosts);
+  for (const rule of CATALOG_ROUTING_RULES) {
+    if (!rule.pattern.test(trimmed)) {
+      continue;
+    }
+    if (rule.skipForPureApiSymbol && pureApiSymbol) {
+      continue;
+    }
+    applyCatalogWeight(boosts, rule.catalog, rule.multiplier);
+  }
+  return boosts;
+}
+function inferSearchCatalog(rawQuery) {
+  return inferNamedSearchCatalog(rawQuery);
+}
+
+// src/doc-index/sqlite-backend.ts
+import { readFile, stat, writeFile } from "fs/promises";
+
+// src/doc-index/sqlite-snippet.ts
+var WORD_BOUNDARY_CHARS = [
+  " ",
+  "\u3002",
+  "\uFF0C",
+  "\uFF1B",
+  "\u3001",
+  ".",
+  "!",
+  "?"
+];
+function findLastWordBoundary(text, minIndex) {
+  let best = -1;
+  for (const ch of WORD_BOUNDARY_CHARS) {
+    const idx = text.lastIndexOf(ch);
+    if (idx > best) {
+      best = idx;
+    }
+  }
+  return best >= minIndex ? best : -1;
+}
+function extractSearchSnippet(content, query, opts = {}) {
+  const {
+    maxLen = DOC_SNIPPET_MAX_CHARS,
+    contextChars = DOC_SNIPPET_CONTEXT_CHARS,
+    excerptTruncated = false
+  } = opts;
+  const normalized = content.replace(/\s+/g, " ").trim();
+  if (!normalized) {
+    return "";
+  }
+  if (normalized.length <= maxLen) {
+    return excerptTruncated ? `${normalized}...` : normalized;
+  }
+  const tokens = query.split(/\s+/).map((token) => token.trim()).filter(Boolean);
+  let bestIndex = 0;
+  for (const token of tokens) {
+    const idx = normalized.toLowerCase().indexOf(token.toLowerCase());
+    if (idx >= 0) {
+      bestIndex = idx;
+      break;
+    }
+  }
+  const start = Math.max(0, bestIndex - contextChars);
+  let end = Math.min(normalized.length, start + maxLen);
+  const window = normalized.slice(start, end);
+  const lastBreak = findLastWordBoundary(window, maxLen - 25);
+  if (lastBreak >= 0) {
+    end = start + lastBreak;
+  }
+  const snippet = normalized.slice(start, end).trim();
+  const prefix = start > 0 ? "..." : "";
+  const suffix = end < normalized.length || excerptTruncated ? "..." : "";
+  return `${prefix}${snippet}${suffix}`;
+}
+
+// src/doc-index/sqlite-fts-search.ts
+var FTS_SEARCH_SQL = `
+  SELECT d.document_id, d.doc_title, s.section_title, s.lead_text, s.excerpt_truncated,
+         d.catalog_id, bm25(segments_fts) AS bm25
+  FROM segments_fts
+  JOIN segments s ON s.id = segments_fts.rowid
+  JOIN documents d ON d.id = s.doc_id
+  WHERE segments_fts MATCH ?
+  ORDER BY bm25(segments_fts)
+  LIMIT ?
+`;
+var FTS_SEARCH_CATALOG_SQL = `
+  SELECT d.document_id, d.doc_title, s.section_title, s.lead_text, s.excerpt_truncated,
+         d.catalog_id, bm25(segments_fts) AS bm25
+  FROM segments_fts
+  JOIN segments s ON s.id = segments_fts.rowid
+  JOIN documents d ON d.id = s.doc_id
+  WHERE segments_fts MATCH ? AND d.catalog_id = ?
+  ORDER BY bm25(segments_fts)
+  LIMIT ?
+`;
+var MANAGER_API_RERANK_BOOST = 3.5;
+var MANAGER_API_REFERENCE_EXTRA = 1.4;
+var TITLE_EXACT_MATCH_BOOST = 4;
+var TITLE_PREFIX_MATCH_BOOST = 1.8;
+var TITLE_TERMS_MATCH_BOOST = 1.35;
+var BROAD_SINGLE_TERM_EXACT_TITLE_BOOST = 3.5;
+var BROAD_SINGLE_TERM_PREFIX_TITLE_BOOST = 1.8;
+var MIN_RERANK_FETCH_LIMIT = 120;
+var TITLE_PREFIX_MIN_CHARS = 6;
+function normalizeForRerank(text) {
+  return text.toLowerCase().replace(/[^\p{L}\p{N}@.]+/gu, "");
+}
+function splitRerankTerms(rawQuery) {
+  return rawQuery.split(/[^\p{L}\p{N}@.]+/u).map(normalizeForRerank).filter((term) => term.length >= 2);
+}
+function containsAllTerms(field, terms) {
+  return terms.length > 1 && terms.every((term) => field.includes(term));
+}
+function isBroadSingleAsciiTerm(rawQuery) {
+  return /^[a-z0-9]{1,4}$/.test(rawQuery.trim().toLowerCase());
+}
+function broadSingleTermTitleBoost(title, term) {
+  if (title === term) {
+    return BROAD_SINGLE_TERM_EXACT_TITLE_BOOST;
+  }
+  if (title.startsWith(term) || title.includes(`@ohos.${term}`)) {
+    return BROAD_SINGLE_TERM_PREFIX_TITLE_BOOST;
+  }
+  return 1;
+}
+function titleMatchBoost(row, rawQuery) {
+  const normalizedQuery = normalizeForRerank(rawQuery);
+  if (normalizedQuery.length < 2) {
+    return 1;
+  }
+  const title = normalizeForRerank(row.doc_title);
+  if (isBroadSingleAsciiTerm(rawQuery)) {
+    return broadSingleTermTitleBoost(title, normalizedQuery);
+  }
+  if (title.includes(normalizedQuery)) {
+    return TITLE_EXACT_MATCH_BOOST;
+  }
+  if (normalizedQuery.length >= TITLE_PREFIX_MIN_CHARS && title.includes(normalizedQuery.slice(0, TITLE_PREFIX_MIN_CHARS))) {
+    return TITLE_PREFIX_MATCH_BOOST;
+  }
+  const terms = splitRerankTerms(rawQuery);
+  if (containsAllTerms(title, terms)) {
+    return TITLE_TERMS_MATCH_BOOST;
+  }
+  return 1;
+}
+function applyTitleBoost(score, boost) {
+  if (boost <= 1) {
+    return score;
+  }
+  return score < 0 ? score * boost : score / boost;
+}
+function effectiveBm25Score(row, boosts, titleQuery, managerCompound) {
+  let score = row.bm25 / (boosts.get(row.catalog_id) ?? 1);
+  score = applyTitleBoost(score, titleMatchBoost(row, titleQuery));
+  if (managerCompound && rowMatchesManagerApiModule(
+    row.doc_title,
+    row.section_title,
+    managerCompound
+  )) {
+    score /= MANAGER_API_RERANK_BOOST;
+    if (row.catalog_id === CATALOG_NAME_TO_ID["harmonyos-references"]) {
+      score /= MANAGER_API_REFERENCE_EXTRA;
+    }
+  }
+  return score;
+}
+function minScoreRow(rows, boosts, titleQuery, managerCompound) {
+  return rows.reduce(
+    (best, row) => effectiveBm25Score(row, boosts, titleQuery, managerCompound) < effectiveBm25Score(best, boosts, titleQuery, managerCompound) ? row : best
+  );
+}
+function segmentMatchesApiSymbols(row, apiSymbols) {
+  return apiSymbols.some(
+    (symbol) => row.section_title.includes(symbol) || row.doc_title.includes(symbol)
+  );
+}
+function pickBestSegmentForDocument(segments, apiSymbols, boosts, titleQuery, managerCompound) {
+  if (managerCompound) {
+    const managerMatches = segments.filter(
+      (row) => rowMatchesManagerApiModule(
+        row.doc_title,
+        row.section_title,
+        managerCompound
+      )
+    );
+    if (managerMatches.length > 0) {
+      return minScoreRow(managerMatches, boosts, titleQuery, managerCompound);
+    }
+  }
+  if (apiSymbols.length > 0) {
+    const titleMatches = segments.filter(
+      (row) => segmentMatchesApiSymbols(row, apiSymbols)
+    );
+    if (titleMatches.length > 0) {
+      return minScoreRow(titleMatches, boosts, titleQuery, managerCompound);
+    }
+  }
+  return minScoreRow(segments, boosts, titleQuery, managerCompound);
+}
+function finalizeSearchRows(rows, rawQuery, titleQuery, limit, deprioritizeTailCatalogs) {
+  const boosts = inferCatalogBoosts(rawQuery);
+  const apiSymbols = extractQueryApiSymbolTokens(rawQuery);
+  const managerSplit = getManagerSplitApiCompound(rawQuery);
+  const managerCompound = managerSplit?.camelCase;
+  const byDocument = /* @__PURE__ */ new Map();
+  for (const row of rows) {
+    const segments = byDocument.get(row.document_id) ?? [];
+    segments.push(row);
+    byDocument.set(row.document_id, segments);
+  }
+  const representatives = [];
+  for (const segments of byDocument.values()) {
+    representatives.push(
+      pickBestSegmentForDocument(
+        segments,
+        apiSymbols,
+        boosts,
+        titleQuery,
+        managerCompound
+      )
+    );
+  }
+  const sorted = representatives.sort(
+    (left, right) => effectiveBm25Score(left, boosts, titleQuery, managerCompound) - effectiveBm25Score(right, boosts, titleQuery, managerCompound)
+  );
+  const ordered = deprioritizeTailCatalogs ? orderRowsWithTailCatalogsLast(sorted) : sorted;
+  return ordered.slice(0, limit);
+}
+function runFtsSearch(reader, catalog, limit, match, query, rawQuery) {
+  const catalogId = catalog ? CATALOG_NAME_TO_ID[catalog] : void 0;
+  const fetchLimit = Math.max(
+    limit,
+    limit * CATALOG_RERANK_POOL_FACTOR,
+    MIN_RERANK_FETCH_LIMIT
+  );
+  const rows = catalogId === void 0 ? reader.all(FTS_SEARCH_SQL, match, fetchLimit) : reader.all(
+    FTS_SEARCH_CATALOG_SQL,
+    match,
+    catalogId,
+    fetchLimit
+  );
+  const ranked = catalogId === void 0 ? finalizeSearchRows(rows, rawQuery, query, limit, true) : finalizeSearchRows(rows, rawQuery, query, limit, false);
+  return ranked.map((row) => ({
+    title: row.doc_title,
+    documentId: row.document_id,
+    sectionTitle: row.section_title || void 0,
+    snippet: extractSearchSnippet(row.lead_text, query, {
+      excerptTruncated: Boolean(row.excerpt_truncated)
+    })
+  }));
+}
+
+// src/doc-index/sqlite-schema.ts
+var SQLITE_INDEX_SCHEMA_SQL = `
+CREATE TABLE documents (
+  id INTEGER PRIMARY KEY,
+  document_id TEXT NOT NULL UNIQUE,
+  catalog_id INTEGER NOT NULL,
+  doc_title TEXT NOT NULL
+);
+
+CREATE TABLE segments (
+  id INTEGER PRIMARY KEY,
+  doc_id INTEGER NOT NULL REFERENCES documents(id),
+  section_title TEXT NOT NULL DEFAULT '',
+  lead_text TEXT NOT NULL DEFAULT '',
+  search_text TEXT NOT NULL,
+  excerpt_truncated INTEGER NOT NULL DEFAULT 0
+);
+
+CREATE VIRTUAL TABLE segments_fts USING fts5(
+  search_text,
+  content='segments',
+  content_rowid='id',
+  tokenize='unicode61'
+);
+
+CREATE TRIGGER segments_ai AFTER INSERT ON segments BEGIN
+  INSERT INTO segments_fts(rowid, search_text) VALUES (new.id, new.search_text);
+END;
+
+CREATE TRIGGER segments_ad AFTER DELETE ON segments BEGIN
+  INSERT INTO segments_fts(segments_fts, rowid, search_text) VALUES('delete', old.id, old.search_text);
+END;
+
+CREATE TRIGGER segments_au AFTER UPDATE ON segments BEGIN
+  INSERT INTO segments_fts(segments_fts, rowid, search_text) VALUES('delete', old.id, old.search_text);
+  INSERT INTO segments_fts(rowid, search_text) VALUES (new.id, new.search_text);
+END;
+
+CREATE INDEX segments_doc_id_idx ON segments(doc_id);
+`;
+
+// src/doc-index/sqlite-backend.ts
+var sqliteModulePromise = null;
+var cachedDb = null;
+var openChain = Promise.resolve();
+async function getSqliteModule() {
+  if (!sqliteModulePromise) {
+    sqliteModulePromise = (async () => {
+      const init = (await import("@sqlite.org/sqlite-wasm")).default;
+      return init();
+    })();
+  }
+  return sqliteModulePromise;
+}
+function createWasmReader(db) {
+  return {
+    all(sql, ...params) {
+      const stmt = db.prepare(sql);
+      if (params.length > 0) {
+        stmt.bind(params);
+      }
+      const rows = [];
+      while (stmt.step()) {
+        rows.push(stmt.get({}));
+      }
+      stmt.finalize();
+      return rows;
+    }
+  };
+}
+async function openReadonlyDbInner(dbPath) {
+  const fileStat = await stat(dbPath);
+  if (cachedDb && cachedDb.dbPath === dbPath && cachedDb.mtimeMs === fileStat.mtimeMs) {
+    return cachedDb.db;
+  }
+  cachedDb?.db.close();
+  const sqlite3 = await getSqliteModule();
+  const capi = sqlite3.capi;
+  const wasm = sqlite3.wasm;
+  const bytes = new Uint8Array(await readFile(dbPath));
+  const ptr = wasm.allocFromTypedArray(bytes);
+  let db;
+  let stored = false;
+  try {
+    db = new sqlite3.oo1.DB(":memory:");
+    const flags = capi.SQLITE_DESERIALIZE_READONLY | capi.SQLITE_DESERIALIZE_RESIZEABLE | capi.SQLITE_DESERIALIZE_FREEONCLOSE;
+    const rc = capi.sqlite3_deserialize(
+      db.pointer,
+      "main",
+      ptr,
+      bytes.byteLength,
+      bytes.byteLength,
+      flags
+    );
+    if (rc !== capi.SQLITE_OK) {
+      throw new Error(
+        `Failed to open readonly database: sqlite3_deserialize returned code ${rc} for: ${dbPath}`
+      );
+    }
+    cachedDb = { dbPath, mtimeMs: fileStat.mtimeMs, db };
+    stored = true;
+    return db;
+  } finally {
+    if (!stored) {
+      db?.close();
+      wasm.dealloc(ptr);
+    }
+  }
+}
+async function openReadonlyDb(dbPath) {
+  let release;
+  const previous = openChain;
+  openChain = new Promise((resolve3) => {
+    release = resolve3;
+  });
+  await previous;
+  try {
+    return await openReadonlyDbInner(dbPath);
+  } finally {
+    release();
+  }
+}
+function resetWasmCache() {
+  cachedDb?.db.close();
+  cachedDb = null;
+}
+async function insertIndexedBatch(db, insertSegment, getOrCreateDocId, batch) {
+  db.exec("BEGIN");
+  for (const row of batch) {
+    const docId = getOrCreateDocId(row.source);
+    insertSegment.bind([
+      docId,
+      row.source.sectionTitle,
+      row.source.leadText,
+      row.searchText,
+      row.source.excerptTruncated ? 1 : 0
+    ]);
+    insertSegment.step();
+    insertSegment.reset();
+  }
+  db.exec("COMMIT");
+}
+function createDocIdResolver(db, cache, insertDocument) {
+  return (source) => {
+    const cached = cache.get(source.documentId);
+    if (cached !== void 0) {
+      return cached;
+    }
+    const existing = db.selectValue(
+      "SELECT id FROM documents WHERE document_id = ?",
+      [source.documentId]
+    );
+    if (existing !== void 0 && existing !== null) {
+      const docId2 = Number(existing);
+      cache.set(source.documentId, docId2);
+      return docId2;
+    }
+    insertDocument.bind([source.documentId, source.catalogId, source.docTitle]);
+    insertDocument.step();
+    insertDocument.reset();
+    const docId = Number(db.selectValue("SELECT last_insert_rowid()"));
+    cache.set(source.documentId, docId);
+    return docId;
+  };
+}
+async function buildWasmIndex(dbPath, sources, onProgress) {
+  await getJieba();
+  const sqlite3 = await getSqliteModule();
+  const db = new sqlite3.oo1.DB(":memory:", "c");
+  db.exec(SQLITE_INDEX_SCHEMA_SQL);
+  const docIdCache = /* @__PURE__ */ new Map();
+  const insertDocument = db.prepare(
+    "INSERT INTO documents(document_id, catalog_id, doc_title) VALUES (?, ?, ?)"
+  );
+  const insertSegment = db.prepare(
+    "INSERT INTO segments(doc_id, section_title, lead_text, search_text, excerpt_truncated) VALUES (?, ?, ?, ?, ?)"
+  );
+  const getOrCreateDocId = createDocIdResolver(db, docIdCache, insertDocument);
+  const total = sources.length;
+  for (let i = 0; i < total; i += INSERT_BATCH_SIZE) {
+    const batch = sources.slice(i, i + INSERT_BATCH_SIZE);
+    const indexedBatch = await Promise.all(
+      batch.map(async (source) => ({
+        source,
+        searchText: await buildDocumentSearchText(source)
+      }))
+    );
+    await insertIndexedBatch(db, insertSegment, getOrCreateDocId, indexedBatch);
+    await onProgress?.(Math.min(i + batch.length, total), total);
+  }
+  db.exec("ANALYZE");
+  const exported = sqlite3.capi.sqlite3_js_db_export(db);
+  await writeFile(dbPath, exported);
+  db.close();
+  resetWasmCache();
+}
+async function searchWasmIndex(dbPath, catalog, limit, match, query, rawQuery) {
+  const db = await openReadonlyDb(dbPath);
+  return runFtsSearch(
+    createWasmReader(db),
+    catalog,
+    limit,
+    match,
+    query,
+    rawQuery
+  );
+}
+async function createSqliteBackend() {
+  await getSqliteModule();
+  return {
+    resetCache: resetWasmCache,
+    buildSearchIndex: buildWasmIndex,
+    searchIndex: (_keywords, catalog, limit, dbPath, match, query, rawQuery) => searchWasmIndex(dbPath, catalog, limit, match, query, rawQuery)
+  };
+}
+
+// src/doc-index/sqlite-backend-cache.ts
+var backendPromise = null;
+var activeBackend = null;
+async function getSqliteBackend() {
+  if (!backendPromise) {
+    backendPromise = createSqliteBackend().then((backend) => {
+      activeBackend = backend;
+      return backend;
+    });
+  }
+  return backendPromise;
+}
+function resetSqliteBackendCache() {
+  activeBackend?.resetCache();
+  backendPromise = null;
+  activeBackend = null;
+}
+
+// src/doc-index/sqlite-index.ts
+async function runSearch(keywords, catalog, limit, match, query, rawQuery, dbPath) {
+  const backend = await getSqliteBackend();
+  const resolvedDbPath = dbPath ?? getSearchDbFile();
+  return backend.searchIndex(
+    keywords,
+    catalog,
+    limit,
+    resolvedDbPath,
+    match,
+    query,
+    rawQuery
+  );
+}
+function resetSearchDbCache() {
+  resetSqliteBackendCache();
+}
+function mergeSearchResults(primary, secondary, limit) {
+  const seen = /* @__PURE__ */ new Set();
+  const merged = [];
+  for (const result of [...primary, ...secondary]) {
+    if (seen.has(result.documentId)) {
+      continue;
+    }
+    seen.add(result.documentId);
+    merged.push(result);
+    if (merged.length >= limit) {
+      break;
+    }
+  }
+  return merged;
+}
+function runPreparedMatch(keywords, catalog, limit, prepared, match, dbPath) {
+  return runSearch(
+    keywords,
+    catalog,
+    limit,
+    match,
+    prepared.expandedQuery,
+    prepared.rawQuery,
+    dbPath
+  );
+}
+async function searchWithAndFallback(keywords, catalog, limit, prepared, dbPath) {
+  const andResults = await runPreparedMatch(
+    keywords,
+    catalog,
+    limit,
+    prepared,
+    buildFtsMatch(prepared.tokens, "AND"),
+    dbPath
+  );
+  if (andResults.length >= limit) {
+    return andResults;
+  }
+  const orResults = await runPreparedMatch(
+    keywords,
+    catalog,
+    limit,
+    prepared,
+    buildFtsMatch(prepared.tokens, "OR"),
+    dbPath
+  );
+  return mergeSearchResults(andResults, orResults, limit);
+}
+async function searchWithPrepared(keywords, catalog, limit, prepared, dbPath) {
+  if (prepared.ftsMatch) {
+    return runPreparedMatch(
+      keywords,
+      catalog,
+      limit,
+      prepared,
+      prepared.ftsMatch,
+      dbPath
+    );
+  }
+  if (!prepared.preferAnd) {
+    return runPreparedMatch(
+      keywords,
+      catalog,
+      limit,
+      prepared,
+      buildFtsMatch(prepared.tokens, "OR"),
+      dbPath
+    );
+  }
+  return searchWithAndFallback(keywords, catalog, limit, prepared, dbPath);
+}
+async function searchWithReferencesGlobalFallback(keywords, limit, prepared, dbPath) {
+  const primary = await searchWithPrepared(
+    keywords,
+    "harmonyos-references",
+    limit,
+    prepared,
+    dbPath
+  );
+  if (primary.length >= limit) {
+    return primary;
+  }
+  const secondary = await searchWithPrepared(
+    keywords,
+    void 0,
+    limit,
+    prepared,
+    dbPath
+  );
+  return mergeSearchResults(primary, secondary, limit);
+}
+function applyTailCatalogOrderWhenGlobal(results, userCatalog) {
+  if (userCatalog !== void 0) {
+    return results;
+  }
+  return orderLocalResultsWithTailCatalogsLast(results);
+}
+async function searchSqliteIndex(keywords, catalog, limit = 10, dbPath) {
+  const prepared = await prepareSearchQuery(keywords);
+  if (shouldMergeReferencesWithGlobalFallback(prepared.rawQuery, catalog)) {
+    const merged = await searchWithReferencesGlobalFallback(
+      keywords,
+      limit,
+      prepared,
+      dbPath
+    );
+    return applyTailCatalogOrderWhenGlobal(merged, catalog);
+  }
+  const effectiveCatalog = catalog ?? inferSearchCatalog(prepared.rawQuery);
+  const results = await searchWithPrepared(
+    keywords,
+    effectiveCatalog,
+    limit,
+    prepared,
+    dbPath
+  );
+  return applyTailCatalogOrderWhenGlobal(results, catalog);
+}
+
+// src/init/doc-initializer.ts
+var DocNotReadyError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "DocNotReadyError";
+  }
+  code;
+};
+function sleep(ms) {
+  return new Promise((resolve3) => setTimeout(resolve3, ms));
+}
+async function attemptBundledInstall(docsZipSha256, spinner, message) {
+  spinner?.start(message);
+  await updateBuildStatus({
+    state: "installing",
+    phase: 1,
+    phaseLabel: "Installing index",
+    message
+  });
+  await installBundledIndex(docsZipSha256);
+  resetSearchDbCache();
+  if (spinner) {
+    spinner.text = "Documentation index installed.";
+  }
+}
+async function runBundledInstallPath(docsZipSha256, spinner) {
+  try {
+    await attemptBundledInstall(
+      docsZipSha256,
+      spinner,
+      "Installing documentation index\u2026"
+    );
+    await finalizeSuccess(spinner);
+    return true;
+  } catch (error) {
+    if (isDocStorageError(error)) {
+      throw error;
+    }
+  }
+  try {
+    await resetBundledInstallScratch();
+    resetSearchDbCache();
+    await attemptBundledInstall(
+      docsZipSha256,
+      spinner,
+      "Retrying documentation index install\u2026"
+    );
+    await finalizeSuccess(spinner);
+    return true;
+  } catch (error) {
+    if (isDocStorageError(error)) {
+      throw error;
+    }
+    return false;
+  }
+}
+async function finalizeSuccess(spinner) {
+  await updateBuildStatus({
+    state: "done",
+    phase: 3,
+    phaseLabel: "Done",
+    message: "Documentation ready.",
+    error: null
+  });
+  spinner?.succeed("Documentation ready.");
+}
+async function finalizeUpToDate(spinner) {
+  const meta = await readBuildMeta();
+  const message = meta ? `Documentation already up to date. Documents: ${meta.segmentCount.toLocaleString()}` : "Documentation already up to date.";
+  spinner?.succeed(message);
+  await updateBuildStatus({
+    state: "done",
+    message,
+    error: null
+  });
+}
+async function handleInitError(error, spinner) {
+  const message = error instanceof Error ? error.message : String(error);
+  await updateBuildStatus({ state: "error", error: message });
+  spinner?.fail(message);
+  throw error;
+}
+async function ensureBuildLockFile() {
+  const indexDir = getIndexDir();
+  await fs9.promises.mkdir(indexDir, { recursive: true });
+  const lockPath = getBuildLockFile();
+  if (!fs9.existsSync(lockPath)) {
+    await fs9.promises.writeFile(lockPath, "", "utf-8");
+  }
+  return lockPath;
+}
+async function acquireBuildLock() {
+  const lockPath = await ensureBuildLockFile();
+  return lockfile.lock(lockPath, { stale: 30 * 60 * 1e3 });
+}
+async function resolveDocsZipSha256() {
+  const zipPath = findDocsZip();
+  const docsZipSha256 = (zipPath ? await sha256File(zipPath) : null) ?? await getBundledDocsZipSha256();
+  if (!docsZipSha256) {
+    throw new Error("docs.zip not found");
+  }
+  return docsZipSha256;
+}
+async function runInitPipeline(options, spinner) {
+  const docsZipSha256 = await resolveDocsZipSha256();
+  const shouldInstall = options.force || await needsIndexInstall(options.force);
+  const rebuildReason = await needsRebuildIndex(options.force);
+  if (!shouldInstall && !rebuildReason && isIndexReady()) {
+    await finalizeUpToDate(spinner);
+    return;
+  }
+  if (isBundledIndexUsable(docsZipSha256) && await runBundledInstallPath(docsZipSha256, spinner)) {
+    return;
+  }
+  throw new Error(
+    "Documentation index bundle is unavailable or corrupted. Reinstall the package with: npm uninstall -g @deveco/deveco-cli && npm install -g <package.tgz>"
+  );
+}
+var DocInitializer = class {
+  static async run(options = {}) {
+    const background = options.background ?? false;
+    const quiet = options.quiet ?? background;
+    const spinner = quiet ? void 0 : ora({ text: "Checking documentation\u2026", color: "cyan" });
+    let release;
+    try {
+      if (!options.assumeStorageSafe) {
+        await assertDocStorageSafe({ mode: "write" });
+      }
+      release = await acquireBuildLock();
+      await writeBuildStatus(
+        createInitialStatus("Starting documentation setup\u2026")
+      );
+      await runInitPipeline(options, spinner);
+    } catch (error) {
+      if (release) {
+        await handleInitError(error, spinner);
+      }
+      throw error;
+    } finally {
+      if (release) {
+        await release();
+      }
+    }
+  }
+};
+async function pollUntilReady(spinner) {
+  while (true) {
+    const status = await readBuildStatus();
+    if (status.state === "done" && isIndexReady()) {
+      return;
+    }
+    if (status.state === "error") {
+      throw new DocNotReadyError(
+        "build-failed",
+        status.error ?? "Documentation setup failed. Try your docs command again in a moment."
+      );
+    }
+    spinner.text = status.message || "Documentation is being prepared\u2026";
+    await sleep(500);
+  }
+}
+async function runSetup(spinner, force = false) {
+  spinner.text = force ? "Repairing documentation index\u2026" : "Starting documentation setup\u2026";
+  await DocInitializer.run({ builtBy: "doc-init", force, quiet: true });
+}
+async function ensureIndexReady() {
+  const rebuildNeeded = await needsRebuildIndex() !== null;
+  if (isIndexReady() && !rebuildNeeded) {
+    return;
+  }
+  const spinner = ora({
+    text: "Documentation is being prepared\u2026",
+    color: "cyan"
+  }).start();
+  try {
+    if (await isBuildInProgress()) {
+      await pollUntilReady(spinner);
+      spinner.succeed("Documentation ready.");
+      return;
+    }
+    if (await needsIndexInstall()) {
+      await runSetup(spinner);
+      spinner.succeed("Documentation ready.");
+      return;
+    }
+    await runSetup(spinner, true);
+    spinner.succeed("Documentation ready.");
+  } catch (error) {
+    spinner.fail(error.message);
+    throw error;
+  }
+}
+async function awaitDocReady() {
+  await assertDocStorageSafe({ mode: "read" });
+  await ensureIndexReady();
+}
+
+// src/service/local-doc-service.ts
+function isCorruptSearchIndexError(error) {
+  const message = error instanceof Error ? error.message : String(error);
+  return /file is not a database|database disk image is malformed|SQLITE_CORRUPT/i.test(
+    message
+  );
+}
+var LocalDocService = class {
+  async search(keywords, catalog, limit = 10) {
+    await awaitDocReady();
+    try {
+      return await searchSqliteIndex(keywords, catalog, limit);
+    } catch (error) {
+      if (!isCorruptSearchIndexError(error)) {
+        throw error;
+      }
+      resetSearchDbCache();
+      await DocInitializer.run({
+        builtBy: "doc-init",
+        force: true,
+        quiet: true,
+        assumeStorageSafe: true
+      });
+      return searchSqliteIndex(keywords, catalog, limit);
+    }
+  }
+  async readDocument(relativePath) {
+    return readMarkdownFromDocsZip(relativePath);
+  }
+};
+var localDocService = new LocalDocService();
+
+// src/engine.ts
+var apiVersion = 1;
+async function createDocsEngine(options) {
+  setCacheDir(options.cacheDir);
+  return {
+    async search(request) {
+      await awaitDocReady();
+      const catalog = request.catalog ? request.catalog : void 0;
+      return localDocService.search(
+        request.keywords,
+        catalog,
+        request.limit ?? 10
+      );
+    },
+    async read(request) {
+      return localDocService.readDocument(request.relativePath);
+    },
+    async catalog() {
+      return CATALOG_NAMES.map((name, index) => ({
+        nodeId: name,
+        nodeName: CATALOG_TITLES[name],
+        relateDocument: "",
+        isLeaf: true,
+        parent: "",
+        children: [],
+        catalogIndex: index
+      }));
+    },
+    async close() {
+      resetSqliteBackendCache();
+      resetSearchDbCache();
+      resetDocsZipReaderCache();
+    }
+  };
+}
+export {
+  CATALOG_NAMES,
+  CATALOG_TITLES,
+  QUERY_MAX_RAW_CHARS,
+  apiVersion,
+  assertDocStorageSafe,
+  createDocsEngine,
+  isDocStorageError
+};