dsh-pkg-info

Readme

# dsh-pkg-info

DSH 包信息查询工具插件。注册一个 `pkg_info` 工具，查询 **npm** 与 **PyPI** 两个 registry 的包元数据，把结果规范化为一个结构化 JSON 对象，供模型与 Code Mode 程序化调用。**零依赖、纯 ESM、无构建**。

## 简介

- 工具名：`pkg_info`
- 能力：查询 npm 包（`registry.npmjs.org`）与 PyPI 包（`pypi.org`）的名称、版本、描述、许可证、作者、主页、仓库、版本数、依赖等信息。
- 行为：**永不抛异常**。404、网络错误、超时、JSON 解析失败都折叠为 `{ ok: false, error: { stage, message?, status? } }`；成功返回 `{ ok: true, registry, name, version, ... }`。

## 安装

```sh
dsh plugin --profile <name> add file:./plugins/dsh-pkg-info
# 或发布后：
dsh plugin --profile <name> add dsh-pkg-info
```

## 参数

| 参数 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
| `registry` | enum | — | `npm` | `npm` / `pypi`，选择要查询的 registry |
| `name` | string | ✅ | — | 包名。npm 作用域包写 `@scope/name`；PyPI 项目名大小写不敏感 |
| `version` | string | — | latest | 指定版本（npm 也支持 dist-tag 如 `latest`/`next`）；缺省查最新版 |

## 返回字段

### npm（`registry: "npm"`）

| 字段 | 类型 | 说明 |
|---|---|---|
| `ok` / `registry` / `name` / `version` | boolean/string | 状态、registry、规范包名、解析到的版本 |
| `description` | string \| null | 包描述 |
| `license` | string \| null | SPDX 许可证（对象/数组会被规范成字符串） |
| `author` | string \| null | 作者，规范为 `"name <email>"` |
| `homepage` | string \| null | 主页 URL |
| `repository` | string \| null | 仓库 URL |
| `distTags` | object | `dist-tags` 映射（如 `{ latest: "2.7.0", ... }`） |
| `created` / `modified` | string \| null | `time` 字段的创建/修改时间（ISO 8601） |
| `versionsCount` | integer | 已发布版本数 |
| `dependencies` | object \| null | 该版本的 `dependencies` |
| `peerDependencies` | object \| null | 该版本的 `peerDependencies` |

### PyPI（`registry: "pypi"`）

| 字段 | 类型 | 说明 |
|---|---|---|
| `ok` / `registry` / `name` / `version` | boolean/string | 状态、registry、规范项目名、解析到的版本 |
| `summary` | string \| null | 项目摘要（`info.summary`） |
| `license` | string \| null | 许可证（`info.license`，空串归一为 null） |
| `author` | string \| null | 作者（`info.author`） |
| `home_page` | string \| null | 主页 URL（`info.home_page`） |
| `releasesCount` | integer | 发布版本数（`releases` 键数） |
| `requiresDist` | string[] \| null | 该版本的 `requires_dist` 依赖列表 |

### 失败（`ok: false`）

`{ ok: false, registry, name, error: { stage: 'http'|'request'|'parse', message?, status? } }`。
- 404：`{ stage: 'http', status: 404 }`
- 网络/超时（10s）：`{ stage: 'request', message }`
- JSON 解析失败：`{ stage: 'parse', message }`

## 示例

```jsonc
// 查 npm 最新版
{ "registry": "npm", "name": "yaml" }
// 查 npm 指定版本
{ "registry": "npm", "name": "yaml", "version": "2.5.0" }
// 查 PyPI 最新版
{ "registry": "pypi", "name": "requests" }
// 查 PyPI 指定版本
{ "registry": "pypi", "name": "requests", "version": "2.28.1" }
```

## License

MIT