菜单
Use when running, verifying, or debugging Threadline locally — starting the three services, choosing between in-memory and MongoDB persistence, reproducing a realtime bug, or diagnosing why the stack will not come up. Read before assuming a symptom is a code defect.
默认使用会先检查来源的 Prompt；你也可以切换为直接命令，或下载本地副本。
决定是否安装前，请先阅读 SKILL.md，以及 SkillsMP 当前展示的配套文件。
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
直接命令不会经过审查 Prompt；运行前请先检查来源。
npx skills add https://github.com/hoangsonww/Threadline-RealTime-Collab --skill threadline-local-stack命令会保持在同一行。复制前请横向滚动并检查完整内容。
想先保存到本地？可下载 SkillsMP 当前能够提供的文件。
正在显示 SKILL.md
| name | threadline-local-stack |
| description | Use when running, verifying, or debugging Threadline locally — starting the three services, choosing between in-memory and MongoDB persistence, reproducing a realtime bug, or diagnosing why the stack will not come up. Read before assuming a symptom is a code defect. |
Three services, three ports. Most "the app is broken" reports resolve to one of the environment conditions below rather than to a code defect, so check here first.
npm run dev # all three: api :4000, realtime :8787, web :3000
npm run dev:api:local # api only
npm run dev:realtime:local
npm run dev:web:local
npm run docker:up # all three as containers, plus MongoDB
make ports # what is currently holding 3000 / 4000 / 8787 / 27017
npm run doctor # full environment diagnosis — run this first when something is off
npm run doctor checks Node against engines, dependency consistency, git hooks, local env files, tracked-but-ignored files, and whether the four ports are free. It reports the remedy for each failure rather than only the failure.
npm run dev:api:local sets MONGODB_URI= empty on purpose. An empty value makes apps/api/src/index.ts select MemoryRepository instead of MongoRepository.
Consequences, all expected rather than broken:
tsx watch, which restarts the process, which discards every user, session, and room. This is documented in docs/troubleshooting.md because it catches everyone once.MongoRepository.connect() is where unique indexes and TTLs are declared. A uniqueness bug that only appears against a real database will not reproduce in memory.For persistence, run npm run docker:up (which includes MongoDB), or set MONGODB_URI to a running instance. In production the fallback is refused outright — see docs/security.md.
One browser tab is not enough. Fan-out, presence, and signalling bugs are invisible with a single client. Open two sessions — two profiles, or one normal and one private window, since a shared session cookie makes both tabs the same participant.
The realtime tier runs under wrangler dev --local, which is a real workerd instance. Behavior there is what production does; behavior under Node is not evidence.
If the Durable Object seems to lose state, check whether the state was in memory rather than in storage. The object hibernates, and in-memory fields do not survive that.
| Port | Service |
|---|---|
| 3000 | apps/web — Next.js |
| 4000 | apps/api — Express |
| 8787 | apps/realtime — Wrangler |
| 27017 | MongoDB (Docker Compose or dev container only) |
| 8080 | TypeDoc preview (npm run docs:serve) |
make ports # show holders
make kill-ports # free 3000, 4000, 8787 — asks first
npm run dev uses concurrently --kill-others-on-fail, so one service failing to bind takes all three down. The error scrolls past quickly; the surviving symptom is "nothing started".
Both are gitignored, and both have a committed example:
cp apps/web/.env.example apps/web/.env.local
cp apps/realtime/.dev.vars.example apps/realtime/.dev.vars
scripts/bootstrap.sh and the dev container's post-create.sh both seed these automatically and never overwrite an existing one.
Nothing in NEXT_PUBLIC_* is secret — those values are compiled into the client bundle.
.devcontainer/ provides the full toolchain plus a MongoDB sidecar, with MONGODB_URI already pointed at it — so the API persists by default in there, unlike on the host. Chromium and shellcheck are preinstalled.
npm run doctor — it checks the boring causes.npm ci — a node_modules that disagrees with package.json produces confusing failures. npm run clean:all && npm ci for the nuclear version.docs/troubleshooting.md — real symptoms with real causes.make info — versions and repository state, worth including in any bug report.Running the app is not the same as verifying the change. State the specific evidence:
npm run check # format, lint, typecheck, test, build — the merge gate
make check # same, with a summary and every step run even after a failure
For a UI change, apps/web has no full automated suite — verify by hand against a running app and say what you observed. For a realtime change, verify with two clients. For an API change, the test suite is the evidence, and the denied path matters more than the allowed one.
Use when preparing a change for review — before committing, before opening a pull request, and before claiming work is complete. Covers the commit convention, the pre-push gate, what the pull request has to contain, and what CI will check.
Use when a change is an architectural decision rather than an incremental fix — a new dependency, a new data model relationship, a new trust boundary, or a reversal of an existing decision. Covers this repository's specific ADR format, which is stricter than the generic template.
Use when adding, changing, or removing an HTTP route in apps/api — including anything that touches the Repository interface, the OpenAPI specification, or an authorization decision. Enforces the six-step order that keeps routes, persistence, policy, spec, tests, and docs in sync.