dsh-plugin-pkgseek

Readme

# dsh-plugin-pkgseek

[![npm version](https://img.shields.io/npm/v/dsh-plugin-pkgseek)](https://www.npmjs.com/package/dsh-plugin-pkgseek)
[![ci](https://github.com/web-casa/dsh-plugin-pkgseek/actions/workflows/ci.yml/badge.svg)](https://github.com/web-casa/dsh-plugin-pkgseek/actions/workflows/ci.yml)

[PkgSeek](https://github.com/yeagoo/pkgseek) Linux package, command and CVE
intelligence as native [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)
(DSH) tools — plus a system-prompt segment that tells the agent when to use them.

The plugin is a thin adapter over PkgSeek's public MCP-over-HTTP endpoint: at
load time it fetches `tools/list` and registers one native DSH tool per
definition (names prefixed `pkgseek_`), so tools go through the same approval,
guard and logging pipeline as built-in tools. Every call is forwarded as
`tools/call` to the hosted API — all tools are read-only and need no API key.

## Install

```sh
# interactive (web) profile
dsh plugin --profile web add dsh-plugin-pkgseek
# one-shot (headless) profile — dsh run uses this one
dsh plugin --profile headless add dsh-plugin-pkgseek
```

web and headless are separate profiles; install into both if you use both.
The package is published on npm as
[`dsh-plugin-pkgseek`](https://www.npmjs.com/package/dsh-plugin-pkgseek);
`dsh plugin add` resolves it from the registry. Installing from the GitHub
source also works (`dsh plugin --profile web add github:web-casa/dsh-plugin-pkgseek`).

The published manifest declares support for DSH `>=0.1.0-rc.7 <0.2.0` on both
the web and Desktop clients. That declaration lets a strict Cordis v4 catalog
verify exact registry evidence; it does not by itself grant marketplace or
Microsoft Store approval.

## Verification

The plugin was smoke-tested against a live `dsh` 0.1.0-rc.7 headless
profile: it loaded, fetched `tools/list` from the production API,
registered `pkgseek_resolve_install`, the model called it, and the session
log shows the API answer (`sudo apt install ripgrep`) flowing back through
`tools/call`. Unit tests cover the JSON-RPC client, the schema adapter, the
offline snapshot and the config surface (`npm test`).

## Configuration

All settings are optional and live in the plugin's `config:` row:

```yaml
- id: pkgseek
  name: dsh-plugin-pkgseek
  config:
    apiBase: https://api.pkgseek.com   # any PkgSeek API deployment
    timeoutMs: 20000                   # per-request timeout
    promptGuidance: true               # register the usage-guidance prompt section
    refreshTools: true                 # refresh tools/list at load (snapshot fallback)
    enabledTools: []                   # allowlist of unprefixed names; empty = all
```

If the live `tools/list` fails at load time (offline, API down), the plugin
registers from its bundled snapshot and tool calls fail individually with a
clear error instead of breaking the profile.

## Tools

22 read-only tools, registered with the `pkgseek_` prefix:

- Command/tool intelligence: `pkgseek_search_tools`, `pkgseek_get_tool`,
  `pkgseek_resolve_install`, `pkgseek_identify_binary`,
  `pkgseek_query_file_provides`, `pkgseek_compare_distros`, `pkgseek_get_context`
- Error & command doctor: `pkgseek_diagnose_linux_error`, `pkgseek_lint_command`,
  `pkgseek_explain_command`, `pkgseek_suggest_fix`
- Packages: `pkgseek_search_packages`, `pkgseek_get_package`,
  `pkgseek_compare_package_versions`, `pkgseek_get_package_history`
- Vulnerabilities: `pkgseek_search_vulnerabilities`, `pkgseek_get_vulnerability`
- Lifecycle & migration: `pkgseek_check_release_lifecycle`,
  `pkgseek_get_distro_lifecycle`, `pkgseek_compare_distro_releases`,
  `pkgseek_plan_distro_migration`
- Meta: `pkgseek_get_repository_health`

## Development

```sh
npm install
npm run sync-tools   # refresh tools.snapshot.json from the live endpoint
npm test             # build + node --test
```

Layout: `src/mcp-client.ts` (JSON-RPC over HTTP), `src/adapter.ts` (MCP tool
definitions → `defineTool`), `src/prompt.ts` (guidance section),
`src/index.ts` (wiring, config schema).

## Release

Releases are deliberately manual. An authorized maintainer dispatches the
`publish.yml` workflow from `main`, enters the exact unpublished
`package.json` version, and types `PUBLISH`. The workflow installs locked
dependencies without lifecycle scripts, runs the tests, packs the tested
artifact, then publishes it through npm Trusted Publishing (GitHub Actions
OIDC). It has no npm write token and does not run for pushes or tags.

The npm trusted-publisher binding is restricted to
`web-casa/dsh-plugin-pkgseek`, `publish.yml`, and the `npm-publish`
environment. Configure required reviewers for that GitHub environment and
protect the default branch before delegating release authority; the workflow's
manual confirmation is not a substitute for an independent review policy.

## License

MIT