From 24946ad820f78241570fc7a547f2060f6fdceaa6 Mon Sep 17 00:00:00 2001 From: claude_code Date: Mon, 6 Jul 2026 05:50:34 +0300 Subject: [PATCH] docs(agents): build shared packages before a consumer's tsc/tests in isolation Document the TS2307 trap: the gitignored build/ of @docmost/prosemirror-markdown, @docmost/git-sync and @docmost/mcp is not honoured by a single-package pnpm --filter test/tsc or a bare pnpm -r test (Nx dependsOn ^build is only applied by nx run-many), so a consumer's typecheck fails with Cannot find module '@docmost/...' until those packages are built first. Mirrors the order .github/workflows/test.yml already uses. --- AGENTS.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 5f0d81ad..30c542ba 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -230,6 +230,24 @@ pnpm build # nx run-many -t build (all packages) pnpm collab:dev # run the collaboration server process standalone (see "Two server processes") ``` +> **Build the shared packages before running a consumer's `tsc`/tests in +> isolation.** The `build/` dirs of `@docmost/prosemirror-markdown`, +> `@docmost/git-sync`, and `@docmost/mcp` are **gitignored** (not committed), and +> a single-package `pnpm --filter test` / `tsc` or a bare `pnpm -r test` +> does **NOT** honour the Nx `dependsOn: ["^build"]` ordering. So a consumer — the +> server's `tsc`, `git-sync`'s vitest typecheck, `mcp`'s `pretest: tsc` — fails +> with `error TS2307: Cannot find module '@docmost/…'` until those packages are +> built first: +> ```bash +> pnpm --filter @docmost/prosemirror-markdown build +> pnpm --filter @docmost/editor-ext build +> pnpm --filter @docmost/git-sync build && pnpm --filter @docmost/mcp build +> ``` +> `pnpm build` (nx run-many) does this for you; CI does it explicitly in +> `.github/workflows/test.yml` (prosemirror-markdown → git-sync/mcp → server, in +> that order). Reach for it whenever you run a consumer package's checks on their +> own rather than through the full `pnpm build`. + **Lint** (per package — there is no root lint script): ```bash pnpm --filter server lint # eslint --fix on server .ts -- 2.52.0