From 91d7515fd82080cd4dd2c169846f644138168410 Mon Sep 17 00:00:00 2001 From: Tianyi Cui <53024+tianyicui@users.noreply.github.com> Date: Sun, 14 Jun 2026 00:51:38 +0800 Subject: [PATCH 1/6] docs: add development setup guide --- README.md | 2 + docs/development.md | 97 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 99 insertions(+) create mode 100644 docs/development.md diff --git a/README.md b/README.md index c13ab43210..aa5cceb162 100644 --- a/README.md +++ b/README.md @@ -18,3 +18,5 @@ yarn demo:coding # the real DeepSeek coding agent (needs DEEPSEEK_API_KEY) ``` For agent instructions see [AGENTS.md](AGENTS.md). For the architecture design see [docs/architecture.md](docs/architecture.md). Each subdirectory has its own README.md with local context: [packages/](packages/), [vendor/](vendor/). + +For local setup, hooks, environment variables, and quality gates, see the [development guide](docs/development.md). diff --git a/docs/development.md b/docs/development.md new file mode 100644 index 0000000000..507c305ae7 --- /dev/null +++ b/docs/development.md @@ -0,0 +1,97 @@ +# Development guide + +This guide covers the local setup needed to work on DeepSeek Harness and run the same checks the hooks and CI run. + +## Prerequisites + +- Node.js 24 or newer. The repo declares `node >=24`, and CI also exercises Node 24. +- Corepack-enabled Yarn. The repo pins `yarn@4.14.1` in `package.json`; run `corepack enable` if `yarn --version` does not resolve through Corepack. +- Git. +- Optional: a DeepSeek API key for the coding-agent demo and real-API e2e tests. + +## First-time setup + +Install dependencies from the repo root: + +```sh +yarn install +``` + +Yarn uses the `node-modules` linker in this repo. The install also runs the root `postinstall` script, which installs lefthook from the repo dev dependency. + +If hooks are missing because dependencies were restored from cache or `postinstall` was skipped, install them manually: + +```sh +yarn lefthook install +``` + +Run typecheck once after a fresh clone: + +```sh +yarn typecheck +``` + +That first typecheck builds declaration output used by type-aware linting for vendored packages. Without it, `yarn lint` can report unresolved-type `no-unsafe-*` errors even when source code is fine. + +If you are preparing to push from a fresh clone or worktree, also build once: + +```sh +yarn build +``` + +`yarn hygiene` includes `publint`, which validates package entrypoints against the built `lib/*.js` files. A fresh worktree has no bundled JS until `yarn build` runs. + +## Environment variables + +The real DeepSeek adapter and coding-agent demo read credentials from the environment or from a gitignored `.env` at the repo root: + +```sh +DEEPSEEK_API_KEY=sk-... +DEEPSEEK_BASE_URL=https://... # optional +``` + +`DEEPSEEK_BASE_URL` is optional and defaults to the public API. Never commit real credentials. The real-API e2e suites self-skip when `DEEPSEEK_API_KEY` is not set. + +## Git hooks + +lefthook is configured in `lefthook.yml` and calls the same package scripts used by CI: + +- `pre-commit` runs staged-file ESLint fixes, `yarn typecheck`, and the vendor manifest guard. +- `pre-push` runs `yarn test` and `yarn hygiene`. + +The vendor manifest guard checks that changes under `vendor/*/src` are staged with the matching `vendor/README.md` manifest update. See `vendor/README.md` before editing vendored code. + +## Daily commands + +Use these from the repo root: + +```sh +yarn test # unit tests +yarn test:coverage # unit tests with per-file coverage gates +yarn test:e2e # real-API tests; self-skips without DEEPSEEK_API_KEY +yarn typecheck # build declarations, then typecheck source, tests, and examples +yarn lint # eslint . +yarn lint:fix # eslint . --fix +yarn build # build declarations and JS bundles +yarn hygiene # knip, publint, and yarn constraints +``` + +When changing package public behavior, update the relevant README or JSDoc in the same change. The repo does not have an automated doc-sync gate. + +## Demos + +The echo demo does not need API credentials: + +```sh +yarn demo:echo +``` + +The coding-agent demo uses the real DeepSeek adapter and needs `DEEPSEEK_API_KEY` in the environment or repo-root `.env`: + +```sh +yarn demo:coding +``` + +## Architecture context + +Read `docs/architecture.md` before changing anything under `packages/`. The codebase is built around Cordis plugins, event-sourced sessions, typed service seams, and explicit extension points. From c3a3b6ae41fdde392d75afb887cec022b724ae62 Mon Sep 17 00:00:00 2001 From: Tianyi Cui <53024+tianyicui@users.noreply.github.com> Date: Sun, 14 Jun 2026 10:38:43 +0800 Subject: [PATCH 2/6] docs: clarify CI and hook gates --- docs/development.md | 21 +++++++++++++++++++-- 1 file changed, 19 insertions(+), 2 deletions(-) diff --git a/docs/development.md b/docs/development.md index 507c305ae7..f2e40a0517 100644 --- a/docs/development.md +++ b/docs/development.md @@ -1,6 +1,6 @@ # Development guide -This guide covers the local setup needed to work on DeepSeek Harness and run the same checks the hooks and CI run. +This guide covers the local setup needed to work on DeepSeek Harness and understand the local hooks, daily checks, and CI gates. ## Prerequisites @@ -54,13 +54,30 @@ DEEPSEEK_BASE_URL=https://... # optional ## Git hooks -lefthook is configured in `lefthook.yml` and calls the same package scripts used by CI: +lefthook is configured in `lefthook.yml` as an early local checkpoint before review: - `pre-commit` runs staged-file ESLint fixes, `yarn typecheck`, and the vendor manifest guard. - `pre-push` runs `yarn test` and `yarn hygiene`. The vendor manifest guard checks that changes under `vendor/*/src` are staged with the matching `vendor/README.md` manifest update. See `vendor/README.md` before editing vendored code. +These hooks do not exactly mirror CI. Notably, `pre-push` runs unit tests without coverage, while CI runs `yarn test:coverage`; CI also runs an echo-agent smoke test and exercises the matrix on Node 24 and 26. + +## CI gates + +The GitHub workflow runs these gates on each pull request: + +- `yarn install --immutable` +- `yarn constraints` +- `yarn typecheck` +- `yarn lint` +- `yarn test:coverage` +- `yarn build` +- `yarn knip && yarn publint` +- an echo-agent smoke test that checks the demo's tool call, tool result, and JSONL output + +`yarn hygiene` is the local shorthand for `yarn knip && yarn publint && yarn constraints`; CI splits `yarn constraints` into its own earlier step, then runs `yarn knip && yarn publint` after `yarn build`. + ## Daily commands Use these from the repo root: From 40298c28472317e1851fa7a9a0dcea14df0fe3b7 Mon Sep 17 00:00:00 2001 From: Tianyi Cui <53024+tianyicui@users.noreply.github.com> Date: Sun, 14 Jun 2026 10:46:17 +0800 Subject: [PATCH 3/6] docs: compact README guidance --- README.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/README.md b/README.md index aa5cceb162..75e879669b 100644 --- a/README.md +++ b/README.md @@ -17,6 +17,4 @@ yarn demo:echo # runnable echo-agent example (no API key needed) yarn demo:coding # the real DeepSeek coding agent (needs DEEPSEEK_API_KEY) ``` -For agent instructions see [AGENTS.md](AGENTS.md). For the architecture design see [docs/architecture.md](docs/architecture.md). Each subdirectory has its own README.md with local context: [packages/](packages/), [vendor/](vendor/). - -For local setup, hooks, environment variables, and quality gates, see the [development guide](docs/development.md). +For humans, start with the [development guide](docs/development.md) for local setup, hooks, environment variables, and quality gates, then read the [architecture design](docs/architecture.md) before package work. For agents, follow [AGENTS.md](AGENTS.md). Local context lives in [packages/](packages/) and [vendor/](vendor/). From 0853f52f49a711d2e2abaea73d7a4ddf7c792608 Mon Sep 17 00:00:00 2001 From: Tianyi Cui <53024+tianyicui@users.noreply.github.com> Date: Sun, 14 Jun 2026 10:47:32 +0800 Subject: [PATCH 4/6] docs: split README guidance by audience --- README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 75e879669b..7c203bf953 100644 --- a/README.md +++ b/README.md @@ -17,4 +17,6 @@ yarn demo:echo # runnable echo-agent example (no API key needed) yarn demo:coding # the real DeepSeek coding agent (needs DEEPSEEK_API_KEY) ``` -For humans, start with the [development guide](docs/development.md) for local setup, hooks, environment variables, and quality gates, then read the [architecture design](docs/architecture.md) before package work. For agents, follow [AGENTS.md](AGENTS.md). Local context lives in [packages/](packages/) and [vendor/](vendor/). +For humans, start with the [development guide](docs/development.md) for local setup, hooks, environment variables, and quality gates, then read the [architecture design](docs/architecture.md) before package work. Local context lives in [packages/](packages/) and [vendor/](vendor/). + +For agents, follow [AGENTS.md](AGENTS.md). From f2524e9c4556eb4923cd8a71ba110ff20983f36c Mon Sep 17 00:00:00 2001 From: Tianyi Cui <53024+tianyicui@users.noreply.github.com> Date: Sun, 14 Jun 2026 10:52:46 +0800 Subject: [PATCH 5/6] docs: sync dev guide with stacked gates --- docs/development.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/development.md b/docs/development.md index f2e40a0517..01edf783bc 100644 --- a/docs/development.md +++ b/docs/development.md @@ -57,7 +57,7 @@ DEEPSEEK_BASE_URL=https://... # optional lefthook is configured in `lefthook.yml` as an early local checkpoint before review: - `pre-commit` runs staged-file ESLint fixes, `yarn typecheck`, and the vendor manifest guard. -- `pre-push` runs `yarn test` and `yarn hygiene`. +- `pre-push` runs `yarn test`, `yarn hygiene`, and `yarn doc-sync`. The vendor manifest guard checks that changes under `vendor/*/src` are staged with the matching `vendor/README.md` manifest update. See `vendor/README.md` before editing vendored code. @@ -71,6 +71,7 @@ The GitHub workflow runs these gates on each pull request: - `yarn constraints` - `yarn typecheck` - `yarn lint` +- `yarn doc-sync` - `yarn test:coverage` - `yarn build` - `yarn knip && yarn publint` @@ -89,11 +90,14 @@ yarn test:e2e # real-API tests; self-skips without DEEPSEEK_API_KEY yarn typecheck # build declarations, then typecheck source, tests, and examples yarn lint # eslint . yarn lint:fix # eslint . --fix +yarn doc-typecheck # compile checked TypeScript snippets in Markdown docs +yarn verify-event-taxonomy # compare docs/architecture.md event names with source +yarn doc-sync # doc-typecheck plus event taxonomy verification yarn build # build declarations and JS bundles yarn hygiene # knip, publint, and yarn constraints ``` -When changing package public behavior, update the relevant README or JSDoc in the same change. The repo does not have an automated doc-sync gate. +When changing package public behavior, update the relevant README or JSDoc in the same change. `yarn doc-sync` catches checked TypeScript snippets and event-taxonomy drift, but broader prose/API sync still needs review. ## Demos From 7586caf2dd7da5920daf484256bc5fcb983f1668 Mon Sep 17 00:00:00 2001 From: Tianyi Cui <53024+tianyicui@users.noreply.github.com> Date: Sun, 14 Jun 2026 11:28:00 +0800 Subject: [PATCH 6/6] docs: clarify Node CI matrix --- docs/development.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/development.md b/docs/development.md index 01edf783bc..123aea44bf 100644 --- a/docs/development.md +++ b/docs/development.md @@ -4,7 +4,7 @@ This guide covers the local setup needed to work on DeepSeek Harness and underst ## Prerequisites -- Node.js 24 or newer. The repo declares `node >=24`, and CI also exercises Node 24. +- Node.js 24 or newer. The repo declares `node >=24`; CI runs the matrix on Node 24 and 26. - Corepack-enabled Yarn. The repo pins `yarn@4.14.1` in `package.json`; run `corepack enable` if `yarn --version` does not resolve through Corepack. - Git. - Optional: a DeepSeek API key for the coding-agent demo and real-API e2e tests.