@catheadowl/dsh-extras
English | 中文
Doing harness work is doing docs work. @catheadowl/dsh-extras is an opinionated attempt at docs health and navigation for the knowledge your dsh agent runs on. It wraps two commonly used dsh hooks into composable base frameworks — gates on agent/turn-stopping (turn close) and enrichment on agent/pre-step, each one a service-seam registration surface (ctx.gates / ctx.enrichment, consumed through the host's soft-dependency injection) instead of every plugin grabbing the raw hook — and ships what that stance implies: Markdown link hygiene, per-path context injection, and routing views over Markdown knowledge bases.
dsh plugin add installs everything at once; every module is a separately toggleable composition row (identified by row id) and can be disabled without affecting the others. What this package is relative to the dsh host — and why it wraps host hooks at all — is covered in docs/host.md.
Install
dsh plugin add @catheadowl/dsh-extras
Requires the dsh CLI. All runtime dependencies come from the dsh host (peerDependencies, resolved against the host at plugin add); the package itself carries only a few pure-JS utility dependencies.
Modules
Extension frameworks (registration seams for consumer plugins):
| Module | Row id | What it provides | Docs |
|---|
| gates | gates | Quality-gate framework (ctx.gates): composable gates run automatically at turn close; consumer plugins register through the ctx.gates service seam | modules/gates/README.md |
| enrichment | enrichment | Enrichment framework (ctx.enrichment): provider registry on agent/pre-step that turns path mentions into budgeted relates context; consumer plugins register through the ctx.enrichment service seam | modules/enrichment/README.md |
Tools & consumers:
| Module | Row id | What it provides | Docs |
|---|
| markdown | markdown | md_rename tool (move a Markdown file and rewrite every internal link) + the doc-link gate + the bundled link-transaction library | modules/markdown/README.md |
| routes | routes | any_nav tool (routing views over Markdown knowledge bases) + the breadcrumb relates provider (an enrichment provider) | modules/routes/README.md |
Each module is an independently toggleable row in the host's plugin composition: no shared state — disable any row and the others behave exactly as before.
Configuration
Disable a single module by row id in your profile patch layer:
- id: gates
disabled: true
Modules with defaults can be overridden. All config keys per row:
| Row | Config keys |
|---|
| gates | maxConsecutiveBlocks (consecutive-block cap, default 3; exhausted → degrade to pass) |
| enrichment | providerTimeoutMs / totalTimeoutMs / renderBudgetChars (example below) |
| markdown / routes | no plugin config keys |
- id: enrichment
config:
providerTimeoutMs: 2000
totalTimeoutMs: 5000
renderBudgetChars: 4000
Adding or removing modules happens through package versions: upgrade this package, then dsh plugin update shrinks or grows the composition rows.
API face
Beyond the composition rows, the package exports a stable subpath for plugin developers:
@catheadowl/dsh-extras/markdown/gate-check — the markdown module's repo-level gates.yml fallback entry (the generic check).
Plugins that build on the gates / enrichment frameworks do not import this package: they register through the service seams (ctx.gates.register(...) / the ctx.enrichment provider registry) via the host's ctx.inject soft dependency and keep no package dependency — each framework module's README documents the recipe.
The Web configuration pages (the gates / enrichment rows' Configure pages on the Plugins page) are loaded from the bundled client sub-package inside this package (modules/client) — nothing to install separately.
The module dependency topology and the exports reconciliation table live in docs/dependencies.md.
Development
# From the repository root
pnpm run build # four module libs + client bundle
pnpm run test:gates # per-module unit tests (test:markdown / test:enrichment / test:routes)
pnpm run verify:package-face # exports / facade checks
pnpm run verify:publish-readiness # release hygiene checks (docs locality, host closure, ...)
Development details — host checkout placement, toolchain borrow, peer junctions, and the host-closure network check — live in docs/development.md.
Known limitations
- Requires the dsh CLI (this package is a plugin carrier, not a standalone app); all runtime peers are provided by the host closure.
- The root README is bilingual (English primary + Chinese); module pages and deep docs are Chinese-first.
- Web configuration pages currently exist only for the gates / enrichment rows (row-level Configure on the Plugins page, loaded via the bundled client sub-package,
modules/client, not published separately).
- The gates consecutive-block cap (
maxConsecutiveBlocks, default 3) degrades to pass when exhausted — it is a safety valve, not a correctness guarantee; the markdown / routes rows expose no plugin config keys.
License
MIT
