{"_id":"@arkanalyzer/ohpm-search","_rev":"3-ae1d3d28700d5fe77b138a6b73f487a3","name":"@arkanalyzer/ohpm-search","dist-tags":{"latest":"1.0.2"},"versions":{"1.0.0":{"name":"@arkanalyzer/ohpm-search","version":"1.0.0","author":{"name":"Sun Bo"},"license":"ISC","_id":"@arkanalyzer/ohpm-search@1.0.0","maintainers":[{"name":"code-sunbo","email":"10715606@qq.com"}],"bin":{"ohpm-search":"dist/cli.js"},"dist":{"shasum":"8e771c5838d9258d0703dc387b42bb41b732742c","tarball":"https://registry.npmjs.org/@arkanalyzer/ohpm-search/-/ohpm-search-1.0.0.tgz","fileCount":52,"integrity":"sha512-1lxlM6DMtQzejUQbYR01GWOxOlhDETEzF8atjb9pluZ+zpGEqX16+GAD6j2d7tN148+0oE91xYWtELg1iRqrAQ==","signatures":[{"sig":"MEUCIQDAidkXRyxk7vjnl3mucvHU3Y1X8Be0JIY2VbJjKSmUEgIgLtz7Yb3xQEkvlgBh3pHVjQl1g+kyUTwWCKMSN5HviLI=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":107012},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./cli":{"import":"./dist/cli.js"}},"gitHead":"ef9693b50fc58e944b748623b931a49bcc71e23a","scripts":{"dev":"tsx src/cli.ts","test":"vitest run","build":"tsc","start":"node dist/cli.js","typecheck":"tsc --noEmit && tsc --noEmit -p test/tsconfig.json","test:watch":"vitest"},"_npmUser":{"name":"code-sunbo","email":"10715606@qq.com"},"_npmVersion":"11.14.1","description":"OpenHarmony third-party package search CLI","directories":{},"_nodeVersion":"24.11.0","dependencies":{"commander":"^14.0.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.20.0","vitest":"^4.1.8","typescript":"^5.9.3","@types/node":"^24.0.0"},"_npmOperationalInternal":{"tmp":"tmp/ohpm-search_1.0.0_1781169362601_0.5054139036540997","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@arkanalyzer/ohpm-search","version":"1.0.1","author":{"name":"Sun Bo"},"license":"ISC","_id":"@arkanalyzer/ohpm-search@1.0.1","maintainers":[{"name":"code-sunbo","email":"10715606@qq.com"}],"homepage":"https://gitcode.com/ProgramAnalysis/ohpm-search#readme","bugs":{"url":"https://gitcode.com/ProgramAnalysis/ohpm-search/issues"},"bin":{"ohpm-search":"dist/cli.js"},"dist":{"shasum":"a767417129626071499255d07cd7c18ae75023e6","tarball":"https://registry.npmjs.org/@arkanalyzer/ohpm-search/-/ohpm-search-1.0.1.tgz","fileCount":52,"integrity":"sha512-iJBePVimfBGwWhUCNTDs6ZiTv8yzak4dZX5bhhl52PtISHdd7oFbuixwZqtxtgaW7krtfaG7umv3SY3BsT1yXw==","signatures":[{"sig":"MEYCIQCvRmKGspCfR1gYg/TsC/Z4Ej7y8pv/VkDU1htH8dhnPAIhAOPieXfqwd3/C8UGe4p0QAihb8QD9niG+9MOBMSo2//j","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":116601},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./cli":{"import":"./dist/cli.js"}},"gitHead":"bd1f9f61571929dca609c74d187a12ded681e862","scripts":{"dev":"tsx src/cli.ts","test":"vitest run","build":"tsc","start":"node dist/cli.js","typecheck":"tsc --noEmit && tsc --noEmit -p test/tsconfig.json","test:watch":"vitest"},"_npmUser":{"name":"code-sunbo","email":"10715606@qq.com"},"repository":{"url":"git+https://gitcode.com/ProgramAnalysis/ohpm-search.git","type":"git"},"_npmVersion":"11.14.1","description":"OpenHarmony third-party package search CLI","directories":{},"_nodeVersion":"24.11.0","dependencies":{"commander":"^14.0.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.20.0","vitest":"^4.1.8","typescript":"^5.9.3","@types/node":"^24.0.0"},"_npmOperationalInternal":{"tmp":"tmp/ohpm-search_1.0.1_1781520930716_0.8490439003693404","host":"s3://npm-registry-packages-npm-production"}},"1.0.2":{"name":"@arkanalyzer/ohpm-search","version":"1.0.2","description":"OpenHarmony third-party package search CLI","license":"ISC","author":{"name":"Sun Bo"},"repository":{"type":"git","url":"git+https://gitcode.com/ProgramAnalysis/ohpm-search.git"},"homepage":"https://gitcode.com/ProgramAnalysis/ohpm-search#readme","bugs":{"url":"https://gitcode.com/ProgramAnalysis/ohpm-search/issues"},"type":"module","bin":{"ohpm-search":"dist/cli.js"},"main":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./cli":{"import":"./dist/cli.js"}},"scripts":{"build":"tsc","dev":"tsx src/cli.ts","start":"node dist/cli.js","test":"vitest run","test:watch":"vitest","typecheck":"tsc --noEmit && tsc --noEmit -p test/tsconfig.json"},"publishConfig":{"access":"public"},"engines":{"node":">=18"},"dependencies":{"commander":"^14.0.0"},"devDependencies":{"@types/node":"^24.0.0","tsx":"^4.20.0","typescript":"^5.9.3","vitest":"^4.1.8"},"gitHead":"4c5a57a8aa2b9c46b1d8017e7a3c5440997ef333","_id":"@arkanalyzer/ohpm-search@1.0.2","_nodeVersion":"24.11.0","_npmVersion":"11.14.1","dist":{"integrity":"sha512-sXnO6tGeqp0mFAIdLNdDHZHrPt4bw+jPQpPzyv9JgWdJnrV4Jq9v7AxPoHa2RL+oFFs9rj94R1rdqae3Ls0RIw==","shasum":"5a331103a63f111ce6ed9abcea5e8b62ae9e430c","tarball":"https://registry.npmjs.org/@arkanalyzer/ohpm-search/-/ohpm-search-1.0.2.tgz","fileCount":52,"unpackedSize":118062,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCgxZKOQOfQeZr+yTiSJ8X2yC4mKeAwFFDGwG/wnoG8VAIhAIrqf5z86oSO35JZpZOmPxsq66nFfdKGg0mYqaGPNmHZ"}]},"_npmUser":{"name":"code-sunbo","email":"10715606@qq.com"},"directories":{},"maintainers":[{"name":"code-sunbo","email":"10715606@qq.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/ohpm-search_1.0.2_1781521907160_0.08413997232056869"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-11T09:16:02.478Z","modified":"2026-06-15T11:11:47.446Z","1.0.0":"2026-06-11T09:16:02.774Z","1.0.1":"2026-06-15T10:55:30.841Z","1.0.2":"2026-06-15T11:11:47.306Z"},"bugs":{"url":"https://gitcode.com/ProgramAnalysis/ohpm-search/issues"},"author":{"name":"Sun Bo"},"license":"ISC","homepage":"https://gitcode.com/ProgramAnalysis/ohpm-search#readme","repository":{"type":"git","url":"git+https://gitcode.com/ProgramAnalysis/ohpm-search.git"},"description":"OpenHarmony third-party package search CLI","maintainers":[{"name":"code-sunbo","email":"10715606@qq.com"}],"readme":"# ohpm-search\n\nCLI and SDK for searching OpenHarmony third-party packages from the [OHPM registry](https://ohpm.openharmony.cn).\n\n## Requirements\n\n- Node.js >= 18\n\n## Install\n\n```bash\nnpm install -g @arkanalyzer/ohpm-search\n```\n\n## Commands\n\n### search\n\nSearch packages by keyword. Queries the OHPM registry first; when the registry returns **no results**, automatically falls back to the [landscape tech map](https://ohpm.openharmony.cn/#/cn/landscape) (`/ohpm/tech-map`).\n\n```bash\nohpm-search search lottie\nohpm-search search hypium --limit 5 --sort popularity\nohpm-search search 基础语音服务          # may hit landscape fallback\nohpm-search --json --fields name,latestVersion,installCommand search axios\nohpm-search search foo --no-fallback    # registry only, skip landscape\n```\n\nLandscape fallback notes:\n\n- JSON `meta.source` is `registry` or `landscape`; landscape hits also include `meta.landscapeUrl`.\n- Landscape rows may have **no `latestVersion`**; `installCommand` is then `ohpm install <name>` without `@version`. Run `resolve` or `info` next for versioned metadata.\n- Matching is case-insensitive substring search on package name and keywords (same idea as the landscape web UI).\n\n### info\n\nShow package metadata.\n\n```bash\nohpm-search info @ohos/hypium\nohpm-search info @ohos/lottie@2.0.31\nohpm-search --json info @ohos/hypium\n```\n\n### readme\n\nFetch package README content.\n\n```bash\nohpm-search readme @ohos/hypium\nohpm-search readme @ohos/hypium --lang en\nohpm-search readme @ohos/hypium --max-chars 4000\n```\n\nWithout `--max-chars`, the full README is returned.\n\n### resolve\n\nResolve package metadata and README in one call. Recommended for agents.\n\n```bash\nohpm-search resolve @ohos/lottie\nohpm-search resolve @ohos/lottie --lang en --max-chars 3000\nohpm-search resolve @ohos/lottie --no-readme\n```\n\nWithout `--max-chars`, the full README summary is returned.\n\n### profile\n\nShow software profile of a package, including repository stats and OpenSSF scorecard metrics.\n\n```bash\nohpm-search profile @tencent/mmkv\nohpm-search profile @tencent/mmkv@2.4.0\nohpm-search --json profile @tencent/mmkv\n```\n\nThe output includes:\n- **Basic info**: language, website\n- **Release info**: latest version, latest version date, release count\n- **Repository stats**: stars, forks, monthly downloads, contributors, code lines\n- **Commit activity**: first commit date, last commit date\n- **OpenSSF Scorecard**: total score and 16 sub-scores (binary artifacts, branch protection, CI tests, code review, contributors, license, maintained, vulnerabilities, fuzzing, SAST, security policy, signed releases, dependency update tool, pinned dependencies, etc.)\n\n## Global options\n\n| Option | Description |\n|--------|-------------|\n| `--registry <url>` | OHPM registry URL (default: `https://ohpm.openharmony.cn`) |\n| `--json` | Force JSON output |\n| `--format json\\|text` | Output format (non-TTY defaults to JSON) |\n| `--fields a,b,c` | Pick JSON fields |\n| `--quiet` | Suppress error output |\n| `--timeout <ms>` | Request timeout (default: 15000) |\n| `--retry <count>` | Retry count on failure (default: 2) |\n| `--help-json` | Print machine-readable command schema |\n\n### search options\n\n| Option | Description |\n|--------|-------------|\n| `--no-fallback` | Disable landscape fallback when registry returns no results (default: fallback enabled) |\n\n### Landscape disk cache\n\nFallback downloads the tech map once and caches it on disk for **8 hours** (per registry URL):\n\n| Variable | Description |\n|----------|-------------|\n| `OHPM_SEARCH_LANDSCAPE_CACHE=0` | Disable disk cache |\n| `OHPM_SEARCH_CACHE_DIR` | Override cache root (default: `~/.cache/ohpm-search/`) |\n| `XDG_CACHE_HOME` | Used when `OHPM_SEARCH_CACHE_DIR` is unset |\n\n## JSON envelope\n\nSuccess:\n\n```json\n{\n  \"ok\": true,\n  \"command\": \"search\",\n  \"data\": {},\n  \"meta\": {}\n}\n```\n\nFailure:\n\n```json\n{\n  \"ok\": false,\n  \"command\": \"info\",\n  \"error\": {\n    \"code\": \"PACKAGE_NOT_FOUND\",\n    \"message\": \"Package not found: @ohos/missing\"\n  }\n}\n```\n\n## Exit codes\n\n| Code | Meaning |\n|------|---------|\n| 0 | Success |\n| 1 | General error |\n| 2 | Validation error |\n| 3 | Package or README not found |\n| 4 | Network or API error |\n\n## Agent workflow\n\n> Cursor agents: see [skills/ohpm-search/SKILL.md](./skills/ohpm-search/SKILL.md) for the preferred skill workflow.\n\nUse this workflow when an agent needs to find, evaluate, or install an OpenHarmony third-party package.\n\nNon-interactive runs (pipes, CI, agents) default to JSON output. You can also force it with:\n\n```bash\nexport OHPM_SEARCH_FORMAT=json\n```\n\n### Decision guide\n\n| Situation | Preferred command |\n|-----------|-------------------|\n| Package name is **unknown** | `search` first |\n| Package name is **known** | `resolve` |\n| Need full README after resolve | `readme --max-chars <n>` |\n| Only need metadata, no README | `resolve --no-readme` or `info` |\n| Assess package health & security | `profile` |\n\n### Preferred workflow\n\n```mermaid\nflowchart TD\n  A[Need a third-party package] --> B{Know exact package name?}\n  B -->|No| C[\"search <keyword> --limit 5\"]\n  C --> D[Pick best match from data.rows]\n  D --> E[\"resolve <package> --max-chars 4000\"]\n  B -->|Yes| E\n  E --> F{Enough detail to install?}\n  F -->|Yes| G[Use installCommand from response]\n  F -->|No| H[\"readme <package> --max-chars 4000\"]\n  H --> G\n```\n\n### Step 1: Discover packages\n\nWhen the exact scoped name is unknown, search with a small page size and only the fields needed for ranking:\n\n```bash\nohpm-search --json \\\n  --fields name,latestVersion,description,license,installCommand,popularity \\\n  search lottie --limit 5\n```\n\nParse `data.rows` and pick the best candidate (official `@ohos/*` packages are usually preferred when multiple matches exist).\n\nIf `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.\n\n### Step 2: Resolve the chosen package (preferred)\n\nOnce you have a package name, use `resolve` as the primary one-shot command:\n\n```bash\nohpm-search --json resolve @ohos/lottie --max-chars 4000\n```\n\n`resolve` returns everything an agent typically needs in one round trip:\n\n- `installCommand` — ready to add to `oh-package.json5` or run in shell\n- `description`, `license`, `repository`, `keywords`\n- `dependencies` / `dependent` counts\n- `readmeSummary` — truncated README for usage notes\n\nUse `--max-chars` to cap README size and save context tokens. Omit it only when the full README is required.\n\n### Step 3: Fallback commands\n\nUse these only when `resolve` is not enough:\n\n```bash\n# More metadata (downloads, versions list, readme URL)\nohpm-search --json info @ohos/lottie\n\n# Deeper README when resolve summary is insufficient\nohpm-search --json readme @ohos/lottie --max-chars 4000 --lang cn\n```\n\n### Agent rules of thumb\n\n1. **Prefer `resolve` over `search` + `info` + `readme`** — fewer shell round trips, stable JSON envelope.\n2. **Always pass `--json` in agent prompts** — even though non-TTY defaults to JSON, being explicit avoids surprises.\n3. **Use `--fields` on `search`** — do not pull full rows when only name/version/description are needed.\n4. **Use `--max-chars` on `resolve` and `readme`** — default to `3000`–`4000` unless the task requires full docs.\n5. **Check `ok` and `error.code`** — retry on exit code `4`, try another candidate on `3`.\n6. **Package names are scoped** — use `@scope/name`, e.g. `@ohos/hypium`, not bare `hypium`, for `info` / `readme` / `resolve`.\n7. **Check `meta.source` on `search`** — `landscape` means no registry hit; follow with `resolve` if `latestVersion` is missing.\n\n### Minimal agent examples\n\n```bash\n# Unknown package: search then resolve\nohpm-search --json --fields name,latestVersion,description,installCommand search network --limit 5\nohpm-search --json resolve @ohos/axios --max-chars 4000\n\n# Known package: resolve only\nohpm-search --json resolve @ohos/hypium@1.0.28 --max-chars 3000\n\n# Metadata only, no README fetch\nohpm-search --json resolve @ohos/lottie --no-readme\n```\n\n## Programmatic API\n\n```ts\nimport { OhpmSearchClient, resolvePackage } from \"@arkanalyzer/ohpm-search\"\n\nconst client = new OhpmSearchClient({\n  registry: \"https://ohpm.openharmony.cn\",\n  timeoutMs: 15000,\n  retries: 2,\n})\n\nconst results = await client.search(\"hypium\", { pageSize: 10 })\nconst detail = await client.getDetail(\"@ohos/hypium\")\nconst profile = await client.getProfile(\"@tencent/mmkv\")\nconst resolved = await resolvePackage(client, \"@ohos/lottie\", {\n  lang: \"cn\",\n  maxChars: 4000,\n})\n```\n\n## Development\n\n```bash\nnpm run dev -- search hypium\nnpm run build\nnpm test\nnpm run test:watch\nnpm run typecheck\n```\n\n## License\n\nISC\n","readmeFilename":"README.md"}