dsh-readme-forge

Readme

# dsh-readme-forge

[![npm](https://img.shields.io/npm/v/dsh-readme-forge.svg)](https://www.npmjs.com/package/dsh-readme-forge)

[![CI](https://github.com/zoahdev/dsh-readme-forge/actions/workflows/ci.yml/badge.svg)](https://github.com/zoahdev/dsh-readme-forge/actions)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![dsh-plugin](https://img.shields.io/badge/dsh--plugin-verified-blue)](https://github.com/topics/dsh-plugin)

Generate a **README.md** for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (dsh) plugin repositories from `package.json` + `cordis.patch.yml` + source layout.

Every new plugin needs a README before it can be found by humans or AI. This one builds a deterministic starter: title, description, install command, CLI, tools (from `cordis.patch.yml`), development, and license — then you polish. Read-only by default; writing is explicit. The companion to [dsh-llms-forge](https://github.com/zoahdev/dsh-llms-forge) (which generates `llms.txt` from the README you just forged).

## Install

```sh
dsh plugin add dsh-readme-forge
```

Or run standalone:

```sh
npx dsh-readme-forge .
```

## CLI

```sh
dsh-readme-forge [dir] [options]

  --write        write README.md to disk
  --overwrite    replace an existing README.md (only with --write)
  --no-tools     omit the Tools section from cordis.patch.yml
  --no-dev       omit the Development section
  --json         print the machine-readable dsh-readme-forge/v1 result
  --help         show this help
```

Exit codes: `0` clean, `1` warnings, `2` usage/IO error.

```sh
npx dsh-readme-forge . --write --overwrite
npx dsh-readme-forge ./my-plugin --no-tools --json
```

## In-harness usage (agent-callable)

Ask your dsh agent:

> 给这个插件仓库生成一份 README：`readme_forge`，目录指向仓库根目录，写入并覆盖。
> Generate a README for this plugin repo: `readme_forge` with `dir` set, then `write: true, overwrite: true`.

The tool returns a `dsh-readme-forge/v1` result with the proposed content and warnings, and writes the file only when `options.write` is true.

## What it generates

```markdown
# dsh-dep-audit

Dependency supply-chain hygiene audit for DeepSeek Harness ...

## Install

dsh plugin add dsh-dep-audit

## CLI

npx dsh-dep-audit --help

## Tools

- `dep_audit`

## Development

pnpm install && pnpm typecheck && pnpm build && pnpm test

## License

MIT © 2026 zoahdev

> Generated by dsh-readme-forge. Keep this file in sync with package.json and cordis.patch.yml.
```

## Why it exists

- The ecosystem grows by thousands of plugins per week; most lack a README, and hand-writing one from scratch is the #1 first-hour friction for new plugin authors.
- Generated READMEs are deterministic and CI-checkable (`--json`, exit code) — the llms-forge pipeline starts where this one ends.
- Zero runtime dependencies, read-only by default, safe to run anywhere.

## Development

```sh
pnpm install
pnpm typecheck
pnpm build
pnpm test
pnpm test:integration
```

CI runs the dsh-plugin-doctor preflight, unit tests, packed-artifact integration (real `readme_forge` invocation), and a fresh-profile `dsh web` boot smoke on Windows.

## License

MIT © 2026 zoahdev

---

# dsh-readme-forge（中文）

为 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（dsh）插件仓库**生成 README.md**：数据源是 `package.json` + `cordis.patch.yml` + 源码目录结构。

每个新插件在被人类或 AI 发现之前都需要 README。本插件生成确定性起始文档：标题、描述、安装命令、CLI、工具（取自 `cordis.patch.yml`）、开发与许可证——之后再人工润色。默认只读，写盘需显式开启。与 [dsh-llms-forge](https://github.com/zoahdev/dsh-llms-forge) 互补（它从刚生成的 README 再生成 llms.txt）。

## 安装

```sh
dsh plugin add dsh-readme-forge
```

独立使用：

```sh
npx dsh-readme-forge .
```

## CLI

```sh
dsh-readme-forge [dir] [options]

  --write        把 README.md 写到磁盘
  --overwrite    覆盖已有 README.md（需配合 --write）
  --no-tools     省略 cordis.patch.yml 的 Tools 小节
  --no-dev       省略 Development 小节
  --json         输出机器可读 dsh-readme-forge/v1 结果
  --help         帮助
```

退出码：`0` 干净，`1` 有警告，`2` 用法/IO 错误。

```sh
npx dsh-readme-forge . --write --overwrite
npx dsh-readme-forge ./my-plugin --no-tools --json
```

## 在 harness 内使用（agent 可调用）

对 agent 说：

> 给这个插件仓库生成一份 README：`readme_forge`，目录指向仓库根目录，写入并覆盖。

工具返回 `dsh-readme-forge/v1` 结果（含生成内容与警告），仅在 `options.write` 为 true 时写盘。

## 为什么需要它

- 生态每周新增上千插件，多数没有 README；从零手写是插件作者第一小时的常见摩擦。
- 生成式 README 可复现、可进 CI（`--json` + 退出码）——llms-forge 管道的起点就在这里。
- 零运行时依赖、默认只读，任何环境都能安全跑。

## 开发

```sh
pnpm install
pnpm typecheck
pnpm build
pnpm test
pnpm test:integration
```

CI 跑 dsh-plugin-doctor 预检、单元测试、打包集成（真实 `readme_forge` 调用）、Windows 全新 profile 的 `dsh web` 启动冒烟。

## 许可证

MIT © 2026 zoahdev
## Related ecosystem tools

- [dsh-dep-audit](https://github.com/zoahdev/dsh-dep-audit) - dependency supply-chain hygiene
- [dsh-quality-score](https://github.com/zoahdev/dsh-quality-score) - plugin quality scorecard + full-registry leaderboard
- [dsh-ecosystem](https://github.com/zoahdev/dsh-ecosystem) - health scan, impact, trend, live dashboard
- [dsh-tutorials](https://github.com/zoahdev/dsh-tutorials) - bilingual plugin pipeline tutorials
## FAQ

- **How do I install?** dsh plugin add dsh-readme-forge or run the CLI directly (see README).
- **Does it need an API key?** No.
- **Is it read-only?** Yes by default; any write/apply is an explicit flag.
## Examples

See the README for full CLI usage. Quick start:

```sh
npx dsh-readme-forge --help
```