ohpm-search

CLI and SDK for searching OpenHarmony third-party packages from the OHPM registry.

Requirements

• Node.js >= 18

Install

cd ohpm-search
npm install
npm run build
npm link   # optional: install `ohpm-search` globally

Commands

search

Search packages by keyword. Queries the OHPM registry first; when the registry returns no results, automatically falls back to the landscape tech map (/ohpm/tech-map).

ohpm-search search lottie
ohpm-search search hypium --limit 5 --sort popularity
ohpm-search search 基础语音服务          # may hit landscape fallback
ohpm-search --json --fields name,latestVersion,installCommand search axios
ohpm-search search foo --no-fallback    # registry only, skip landscape

Landscape fallback notes:

• JSON meta.source is registry or landscape; landscape hits also include meta.landscapeUrl.
• Landscape rows may have no latestVersion; installCommand is then ohpm install <name> without @version. Run resolve or info next for versioned metadata.
• Matching is case-insensitive substring search on package name and keywords (same idea as the landscape web UI).

info

Show package metadata.

ohpm-search info @ohos/hypium
ohpm-search info @ohos/[email protected]
ohpm-search --json info @ohos/hypium

readme

Fetch package README content.

ohpm-search readme @ohos/hypium
ohpm-search readme @ohos/hypium --lang en
ohpm-search readme @ohos/hypium --max-chars 4000

Without --max-chars, the full README is returned.

resolve

Resolve package metadata and README in one call. Recommended for agents.

ohpm-search resolve @ohos/lottie
ohpm-search resolve @ohos/lottie --lang en --max-chars 3000
ohpm-search resolve @ohos/lottie --no-readme

Without --max-chars, the full README summary is returned.

Global options

| Option | Description | |--------|-------------| | --registry <url> | OHPM registry URL (default: https://ohpm.openharmony.cn) | | --json | Force JSON output | | --format json\|text | Output format (non-TTY defaults to JSON) | | --fields a,b,c | Pick JSON fields | | --quiet | Suppress error output | | --timeout <ms> | Request timeout (default: 15000) | | --retry <count> | Retry count on failure (default: 2) | | --help-json | Print machine-readable command schema |

search options

| Option | Description | |--------|-------------| | --no-fallback | Disable landscape fallback when registry returns no results (default: fallback enabled) |

Landscape disk cache

Fallback downloads the tech map once and caches it on disk for 8 hours (per registry URL):

| Variable | Description | |----------|-------------| | OHPM_SEARCH_LANDSCAPE_CACHE=0 | Disable disk cache | | OHPM_SEARCH_CACHE_DIR | Override cache root (default: ~/.cache/ohpm-search/) | | XDG_CACHE_HOME | Used when OHPM_SEARCH_CACHE_DIR is unset |

JSON envelope

Success:

{
  "ok": true,
  "command": "search",
  "data": {},
  "meta": {}
}

Failure:

{
  "ok": false,
  "command": "info",
  "error": {
    "code": "PACKAGE_NOT_FOUND",
    "message": "Package not found: @ohos/missing"
  }
}

Exit codes

| Code | Meaning | |------|---------| | 0 | Success | | 1 | General error | | 2 | Validation error | | 3 | Package or README not found | | 4 | Network or API error |

Agent workflow

Cursor agents: see skills/ohpm-search/SKILL.md for the preferred skill workflow.

Use this workflow when an agent needs to find, evaluate, or install an OpenHarmony third-party package.

Non-interactive runs (pipes, CI, agents) default to JSON output. You can also force it with:

export OHPM_SEARCH_FORMAT=json

Decision guide

| Situation | Preferred command | |-----------|-------------------| | Package name is unknown | search first | | Package name is known | resolve | | Need full README after resolve | readme --max-chars <n> | | Only need metadata, no README | resolve --no-readme or info |

Preferred workflow

flowchart TD
  A[Need a third-party package] --> B{Know exact package name?}
  B -->|No| C["search <keyword> --limit 5"]
  C --> D[Pick best match from data.rows]
  D --> E["resolve <package> --max-chars 4000"]
  B -->|Yes| E
  E --> F{Enough detail to install?}
  F -->|Yes| G[Use installCommand from response]
  F -->|No| H["readme <package> --max-chars 4000"]
  H --> G

Step 1: Discover packages

When the exact scoped name is unknown, search with a small page size and only the fields needed for ranking:

ohpm-search --json \
  --fields name,latestVersion,description,license,installCommand,popularity \
  search lottie --limit 5

Parse data.rows and pick the best candidate (official @ohos/* packages are usually preferred when multiple matches exist).

If meta.source is landscape, the match came from the tech map — check whether latestVersion is present; use resolve on the chosen name to obtain version and README before installing.

Step 2: Resolve the chosen package (preferred)

Once you have a package name, use resolve as the primary one-shot command:

ohpm-search --json resolve @ohos/lottie --max-chars 4000

resolve returns everything an agent typically needs in one round trip:

• installCommand — ready to add to oh-package.json5 or run in shell
• description, license, repository, keywords
• dependencies / dependent counts
• readmeSummary — truncated README for usage notes

Use --max-chars to cap README size and save context tokens. Omit it only when the full README is required.

Step 3: Fallback commands

Use these only when resolve is not enough:

# More metadata (downloads, versions list, readme URL)
ohpm-search --json info @ohos/lottie

# Deeper README when resolve summary is insufficient
ohpm-search --json readme @ohos/lottie --max-chars 4000 --lang cn

Agent rules of thumb

1. Prefer resolve over search + info + readme — fewer shell round trips, stable JSON envelope.
2. Always pass --json in agent prompts — even though non-TTY defaults to JSON, being explicit avoids surprises.
3. Use --fields on search — do not pull full rows when only name/version/description are needed.
4. Use --max-chars on resolve and readme — default to 3000–4000 unless the task requires full docs.
5. Check ok and error.code — retry on exit code 4, try another candidate on 3.
6. Package names are scoped — use @scope/name, e.g. @ohos/hypium, not bare hypium, for info / readme / resolve.
7. Check meta.source on search — landscape means no registry hit; follow with resolve if latestVersion is missing.

Minimal agent examples

# Unknown package: search then resolve
ohpm-search --json --fields name,latestVersion,description,installCommand search network --limit 5
ohpm-search --json resolve @ohos/axios --max-chars 4000

# Known package: resolve only
ohpm-search --json resolve @ohos/[email protected] --max-chars 3000

# Metadata only, no README fetch
ohpm-search --json resolve @ohos/lottie --no-readme

Programmatic API

import { OhpmSearchClient, resolvePackage } from "@arkanalyzer/ohpm-search"

const client = new OhpmSearchClient({
  registry: "https://ohpm.openharmony.cn",
  timeoutMs: 15000,
  retries: 2,
})

const results = await client.search("hypium", { pageSize: 10 })
const detail = await client.getDetail("@ohos/hypium")
const resolved = await resolvePackage(client, "@ohos/lottie", {
  lang: "cn",
  maxChars: 4000,
})

Development

npm run dev -- search hypium
npm run build
npm test
npm run test:watch
npm run typecheck

License

ISC