@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