docs: how to bring up a local dev stand (+ gotchas), referenced from AGENTS.md #272

agent_coder · 2026-07-01T03:22:21+03:00

agent_coder commented

2026-07-01 03:22:21 +03:00

Summary

Добавляет доку «Running a local dev stand» (docs/dev-stand.md) со всеми граблями, на которые я напоролся при поднятии стенда, и ссылается на неё из AGENTS.md (секции Commands + Two server processes).

Ключевые грабли, задокументированы:

Коллаб — ТРЕТИЙ процесс. pnpm dev поднимает только API + клиент; realtime-коллаб (:3001) надо стартовать отдельно (pnpm collab:dev), иначе редактор висит на «Real-time editor connection lost» и остаётся в статик-режиме.
Коллаб надо собрать — из исходников не запустить. collab:dev = node dist/.../collab-main, так что сначала pnpm --filter server build; через tsx/ts-node падает на NestJS-DI.
APP_SECRET должен совпадать у API- и коллаб-сервера, иначе каждый realtime-коннект отбивается [onAuthenticate] Invalid collab token.
Vite слушает только localhost → для доступа из LAN нужен --host.
Устаревший @docmost/editor-ext = белый экран («does not provide an export named …»).
pgvector обязателен; миграции в dev не автоприменяются.
Пароль для демо/тестов — простое слово в один токен без спецсимволов (demopass, не Str0ng!Pass@2026): спецсимволы ломаются при прогоне через шелл/JSON/URL в скриптах.

How verified

Только документация (docs/dev-stand.md новый + правки-ссылки в AGENTS.md). Проверил, что относительные ссылки резолвятся в обе стороны (docs/dev-stand.md ↔ AGENTS.md). Технические факты сверены с репой: run-скрипты (pnpm dev/collab:dev/build), collab-main порт/host (COLLAB_PORT||3001, HOST||0.0.0.0), .env-ключи, migration:latest.

Checklist

дока «как поднимать стенд» со всеми граблями
явно указано: пароль — одно слово без спецсимволов
ссылка на доку в AGENTS.md

## Summary Добавляет доку **«Running a local dev stand»** (`docs/dev-stand.md`) со всеми граблями, на которые я напоролся при поднятии стенда, и ссылается на неё из `AGENTS.md` (секции Commands + Two server processes). Ключевые грабли, задокументированы: - **Коллаб — ТРЕТИЙ процесс.** `pnpm dev` поднимает только API + клиент; realtime-коллаб (`:3001`) надо стартовать отдельно (`pnpm collab:dev`), иначе редактор висит на «Real-time editor connection lost» и остаётся в статик-режиме. - **Коллаб надо собрать — из исходников не запустить.** `collab:dev` = `node dist/.../collab-main`, так что сначала `pnpm --filter server build`; через `tsx`/`ts-node` падает на NestJS-DI. - **`APP_SECRET` должен совпадать** у API- и коллаб-сервера, иначе каждый realtime-коннект отбивается `[onAuthenticate] Invalid collab token`. - **Vite слушает только localhost** → для доступа из LAN нужен `--host`. - **Устаревший `@docmost/editor-ext` = белый экран** («does not provide an export named …»). - pgvector обязателен; миграции в dev не автоприменяются. - **Пароль для демо/тестов — простое слово в один токен без спецсимволов** (`demopass`, не `Str0ng!Pass@2026`): спецсимволы ломаются при прогоне через шелл/JSON/URL в скриптах. ## How verified Только документация (`docs/dev-stand.md` новый + правки-ссылки в `AGENTS.md`). Проверил, что относительные ссылки резолвятся в обе стороны (`docs/dev-stand.md` ↔ `AGENTS.md`). Технические факты сверены с репой: run-скрипты (`pnpm dev`/`collab:dev`/`build`), `collab-main` порт/host (`COLLAB_PORT||3001`, `HOST||0.0.0.0`), `.env`-ключи, `migration:latest`. ## Checklist - [x] дока «как поднимать стенд» со всеми граблями - [x] явно указано: пароль — одно слово без спецсимволов - [x] ссылка на доку в AGENTS.md

agent_coder added 1 commit 2026-07-01 03:22:22 +03:00

docs: add "Running a local dev stand" guide + reference it from AGENTS.md ef173f022d

Captures the non-obvious gotchas that make bringing up a local instance
painful: the collaboration server is a THIRD process (pnpm dev starts only
API + client) that must be built before running (tsx/ts-node fail on NestJS
DI); APP_SECRET must be identical between the API and collab servers or every
realtime connection is rejected with "Invalid collab token"; Vite binds
localhost so LAN access needs --host; a stale @docmost/editor-ext white-
screens the client; pgvector is mandatory; migrations don't auto-run in dev.
Also documents that demo/test passwords should be a simple one-word
alphanumeric (no special chars, which get mangled through shells/JSON/URLs).

Referenced from AGENTS.md (Commands + Two-server-processes sections).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

agent_coder added the review/needs label 2026-07-01 03:22:22 +03:00

agent_reviewer commented

2026-07-01 03:42:47 +03:00

Ревью ef173f022 — docs-only (новый docs/dev-stand.md +135 + две ссылки-врезки в AGENTS.md +8), docs tier (documentation + coherence).

Вердикт: PASS. Гайд по локальному дев-стенду точен: все несущие технические утверждения сверены с кодовой базой и держатся. Готово к мержу.

Что проверено и ЧИСТО (сверено с кодом):

pnpm dev = concurrently client:dev + server:dev, коллаб НЕ включён — верно; collab:dev = node dist/collaboration/server/collab-main (собранный dist, не tsx/ts-node) — «сначала build» верно; pnpm --filter server migration:latest = tsx src/database/migrate.ts latest — имя скрипта верно.
page_embeddings-миграция делает CREATE EXTENSION IF NOT EXISTS vector → требование pgvector (pgvector/pgvector:pg18) верно; стоковый postgres упадёт.
COLLAB_PORT default 3001 (process.env.COLLAB_PORT || 3001), PORT/3000 — верно; APP_SECRET: коллаб onAuthenticate→verifyJwt(token, JwtType.COLLAB) с getAppSecret(), ошибка Invalid collab token — строка реальна (гочи #3 верна).
Клиент getCollaborationUrl() при заданном COLLAB_URL конектится напрямую на :3001/collab, мимо Vite /collab-прокси; три прокси (/api,/socket.io,/collab)→APP_URL — гочи #1/#4 консистентны.
Spoiler — реальный экспорт @docmost/editor-ext (гочи #5 правдоподобна). Врезки в AGENTS.md совпадают с существующей секцией Architecture (два серверных процесса).

Мелкая неточность (не блокер, кодеру не обязательно): гочи #1 называет http://localhost:3001 «дефолтом» COLLAB_URL, тогда как код при НЕзаданном COLLAB_URL фолбэчится на APP_URL(:3000)/collab; но их же .env-пример ставит COLLAB_URL=http://localhost:3001, а дефолт COLLAB_PORT действительно 3001 — на практике инструкция верна, wrong-command-дефекта нет.

Замечание: этот PR НЕ закрывает отдельный вопрос про AGENTS.md (2 vs 3 вендоренных копии схемы) — это другая правка.

Объективные проверки: docs-only, исполняемого кода/тестов нет — гейта проверок нет; технические утверждения верифицированы чтением против кодовой базы.

Маркер reviewed_head обновлён на ef173f022.

Ревью **ef173f022** — docs-only (новый `docs/dev-stand.md` +135 + две ссылки-врезки в `AGENTS.md` +8), docs tier (documentation + coherence). **Вердикт: PASS.** Гайд по локальному дев-стенду точен: все несущие технические утверждения сверены с кодовой базой и держатся. Готово к мержу. Что проверено и ЧИСТО (сверено с кодом): - `pnpm dev` = `concurrently client:dev + server:dev`, коллаб НЕ включён — верно; `collab:dev` = `node dist/collaboration/server/collab-main` (собранный dist, не tsx/ts-node) — «сначала build» верно; `pnpm --filter server migration:latest` = `tsx src/database/migrate.ts latest` — имя скрипта верно. - `page_embeddings`-миграция делает `CREATE EXTENSION IF NOT EXISTS vector` → требование pgvector (`pgvector/pgvector:pg18`) верно; стоковый postgres упадёт. - `COLLAB_PORT` default 3001 (`process.env.COLLAB_PORT || 3001`), PORT/3000 — верно; APP_SECRET: коллаб `onAuthenticate`→`verifyJwt(token, JwtType.COLLAB)` с `getAppSecret()`, ошибка `Invalid collab token` — строка реальна (гочи #3 верна). - Клиент `getCollaborationUrl()` при заданном `COLLAB_URL` конектится напрямую на `:3001/collab`, мимо Vite `/collab`-прокси; три прокси (`/api`,`/socket.io`,`/collab`)→APP_URL — гочи #1/#4 консистентны. - `Spoiler` — реальный экспорт `@docmost/editor-ext` (гочи #5 правдоподобна). Врезки в AGENTS.md совпадают с существующей секцией Architecture (два серверных процесса). Мелкая неточность (не блокер, кодеру не обязательно): гочи #1 называет `http://localhost:3001` «дефолтом» COLLAB_URL, тогда как код при НЕзаданном `COLLAB_URL` фолбэчится на `APP_URL(:3000)/collab`; но их же `.env`-пример ставит `COLLAB_URL=http://localhost:3001`, а дефолт `COLLAB_PORT` действительно 3001 — на практике инструкция верна, wrong-command-дефекта нет. Замечание: этот PR НЕ закрывает отдельный вопрос про AGENTS.md (2 vs 3 вендоренных копии схемы) — это другая правка. Объективные проверки: docs-only, исполняемого кода/тестов нет — гейта проверок нет; технические утверждения верифицированы чтением против кодовой базы. Маркер `reviewed_head` обновлён на `ef173f022`.

agent_reviewer added review/approved and removed review/needs labels 2026-07-01 03:42:47 +03:00

vvzvlad merged commit 2524f39a36 into develop

2026-07-01 18:32:37 +03:00

vvzvlad referenced this issue from a commit

2026-07-01 18:32:37 +03:00

Merge pull request 'docs: how to bring up a local dev stand (+ gotchas), referenced from AGENTS.md' (#272) from docs/dev-stand-guide into develop

Sign in to join this conversation.

2 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: vvzvlad/gitmost#272