Ansonfishing/dsh-ca-ref

Languages: English | 中文

Clean Architecture reference library — a plugin for DSH (DeepSeek Harness).

Why

When reviewing Clean Arch / DDD / hexagonal projects, the "known-good" answers are scattered across architecture tests and docs in various reference repos, and every review means digging through them again.

This plugin pre-indexes 8 pinned reference repos (Go / Java / C# / Python) into a local FTS5 database, so you can pull the full "answer set" in one call before a review, log the review afterwards, and feed hit statistics back into library curation.

Quick start

Prerequisites: DSH (with web) + pnpm; Node ≥ 24 (node:sqlite is built into Node 24).

cd ~/.dsh/profiles/web                      # your DSH web profile directory
pnpm add github:Ansonfishing/dsh-ca-ref

Then add "dsh-ca-ref" to the dsh.profile.bundles array in package.json and restart dsh. A "CA Reference Library" tab appears in the conversation view.

The index is built automatically on first use. The corpus defaults to ~/AI/ca-ref (override with the CAREF_CORPUS env var). The corpus is 8 public reference repos — clone URLs and verification commands live in each entry's verify_cmd field in seed/repos.json. If a corpus item is missing locally, the corresponding checks are skipped automatically (a data gap, not a code bug).

Features

• 8 pinned reference repos — pinned to fixed commits; a daily tick runs git rev-parse HEAD read-only drift checks, no automatic re-clone.
• FTS5 full-text search — over repo assertions, docs, and structure; Chinese matches by substring, English via FTS5; citations carry a <repo>:<path> source.
• Mechanizable rule list — each rule carries an assertion template and its source; ca_ref_baseline returns the full "answer set" for a language in one call (including 8 red flags).
• Review ledger — ca_ref_record logs a review (project, language, rules hit, evidence); hit statistics feed back into curation.
• Observation-window panel — a read-only tab with 30s auto-refresh: baseline (repo list + rule coverage table + full card), search log, review ledger, hit statistics.

Agent tools

Tool	Purpose
ca_ref_search	Full-text search over reference assertions/docs/structure
ca_ref_baseline	Fetch repo summary cards + rule list + 8 red flags for a language
ca_ref_record	Log a completed review (project / language / rules hit / evidence)
ca_ref_status	Library health: pinned SHAs, verification status, index state, ledger size

A /ca-ref status\|search\|baseline\|ledger\|stats\|reindex command channel (with --json) feeds the panel.

No DSH? Take a look anyway

Clone this repo and open test/harness/index.html in a browser — a zero-dependency render harness (mock data, ?chrome=0 hides the harness bar).

Updating the corpus

The daily tick runs git rev-parse HEAD as a read-only drift check against the pinned SHAs in seed/repos.json: on drift the panel's baseline tab shows ⚠️, but nothing is re-cloned automatically. When you decide to update, run, in the corpus directory for the affected repo:

git fetch --all && git checkout <new sha>   # or keep the old pinned version
<the repo's verify_cmd>                      # e.g. make test, to confirm the build still passes

Then run /ca-ref reindex to rebuild the index. If a repo's corpus is missing, its search/indexing is skipped automatically (a data gap, not a code bug).

Development

npm test                       # hermetic contract tests (node --test, no local corpus needed)
node scripts/smoke.mjs         # smoke: 8 pinned repos + toolchain + index (missing local corpus items are skipped)

Local development: after cloning, use pnpm add link:../path/to/dsh-ca-ref in your profile. Client-only changes need a browser refresh; Node-side changes (index.js / lib/*.js) need a dsh restart.

License

MIT © Ansonfishing