@oniroproject/oniro-app 0.18.0 → 0.19.0

package/README.md

@@ -387,6 +387,35 @@ The SDK is `--sdk <dir>`, else `<sdk home>/<--api>`, else the one the project's
 | `--no-other-sdks` | `show` only: on a miss, do not look in the other installed SDKs. |
 | `--json` | `search`: `sdk` (`dir`, `api`, `version`, `source`), `query`, `total`, `hits` (the fields above as `name`, `qualifiedName`, `kind`, `kit`, `import`, `global`, `module`, `since`, `sinceText`, `deprecated`, `deprecatedSince`, `useInstead`, `syscap`, `systemApi`, `file`, `path`, `line`, `signature`, `doc`, `overloads`, `score`). `show`: `sdk`, `symbol`, `found`, `entries`, and on a miss `alsoIn` (`[{ api, since }]`) and `suggestions`. |
 
+#### `docs sync` / `docs search` / `docs show` — read the OpenHarmony documentation
+
+The application-development documentation of the OpenHarmony release matching the SDK (`en/application-dev` of [gitcode.com/openharmony/docs](https://gitcode.com/openharmony/docs)): usage guides (ArkUI components, navigation, state management, data storage, abilities), kit API prose, the business error codes each kit throws and platform behaviour (lifecycle, permissions, threads). `api search` says whether a symbol exists and with what signature; this says how it is used.
+
+- `docs sync` clones the release's tree once: a partial, sparse clone without figures, about 100 MB (a plain clone of the tree is 2 GB), under `<sdkRootDir>/docs/<branch>` (`ONIRO_DOCS_DIR`). The branch comes from the SDK's version (`6.1.0.31` → `OpenHarmony-6.1-Release`, `5.1.0.107` → `OpenHarmony-5.1.0-Release`) or `--ref`. A second `sync` brings the clone up to date. Needs `git`.
+- `docs search <query...>` ranks documents that contain every word (any word when none does) by where the words occur: title, headings, path, body; a camelCase or dotted identifier also matches by its parts (`NavPathStack` → nav, path, stack, weighing less). A document whose title is exactly a query word, or that holds the whole query in a title or heading, ranks higher; the generated API reference a little below the guides; system-API pages and tables of contents below everything. Each hit prints the path, the title, the matching sections with their line numbers and the first line. Exits 1 when nothing matches. The index is built in memory on first use (about 3 s for 5,000 documents) and answers in milliseconds.
+- `docs show <path>` prints one document (a path `search` printed, relative to `en/application-dev`), or one section of it with `--heading` (a heading or a distinctive part of it, case-insensitive: from that heading to the next of the same or a higher level). Image lines and inline HTML are dropped; a long document is cut at `--lines` (default 250) with the list of its sections, so ask for a heading rather than the whole file. Exits 1 when the document or heading does not exist, suggesting close paths or the document's headings.
+
+```
+$ oniro-app docs search --api 23 relationalStore insert
+reference/apis-arkdata/arkts-apis-data-relationalStore-RdbStore.md  —  Interface (RdbStore)
+  sections: "insert" (line 94), "insert10+" (line 178), "insertSync12+" (line 443), …
+  Provides APIs for managing data in an RDB store.
+…
+$ oniro-app docs show --api 23 reference/apis-arkdata/errorcode-data-rdb.md --heading 14800011
+## 14800011 Database File Corrupted
+…
+```
+
+| Flag | Description |
+| --- | --- |
+| `--api <level>` / `--sdk <dir>` / `--project <dir>` | The SDK whose release picks the docs, as for `api search`. |
+| `--ref <branch>` | A docs branch or tag (`OpenHarmony-6.1-Release`, `master`) instead of the SDK-chosen one. |
+| `--limit <n>` | `search` only: at most n hits (default 8). |
+| `--section <dir>` | `search` only: only documents under this subtree (`ui`, `database`, `reference/errorcodes`, `application-models`). |
+| `--heading <text>` | `show` only: only that section. |
+| `--lines <n>` | `show` only: at most n lines (default 250). |
+| `--json` | `sync`: `docs` (`ref`, `dir`, `tree`, `sdk`), `files`, `updated`, `commit`. `search`: `docs`, `query`, `terms`, `total`, `hits` (`path`, `title`, `score`, `headings` `[{ line, text }]`, `snippet`). `show`: `docs`, `found`, `path`, `text`, `truncated`, `lines`, `headings`; on a miss `error` and `suggestions`. |
+
 #### `lint` — run the OpenHarmony codelinter
 
 `lint [project-dir]` (defaults to the current directory). Prints each finding as `file:line:col severity message [rule]`, then the totals (`N defects: E errors, W warnings, S suggestions.`). Exits 1 on error-severity findings or when codelinter fails to produce a report; warnings alone exit 0, although codelinter itself exits 1 for them. When codelinter says its report is incomplete, for example because the command-line tools' flavour (see `cmdtools status`) does not match the project's `runtimeOS`, it exits 2: it skipped checks, so a clean report is not evidence of clean code. Its notices, and a hint when the flavour is the cause, go to stderr.
@@ -1005,10 +1034,12 @@ Tools (the inputs are the command's flags in camelCase, with the same defaults;
 | `screens` | `screens --json` | `project` |
 | `api_search` | `api search --json` | `query` (required), `kit`, `kind[]`, `lang`, `limit`, `deprecated`, `systemapi`, `api`, `sdk`, `project`, `rebuild` |
 | `api_show` | `api show --json` | `symbol` (required), `kit`, `otherSdks`, `api`, `sdk`, `project`, `rebuild` |
+| `docs_search` | `docs search --json` | `query` (required), `limit`, `section`, `api`, `sdk`, `ref`, `project` |
+| `docs_show` | `docs show --json` | `path` (required), `heading`, `maxLines`, `api`, `sdk`, `ref`, `project` |
 | `doctor` | `doctor --json` | `project`, `fix`, `device` (boolean, as `--no-device`), `serial`, `arktsCheck` |
 | `devices` | `devices --json` | `long`; the array comes wrapped as `{ "devices": [...] }` |
 
-- **Errors.** A tool result has `isError: true` when the command would exit non-zero: a failed build, `check_arkts` with an error or one that could not run, a failed or incomplete test run, a failed smoke check, a `perf_trace` threshold exceeded or capture failed, an `api_show` miss or an `api_search` without hits, a failing `doctor` check, or a tool that threw (no device, a timeout, bad arguments). The JSON is still there to read. `logs_crash` is not an error when there was no crash; check `crashed`. JSON-RPC errors are kept for protocol problems (an unknown tool or method).
+- **Errors.** A tool result has `isError: true` when the command would exit non-zero: a failed build, `check_arkts` with an error or one that could not run, a failed or incomplete test run, a failed smoke check, a `perf_trace` threshold exceeded or capture failed, an `api_show` miss or an `api_search` without hits, a `docs_search` without hits, a `docs_show` of a missing document or heading, or either when the release's docs are not synced (the text says to run `docs sync`), a failing `doctor` check, or a tool that threw (no device, a timeout, bad arguments). The JSON is still there to read. `logs_crash` is not an error when there was no crash; check `crashed`. JSON-RPC errors are kept for protocol problems (an unknown tool or method).
 - **Images.** `screenshot` returns the capture as an `image/jpeg` content block downscaled to `maxDim` (with `grid`, the 10x10 coordinate grid), plus its dimensions as JSON; `crop` and `target*` return a full-resolution crop, `contactSheet` the tiled burst, `diff` the comparison and the current screen. `output` also writes the image to a file (with `diff`, the full-resolution capture, usable as a later baseline).
 - **Layouts.** `dump_layout` without `flat` or `summary` returns the whole tree; `flat` (text) is the cheap way to read a screen. `output` saves what is returned, so `{ "output": "before.json" }` then `{ "diff": "before.json" }` compares two moments.
 

package/dist/oniro-app.js

@@ -2,7 +2,7 @@
 
 // src/bin/oniro-app.ts
 import { Command as Command11, CommanderError } from "commander";
-import { OniroError as OniroError6 } from "@oniroproject/core";
+import { OniroError as OniroError7 } from "@oniroproject/core";
 
 // src/commands/sdk.ts
 import * as fs from "fs";
@@ -80,7 +80,8 @@ var ENV_VAR_BY_KEY = {
   harmonyosSdkPath: "ONIRO_HARMONYOS_SDK_PATH",
   harmonyosAuthDir: "ONIRO_HARMONYOS_AUTH_DIR",
   harmonyosSigningDir: "ONIRO_HARMONYOS_SIGNING_DIR",
-  cacheDir: "ONIRO_CACHE_DIR"
+  cacheDir: "ONIRO_CACHE_DIR",
+  docsDir: "ONIRO_DOCS_DIR"
 };
 function createEnvConfig(env = process.env) {
   return {
@@ -3222,10 +3223,160 @@ function registerApiCommand(program) {
   });
 }
 
+// src/commands/docs.ts
+import {
+  DocsIndex,
+  docsDirFor,
+  docsRefFor,
+  docsTree,
+  readSdkRelease,
+  syncDocs,
+  OniroError as OniroError5
+} from "@oniroproject/core";
+function selectDocs(opts) {
+  const { config, logger } = getRuntime();
+  if (opts.ref) return { ref: opts.ref, dir: docsDirFor(config, opts.ref) };
+  const api = opts.api !== void 0 ? Number(opts.api) : void 0;
+  let sel;
+  try {
+    sel = selectSdk(opts);
+  } catch (err) {
+    if (api === void 0 || !Number.isInteger(api) || api <= 0) throw err;
+    const ref2 = docsRefFor({ api });
+    logger.warn(`The API ${api} SDK is not installed; taking the ${ref2} docs for it.`);
+    return { ref: ref2, dir: docsDirFor(config, ref2), sdk: { api } };
+  }
+  const release = readSdkRelease(sel.sdkDir);
+  const ref = docsRefFor({ api: release.api ?? sel.api, version: release.version });
+  return { ref, dir: docsDirFor(config, ref), sdk: { dir: sel.sdkDir, api: release.api ?? sel.api, version: release.version } };
+}
+function docsJson(sel, tree) {
+  return { ref: sel.ref, dir: sel.dir, tree, sdk: sel.sdk };
+}
+function openDocs(sel) {
+  const tree = docsTree(sel.dir);
+  if (!tree) {
+    const flag = sel.sdk?.api !== void 0 ? ` --api ${sel.sdk.api}` : sel.ref ? ` --ref ${sel.ref}` : "";
+    throw new OniroError5(
+      `The ${sel.ref} docs are not synced (no ${sel.dir}). Run \`oniro-app docs sync${flag}\` first (a partial clone of gitcode.com/openharmony/docs, about 100 MB).`
+    );
+  }
+  return { tree, index: DocsIndex.load(tree) };
+}
+function runDocsSearch(query, opts) {
+  const sel = selectDocs(opts);
+  const { tree, index } = openDocs(sel);
+  const limit = opts.limit !== void 0 ? Number(opts.limit) : void 0;
+  if (limit !== void 0 && (!Number.isInteger(limit) || limit <= 0)) {
+    throw new OniroError5(`--limit expects a positive number, got "${opts.limit}".`);
+  }
+  const result = index.search(query, { limit, section: opts.section });
+  return { json: { docs: docsJson(sel, tree), ...result }, result, tree };
+}
+function runDocsShow(docPath, opts) {
+  const sel = selectDocs(opts);
+  const { tree, index } = openDocs(sel);
+  const maxLines = opts.lines !== void 0 ? Number(opts.lines) : void 0;
+  if (maxLines !== void 0 && (!Number.isInteger(maxLines) || maxLines <= 0)) {
+    throw new OniroError5(`--lines expects a positive number, got "${opts.lines}".`);
+  }
+  const result = index.show(docPath, { heading: opts.heading, maxLines });
+  return { json: { docs: docsJson(sel, tree), ...result }, result, tree };
+}
+async function runDocsSync(opts) {
+  const { logger } = getRuntime();
+  const sel = selectDocs(opts);
+  const result = await syncDocs({ ref: sel.ref, dir: sel.dir, logger });
+  const tree = docsTree(sel.dir);
+  if (tree) DocsIndex.forget(tree);
+  return { json: { docs: docsJson(sel, tree ?? sel.dir), sdk: sel.sdk, ...result }, result, sel };
+}
+function formatDocHit(h) {
+  const lines = [`${h.path}  \u2014  ${h.title}`];
+  if (h.headings.length) lines.push(`  sections: ${h.headings.map((x) => `"${x.text}" (line ${x.line})`).join(", ")}`);
+  if (h.snippet) lines.push(`  ${h.snippet}`);
+  return lines.join("\n");
+}
+function registerDocsCommand(program) {
+  const docs = program.command("docs").description(
+    "Search the OpenHarmony application-development documentation (gitcode.com/openharmony/docs, `en/application-dev`) of the release matching the SDK: usage guides, kit API prose, business error codes and platform behaviour, which the SDK typings behind `api search` do not say. `docs sync` clones the release's tree once (a partial, sparse clone without figures, about 100 MB) under <sdkRootDir>/docs (ONIRO_DOCS_DIR)."
+  );
+  const docsOptions = (cmd) => cmd.option(
+    "--api <level>",
+    "The SDK API level whose release picks the docs. Default: the project's compileSdkVersion (from the current directory or --project), else the newest installed SDK."
+  ).option("--sdk <dir>", "An SDK API directory (holding ets/) whose version picks the docs.").option("--project <dir>", "The project whose compileSdkVersion picks the SDK (default: the current directory).").option("--ref <branch>", "A docs branch or tag (`OpenHarmony-6.1-Release`, `master`) instead of the SDK-chosen one.");
+  docsOptions(
+    docs.command("sync").description(
+      "Clone the docs of the release matching the SDK (6.1.0.x \u2192 OpenHarmony-6.1-Release), or bring an existing clone up to date. Needs git."
+    )
+  ).option("--json", "Print JSON: docs (ref, dir, tree, sdk), files, updated, commit.").action(async (opts) => {
+    const { json, result, sel } = await runDocsSync(opts);
+    if (opts.json) process.stdout.write(`${JSON.stringify(json, null, 2)}
+`);
+    else {
+      process.stdout.write(
+        `${result.updated ? "Updated" : "Cloned"} the ${sel.ref} docs${result.commit ? ` (${result.commit})` : ""}: ${result.files} documents in ${result.dir}
+`
+      );
+    }
+  });
+  docsOptions(
+    docs.command("search <query...>").description(
+      "Ranked search: documents containing every word (any word when none does), scored by where the words occur (title, headings, path, body); a camelCase or dotted identifier also matches by its parts. Each hit names the sections that match, to read with `docs show`. Exits 1 when nothing matches."
+    )
+  ).option("--limit <n>", "At most n hits.", "8").option("--section <dir>", "Only documents under this subtree: `ui`, `database`, `reference/errorcodes`, `application-models`.").option("--json", "Print JSON: docs (ref, dir, tree, sdk), query, terms, total, hits (path, title, score, headings, snippet).").action((words, opts) => {
+    const { json, result, tree } = runDocsSearch(words.join(" "), opts);
+    if (opts.json) {
+      process.stdout.write(`${JSON.stringify(json, null, 2)}
+`);
+    } else {
+      for (const h of result.hits) process.stdout.write(`${formatDocHit(h)}
+
+`);
+      const shown = result.hits.length < result.total ? `${result.hits.length} of ${result.total}` : `${result.total}`;
+      process.stdout.write(
+        result.total ? `${shown} document${result.total === 1 ? "" : "s"} match; paths are relative to ${tree}.
+` : "No document matches; try fewer or different words (component or kit names, decorators, an error code).\n"
+      );
+    }
+    process.exitCode = result.total ? 0 : 1;
+  });
+  docsOptions(
+    docs.command("show <path>").description(
+      "One document (a path `docs search` printed, relative to en/application-dev), or one section of it by heading. Images and inline HTML are dropped; long documents are cut at --lines with a list of their sections. Exits 1 when the document or heading does not exist, suggesting close paths or the headings."
+    )
+  ).option("--heading <text>", "A heading (or a distinctive part of it, case-insensitive): only that section.").option("--lines <n>", "At most n lines (default 250).").option(
+    "--json",
+    "Print JSON: docs (ref, dir, tree, sdk), found, path, text, truncated, lines, headings; on a miss error and suggestions."
+  ).action((docPath, opts) => {
+    const { json, result } = runDocsShow(docPath, opts);
+    if (opts.json) {
+      process.stdout.write(`${JSON.stringify(json, null, 2)}
+`);
+    } else if (result.found) {
+      process.stdout.write(`${result.text}
+`);
+      if (!opts.heading && result.headings.length) {
+        process.stdout.write(`
+[sections: ${result.headings.slice(0, 40).map((h) => h.text).join(" | ")}]
+`);
+      }
+    } else {
+      process.stdout.write(`${result.error}
+`);
+      if (result.suggestions.length) {
+        process.stdout.write(`  ${opts.heading ? "headings" : "close paths"}: ${result.suggestions.join(" | ")}
+`);
+      }
+    }
+    process.exitCode = result.found ? 0 : 1;
+  });
+}
+
 // src/commands/serve.ts
 import * as fs10 from "fs";
 import * as path19 from "path";
-import { OniroError as OniroError5 } from "@oniroproject/core";
+import { OniroError as OniroError6 } from "@oniroproject/core";
 
 // src/mcp/protocol.ts
 import * as readline2 from "readline";
@@ -4488,6 +4639,76 @@ var apiShow = {
     return jsonResult(run.json, !run.found);
   }
 };
+var DOCS_PROPS = {
+  api: int("The SDK API level whose release picks the docs (default: the project's compileSdkVersion, else the newest installed SDK)."),
+  sdk: str("An SDK API directory (holding ets/) whose version picks the docs."),
+  ref: str("A docs branch or tag (`OpenHarmony-6.1-Release`, `master`) instead of the SDK-chosen one."),
+  ...PROJECT
+};
+function docsOpts(a, ctx) {
+  return {
+    api: a.api !== void 0 ? String(a.api) : void 0,
+    sdk: pathArg(a, "sdk", ctx),
+    ref: a.ref,
+    project: projectOf(a, ctx)
+  };
+}
+var docsSearch = {
+  name: "docs_search",
+  title: "Search the OpenHarmony docs",
+  description: "Ranked search of the OpenHarmony application-development documentation of the release matching the SDK (`oniro-app docs search --json`): usage guides (ArkUI components, navigation, state management, data storage, abilities), kit API prose, business error codes and platform behaviour, which the SDK typings behind api_search do not say. Documents containing every word rank by where the words occur (title, headings, path, body); each hit names the matching sections, to read with docs_show. Use domain words (a component, kit or decorator name, an error code), not sentences. Returns docs (ref, dir, tree, sdk), query, terms, total, hits (path, title, score, headings [{line, text}], snippet). isError when nothing matches, or when the docs are not synced (`oniro-app docs sync`).",
+  inputSchema: object(
+    {
+      query: str('The search words, e.g. "LazyForEach reuse", "relationalStore insert", "14800011".'),
+      limit: int("At most n hits.", { minimum: 1, maximum: 30, default: 8 }),
+      section: str("Only documents under this subtree: `ui`, `database`, `reference/errorcodes`, `application-models`."),
+      ...DOCS_PROPS
+    },
+    ["query"]
+  ),
+  annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+  changesDevice: false,
+  async call(a, ctx) {
+    try {
+      const run = runDocsSearch(a.query, {
+        ...docsOpts(a, ctx),
+        limit: a.limit !== void 0 ? String(a.limit) : void 0,
+        section: a.section
+      });
+      return jsonResult(run.json, run.result.total === 0);
+    } catch (err) {
+      return errorResult(message(err));
+    }
+  }
+};
+var docsShow = {
+  name: "docs_show",
+  title: "Read one OpenHarmony doc",
+  description: "One documentation file (a path docs_search returned, relative to en/application-dev), or one section of it by heading (`oniro-app docs show --json`). Images and inline HTML are dropped; a long document is cut at maxLines with the list of its sections, so ask for a heading rather than the whole file. Returns docs, found, path, text, truncated, lines, headings; isError with suggestions (close paths, or the headings when the heading did not match).",
+  inputSchema: object(
+    {
+      path: str("The document path, e.g. `ui/arkts-navigation-jump.md`."),
+      heading: str("A heading (or a distinctive part of it, case-insensitive): only that section."),
+      maxLines: int("At most n lines.", { minimum: 20, maximum: 1200, default: 250 }),
+      ...DOCS_PROPS
+    },
+    ["path"]
+  ),
+  annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+  changesDevice: false,
+  async call(a, ctx) {
+    try {
+      const run = runDocsShow(a.path, {
+        ...docsOpts(a, ctx),
+        heading: a.heading,
+        lines: a.maxLines !== void 0 ? String(a.maxLines) : void 0
+      });
+      return jsonResult(run.json, !run.result.found);
+    } catch (err) {
+      return errorResult(message(err));
+    }
+  }
+};
 var doctor = {
   name: "doctor",
   title: "Check the toolchain",
@@ -4552,6 +4773,8 @@ var ALL_TOOLS = [
   screens,
   apiSearch,
   apiShow,
+  docsSearch,
+  docsShow,
   doctor,
   devices
 ];
@@ -4568,7 +4791,7 @@ function selectTools(names, readOnly) {
 function parseToolList(raw) {
   if (raw === void 0) return void 0;
   const names = raw.split(",").map((s) => s.trim()).filter(Boolean);
-  if (!names.length) throw new OniroError5("--tools needs at least one tool name.");
+  if (!names.length) throw new OniroError6("--tools needs at least one tool name.");
   return names;
 }
 function instructions(ctx, toolCount) {
@@ -4581,9 +4804,9 @@ function registerServeCommand(program) {
   ).allowExcessArguments(false).option("--project <dir>", "Project the tools work on unless a call names another (default: the current directory).").option("--device <serial>", "Device the tools target unless a call names another (default: the only connected one).").option("--tools <list>", `Expose only these tools, comma-separated (of ${TOOL_NAMES.join(", ")}).`).option("--read-only", "Leave out the tools that change the device: apply, launch, input, test.").action(async (opts) => {
     const { logger } = getRuntime();
     const projectDir = path19.resolve(opts.project ?? process.cwd());
-    if (!fs10.existsSync(projectDir)) throw new OniroError5(`--project ${projectDir} does not exist.`);
+    if (!fs10.existsSync(projectDir)) throw new OniroError6(`--project ${projectDir} does not exist.`);
     const tools = selectTools(parseToolList(opts.tools), !!opts.readOnly);
-    if (!tools.length) throw new OniroError5("No tool left to serve: --read-only removed every tool --tools named.");
+    if (!tools.length) throw new OniroError6("No tool left to serve: --read-only removed every tool --tools named.");
     const context = { projectDir, deviceSerial: opts.device };
     const server = new McpServer({
       name: "oniro-app",
@@ -4728,7 +4951,7 @@ function registerReplayCommand(program) {
 }
 
 // src/bin/oniro-app.ts
-var CLI_VERSION = "0.18.0";
+var CLI_VERSION = "0.19.0";
 function buildProgram() {
   const program = new Command11().name("oniro-app").description(
     "Cross-platform CLI for Oniro/OpenHarmony app development.\n\nDesigned for non-interactive use (CI, scripts, agents): every command\ntakes explicit flags, results go to stdout, progress/logs go to stderr,\nand a non-zero exit code indicates failure."
@@ -4754,6 +4977,7 @@ function buildProgram() {
   registerDoctorCommand(program);
   registerScreensCommand(program);
   registerApiCommand(program);
+  registerDocsCommand(program);
   registerTestCommand(program);
   registerInputCommand(program);
   registerRecordCommand(program);
@@ -4773,7 +4997,7 @@ async function main() {
       process.exitCode = err.exitCode;
       return;
     }
-    const message2 = err instanceof OniroError6 ? err.message : err instanceof Error ? err.message : String(err);
+    const message2 = err instanceof OniroError7 ? err.message : err instanceof Error ? err.message : String(err);
     const stack = process.env.ONIRO_DEBUG === "1" && err instanceof Error && err.stack ? `${err.stack}
 ` : "";
     process.stderr.write(`[error] ${message2}