setup-ts-deep-modules

Setup TS Deep Modules

让 repo 中每个 package 成为 deep module：用小 interface 隐藏大量 behaviour。Package 的 public surface 是其 entry points（package root 中的 files），所有 subfolders 都隐藏。这个 skill 会安装 dependency-cruiser，加入强制只能通过 entry points 访问的 rules，并证明这些 rules 确实会拦截违规。

Vocabulary（deep module、interface、seam、depth）来自 /codebase-design skill；整个过程都使用它的语言。

The shape this enforces

src/packages/
  <name>/
    index.ts        ← an entry point (public). Import this from outside.
    client.ts       ← another entry point. Packages may expose SEVERAL.
    lib/            ← implementation: hidden from outside, free to import each other.
    tests/          ← co-located tests + fixtures (a subfolder, so private).

Public surface 是 package 的 root files，并非指定的单个 index.ts。按 convention，implementation 放在 lib/，tests 放在 tests/，使所有 packages 采用相同的 two-folder shape。Rule 本身是通用的：任何 subfolder 中的任何内容都是 private，因此永远无需为了新增 folder 扩展 config。

四条 rules，全部为 error：

1. Entry-point boundary — package 外的 code（app code 或其他 package）只能 import 该 package 的 entry points（root files），不能 import subfolder 中的任何内容。
2. Intra-package freedom — package 自己的 files 可以自由互相 import。
3. Tests through the entry points — <pkg>/tests/ 下的 files 可以 import 任意 package 的 entry points 和自己的 tests/ fixtures，但不能 import 任何 package 的 subfolder internals（包括自己的）。允许跨 package integration tests，不允许 deep imports。
4. No cycles — 不允许 dependency cycles。

Entry points, not a barrel. Public surface 是每个 root file，因此 package 可以提供多个小 entry points（index.ts、client.ts、server.ts），不必把一切汇入巨大的 index.ts。不鼓励 re-export 整个 subtree 的 barrel files；entry points 要小，implementation 隐藏在 subfolders。

Layering（哪些 packages 可以依赖哪些）是另一个 concern，在 config 中保留 commented stub，由当前 repo 填写。

Steps

1. Detect the environment

• Package manager — pnpm-lock.yaml → pnpm，yarn.lock → yarn，bun.lockb → bun，否则 npm。后续每条 command 都使用它（pnpm/yarn/npm run/bunx）。
• Packages root — 存在 src/ 就用 src/packages，否则用 packages。如果 repo 已有明显不同的 convention，与用户确认。
• Existing config — 检查 .dependency-cruiser.* file。若存在，不要覆盖；merge 四条 rules 和 options，并说明添加了什么。