diff --git a/.devbox b/.devbox index 3fb5737..1365ce3 100644 --- a/.devbox +++ b/.devbox @@ -1,7 +1,7 @@ # .devbox-project — тег проекта для Trello-задач (task-manager pipeline, ранее .trello-project). # Сгенерировано scripts/task-manager/init.sh. Без секретов — можно коммитить. # BOARD/LIST — дефолтные доска/лист (точные имена); запоминаются через create.sh --save-defaults. -NAME=Web2Bizz/devbox-backend +NAME=Web2Bizz/rush-code PROFILE_MONOREPO=yes PROFILE_MICROSERVICES=yes PROFILE_FRONTEND=react diff --git a/.dockerignore b/.dockerignore index b5bf86e..c1e86c8 100644 --- a/.dockerignore +++ b/.dockerignore @@ -13,5 +13,4 @@ npm-debug.log* **/tmp/opencode **/.opencode/.cache apps/mobile -apps/opencode-server contracts/ diff --git a/.env.develop b/.env.develop index f1dade3..e17dd34 100644 --- a/.env.develop +++ b/.env.develop @@ -6,4 +6,4 @@ # credentials, ...) — stays OUTSIDE git (repo vars / protected CI stores / # external environment). This file is the ONLY source of build values in CI # (no vars-override). Never add sensitive values here. -NEXT_PUBLIC_API_URL=https://devbox-app-ijn8k6-backend-194-163-150-160.sslip.io +NEXT_PUBLIC_API_URL=https://rush-code-app-ijn8k6-backend-194-163-150-160.sslip.io diff --git a/.env.example b/.env.example index b9fdccb..ef6dfbf 100644 --- a/.env.example +++ b/.env.example @@ -2,8 +2,8 @@ # Validation rules (zod@4, ERROR vs WARN taxonomy, [env] format, never-log-secrets): # docs/env-validation.md — enforced by apps/backend/src/env.ts + env.spec.ts. # Precedence everywhere: shell process.env > .env file > built-in defaults. -# Interpolation: ${VAR} / ${VAR:-default} (dotenv-expand / docker-compose / ecosystem.config.cjs). -# Empty HOSTs fall back to `localhost` in code (backend src/env.ts) and pm2 defaults, +# Interpolation: ${VAR} / ${VAR:-default} (dotenv-expand / docker-compose / scripts/dev/with-env.ts). +# Empty HOSTs fall back to `localhost` in code (backend src/env.ts) and dev defaults, # so the composites below never boot as broken `http://:`. # # DEV (local .env): leave APP_BACKEND_HOST empty and either @@ -11,10 +11,9 @@ # code fills localhost dev-fallbacks (DB via POSTGRES_*/localhost composition). # Compose has no local postgres service: DATABASE_URL is REQUIRED there # (fail-fast, external postgres only). -# OPENCODE_* ships with stand defaults below (0.0.0.0:4096). # PROD (external env / Dokploy): set DATABASE_URL to the external postgres URL # (or set POSTGRES_HOST to the real host, e.g. pg.db.web2bizzz.store, -# and let DATABASE_URL compose from POSTGRES_* for host-local/PM2 runs — +# and let DATABASE_URL compose from POSTGRES_* for host-local runs — # compose itself still requires DATABASE_URL explicitly), # and set APP_BACKEND_SOCKET / NEXT_PUBLIC_API_URL to the public backend URL. # Compose reads a SINGLE docker-compose.yml; there are no @@ -28,48 +27,44 @@ APP_BACKEND_HOST= APP_BACKEND_PROTOCOL=http APP_BACKEND_SOCKET=${APP_BACKEND_PROTOCOL}://${APP_BACKEND_HOST}:${APP_BACKEND_PORT} - -# OpenCode connection data (stand: `opencode serve` listens on 0.0.0.0:4096 — -# all interfaces. The composed URL keeps 0.0.0.0 verbatim; the backend remaps -# it to 127.0.0.1 for outbound dialing in OpencodeService.dialUrl()). -OPENCODE_HOST=0.0.0.0 -OPENCODE_PORT=4096 -OPENCODE_PROTOCOL=http -OPENCODE_URL=${OPENCODE_PROTOCOL}://${OPENCODE_HOST}:${OPENCODE_PORT} -# Optional bearer token for the opencode server ('' = unauthenticated). -# Sent as `Authorization: Bearer …` by the sdk reverse-proxy (/api/opencode/*). -# Never logged, never committed — set locally / via secrets only. -# OPENCODE_TOKEN= -# Server password for the opencode service in docker-compose (REQUIRED there — -# compose fail-fasts if unset; host-local `opencode serve` takes it via env too). -# Inside the compose network the backend reaches opencode at -# http://opencode:4096 (compose default) — an explicit OPENCODE_URL above -# overrides it, so leave OPENCODE_* unset for `docker compose up`. -# OPENCODE_SERVER_PASSWORD= - -# Per-user OpenCode keys (GET/PUT/DELETE /api/v1/key + GET /api/v1/usage). +# Per-user vault secrets (GET/POST/PUT/DELETE /api/v1/vault/secrets + GET /api/v1/usage). # Each user stores their OWN opencode.ai API key; the backend keeps ONLY the -# AES-256-GCM ciphertext (user_opencode_keys table) and proxies usage with the +# AES-256-GCM ciphertext (vault_secrets table) and proxies usage with the # per-user Bearer. Plaintext keys are never logged, never returned. -# OPENCODE_KEYS_ENCRYPTION_KEY: server secret for at-rest encryption (≥32 chars, -# REQUIRED for the key endpoints — unset → they answer 500 opencode_keys_unconfigured; -# short → boot ERROR). One key per deploy, no rotation/re-encrypt in this iteration. +# OPENCODE_KEYS_ENCRYPTION_KEY: ACTIVE server secret for at-rest encryption +# (≥32 chars, REQUIRED for the key endpoints — unset → they answer 500 +# opencode_keys_unconfigured; short → boot ERROR). New rows are wrapped with +# it under OPENCODE_KEYS_ACTIVE_KEY_ID ("v1" default). # Generate: bun -e "console.log(require('node:crypto').randomBytes(48).toString('base64url'))". # Never log it, never commit it — set locally / via secrets only. # OPENCODE_KEYS_ENCRYPTION_KEY= -# OPENCODE_BILLING_URL: upstream usage endpoint (GET, per-user Bearer). -# Default https://api.opencode.ai/usage is UNVERIFIED (no public billing path was -# discoverable) — override when the real endpoint is known. Unreachable/bad-shape -# upstream answers 503 EXTERNAL_UNAVAILABLE (Retry-After 30), timeouts 504. -# OPENCODE_BILLING_URL=https://api.opencode.ai/usage +# KEK rotation (no downtime, no data loss): +# 1. Deploy the new secret as OPENCODE_KEYS_ENCRYPTION_KEY (+ bump +# OPENCODE_KEYS_ACTIVE_KEY_ID, e.g. "v2") and keep the old secret as +# OPENCODE_KEYS_ENCRYPTION_KEY_PREVIOUS (+ OPENCODE_KEYS_PREVIOUS_KEY_ID +# matching the old rows). Old rows keep decrypting (dual-read by key_id; +# version-less legacy rows fall back to active → previous). +# 2. Converge: GET /api/v1/usage lazily re-wraps stale rows on read; run +# `bun run keys:reencrypt` (backend package script) for rows never read. +# 3. Drop OPENCODE_KEYS_ENCRYPTION_KEY_PREVIOUS once no stale rows remain. +# (stale = vault_secrets.key_id != active id). +# OPENCODE_KEYS_ACTIVE_KEY_ID=v1 +# OPENCODE_KEYS_ENCRYPTION_KEY_PREVIOUS= +# OPENCODE_KEYS_PREVIOUS_KEY_ID=v0 +# OPENCODE_BILLING_URL removed (breaking): the upstream usage endpoint is a +# hard-coded module constant (apps/backend/src/opencode/modules/billing/opencode-billing.service.ts +# OPENCODE_BILLING_URL = https://opencode.ai/zen/go/v1/usage — Zen Go, per spec +# https://opencode.ai/v2/docs/api has no billing surface) — env override is no +# longer read. Unreachable/bad-shape upstream answers 503 EXTERNAL_UNAVAILABLE +# (Retry-After 30), timeouts 504. # Postgres — always EXTERNAL (no postgres service in docker-compose). # Compose requires DATABASE_URL explicitly (fail-fast when unset). -# Host-local / PM2 runs may leave DATABASE_URL unset and let the backend -# compose it from POSTGRES_* (POSTGRES_HOST empty → localhost dev fallback). -POSTGRES_USER=devbox +# Host-local dev runs (nx `bun run dev`, dotenv without path) may leave +# DATABASE_URL unset and let the backend compose it from POSTGRES_* +POSTGRES_USER=rushcode POSTGRES_PASSWORD=changeme -POSTGRES_DB=devbox +POSTGRES_DB=rushcode POSTGRES_PORT=5432 POSTGRES_HOST=pg.db.web2bizzz.store @@ -89,13 +84,16 @@ REQUEST_TIMEOUT_MS=10000 # JWT_REFRESH_SECRET= # JWT_ACCESS_TTL=15m (formats: 15m | 1h | 7d | seconds 60-7776000) # JWT_REFRESH_TTL=7d -# Legacy x-user-id / ?userId mock identity fallback (dev default unset→true+WARN). -# Set "false" for production (JwtAuthGuard then requires Bearer everywhere). -# AUTH_LEGACY_MOCK_FALLBACK=true +# Legacy x-user-id / ?userId mock identity fallback (strict default unset→false+WARN: +# JwtAuthGuard requires Bearer everywhere). Set "true" for local dev only (WARN, +# never for production — header/query spoofing is ignored by all controllers). +# AUTH_LEGACY_MOCK_FALLBACK=false +# Session cookie SameSite policy: lax (default) | strict | none. +# "none" forces Secure regardless of NODE_ENV (needed for cross-site cookies). +# AUTH_COOKIE_SAMESITE=lax -# Organizations: single-use invite-token TTL in seconds (default 86400 = 24h, -# range 60-7776000). No per-invite override — one server-wide policy. -# ORG_INVITE_TTL_SEC=86400 +# Organizations: invites are persistent uuidv7 rows (no TTL — links never +# expire, single-use, replay → 404). No env tuning. # Upstream retry: idempotent GET + 429/5xx/timeout only (POST runs once; # backoff base doubles per attempt, capped at max, equal jitter). @@ -123,6 +121,14 @@ PROJECTS_ROOT= # Must exist + be readable when set explicitly, otherwise boot fails fast with [env] REPOS_ROOT. # REPOS_ROOT= +# Clone source allow-list (POST /api/v1/workspaces/clone): only https://, ssh:// +# and git@host:path URLs whose host matches the list are accepted. file://, +# http://, git://, absolute local paths and ../ are rejected with +# 400 REPO_URL_NOT_ALLOWED; the clone destination is jailed to REPOS_ROOT (403). +# Built-in hosts (always allowed, exact match): github.com, gitlab.com, bitbucket.org. +# CLONE_ALLOWED_HOSTS appends extra bare hostnames (comma-separated). +# CLONE_ALLOWED_HOSTS= + # GitHub link (optional defaults only — tokens are NEVER stored; link endpoints # validate owner/repo/branch format and assemble https://github.com URLs) # GITHUB_OWNER= @@ -140,15 +146,20 @@ PROJECTS_ROOT= # empty pair → github endpoints answer 401/503. # GITHUB_APP_ID=123456 # Preferred: keep the PEM out of env — point at a file (avoids multiline -# quoted PEM breaking dotenv/compose/pm2 parsers). Path wins when set; may be +# quoted PEM breaking dotenv/compose parsers). Path wins when set; may be # absolute or relative to the backend cwd (e.g. ./keys/github-app.pem). # GITHUB_APP_PRIVATE_KEY_PATH=./keys/github-app.pem # Fallback: inline key (raw PEM with \n escapes ok, or base64-encoded PEM). # GITHUB_APP_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----" # (raw PEM, \n escapes ok, or base64-encoded PEM) -# GITHUB_APP_SLUG=my-devbox-app (https://github.com/apps//installations/new) +# GITHUB_APP_SLUG=my-rush-code-app (https://github.com/apps//installations/new) # GITHUB_WEBHOOK_SECRET=change-me (must match the App webhook secret; X-Hub-Signature-256) +# GITHUB_STATE_SECRET=change-me (optional: HMAC key for the signed install state; +# empty → falls back to GITHUB_WEBHOOK_SECRET) # GITHUB_API_URL=https://api.github.com (override for GitHub Enterprise) +# Per-attempt budget ms for GitHub API calls (default 15000; positive int). +# Enforced via AbortSignal.timeout — octokit@5 ignores request.timeout. +# GITHUB_REQUEST_TIMEOUT_MS=15000 # Legacy dev fallback (deprecated, single install without the install flow): # GITHUB_APP_INSTALLATION_ID=789012 @@ -223,9 +234,9 @@ NEXT_PUBLIC_API_URL=${APP_BACKEND_SOCKET} # Frontend UI kit: @web2bizz/ui pinned exact in apps/frontend/package.json # (currently 0.25.7 — bump via `bun add @web2bizz/ui@` in apps/frontend). # Peer deps: react>=19, react-dom>=19 (frontend is on React 19; do NOT -# downgrade to 18 — the kit's ThemeProvider/components require 19). -# Consumer wiring: `@web2bizz/ui/styles.css` once in app/layout.tsx + -# via src/providers.tsx (mount-guarded for SSR). +# downgrade to 18 — the kit's components require 19). +# Consumer wiring: `@web2bizz/ui/styles.css` once in app/layout.tsx +# (no — NOT SSR-safe, mount-guard banned). # Full registry/auth/publish guide: docs/npm-registry.md. # # CI-only: Dokploy compose redeploy (НЕ читается compose/backend — только @@ -235,3 +246,8 @@ NEXT_PUBLIC_API_URL=${APP_BACKEND_SOCKET} # создать webhook в Dokploy (Compose → Deployments → Webhook) и добавить его # URL как GitHub secret. Локально не нужен (намеренно закомментировано). # DOKPLOY_COMPOSE_WEBHOOK= +# +# Web-поиск для агентов: pack-тул `tavily` (Tavily Search API). +# Ключ — только env, в git не коммитится: console.tavily.com → API Keys (tvly-...). +# Без ключа тул падает с понятной ошибкой, агенты откатываются на `websearch`. +# TAVILY_API_KEY= diff --git a/.github/workflows/activation-e2e.yml b/.github/workflows/activation-e2e.yml index d6c4642..e1cdc92 100644 --- a/.github/workflows/activation-e2e.yml +++ b/.github/workflows/activation-e2e.yml @@ -33,19 +33,19 @@ name: Activation E2E (Maestro) # devices against a real server, so asserting on it here would be asserting # on the harness rather than the app. # -# NOTE: this workflow intentionally has NO `push:` trigger. The pull_request -# check is the only gate for the activation suite. With `push:` present the -# same commit was tested twice — once as pull_request, and then again as `push` -# to dev/main the moment the PR merged — and the emulator jobs below are -# budgeted by the tens of minutes, so that second run was a full duplicate of -# a suite that had already passed on that exact tree. Removing `push:` means a -# direct push to dev/main (i.e. bypassing a PR) will NOT run E2E. +# POLICY: no APK assembly on pull_request. The PR stage runs only fast checks +# (mobile.yml `test` + ci.yml lint/build/test); the emulator suite below needs +# a freshly assembled APK, so it runs ONLY after merge — on `push` to +# dev/main — exactly once per merged tree. With a `pull_request` trigger the +# same tree would pay emulator time twice (tens of minutes per half), so it +# is deliberately absent here. # -# That is deliberate, not a hole: neither branch is protected today, but branch -# protection is the documented way to make the PR check mandatory, and once it -# is enabled every change to dev/main must arrive through a pull_request — -# exactly where this workflow runs. Until then, workflow_dispatch stays the -# manual escape hatch for an on-demand run. +# Direct pushes to dev/main (bypassing a PR) WILL run E2E — that is the price +# of the post-merge gate, not a hole. Neither branch is protected today, but +# once branch protection is enabled every change must arrive through a +# pull_request, and the fast checks above are the mandatory PR gate (do NOT +# list apk/core/newer as required PR checks — they never report on a PR). +# workflow_dispatch stays the manual escape hatch for an on-demand run. # # WHY THIS IS THREE JOBS (and not one 90-minute job anymore): # The old single job was CANCELLED at its timeout-minutes: 90 ceiling on run @@ -76,7 +76,7 @@ name: Activation E2E (Maestro) # suite behaviour in the middle of a flake investigation). on: - pull_request: + push: branches: [main, dev] paths: - "apps/mobile/app/**" @@ -294,7 +294,7 @@ jobs: # ===================================================================== # core — the regression gate. Boots ONE emulator, runs CORE_FLOWS only # (run-e2e-flows.sh core: blocking semantics, break-on-failure, rc=1). - # Runs in PARALLEL with `newer`; its failure blocks the PR check, its + # Runs in PARALLEL with `newer`; its failure fails the post-merge run, its # artifacts are independent of newer's. # ===================================================================== core: diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index c592bec..9323f8e 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -1,64 +1,31 @@ name: ci -# Monorepo (backend + frontend bun workspace). apps/mobile is intentionally NOT -# covered here: it is a standalone npm/Expo project with its own package-lock.json -# and its own workflows (mobile.yml, activation-e2e.yml). on: push: - paths: - - "apps/backend/**" - - "apps/frontend/**" - - "package.json" - - "bun.lock" - - "bunfig.toml" - - ".npmrc" - - ".bun-version" - - "tsconfig.base.json" - - ".github/workflows/ci.yml" + branches: [main] pull_request: - paths: - - "apps/backend/**" - - "apps/frontend/**" - - "package.json" - - "bun.lock" - - "bunfig.toml" - - ".npmrc" - - ".bun-version" - - "tsconfig.base.json" jobs: - build: + quality: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v4 - with: - fetch-depth: 0 + - uses: actions/checkout@v5 - uses: oven-sh/setup-bun@v2 with: - # Single source of truth for the pin is .bun-version - # (mirrored in packageManager/engines/oven-bun Docker tags). - bun-version-file: ".bun-version" + bun-version: 1.4.2 - name: Install - run: bun install - env: - # Private scope @web2bizz → https://npm.registry.web2bizz.team. - # GitHub masks secrets.* in logs automatically; empty → public-only install. - NPM_TOKEN: ${{ secrets.NPM_TOKEN }} + run: bun install --frozen-lockfile - - uses: nrwl/nx-set-shas@v4 - id: setshas - with: - main-branch-name: main + - name: Typecheck + run: bun run typecheck - # no-console in backend src is enforced by biome (backend lint script), - # scoped to runtime sources — spec/e2e/test reporters are excluded. - - name: Lint affected (tsc --noEmit) - run: bunx nx affected -t lint --base=${{ steps.setshas.outputs.base }} --head=${{ steps.setshas.outputs.head }} + - name: Lint + run: bun run lint - - name: Build affected - run: bunx nx affected -t build --base=${{ steps.setshas.outputs.base }} --head=${{ steps.setshas.outputs.head }} + - name: Test + run: bun run test - - name: Test affected - run: bunx nx affected -t test --base=${{ steps.setshas.outputs.base }} --head=${{ steps.setshas.outputs.head }} + - name: Build + run: bun run build \ No newline at end of file diff --git a/.github/workflows/docker.yml b/.github/workflows/docker.yml index 06b5fd0..0b9be66 100644 --- a/.github/workflows/docker.yml +++ b/.github/workflows/docker.yml @@ -16,15 +16,14 @@ name: Docker # .env.production; триггер сейчас dev + dispatch — для main оставлена # готовность маппинга, новый триггер НЕ добавлялся). Файл — ЕДИНСТВЕННЫЙ # источник build-значений (vars-override нет; CHANGEME из файла никогда -# не запекается — guard падает fail-fast). Версия opencode ниоткуда не -# пробрасывается — берётся дефолт Dockerfile (ARG OPENCODE_VERSION). +# не запекается — guard падает fail-fast). # Compose runtime по-прежнему читает ТОЛЬКО внешнее окружение (см. шапку # docker-compose.yml): чувствительное (DATABASE_URL, пароли, токены, # webhook) — через secrets/vars/compose `:?`, в `.env.develop`/ # `.env.production` ему места нет. # - needs-цепочка внутри этого workflow, а не отдельный workflow_run: -# deploy видит outputs affected-матрицы/opencode-фильтра и пропускается -# при пустой публикации; workflow_run не имел бы к ним доступа. +# deploy видит outputs affected-матрицы и пропускается при пустой +# публикации; workflow_run не имел бы к ним доступа. # Required configuration: # secrets.DOCKER_REGISTRY_PASSWORD ... пароль registry (логин: app) # secrets.NPM_TOKEN ................ приватный npm registry (@web2bizz/*) @@ -34,14 +33,7 @@ name: Docker # CI-only блок в .env.example). # Нейминг — через ./.github/actions/resolve-names: ORG/REPO/SERVICE # Сервисы ищутся в apps/* и services/* (монорепозиторий). -# NOTE(apps/opencode-server): opencode-server НЕ входит в affected-матрицу -# (у него нет package.json — не Nx-проект, в `nx show projects --affected` -# не появляется, плюс его Dockerfile собирается своим контекстом, а не -# корнем `.`), поэтому собирается ниже отдельным job'ом `opencode` вне -# матрицы (Dockerfile apps/opencode-server/Dockerfile, контекст -# apps/opencode-server, нейминг через resolve-names: -# REGISTRY/OWNER/REPO/opencode). Корневой -# docker-compose.yml при этом тянет ВСЕ образы из registry (тег через `TAG`, +# Корневой docker-compose.yml тянет ВСЕ образы из registry (тег через `TAG`, # дефолт `:latest`; локальных build'ов в compose нет). Публикуемые образы — # для Dokploy-деплоев, забирающих готовые образы из registry. # NOTE(bun): адаптация шаблона @web2bizz/scaffold под bun-монорепо — @@ -104,14 +96,6 @@ jobs: run: | DISCOVERED='${{ steps.discover.outputs.services }}' echo "Discovered services (apps/*, services/*): $DISCOVERED" - # opencode-server собирается отдельным job'ом `opencode` (свой - # build-контекст apps/opencode-server, не корень `.`) — из общей - # матрицы исключён всегда: иначе ручной запуск (matrix=DISCOVERED) - # и Nx-fail-safe собрали бы его с неверным контекстом и дважды - # (дубль job'а `opencode`). В affected-ветке исключение no-op: - # без package.json это не Nx-проект и в пересечение не попадает. - DISCOVERED=$(echo "$DISCOVERED" | python3 -c "import json,sys; print(json.dumps([s for s in json.load(sys.stdin) if s != 'opencode-server']))") - echo "Docker services (opencode-server excluded): $DISCOVERED" if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then # ручной запуск — все сервисы из discover echo "matrix=$DISCOVERED" >> "$GITHUB_OUTPUT" @@ -239,129 +223,22 @@ jobs: secrets: | NPM_TOKEN=${{ secrets.NPM_TOKEN }} - # apps/opencode-server — не Nx-проект (нет package.json) и собирается - # своим контекстом, поэтому вне affected-матрицы по дизайну: явный job - # ниже, при push — только если затронуты apps/opencode-server/** или сам - # workflow; при ручном запуске — всегда. В discovery (apps/*) он появится, - # но affected-пересечение его отсекает (как mobile) — двойной сборки нет. - opencode-filter: - runs-on: ubuntu-latest - outputs: - build: ${{ steps.check.outputs.build }} - steps: - - name: Checkout code - uses: actions/checkout@v4 - with: - fetch-depth: 0 - submodules: recursive - - - name: Check whether opencode needs a build - id: check - run: | - if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then - echo "build=true" >> "$GITHUB_OUTPUT" - exit 0 - fi - BEFORE="${{ github.event.before }}" - if [ -z "$BEFORE" ] || [ "$BEFORE" = "0000000000000000000000000000000000000000" ]; then - # неизвестная база (новая ветка/форс-пуш) — fail-safe: собираем - echo "build=true" >> "$GITHUB_OUTPUT" - exit 0 - fi - if git diff --name-only "$BEFORE" "${{ github.sha }}" -- apps/opencode-server .github/workflows/docker.yml | grep -q .; then - echo "build=true" >> "$GITHUB_OUTPUT" - else - echo "build=false" >> "$GITHUB_OUTPUT" - fi - - opencode: - needs: [opencode-filter] - if: needs.opencode-filter.outputs.build == 'true' - runs-on: ubuntu-latest - env: - REGISTRY: docker.registry.web2bizz.team - steps: - - name: Checkout code - uses: actions/checkout@v4 - with: - fetch-depth: 0 - submodules: recursive - - - name: Resolve registry names - id: names - uses: ./.github/actions/resolve-names - with: - registry: ${{ env.REGISTRY }} - service: opencode - - - name: Set up Docker Buildx - uses: docker/setup-buildx-action@v3 - - - name: Log in to Docker Registry - uses: docker/login-action@v3 - with: - registry: ${{ env.REGISTRY }} - username: app - password: ${{ secrets.DOCKER_REGISTRY_PASSWORD }} - - - name: Docker metadata - id: meta - uses: docker/metadata-action@v5 - with: - images: ${{ steps.names.outputs.service_image_path }} - tags: | - type=ref,event=branch - type=sha,prefix= - type=raw,value=latest - - - name: Load build-time env file - run: | - case "${{ github.ref_name }}" in - main) ENV_FILE=.env.production ;; - *) ENV_FILE=.env.develop ;; - esac - test -f "$ENV_FILE" || { echo "::error::$ENV_FILE is missing — tracked build-time env files (.env.develop/.env.production) must exist"; exit 1; } - echo "Loading build-time env from $ENV_FILE (branch ${{ github.ref_name }})" - set -a - # shellcheck disable=SC1090 - . "./$ENV_FILE" - set +a - # No version passthrough: opencode builds with the Dockerfile - # default (ARG OPENCODE_VERSION). The file is sourced whole for - # future build-time values. - - - name: Build and push opencode image - uses: docker/build-push-action@v6 - with: - context: apps/opencode-server - file: apps/opencode-server/Dockerfile - push: true - tags: ${{ steps.meta.outputs.tags }} - labels: ${{ steps.meta.outputs.labels }} - cache-from: type=gha - cache-to: type=gha,mode=max - # No build-args: apps/opencode-server/Dockerfile declares - # ARG OPENCODE_VERSION with its own default — the image builds - # with that version, nothing is passed from CI. - # Redeploy всего compose-стека в Dokploy одним POST на webhook # compose-сущности (сценарий `compose` шаблона — см. шапку файла). # Запускается только если что-то реально опубликовано (непустая affected- - # матрица или opencode-билд) и никто не упал; иначе скипается молча. + # матрица) и никто не упал; иначе скипается молча. # Ручной workflow_dispatch публикует всё + триггерит redeploy (escape hatch). deploy: name: Trigger Dokploy compose redeploy - needs: [affected, docker, opencode-filter, opencode] - # always(): docker/opencode скипаются при пустой матрице/фильтре — + needs: [affected, docker] + # always(): docker скипается при пустой матрице — # без always() deploy тоже скипался бы и условие не вычислилось бы. if: >- always() && needs.affected.result == 'success' && - needs.opencode-filter.result == 'success' && (needs.docker.result == 'success' || needs.docker.result == 'skipped') && - (needs.opencode.result == 'success' || needs.opencode.result == 'skipped') && - ((needs.affected.outputs.matrix != '[]' && needs.affected.outputs.matrix != '') || - needs.opencode-filter.outputs.build == 'true') + needs.affected.outputs.matrix != '[]' && + needs.affected.outputs.matrix != '' runs-on: ubuntu-latest steps: - name: Redeploy compose stack diff --git a/.github/workflows/product-intelligence.yml b/.github/workflows/product-intelligence.yml deleted file mode 100644 index 8e91634..0000000 --- a/.github/workflows/product-intelligence.yml +++ /dev/null @@ -1,137 +0,0 @@ -name: Daily Product Intelligence - -# Monorepo: schedule/dispatch only, so there is no push/pull_request `paths` -# filter to add. The scripts it runs are apps/mobile-local. -on: - workflow_dispatch: - schedule: - # 06:00 UTC daily - - cron: "0 6 * * *" - -# Monorepo: scripts/product-intelligence*.mjs live in apps/mobile. -defaults: - run: - working-directory: apps/mobile - -permissions: - actions: read - contents: read - issues: write - -concurrency: - group: product-intelligence-${{ github.ref }} - cancel-in-progress: false - -jobs: - report: - runs-on: ubuntu-latest - timeout-minutes: 10 - steps: - - uses: actions/checkout@v6 - - - uses: actions/setup-node@v6 - with: - node-version: 24 - - - name: Test product-signal classification - run: node --test scripts/product-intelligence.test.mjs - - - name: Collect aggregate product signals - id: collect - continue-on-error: true - env: - GITHUB_TOKEN: ${{ github.token }} - run: | - node scripts/product-intelligence.mjs \ - --report "$RUNNER_TEMP/product-intelligence.md" \ - --json "$RUNNER_TEMP/product-intelligence.json" - - - name: Create material-signal issue - if: always() - uses: actions/github-script@v8 - env: - REPORT_PATH: ${{ runner.temp }}/product-intelligence.json - with: - script: | - const fs = require("fs") - - if (!fs.existsSync(process.env.REPORT_PATH)) { - core.setFailed("Product intelligence collector produced no report.") - return - } - - const report = JSON.parse(fs.readFileSync(process.env.REPORT_PATH, "utf8")) - const allowedSignals = new Set([ - "repeated-workflow-failure", - ]) - const validDate = typeof report.date === "string" && /^\d{4}-\d{2}-\d{2}$/.test(report.date) - const validSignals = Array.isArray(report.signals) && - report.signals.length > 0 && - report.signals.every((signal) => allowedSignals.has(signal)) - - if (!report.material) { - core.info("No material signal. No GitHub issue created.") - return - } - if (!validDate || !validSignals) { - core.setFailed("Collector report failed public issue allowlist validation.") - return - } - - const issues = await github.paginate(github.rest.issues.listForRepo, { - owner: context.repo.owner, - repo: context.repo.repo, - state: "open", - per_page: 100, - }) - const title = "Product intelligence: material signal" - const marker = `` - const body = [ - marker, - "", - "## Material aggregate signal", - "", - `The daily product-intelligence run detected: ${[...report.signals].sort().join(", ")}.`, - "", - "This issue intentionally contains no raw diagnostic, review, request, or user-generated content. Review the sanitized Actions artifact and reproduce the behavior in the affected user channel before implementing a fix.", - ].join("\n") - const existing = issues.find((issue) => issue.title === title) - - if (existing) { - await github.rest.issues.update({ - owner: context.repo.owner, - repo: context.repo.repo, - issue_number: existing.number, - title, - body, - }) - core.info(`Updated #${existing.number}.`) - return - } - - const { data: issue } = await github.rest.issues.create({ - owner: context.repo.owner, - repo: context.repo.repo, - title, - body, - labels: ["P1"], - }) - core.info(`Created #${issue.number}.`) - - - name: Upload sanitized report - if: always() - uses: actions/upload-artifact@v7 - with: - name: product-intelligence-${{ github.run_id }} - path: | - ${{ runner.temp }}/product-intelligence.md - ${{ runner.temp }}/product-intelligence.json - if-no-files-found: error - - - name: Fail when a required source is unavailable - # scripts/product-intelligence.mjs only sets a non-zero exit code for - # a genuinely required-source failure (GitHub unavailable). - if: steps.collect.outcome == 'failure' - run: | - echo "::error::A required product-intelligence source was unavailable. See the report summary for the exact source and error." - exit 1 diff --git a/.github/workflows/triage-reviews.yml b/.github/workflows/triage-reviews.yml deleted file mode 100644 index fc14de7..0000000 --- a/.github/workflows/triage-reviews.yml +++ /dev/null @@ -1,44 +0,0 @@ -name: Play Store Review Triage - -# Monorepo: schedule/dispatch only, so there is no push/pull_request `paths` -# filter to add. scripts/triage-reviews.py lives in apps/mobile. -on: - workflow_dispatch: - schedule: - # 07:00 UTC daily (staggered after Daily Product Intelligence at 06:00 UTC) - - cron: "0 7 * * *" - -# Monorepo: the triage script is apps/mobile-local. -defaults: - run: - working-directory: apps/mobile - -permissions: - contents: read - issues: write - -concurrency: - group: triage-reviews-${{ github.ref }} - cancel-in-progress: false - -jobs: - triage: - runs-on: ubuntu-latest - timeout-minutes: 10 - steps: - - uses: actions/checkout@v6 - - - uses: actions/setup-python@v5 - with: - python-version: "3.12" - - - name: Install dependencies - run: pip install google-auth google-auth-httplib2 google-api-python-client - - - name: Triage Play Store reviews - env: - # Repo secret is named PLAY_STORE_SERVICE_ACCOUNT_JSON (see docs/playstore.md); - # mapped here to the env var name the script expects. - GOOGLE_SERVICE_ACCOUNT_JSON: ${{ secrets.PLAY_STORE_SERVICE_ACCOUNT_JSON }} - GH_TOKEN: ${{ secrets.GH_TOKEN || secrets.GITHUB_TOKEN }} - run: python scripts/triage-reviews.py diff --git a/.gitignore b/.gitignore index 3aa7a3b..49adb26 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1,6 @@ -# graphify — индексы вне репо (/tmp/opencode), на случай in-repo кеша — игнор +# graphify — индексы в проекте (.graphify/ — персистентно, переживает reboot /tmp; graphify-out/ — граф знаний и кеш), в git не отправлять .graphify/ +graphify-out/ .tmp/ tmp/opencode/ .opencode/.cache/ @@ -34,8 +35,7 @@ build/ *.tgz # GitHub App private key (file-based, never commit the PEM) -keys/ -keys/*.pem +/keys/ *.pem # Logs @@ -52,7 +52,7 @@ npm-debug.log* # Docker / misc .docker/ -# Devbox workspace +# Rush Code workspace workspace/** !workspace/.gitkeep @@ -69,3 +69,7 @@ apps/backend/repos/** apps/mobile/.supervisor/ apps/mobile/.autopilot/ apps/mobile/.playwright-mcp/ +.playwright-mcp/ + +# Tavily research captures (local cache, not repo content) +.tavily/** \ No newline at end of file diff --git a/.husky/commit-msg b/.husky/commit-msg new file mode 100755 index 0000000..da99483 --- /dev/null +++ b/.husky/commit-msg @@ -0,0 +1 @@ +npx --no -- commitlint --edit "$1" diff --git a/.husky/pre-commit b/.husky/pre-commit new file mode 100755 index 0000000..d0c0e08 --- /dev/null +++ b/.husky/pre-commit @@ -0,0 +1,2 @@ +bun run typecheck +bun run test diff --git a/.npmrc b/.npmrc index a3bf02d..81bf0f0 100644 --- a/.npmrc +++ b/.npmrc @@ -5,3 +5,5 @@ # Global auth in ~/.npmrc is left untouched — this file is project-level only. @web2bizz:registry=https://npm.registry.web2bizz.team/ //npm.registry.web2bizz.team/:_authToken=${NPM_TOKEN} +# legacy-peer-deps for npm/mobile standalone (bun ignores this flag); mobile inherits config up the tree. +legacy-peer-deps=true diff --git a/.opencode b/.opencode index b9ac5a0..975dee5 160000 --- a/.opencode +++ b/.opencode @@ -1 +1 @@ -Subproject commit b9ac5a089bd07c98e5f79e734cca20491b8dca44 +Subproject commit 975dee5e7208d72881c0bd4e126b682a81ce3afe diff --git a/.plans/agent-harness-prototype/PLAN.md b/.plans/agent-harness-prototype/PLAN.md new file mode 100644 index 0000000..d35c689 --- /dev/null +++ b/.plans/agent-harness-prototype/PLAN.md @@ -0,0 +1,728 @@ +# План прототипа агентской системы (по ADR-0001 Rev.6 / ADR-0002 Rev.2) + +> Источники: `docs/adr/0001-cloud-agent-harness.md` (Rev.6), `docs/adr/0002-agent-harness-prototype.md` (Rev.2). +> Глубина: Эпики + шаги (7 эпиков, БЕЗ нарезки на Trello-карточки). Без TCO/сроков — только scope + критерии готовности. +> forwardOnly: baseCommit `00c39` — не откатываться, только новый файл в `.plans/`. Код проекта не трогать. + +--- + +## §0. Связки (ADR → план, инварианты, решения) + +### 0.1. Таблица ADR → план + +| ADR-источник | Содержание | Эпик плана | +| --- | --- | --- | +| ADR-0001 §8.7.1 / ADR-0002 §6.1 | DDL `run_runs/run_steps/run_events/run_leases` (+ полные `run_effects/run_definitions` как ориентир) | E2 | +| ADR-0001 §8.7.2 / ADR-0002 §6.2 | REST `/api/runs*` (`CreateRunRequest`/`RunInfo`, C4, `VERSION_NEUTRAL`, `ZodValidationPipe`, `ApiError`) | E1 (схемы), E3 (API) | +| ADR-0001 §8.7.3 / ADR-0002 §6.3 | SSE-кадр `RunStreamFrame` (10 типов; прототип — 4), `relaySse` catch-up + live | E1 (схемы), E3 (endpoint), E4 (append), E6 (фронт) | +| ADR-0001 §8.1+§8.7.4 / ADR-0002 §6.4 | `ToolDescriptor` / `ToolView` (zod), политика в дескрипторе, префикс источника | E1 (схемы), E4 (реестр), E5 (enforcement) | +| ADR-0001 §9.8 / ADR-0002 §5 (диаграмма) | `ModelGateway` (1 провайдер, `tools?: ToolView[]`, `need`-флаги) | E4 | +| ADR-0001 §9.2 / ADR-0002 §6.1, D9 | Claim-loop `SKIP LOCKED`, `run_leases` упрощённые (без `epoch`, `TODO(full-fencing)`) | E2 (таблица), E4 (loop) | +| ADR-0001 §9.3 / ADR-0002 D8 | Dual-write `intent → confirm`, трейлер `(run_id, step_id)` как identity (`TODO(dual-write-reconcile)`) | E4 (intent в прототипе), §8 (отложено) | +| ADR-0001 §9.4 / ADR-0002 §6.1, §7-п.7 | `1 run = 1 ветка `agent/` + 1 worktree в jail`, `WorkspacePathService`, флаг «без сабмодулей» | E4 | +| ADR-0001 §9.6 / ADR-0002 D7 | Hot-reload данными (`definitions.active`), пиннинг `definition_set_hash` по `commit_sha` | E5 | +| ADR-0001 §9.7 / ADR-0002 D6 | Стриминг `relaySse` + курсор `seq`, probe-до-заголовков, `x-accel-buffering: no` | E3, E6 | +| ADR-0001 §18.2 (тонкий срез 7 шагов) / ADR-0002 §7 | Порядок сборки E1→E7, каждый шаг независимо проверяем | Структура настоящего плана | +| ADR-0001 §18.1 / ADR-0002 §7 | Сквозной критерий готовности | §9 | +| ADR-0001 §18.3 / ADR-0002 §8 | Отложенное с TODO-метками | §8 | +| ADR-0001 §16 / ADR-0002 §9 | Канон репо и образцы для переиспользования | reuse-блок в конце | + +### 0.2. Инварианты (обязательны для всех эпиков) + +| Инвариант | Формулировка | Где проверяется | +| --- | --- | --- | +| I1 | Воркеры stateless (состояние только в БД-журнале + git) | E4 (claim-loop без локального состояния между итерациями) | +| I2 | Два носителя состояния (БД-журнал + git-репозиторий) | E2 (журнал), E4 (ветка/worktree) | +| I3 | Event-driven, журнал — источник истины для восстановления | E2–E4, E7 (replay из журнала) | +| I4 | Стек TS/Node или Bun (факт: `bun@1.4.2`, NestJS 12, TS, `zod ^4.6.5`, `drizzle-orm ^0.45.3` + `pg ^8.12`, `nx`, `biome`; фронт Next.js 16.3 Turbopack, React Query) | Все эпики | +| I5 | Forward-Only: история `baseCommit` никогда не переписывается назад; допустим только рост (`revert`, новые коммиты), `reset --hard`/`push --force` запрещены | E4 (jail + deny-политика), §9 | +| I6 | Модулит: один деплоящийся NestJS-монолит (`processes/ → organizations/ → common/`); новые границы — только NestJS-модули (`/modules//`), отдельных микросервисов/service mesh/кросс-сервисных саг нет | E3–E4 (раскладка `processes/modules/runs/`, `processes/modules/workers/`) | + +### 0.3. Решения D1–D9 (ADR-0002 §3, итог) + +| # | Решение | Эпик-носитель | +| --- | --- | --- | +| D1 | Ядро V3: собственное event-sourced ядро на Postgres в монолите | E2–E4 | +| D2 | Исполнитель — существующий opencode-runner, без per-run ресурсов (логическая изоляция: jail + ветка/worktree + claim-loop + C4) | E4 | +| D3 | Инструменты — `ToolDescriptor` + проекция `ToolView` (модель видит только `{id,title,description,inputSchema,outputSchema?}`) | E1, E4, E5 | +| D4 | Инструкции — skills как git-артефакты, эффект наследуется от скриптов, enforcement `allowed-tools` — наше | E5 | +| D5 | MCP — только потребление: stateless-клиент + один `initialize`-фолбэк в прототипе; своего MCP-сервера нет (`TODO(mcp-dual-era)` на полный dual-era) | E4, §8 | +| D6 | Стриминг — `relaySse` + курсор `seq` из журнала | E3, E6 | +| D7 | Hot-reload — данными (`definitions.active`), пиннинг `definition_set_hash` на run | E5 | +| D8 | Dual-write — `intent → confirm`, трейлер как identity (полный reconcile — `TODO(dual-write-reconcile)`) | E4 (intent), §8 | +| D9 | Fencing в прототипе — упрощённый (`SKIP LOCKED`, `epoch` — `TODO`); прототип переживает только graceful-рестарт | E2, E4, §8 | + +--- + +## E1. Контракты-минимум + +**Цель.** Зафиксировать wire-контракт runs: типы + `zod v4` boundary-схемы + `openapi.yaml`-патч. Зеркало поле-в-поле (расхождение YAML ↔ пакет = баг пакета). + +**Scope.** + +Входит: + +- `packages/contracts/src/runs/runs.ts` — `export type` only (без `interface`): `RunStatus`, `RunStepStatus`, `RunStepType`, `RunInfo`, `RunInfoList`, `CreateRunRequest`, `RunStreamFrame` (4 типа прототипа), `ToolView`-реэкспорт/ссылка (полные `ToolDescriptor` — см. черновик, в прототипе фиксируем минимум для `ToolView`). +- `packages/contracts/src/runs/runs.schema.ts` — `zod v4` boundary-схемы (`satisfies z.ZodType<…>`): `runStatusSchema`, `runInfoSchema`, `createRunRequestSchema`, `runStreamFrameSchema` (+ 4 суженных фрейма при необходимости), `toolIdSchema`/`toolViewSchema`-минимум. +- `packages/contracts/src/runs/index.ts` — баррель домена. +- Патч `contracts/openapi.yaml`: `components/schemas` (`RunInfo`, `RunInfoList`, `CreateRunRequest`, `RunStreamFrame`, `ToolView`) + `paths /api/runs*` (минимум E3). +- `ApiError`-envelope без изменений (переиспользование `packages/contracts/src/api-error/`). + +Не входит: + +- Полный набор SSE-типов (остальные 6 — только схема + `TODO`, реализация в E3/E4 — заглушки типов без эмиссии). +- Полный `ToolDescriptor` с `transport/effects/limits/auth` валидацией на границе (фиксируем схему, enforcement — E4/E5). +- `run_effects`/`run_definitions` wire-типы (БД-ориентир E2, не публичный контракт прототипа). +- Биллинг/OTel-поля, per-run ресурсы, дашборды. + +**Пути файлов.** + +- Создать: `packages/contracts/src/runs/runs.ts`, `packages/contracts/src/runs/runs.schema.ts`, `packages/contracts/src/runs/index.ts`. +- Изменить: `packages/contracts/src/index.ts` (реэкспорт домена `runs`), `contracts/openapi.yaml` (патч схем + путей). +- Образцы стиля (читать, не менять): `packages/contracts/src/sessions/sessions.ts`, `packages/contracts/src/sessions/sessions.schema.ts`, `packages/contracts/src/sessions/index.ts`, `packages/contracts/AGENTS.md`. +- Проверки рядом: `packages/contracts` — `bun run lint` (`tsc --noEmit` + `biome lint`), `bun run build`, `bun run test` (юнит-тесты схем). + +**Черновик решения.** + +> DRAFT — опора для реализации, не финальный код. Источник: ADR-0001 §8.7.2–§8.7.4, ADR-0002 §6.2–§6.4. + +```ts +// packages/contracts/src/runs/runs.ts (DRAFT ~30 строк) +import type { SessionInfoModel } from '../sessions/sessions'; + +export type RunStatus = 'open' | 'running' | 'awaiting_human' | 'failed' | 'merged' | 'abandoned'; +export type RunStepStatus = 'pending' | 'running' | 'committed' | 'failed' | 'skipped'; +export type RunStepType = 'llm.call' | 'tool.call' | 'sandbox.exec' | 'git.commit' | 'await_human' | 'router'; + +export type RunInfo = { + id: string; // uuidv7 (Bun.randomUUIDv7()) + projectId: string; // uuid (C4-scope) + title: string | null; // explicit nullable, never optional + status: RunStatus; + definitionSetHash: string; // пин §9.6 ADR-0001 + baseCommit: string; // I5, sha + branch: string; // agent/ + agentId: string | null; // registry id, nullable как у sessions + model: SessionInfoModel | null; // reuse из sessions (never duplicate) + createdAt: string; // ISO-8601 Z + updatedAt: string; +}; +export type RunInfoList = Array; +export type CreateRunRequest = { + projectId: string; + title?: string; + agentId?: string; + model?: SessionInfoModel; + definitionSetHash?: string; // default: active-набор +}; + +// Прототип: только 4 типа кадров (остальные — схема + TODO) +export type RunStreamFrameTypeProto = 'run.started' | 'run.step.started' | 'run.step.committed' | 'run.step.failed'; +export type RunStreamFrame = { + id: string; // seq как строка, монотонный per-run + type: RunStreamFrameTypeProto; // frozen-расширение до полного union позже + data: Record; + run?: string; // hoisted run id (аналог session) +}; +``` + +```ts +// packages/contracts/src/runs/runs.schema.ts (DRAFT ~40 строк) +import { z } from 'zod'; +import type { CreateRunRequest, RunInfo, RunInfoList, RunStreamFrame } from './runs'; +import { sessionInfoModelSchema, agentIdSchema } from '../sessions/sessions.schema'; + +export const runStatusSchema = z.enum(['open', 'running', 'awaiting_human', 'failed', 'merged', 'abandoned']); +export const runInfoSchema = z.object({ + id: z.uuid({ error: 'Field "id" is required' }), + projectId: z.uuid({ error: 'Field "projectId" is required' }), + title: z.string().nullable(), + status: runStatusSchema, + definitionSetHash: z.string({ error: 'Field "definitionSetHash" is required' }).min(1), + baseCommit: z.string({ error: 'Field "baseCommit" is required' }).min(1), + branch: z.string({ error: 'Field "branch" is required' }).min(1), + agentId: agentIdSchema.nullable(), + model: sessionInfoModelSchema.nullable(), + createdAt: z.iso.datetime({ error: 'Field "createdAt" must be an ISO-8601 timestamp' }), + updatedAt: z.iso.datetime({ error: 'Field "updatedAt" must be an ISO-8601 timestamp' }), +}) satisfies z.ZodType; +export const runInfoListSchema = z.array(runInfoSchema) satisfies z.ZodType; +export const createRunRequestSchema = z.object({ + projectId: z.uuid({ error: 'Field "projectId" is required' }), + title: z.string().min(1).max(200).optional(), + agentId: agentIdSchema.optional(), + model: sessionInfoModelSchema.optional(), + definitionSetHash: z.string().min(1).optional(), +}) satisfies z.ZodType; +export const runStreamFrameSchema = z.object({ + id: z.string({ error: 'Field "id" is required' }).min(1), + type: z.enum(['run.started', 'run.step.started', 'run.step.committed', 'run.step.failed']), + data: z.record(z.string(), z.unknown()), + run: z.string().optional(), +}) satisfies z.ZodType; + +// ToolView — единственное, что уходит в модель (D3; обрезка на сервере) +export const toolViewSchema = z.object({ + id: z.string().min(1).max(200).regex(/^(mcp|skill|native):[a-z0-9/_-]+$/), + title: z.string().min(1).max(200), + description: z.string().min(1).max(2000), + inputSchema: z.record(z.string(), z.unknown()), + outputSchema: z.record(z.string(), z.unknown()).optional(), +}); +``` + +**Проверки.** + +- `bun run lint` в `packages/contracts` (типы + `biome`), `bun run build`, `bun run test` (юнит-тесты схем: валид/невалид `CreateRunRequest`, 4 кадра, `ToolView`-префикс). +- Ручной diff-аудит: каждое поле `runs.ts` ↔ `openapi.yaml components/schemas` 1:1 (nullable explicit, never optional — как у sessions). +- `grep` на `interface` в `src/runs/` — ноль совпадений (только `export type`). + +**Критерий готовности.** `runs.ts`/`runs.schema.ts`/`index.ts` + `openapi.yaml`-патч смержены; зеркало поле-в-поле; `lint/build/test` пакета зелёные; E3 может импортировать схемы без правок контракта. + +**Зависимости.** Blocked by: нет (корень цепочки; образцы sessions уже в репо). + +--- + +## E2. БД-минимум + +**Цель.** Дополнить `common/db/schema.ts` таблицами `run_runs/run_steps/run_events` + упрощённой `run_leases` (без `epoch`), теми же конвенциями, что у `project_sessions`/`session_messages`; миграция `drizzle/`; `db:check-integrity` зелёный. + +**Scope.** + +Входит: + +- `run_runs(id uuid PK defaultRandom, projectId FK→projects RESTRICT, title?, status default 'open', definitionSetHash, baseCommit, branch, worktree, sandboxId?, agentId?, model jsonb?, createdAt/updatedAt defaultNow notNull, deletedAt?)`, индексы `(projectId)`, `(projectId,status)`. +- `run_steps(id uuid PK, runId FK RESTRICT, seq bigint per-run, type, status default 'pending', attempt, inputHash, idempotencyKey UNIQUE, observedEpoch default 0, resultRef? jsonb, error? jsonb, startedAt/endedAt?)`, `UNIQUE(runId,seq)`, индекс `(runId,status)`. +- `run_events(id uuid PK, runId FK RESTRICT, seq bigint per-run, type, data jsonb, prevHash, createdAt defaultNow)`, `UNIQUE(runId,seq)`; UPDATE/DELETE запрещены политикой (доктрина, не триггер в прототипе). +- `run_leases(runId PK FK CASCADE, holder, expiresAt)` — упрощённая, без `epoch`/`soft-delete`; пометка `TODO(full-fencing)` рядом. +- `*Row`-типы (`RunRow`/`RunStepRow`/`RunEventRow`/`RunLeaseRow`) рядом с существующими. +- Миграция `drizzle/` (`drizzle-kit`), `db:check-integrity`. + +Не входит: + +- `run_effects` + reconciliation (ориентир DDL из ADR — только как комментарий/`TODO(dual-write-reconcile)`; таблица может быть отложена полностью — см. §8; в прототипе git-ошибка = `step.failed`). +- `run_definitions`/`tool_defs` полнота (E5 хранит определения минимально; индексы метаданных — позже). +- `epoch`/`FOR UPDATE` fencing, advisory-lock очереди мержа, партиционирование, read-replica (см. §8). +- CHECK-ограничения статусов в SQL сверх `default` (frozen-перечисления живут в контракте; CHECK — только если это уже конвенция файла). + +**Пути файлов.** + +- Изменить: `apps/backend/src/common/db/schema.ts` (таблицы + `*Row`-типы). +- Создать: `apps/backend/src/common/db/drizzle/NNNN_*.sql` (миграция через `drizzle-kit`), при необходимости патч `schema-integrity` снапшота тем же механизмом, что и `migrations 0002/0003`. +- Образцы: `projectSessions` (~строки 92–115 `schema.ts`), `sessionMessages` (127+), `sessionAgents` (159+); `docs/manual-migration-orgs-layout.md` (прецедент ручной миграции с `pg_dump`-бэкапом); `docs/backend-hardening-plan.md` (testcontainers + `db:check-integrity`). +- Проверки: `bun run db:check-integrity`, `bun run lint`, `bun run build`. + +**Черновик решения.** + +> DRAFT — опора для реализации, не финальный код. Источник: ADR-0001 §8.7.1, ADR-0002 §6.1. + +```ts +// apps/backend/src/common/db/schema.ts — дополнение (DRAFT ~45 строк) +import { bigint, boolean, index, integer, jsonb, pgTable, text, timestamp, uniqueIndex, uuid } from 'drizzle-orm/pg-core'; + +// run_runs — реестр run (мягкое удаление, история не стирается) +export const runRuns = pgTable('run_runs', { + id: uuid('id').primaryKey().defaultRandom(), // run_id; в app — Bun.randomUUIDv7() + projectId: uuid('project_id').notNull() + .references(() => projects.id, { onDelete: 'restrict' }), // C4-scope, RESTRICT как у sessions + title: text('title'), + status: text('status').notNull().default('open'), + definitionSetHash: text('definition_set_hash').notNull(), + baseCommit: text('base_commit').notNull(), // I5, событие run.started + branch: text('branch').notNull(), // agent/ + worktree: text('worktree').notNull(), // REPOS_ROOT/.../content/wt/ + sandboxId: text('sandbox_id'), // opencode-runner слот + agentId: text('agent_id'), // registry id, nullable как у sessions + model: jsonb('model'), // SessionInfoModel | null + createdAt: timestamp('created_at', { withTimezone: true }).defaultNow().notNull(), + updatedAt: timestamp('updated_at', { withTimezone: true }).defaultNow().notNull(), + deletedAt: timestamp('deleted_at', { withTimezone: true }), // soft-delete, чтение — isNull(deletedAt) +}, (t) => [index('run_runs_project_idx').on(t.projectId), index('run_runs_project_status_idx').on(t.projectId, t.status)]); + +// run_steps — шаги run (write-ahead result, см. ADR-0001 §9.1) +export const runSteps = pgTable('run_steps', { + id: uuid('id').primaryKey().defaultRandom(), + runId: uuid('run_id').notNull().references(() => runRuns.id, { onDelete: 'restrict' }), + seq: bigint('seq', { mode: 'number' }).notNull(), // монотонный per-run + type: text('type').notNull(), // llm.call | tool.call | sandbox.exec | git.commit | await_human | router + status: text('status').notNull().default('pending'), + attempt: integer('attempt').notNull().default(0), + inputHash: text('input_hash').notNull(), + idempotencyKey: text('idempotency_key').notNull().unique(), // hash(run_id, step_id, effect_class, input_hash) + observedEpoch: integer('observed_epoch').notNull().default(0), // fencing — TODO(full-fencing) + resultRef: jsonb('result_ref'), // {artifact_ref, hash} | null до committed + error: jsonb('error'), // {code, message-sanitized} | null + startedAt: timestamp('started_at', { withTimezone: true }), + endedAt: timestamp('ended_at', { withTimezone: true }), +}, (t) => [uniqueIndex('run_steps_run_seq_idx').on(t.runId, t.seq), index('run_steps_run_status_idx').on(t.runId, t.status)]); + +// run_events — append-only журнал (источник истины; UPDATE/DELETE запрещены политикой) +export const runEvents = pgTable('run_events', { + id: uuid('id').primaryKey().defaultRandom(), + runId: uuid('run_id').notNull().references(() => runRuns.id, { onDelete: 'restrict' }), + seq: bigint('seq', { mode: 'number' }).notNull(), // id SSE-кадра, per-run + type: text('type').notNull(), + data: jsonb('data').notNull(), + prevHash: text('prev_hash').notNull(), // tamper-evident цепочка (§9.9) + createdAt: timestamp('created_at', { withTimezone: true }).defaultNow().notNull(), +}, (t) => [uniqueIndex('run_events_run_seq_idx').on(t.runId, t.seq)]); + +// run_leases — аренда run (эфемерно, без soft-delete; EPOCH — TODO(full-fencing)) +export const runLeases = pgTable('run_leases', { + runId: uuid('run_id').primaryKey().references(() => runRuns.id, { onDelete: 'cascade' }), + holder: text('holder').notNull(), + expiresAt: timestamp('expires_at', { withTimezone: true }).notNull(), +}); +export type RunRow = typeof runRuns.$inferSelect; // + RunStepRow / RunEventRow / RunLeaseRow рядом +``` + +**Проверки.** + +- `bun run db:check-integrity` зелёный; миграция применяется на чистом `postgres:16-alpine` (тот же механизм, что e2e-контейнер). +- `bun run lint` + `bun run build` бэкенда зелёные. +- Ручные asserts: `id` генерируется в app через `Bun.randomUUIDv7()` (не полагаться на `defaultRandom` как истину); чтение `run_runs` всегда с `isNull(deletedAt)`; FK — `restrict` (кроме `run_leases` → `cascade`); `uuidv7`-комментарий в коде. + +**Критерий готовности.** Таблицы + миграция + `*Row`-типы в `schema.ts`; `db:check-integrity` зелёный; E3/E4 могут писать `run_runs/run_steps/run_events` без новых DDL-правок. + +**Зависимости.** Blocked by: E1 (статусы/типы frozen в контракте — DDL обязан им соответствовать). + +--- + +## E3. API-минимум + +**Цель.** `processes/modules/runs/`: `POST /api/runs`, `GET /api/runs/:id`, `GET /api/runs/:id/events` (через `relaySse`, probe + C4 + `VERSION_NEUTRAL` + `ZodValidationPipe` + `ApiError`-envelope). + +**Scope.** + +Входит: + +- `runs.module.ts` / `runs.controller.ts` / `runs.service.ts` / `runs.dto.ts` (реэкспорт `@rush-code/contracts` — как `sessions.dto.ts`) в `apps/backend/src/processes/modules/runs/`. +- `POST /api/runs` — вход `CreateRunRequest`, успех 201 `RunInfo`; 400/404 (C4: чужой проект → 404 без утечки)/503 `EXTERNAL_UNAVAILABLE` + `Retry-After: 30` (через `dbUnavailable`). +- `GET /api/runs/:id` — 200 `RunInfo`; те же ошибки. +- `GET /api/runs/:id/events?cursor=` — SSE кадров E1; до заголовков — JSON-ошибки через probe (down → честный 503, не 200-тишина); после — только close; `JwtAuthGuard` + C4 `ProjectAccessService`; механика `relaySse` 1:1 (probe, abort на disconnect, `x-accel-buffering: no` + `x-correlation-id`, `return()`-гонка 1500 мс); catch-up `seq > cursor` → live (`LISTEN/NOTIFY` несёт только `run_id + next_seq`); кадры без `run` дропаются; фильтр — scope gated-проекта. +- `VERSION_NEUTRAL`, `ZodValidationPipe`, замороженный `ApiError {code,message,correlationId}` + `x-correlation-id`; логи только `AppLogger` (normal path — однострочники без URL/body/секретов). + +Не входит: + +- `GET /api/runs?projectId=` список, `POST :id/interrupt`, `POST :id/upgrade-definition` (контракт E1 их описывает, реализация — после прототипа; `upgrade-definition` в терминальном → 409 — тоже позже). +- Полный `RunStreamFrame`-union (10 типов): endpoint отдаёт 4 типа прототипа, остальные — схема + `TODO`. +- Reconciliation/merge-очередь, OTel-дашборды, биллинг. + +**Пути файлов.** + +- Создать: `apps/backend/src/processes/modules/runs/runs.module.ts`, `runs.controller.ts`, `runs.service.ts`, `runs.dto.ts` (+ `__tests__/` рядом для спеки при необходимости). +- Переиспользовать без копипасты: `apps/backend/src/common/sse/sse-relay.ts` (`relaySse`), `apps/backend/src/processes/modules/ai/modules/sessions/sessions.controller.ts` (`:202 events`-образец), `session-harness.service.ts` (`streamEvents`: replay буфера + live-хвост, `LOCAL_IDLE_MS`/`STREAM_CAP_MS`), `sessions.dto.ts` (реэкспорт-паттерн), `common/db/DbService` (`dbUnavailable` → 503), `common/logger` (`AppLogger`), `JwtAuthGuard` + `ProjectAccessService` (C4). +- Регистрация модуля: по `ARCHITECTURE.md` (модулит: `processes/modules/runs/`, вложенность только `/modules//`). + +**Черновик решения.** + +> DRAFT — опора для реализации, не финальный код. Источник: ADR-0001 §8.7.2–§8.7.3 + §9.7, ADR-0002 §6.2–§6.3. + +```ts +// runs.dto.ts (DRAFT ~12 строк) — паттерн sessions.dto.ts +export { createRunRequestSchema, runInfoSchema, runInfoListSchema, runStreamFrameSchema, + type CreateRunInput, type RunInfo, type RunInfoList, type RunStreamFrame } from '@rush-code/contracts'; + +// runs.controller.ts — сигнатуры (DRAFT ~35 строк) +@UseGuards(JwtAuthGuard) +@Post() +@Version(VERSION_NEUTRAL) +@HttpCode(HttpStatus.CREATED) +async create( + @ReqUser() identity: RequestIdentity, + @Body(new ZodValidationPipe(createRunRequestSchema)) body: CreateRunInput, + @Headers('x-correlation-id') correlationId?: string, +): Promise { return this.runs.create(identity.id, body, correlationId ?? ''); } + +@Get(':id') +@Version(VERSION_NEUTRAL) +async getOne(@ReqUser() identity: RequestIdentity, @Param('id') id: string, + @Headers('x-correlation-id') correlationId?: string): Promise { + return this.runs.getOne(identity.id, id, correlationId ?? ''); +} + +@Get(':id/events') // SSE: до заголовков — JSON-ошибки через probe, после — только close +@Version(VERSION_NEUTRAL) +async events(@ReqUser() identity: RequestIdentity, @Req() req: ExpressRequest, + @Res({ passthrough: false }) res: ExpressResponse, @Param('id') id: string, + @Query('cursor') cursor?: string, @Headers('x-correlation-id') correlationId?: string, +): Promise { return this.runs.streamEvents(identity.id, id, cursor, correlationId ?? '', req, res); } +``` + +```ts +// runs.service.streamEvents — relaySse вызов (DRAFT ~25 строк) +await relaySse({ + operation: 'GET /api/runs/:id/events', cid, req, res, logger, prefix: '[runs]', + probe: async () => (await this.db.isAvailable() ? 'up' : 'down'), // до заголовков → честный 503 + unreachableError: () => this.db.dbUnavailable(cid), // EXTERNAL_UNAVAILABLE + Retry-After: 30 + subscribeFailedError: (err) => toExternalError(err, cid), + subscribe: (signal) => this.runEventSource.subscribe(runId, cursor, signal), // catch-up seq>cursor + live LISTEN/NOTIFY + mapFrame: (row) => ({ id: String(row.seq), type: row.type, data: row.data, run: runId }), // RunStreamFrame + filterFrame: (f) => typeof (f as RunStreamFrame).run === 'string', // кадры без run дропаются +}); +``` + +**Проверки.** + +- `bun run lint` + `bun run build` бэкенда зелёные. +- Ручные asserts (до E7): `POST /api/runs` без `projectId` → 400; чужой `projectId` → 404 без утечки (C4); даун БД → 503 + `Retry-After: 30`; `GET events` при даун-источнике → 503 до заголовков (не 200-тишина); disconnect клиента — abort upstream (лог `debug`, без стека). +- e2e-скан секретов (эталон `keys.e2e.ts`) — в E7, но структура ошибок уже обязана быть `ApiError`-envelope + `x-correlation-id`. + +**Критерий готовности.** Три endpoint отвечают по контракту E1; SSE идёт через `relaySse` с курсором; C4 + `ApiError` + probe-семантика 1:1 с sessions-образцом. + +**Зависимости.** Blocked by: E1 (схемы), E2 (таблицы). + +--- + +## E4. Движок-минимум + +**Цель.** In-process claim-loop в `WorkersModule`: `claim → llm.call` (заглушка `ModelGateway`, 1 провайдер) `→ tool.call` (native `git.recon` + 1 внешний MCP) `→ sandbox.exec` (opencode-runner `:4096`) `→ step.committed → SSE`; jail `WorkspacePathService`; ветка `agent/`. + +**Scope.** + +Входит: + +- Claim-loop в `processes/modules/workers/` (scaffold `WorkersModule` → рабочий провайдер): `SELECT … FOR UPDATE SKIP LOCKED` по `run_leases`/outbox, heartbeat продлением `expiresAt` владельцем; запись результата в **одной транзакции** (lease-check → append `run_steps`/`run_events`); `TODO(full-fencing)` рядом с местом, где позже будет `epoch` + `FOR UPDATE` по строке lease. +- `llm.call` — заглушка `ModelGateway` с одним провайдером (интерфейс + адаптер-заглушка; логические имена моделей, `tools?: ToolView[]`, `need`-флаги; журналируется нормализованный запрос/ответ + `usage`). +- `tool.call` — `ToolRegistry`: native `git.recon` (in-process, эффект `read`) + 1 внешний MCP-инструмент через stateless-клиент (modern + один `initialize`-фолбэк; `TODO(mcp-dual-era)` на полный dual-era/Tasks); каждый `tools/call` — шаг журнала (`request_hash/response_hash/attempt/durationMs/bytesIn-Out`); разрыв = переотправка с новым id **с проверкой по `request_hash`**; в модель уходит только `ToolView`. +- `sandbox.exec` — существующий opencode-runner (`:4096`, back-сеть) через `OpencodeSdkClient` / `fetchWithRetry` + `serveBasicAuthHeader`; ошибки → `EXTERNAL_*` → `ApiError`-envelope; без per-run ресурсов (квота = лимиты compose + диск). +- `git.commit` (intent в прототипе): `INSERT intent`-эффект → `git commit` с детерминированным трейлером `Run-Id/Step-Id` → append `step.committed`; git-ошибка = `step.failed`, без авто-догона (`TODO(dual-write-reconcile)`). +- Ветка `agent/` + worktree `REPOS_ROOT/.../content/wt/` через `WorkspacePathService.ensureDir` + `assertInsideJail` (путь никогда не из `cwd`/`__dirname`); `baseCommit` фиксируется в `run.started`; Forward-Only (`merge-base --is-ancestor`, deny `reset --hard`/`push --force`); флаг «без сабмодулей». +- Append `step.committed` → событие SSE (источник для E3 catch-up/live); `heartbeat`-комментарий `:\n\n` ~15 с. + +Не входит: + +- Полный fencing (`epoch`, `FOR UPDATE` по lease) — `TODO(full-fencing)`; kill -9 посреди шага не переживается (только graceful-рестарт). +- `run_effects` + reconciliation-job по трейлерам (`git log --grep`, `superseded`, rebase-правило) — `TODO(dual-write-reconcile)`. +- MCP dual-era полностью, Tasks-расширение (`tasks/get`), `ttlMs/cacheScope`-кэш — `TODO(mcp-dual-era)`; своего MCP-сервера нет вообще (D5). +- Merge-очередь (`pg_advisory_xact_lock`), `resolve.conflict`, push/PR fail-closed, GC worktree по лимитам, OTel-спаны, биллинг. + +**Пути файлов.** + +- Изменить: `apps/backend/src/processes/modules/workers/workers.module.ts` (scaffold → claim-loop провайдер(ы) + `__tests__/`). +- Создать (внутри `workers/modules//` по модулиту): claim-loop сервис, `model-gateway/` (интерфейс + заглушка-адаптер), `tool-registry/` (native `git.recon` + MCP-клиент), `sandbox/` (тонкий провайдер поверх `OpencodeSdkClient`/`fetchWithRetry`), git-хелпер поверх `repository/{repos,workspaces,clone}` + `utils/{repos-git,submodules}`. +- Переиспользовать: `common/db/DbService`, `common/storage/workspace-path.service.ts` (`assertInsideJail/ensureDir/removeDir`), `common/sse/sse-relay.ts` (только E3, движок лишь append-ит), `OpencodeSdkClient` + `fetchWithRetry` + `serveBasicAuthHeader` (задел исполнителя), `AppLogger` + `ExternalClient`-семантика, `Bun.randomUUIDv7()`. +- Конвенции: `private readonly` DI, `utils//index.ts` + `__tests__`, без `*.module.ts` в `common/`-подпапках. + +**Черновик решения.** + +> DRAFT — опора для реализации, не финальный код. Источник: ADR-0001 §9.1–§9.2 + §9.5 + §9.8, ADR-0002 §5 + D2/D5/D9. + +```ts +// ModelGateway интерфейс + заглушка (DRAFT ~22 строки, ADR-0001 §9.8) +interface ModelGateway { + stream(req: { model: string; system?: string; messages: Message[]; + tools?: ToolView[]; responseFormat?: JSONSchema; // только ToolView, не полный дескриптор (D3) + maxTokens?: number; temperature?: number; + need: { toolCalls?: boolean; jsonSchema?: boolean; vision?: boolean; reasoning?: boolean }; + }): AsyncIterable; // {type:'delta'|'tool_call'|'usage'|'done'} +} +class StubModelGateway implements ModelGateway { // 1 провайдер в прототипе + async *stream(req: GatewayReq): AsyncIterable { + this.logger.info(`[runs] llm.call model=${req.model} tools=${req.tools?.length ?? 0}`, cid); + yield { type: 'delta', text: 'stub-turn' }; // заглушка: журналируется как нормализованный ответ + usage + yield { type: 'done', usage: { in: 0, out: 1 } }; + } +} +``` + +```ts +// Workers claim-loop псевдокод (DRAFT ~28 строк, ADR-0001 §9.2; TODO(full-fencing)) +async function claimLoop(): Promise { + for (;;) { + const lease = await db.tx(async (tx) => // claim свободной работы + tx.query(`SELECT * FROM run_leases WHERE expires_at < now() LIMIT 1 FOR UPDATE SKIP LOCKED`)); + if (!lease) { await sleep(POLL_MS); continue; } + await touchLease(lease.runId, HOLDER, TTL); // heartbeat — продление владельцем + const step = await planNextStep(lease.runId); // llm.call → tool.call → sandbox.exec → git.commit(intent) + try { + const out = await runStep(step); // native git.recon | MCP tools/call | opencode-runner :4096 + await db.tx(async (tx) => { // ОДНА транзакция: lease-check → append + // TODO(full-fencing): SELECT leases … FOR UPDATE + проверка epoch/holder; несовпадение → fenced + останов + await tx.insert(runSteps).values({ ...step, status: 'committed', resultRef: out.artifactRef }); + await tx.insert(runEvents).values({ runId: step.runId, seq: step.seq, type: 'run.step.committed', data: out, prevHash }); + }); + } catch (err) { await appendStepFailed(step, sanitize(err)); } // git-ошибка = step.failed; TODO(dual-write-reconcile) + } +} +``` + +**Проверки.** + +- `bun run lint` + `bun run build` зелёные; юнит-спеки claim-loop (claim → heartbeat → append; зомби-lease перехватывается). +- Ручные asserts: worktree создан внутри jail (`assertInsideJail`), ветка `agent/` существует, `baseCommit` записан в `run.started`; повторный `tools/call` с тем же `request_hash` не двоит эффект; даун opencode-runner → `EXTERNAL_*` + `step.failed` (не тишина); логи — однострочники без URL/body/секретов. +- e2e-скан секретов (в E7). + +**Критерий готовности.** Один run in-process проходит `claim → llm.call → tool.call → sandbox.exec → step.committed → SSE-кадр`; worktree в jail; журнал — истина (рестарт процесса продолжает со следующего незавершённого шага, `committed` не пере-исполняется). + +**Зависимости.** Blocked by: E2 (таблицы/leases), E3 (journal-append + SSE-источник). Параллельно с E3 — только по замороженному контракту E1. + +--- + +## E5. Агенты + инструкции + +**Цель.** Реестр агентов (`AgentBase` + `AskAgent`) + skills-лоадер (frontmatter → тело → ресурсы, 1 пилот-скилл, `allowed-tools` deny-by-default) + пиннинг `definition_set_hash` по `commit_sha`. + +**Scope.** + +Входит: + +- Реестр агентов в `processes/modules/ai/modules/agents/`: `AgentBase` (существующий) + `AskAgent` (зародыш из стека) как первый исполнитель за `Executor`-интерфейсом (уровень шага, не `ModelGateway`); `agents.service`/`agents.controller` (`GET /api/v1/agents`) — переиспользование. +- Skills-лоадер: каталог `skills//SKILL.md` (frontmatter `name ≤64`, `description ≤1024`, `allowed-tools` экспериментально) + `scripts/`/`references/`/`assets/`; progressive disclosure (метаданные ~100 токенов на старте → тело `<5000` токенов при активации → ресурсы по требованию); 1 пилот-скилл: frontmatter → тело подмешивается в системный промпт; `allowed-tools` проверяется ядром, deny по умолчанию. +- Классификация эффекта скилла: чистые инструкции/шаблоны = `read`; скиллы с исполняемыми `scripts/` = минимум `write-local` (переоценка вверх обязательна, вниз — запрещена). +- Пиннинг: `run` фиксирует `definition_set_hash` при старте; воркер читает срезы строго по пинованному хэшу (тело скилла — по `commit_sha`, «свежий» текст идущему run запрещён); смена `active` влияет только на новые run; явный апгрейд — только событием `run.upgrade_definition` (endpoint — после прототипа). +- Валидация публикации `skills-ref validate` в CI (если тривиально добавляется; иначе — ручной чек-лист). + +Не входит: + +- Полный `run_definitions`/`tool_defs` индекс с версионированием всех видов (`agent|skill|tool-registry|mcp-config`) — минимум под 1 скилл + реестр. +- Hot-reload endpoint (`upgrade-definition`), Tasks-инструменты, OTel-корреляция `agent/definition_version` сверх `AppLogger` + `x-correlation-id`. +- Новые SDK-исполнители (Claude/OpenAI Agents как `Executor`) — только точка расширения. + +**Пути файлов.** + +- Переиспользовать: `apps/backend/src/processes/modules/ai/modules/agents/{agent.base.ts,ask.agent.ts,agents.service.ts,agents.controller.ts,agents.module.ts,agents.dto.ts}` + `__tests__/agents.controller.security.spec.ts`. +- Создать: skills-лоадер (`processes/modules/ai/modules/skills/` или `workers/modules/skills/` — решить по `ARCHITECTURE.md` на реализации; вложенность только `/modules//`), `skills/<пилот>/SKILL.md` (пилот-скилл как git-артефакт), тест лоадера в `__tests__/`. +- Контракт: `definitions.active`-флаг и `definition_set_hash` уже в E1/E2 (`run_runs.definitionSetHash`). + +**Черновик решения.** + +> DRAFT — опора для реализации, не финальный код. Источник: ADR-0001 §8.4 + §9.6, ADR-0002 D4/D7. + +```ts +// skills-лоадер (DRAFT ~30 строк) +type SkillMeta = { name: string; description: string; allowedTools?: string[] }; // frontmatter: name ≤64, description ≤1024 +async function loadSkill(skillDir: string): Promise<{ meta: SkillMeta; body: string }> { + const raw = await fs.readFile(join(skillDir, 'SKILL.md'), 'utf8'); + const { meta, body } = parseFrontmatter(raw); // frontmatter → тело + assertSkillMeta(meta); // name/description лимиты; allowed-tools — экспериментально, enforcement наше + return { meta, body }; // ресурсы scripts//references//assets — только по требованию (progressive disclosure) +} +function buildSystemPrompt(base: string, skills: LoadedSkill[]): string { + return [base, ...skills.map((s) => `\n${s.body}\n`)].join('\n\n'); +} +function checkAllowedTools(skill: SkillMeta, toolId: string): void { + const allow = skill.allowedTools ?? []; // deny-by-default: нет списка — нет вызовов + if (!allow.includes(toolId)) throw new ForbiddenToolError(skill.meta.name, toolId); +} +// Пиннинг: тело скилла читается строго по commit_sha из run.started; чтение «свежего» текста идущим run запрещено. +async function loadSkillPinned(repo: string, commitSha: string, name: string) { + return gitShow(`${commitSha}:skills/${name}/SKILL.md`); // тот же follow-up, что baseCommit (I5) +} +``` + +**Проверки.** + +- `bun run lint` + `bun run build` зелёные; спеки лоадера (frontmatter-парсинг, лимиты, deny-by-default, пин по `commit_sha`). +- Ручные asserts: пилот-скилл активируется по описанию, тело попадает в системный промпт, запрещённый тул отклоняется ядром; смена `active` не трогает идущий run; новая версия видна только новым run. +- `skills-ref validate` (или ручной чек) на пилот-скилл. + +**Критерий готовности.** `AskAgent` отвечает через реестр; 1 пилот-скилл грузится трёхступенчато и участвует в промпте; `allowed-tools` enforced; пиннинг `definition_set_hash` соблюдён. + +**Зависимости.** Blocked by: E4 (точка `system+Skill+ToolView` в loop). Контракт E1 — вход. + +--- + +## E6. Фронт-минимум + +**Цель.** `api/runs-client.ts` (фасад над `client.ts`) + хуки `useRuns`/`useRun`/`useRunEvents` + `query-keys.ts`; SSE — `useEffect`-исключение (аналог `streamSessionEvents`), переиспользование chat-паттерна; отдельного дизайна run-экрана нет. + +**Scope.** + +Входит: + +- `apps/frontend/src/api/runs-client.ts`: `listRuns/createRun/getRun` (+ `runEventStream` SSE-генератор) поверх единого `src/api/client.ts` (`request()`/`requestV1()`, `NEXT_PUBLIC_API_URL` verbatim, `ApiClientError`, `x-correlation-id`, парсинг boundary-схемами E1); `withAuth` + `ensureSessionAuth` + `toErrorMessage` — как в `sessions-client.ts`. +- Хуки: `useRuns`/`useRun` на React Query (`useQuery`/`useMutation`, `reload` = `invalidateQueries`), ключи только из `query-keys.ts` (`runsQueryKey`, `runQueryKey`); `useRunEvents` — `useEffect` + доменный SSE с комментом-обоснованием (как `useChat`/`useSessionEvents`); финал цепочки прототипа — `run.step.committed`; `stop()`-семантика — abort + drop кадров (`sendingRef`-гард) по образцу `useChat`. +- SSE-парсинг: `data:`-джойн многострочных payload, `runStreamFrameSchema.parse` (malformed → FAIL LOUD + redial с backoff, не silent cast); heartbeat-комменты без `data:` скипаются транспортом; дедуп по `seq`; фильтр scope по `frame.run`. +- Guard `no-opencode-transport` не трогать, но не нарушить: только `/api/runs*` через доменный клиент. + +Не входит: + +- Run-экран дизайн, `interrupt`/`upgrade-definition` кнопки, провайдер/модель-селекторы для runs, OTel-дашборды, биллинг-индикаторы. +- Второй транспорт (WebSocket), React Query поверх SSE (исключение зафиксировано каноном). + +**Пути файлов.** + +- Создать: `apps/frontend/src/api/runs-client.ts`, `apps/frontend/src/hooks/useRuns.ts` (или `useRuns`/`useRun`/`useRunEvents` рядом), патч `apps/frontend/src/hooks/query-keys.ts`. +- Образцы (читать, не менять): `apps/frontend/src/api/sessions-client.ts` (`withAuth`, `sessionEventStream`, `toErrorMessage`), `apps/frontend/src/api/client.ts` (`request()`, `streamSessionEvents`-исключение), `apps/frontend/src/hooks/useChat.ts` (`sendingRef`-гард, `session.step.ended`-финал), `apps/frontend/src/hooks/query-keys.ts`, `apps/frontend/AGENTS.md` (слои, `useEffect`-исключение). +- Проверки: `bun run lint` (`tsc --noEmit` + `biome lint`) + `bun run build` (`next build --turbopack`) фронта. + +**Черновик решения.** + +> DRAFT — опора для реализации, не финальный код. Источник: ADR-0001 §9.7, ADR-0002 §6.3 + §6.6; образец `sessions-client.ts:187-248`, `useChat.ts`. + +```ts +// runs-client.ts — фасад + SSE (DRAFT ~40 строк) +import { ApiClientError, api } from './client'; +import { runStreamFrameSchema } from '@rush-code/contracts'; +import type { CreateRunRequest, RunInfo, RunStreamFrame } from '@rush-code/contracts'; + +export function listRuns(projectId: string, opts?: { signal?: AbortSignal }): Promise { + return withAuth((token) => api.listRuns(token, projectId, opts)); // request() + parseBoundary, как listSessions +} +export function createRun(body: CreateRunRequest): Promise { + return withAuth((token) => api.createRun(token, body)); +} +// SSE-исключение: useEffect + доменный SSE, на React Query не переносится (канон фронта). +export async function* runEventStream(runId: string, projectId: string, cursor: number, signal: AbortSignal, +): AsyncGenerator { + const res = await withAuth((token) => api.streamRunEvents(token, runId, projectId, cursor, { signal })); + const reader = res.body!.getReader(); const decoder = new TextDecoder(); let buffer = ''; + try { + for (;;) { const { done, value } = await reader.read(); if (done) return; + buffer += decoder.decode(value, { stream: true }); + buffer = buffer.replace(/\r\n/g, '\n'); let idx = buffer.indexOf('\n\n'); + while (idx >= 0) { const chunk = buffer.slice(0, idx); buffer = buffer.slice(idx + 2); idx = buffer.indexOf('\n\n'); + const lines = chunk.split('\n').filter((l) => l.startsWith('data:')).map((l) => l.slice(5).trim()); + if (!lines.length) continue; // heartbeat — скип транспортом + yield runStreamFrameSchema.parse(JSON.parse(lines.join('\n'))); // malformed → throw → redial с backoff + } + } + } finally { try { await reader.cancel().catch(() => null); } catch {} try { reader.releaseLock(); } catch {} } +} +``` + +```ts +// useRunEvents скелет (DRAFT ~20 строк) — useEffect-исключение с комментом-обоснованием +export function useRunEvents(runId: string | null, projectId: string, cursor = 0) { + // Исключение из React Query: streaming/SSE — useEffect + доменный SSE (см. useChat). + const [frames, setFrames] = useState([]); + useEffect(() => { if (!runId) return; const ac = new AbortController(); let live = true; + (async () => { for await (const f of runEventStream(runId, projectId, cursor, ac.signal)) { + if (!live || f.run !== runId) continue; // scope по frame.run; дедуп по f.id (seq) + setFrames((prev) => (prev.some((p) => p.id === f.id) ? prev : [...prev, f])); + if (f.type === 'run.step.committed') queryClient.invalidateQueries({ queryKey: runQueryKey(runId) }); + } })().catch((e) => { if (!isAbort(e)) setError(toErrorMessage(e)); }); + return () => { live = false; ac.abort(); }; // stop(): abort + drop кадров + }, [runId, projectId, cursor]); + return { frames }; +} +``` + +**Проверки.** + +- `bun run lint` + `bun run build` фронта зелёные; `no-opencode-transport` guard зелёный. +- Ручные asserts: `createRun` → карточка в списке после invalidate; SSE показывает `run.started → run.step.committed`; reconnect с `cursor` не дублирует кадры (дедуп по `seq`); чужой проект — `404` (не логаут, `400/404` никогда не разлогинивают — как в `sessions-client.ts`). + +**Критерий готовности.** Фронт создаёт run, показывает прогресс по SSE и переживает reconnect без потерь/дублей; chat-паттерн переиспользован, новых транспортов нет. + +**Зависимости.** Blocked by: E1 (схемы/парсинг), E3 (endpoint `/api/runs*` + SSE-формат). + +--- + +## E7. E2E-минимум + +**Цель.** `runs.e2e.ts` на testcontainers (`postgres:16-alpine`) по образцу `sessions.e2e.ts`: создать run → `step.committed` → переподключение с `cursor` → replay; asserts: jail-путь, ветка `agent/`, чужой `projectId` → `404`. + +**Scope.** + +Входит: + +- Сьют `apps/backend/.../__tests__/runs.e2e.ts` (место — рядом с `sessions/__tests__/sessions.e2e.ts` или в `processes/modules/runs/__tests__/`; решить по `ARCHITECTURE.md` на реализации): запуск против COMPILED `dist` (декораторы), `scripts/e2e.ts` бюджет `E2E_SUITE_TIMEOUT_MS=300000`. +- Строгий Postgres: одноразовый `postgres:16-alpine` через `e2e-db.container.ts`, миграции `drizzle/`, гашение в `stop()` (+ Ryuk); `TEST_DATABASE_URL`/`E2E_DB_MODE=unreachable` — только явные override; `DATABASE_URL` в e2e не читается. +- Сценарий: `POST /api/runs` → дождаться `step.committed` (poll `GET :id` + SSE) → переподключиться `GET :id/events?cursor=` → проверить replay без потерь. +- Asserts: worktree-путь внутри `REPOS_ROOT` (jail, патч `WorkspacePathService` как в `sessions.e2e.ts`), ветка `agent/` существует, чужой `projectId` → `404 not_found` (C4, без утечки), гость → 401, `PROJECT_REQUIRED` без `projectId`, секреты (Basic-пароль, upstream-секрет) нигде не в логах/ответах, warn/error — однострочники (`AppLogger`-захват по образцу `keys.e2e.ts`). +- Outage-поверхность: `E2E_DB_MODE=unreachable` → 503 + `Retry-After: 30` (явный прогон, не дефолт). + +Не входит: + +- Нагрузочные бенчмарки `LISTEN/NOTIFY`, долгоживущие run, kill -9/fencing-проверки, merge-очередь, MCP-матрица `endpoint × era × supported` (пилот D5 — отдельным прогоном, не в этом сьюте). +- Фронт-e2e (только API-уровень). + +**Пути файлов.** + +- Создать: `.../__tests__/runs.e2e.ts` (образец: `apps/backend/src/processes/modules/ai/modules/sessions/__tests__/sessions.e2e.ts`, ~структура: детерминированный env → stub upstream → `configureApp()/setupSwagger()` → патч C4-гейта → сценарий → asserts → скан секретов). +- Переиспользовать: `src/common/db/e2e-db.container.ts`, `scripts/e2e.ts`, `docs/backend-hardening-plan.md` (стенд), `src/processes/modules/ai/modules/opencode/__tests__/keys.e2e.ts` (скан секретов + `AppLogger`-захват). +- Проверки: `bun run build && <скомпилированный сьют>`; точечный фильтр `bun scripts/e2e.ts runs.e2e`. + +**Черновик решения.** + +> DRAFT — опора для реализации, не финальный код. Источник: ADR-0001 §13-п.3 + §8.7.6, ADR-0002 §6.6 + §7-п.7; образец `sessions.e2e.ts:1-80`. + +```ts +// runs.e2e.ts — скелет (DRAFT ~45 строк) +import assert from 'node:assert/strict'; +// Runs against COMPILED dist (tsc emits decorator metadata; bun test on TS sources must not run this). +process.env.APP_BACKEND_PORT ??= '3000'; +process.env.REQUEST_TIMEOUT_MS = '2000'; +process.env.OPENCODE_URL = 'http://127.0.0.1:9'; // stub ниже (opencode-runner :4096 в e2e — стаб) +process.env.JWT_ACCESS_SECRET = 'e2e-access-secret-not-real-0123456789'; +const E2E_PROJECT_ID = '123e4567-e89b-12d3-a456-426614174090'; +const JAIL_DIR = '/tmp/rush-code-e2e-runs'; // патч WorkspacePathService → jail (как sessions.e2e JAIL_DIR) + +async function main(): Promise { + const { container, url } = await startThrowawayPostgres('postgres:16-alpine'); // e2e-db.container.ts + try { + await applyMigrations(url); // drizzle/ — включая run_runs/run_steps/run_events/run_leases + const app = await bootApp({ databaseUrl: url, workspaceRoot: JAIL_DIR }); // C4-гейт патчится как в sessions.e2e + // 1. создать run + const created = await api('POST /api/runs', { projectId: E2E_PROJECT_ID, title: 'e2e-run' }); + assert.equal(created.status, 201); const runId: string = created.body.id; + assert.match(created.body.branch, /^agent\//); + // 2. дождаться step.committed (poll + SSE) + const committed = await waitFor(() => api(`GET /api/runs/${runId}`), (r) => hasStepCommitted(r)); + assert.ok(committed, 'step.committed not observed'); + // 3. переподключение с cursor → replay без потерь + const replay = await collectSse(`GET /api/runs/${runId}/events?cursor=0`, /* then abort+reconnect with cursor */); + assert.deepEqual(ids(replay), ids(live), 'replay loss'); + // 4. asserts: jail-путь, ветка, C4 + assert.ok(created.body.worktree.startsWith(JAIL_DIR), 'worktree outside jail'); + assert.ok(await gitBranchExists(created.body.worktree, created.body.branch), 'branch agent/ missing'); + assert.equal((await api('GET /api/runs/' + runId, { projectId: STRANGER_PROJECT })).status, 404); // чужой → 404 + assertNoSecretsLeaked(logCapture, [BASIC_PASSWORD, UPSTREAM_SECRET]); // эталон keys.e2e.ts + } finally { await container.stop(); } +} +``` + +**Проверки.** + +- `bun run build` + скомпилированный `runs.e2e.js` зелёный; фильтр `bun scripts/e2e.ts runs.e2e`. +- Отдельный прогон `E2E_DB_MODE=unreachable` → 503 + `Retry-After: 30`. +- Без Docker — явная ошибка (не скип), per канон e2e. + +**Критерий готовности.** Сьют зелёный: run сквозняком, `step.committed` наблюдаем, reconnect с `cursor` отдаёт историю без потерь, jail/ветка/C4 asserts держат, секреты не текут. + +**Зависимости.** Blocked by: E1–E6 (нужен весь срез: контракт → БД → API → движок → фронт-формат кадров). + +--- + +## §8. Отложенное с TODO-метками (не молча) + +| Метка | Что откладываем | Где ставить | Что делает прототип вместо | +| --- | --- | --- | --- | +| `TODO(full-fencing)` | Полный fencing: `epoch` в `run_leases`, `SELECT … FOR UPDATE` по строке lease в одной транзакции с append, `epoch` только растёт, чужой/протухший `epoch` → `fenced` + останов воркера | `WorkersModule` claim-loop (место lease-check), `schema.ts` у `run_leases` (`observedEpoch` уже есть как задел) | Упрощённый claim `SKIP LOCKED` + heartbeat; прототип честно переживает только graceful-рестарт, не kill -9 посреди шага (ADR-0001 §18.3, ADR-0002 D9/§8) | +| `TODO(dual-write-reconcile)` | `run_effects` + reconciliation по трейлерам (`intent → committed/failed`, `committed → superseded`, `git log --grep` по ветке `agent/`, индекс `(trailerRunId,trailerStepId)`, rebase-правило §9.3) | Движок `git.commit`, будущий reconciliation-job | Git-ошибка = `step.failed` без авто-догона; оператор видит `failed` и решает (ADR-0001 §18.3, ADR-0002 D8/§8) | +| `TODO(mcp-dual-era)` | Полный MCP dual-era (разбор `400` → `initialize`-фолбэк → HTTP+SSE-фолбэк), Tasks-расширение (`tasks/get` polling), `ttlMs/cacheScope`-кэш дескрипторов | MCP-клиент в `ToolRegistry`/`ExternalClient` | Один modern-клиент + один `initialize`-фолбэк; матрица пилота `endpoint × era × supported` отдельно (ADR-0001 §8.3/§13-п.5, ADR-0002 D5/§8) | +| (без метки — вне прототипа) | Биллинг/SLA, OTel-дашборды (`gen_ai.*` нестабильны — только `AppLogger` + `x-correlation-id`), per-run ресурсы/cgroup/microVM (E2B — лишь имя будущего `SandboxProvider`), сабмодули (флаг «без сабмодулей») | Нигде в коде прототипа | Квоты общие (compose `2G/2.0` + диск `opencode-projects`); параллельных run — «десятки», мерим e2e-стендом | + +--- + +## §9. Сквозной критерий готовности (§18.1 ADR-0001) + инварианты + +**Сквозной run (все пункты — обязательно, по ADR-0001 §18.1 / ADR-0002 §7):** + +1. `POST /api/runs` создал run (201 `RunInfo`). +2. Агент вызвал ≥1 tool (`tool.call` в журнале: `request_hash/response_hash/attempt`). +3. Результат записан в журнал (`run_steps`: `step.committed` + `resultRef`; `run_events`: цепочка с `prevHash`). +4. SSE показал `run.started → run.step.committed` (catch-up + live через `relaySse`). +5. Worktree с веткой `agent/` создан в jail (`REPOS_ROOT/.../content/wt/`, `assertInsideJail`) и виден в git. +6. Повторный `GET events?cursor=` отдал историю без потерь (replay = live по `seq`, дедуп на клиенте). + +**Инварианты приёмки (нарушение = не готово):** + +- **I5 Forward-Only:** `git merge-base --is-ancestor base HEAD` = 0; в коде/политике запрещены `reset --hard`/`push --force` (deny на уровне tool-дескриптора `git.*`); откат — только `revert`/новые коммиты. +- **C4:** чужой `projectId` → `404 not_found` без утечки существования (все `/api/runs*`, включая `events`); `missing projectId` → 400 `PROJECT_REQUIRED`; гость → 401 (не маскируется под 400/404). +- **ApiError-envelope:** все ошибки — замороженный `ApiError {code,message,correlationId}` + `x-correlation-id`; БД/раннер down → 503 `EXTERNAL_UNAVAILABLE` + `Retry-After: 30` (до SSE-заголовков — JSON, после — только close); логи — `AppLogger`-однострочники без URL/body/секретов, стек только в `debug` через `serializeCause`; `console.*` — ноль. + +--- + +## reuse-блок (для гейта) + +```json +{ + "queries": ["sessions contract", "sse relay", "workers scaffold", "workspace jail", "agents registry", "frontend SSE hooks", "e2e testcontainers", "neighbor plans format"], + "found": ["packages/contracts/src/sessions/{sessions.ts,sessions.schema.ts,index.ts}", "apps/backend/src/common/sse/sse-relay.ts", "apps/backend/src/processes/modules/ai/modules/sessions/{sessions.controller.ts,sessions.service.ts,session-harness.service.ts,sessions.dto.ts,__tests__/sessions.e2e.ts}", "apps/backend/src/processes/modules/workers/workers.module.ts", "apps/backend/src/common/db/schema.ts (projectSessions/sessionMessages/sessionAgents)", "apps/backend/src/common/storage/workspace-path.service.ts", "apps/backend/src/processes/modules/ai/modules/agents/{agent.base.ts,ask.agent.ts,agents.service.ts}", "apps/frontend/src/api/{client.ts,sessions-client.ts}", "apps/frontend/src/hooks/{query-keys.ts,useChat.ts}", ".plans/password-service/PLAN.md", "docs/adr/0001,0002 (Rev.6/Rev.2)"], + "reused": ["sessions.ts/sessions.schema.ts — стиль mirrorulu поле-в-поле, nullable-паттерн, agentId-regex, z.iso.datetime (E1)", "sse-relay.ts — relaySse 1:1: probe-до-заголовков, abort, x-accel-buffering, return-гонка 1500мс (E3)", "sessions.controller.ts:202 events + streamEvents replay+live — структура endpoint и catch-up/live (E3)", "sessions.dto.ts — реэкспорт-паттерн @rush-code/contracts (E3)", "sessions.e2e.ts + e2e-db.container.ts + scripts/e2e.ts + keys.e2e.ts — стенд testcontainers postgres:16-alpine, бюджет 300000, скан секретов (E7)", "schema.ts projectSessions/sessionMessages — RESTRICT, soft-delete isNull(deletedAt), индексы (projectId)/(session_id,createdAt) (E2)", "WorkspacePathService assertInsideJail/ensureDir/removeDir — jail WorktreePathService (E4)", "agent.base.ts/ask.agent.ts/agents.service.ts — AgentBase+AskAgent реестр (E5)", "sessions-client.ts withAuth/sessionEventStream/toErrorMessage + client.ts request()/parseBoundary — фасад и SSE-парсинг (E6)", "useChat.ts sendingRef-гард + session.step.ended-финал, query-keys.ts — хуки-исключения и ключи (E6)", "workers.module.ts scaffold — дом claim-loop (E4)", "password-service/PLAN.md — формат соседнего плана (структура настоящего файла)"], + "created_new_why": ["packages/contracts/src/runs/ — нового домена runs нет, sessions не покрывает RunInfo/RunStreamFrame/ToolView", "processes/modules/runs/ — нового REST-домена /api/runs* нет, sessions-контроллер чужого scope", "claim-loop + ModelGateway-заглушка + ToolRegistry(git.recon+MCP) + sandbox.exec + git.commit(intent) — движка run нет, sessions-harness покрывает только чат-стрим", "skills-лоадер (frontmatter→тело→ресурсы, 1 пилот-скилл) — в репо skills-лоадера нет", "runs-client.ts + useRuns/useRun/useRunEvents — фронта runs нет", "runs.e2e.ts — e2e runs нет; sessions.e2e покрывает только /api/sessions*"] +} +``` diff --git a/.plans/ai-stream-model/PLAN.md b/.plans/ai-stream-model/PLAN.md new file mode 100644 index 0000000..e725658 --- /dev/null +++ b/.plans/ai-stream-model/PLAN.md @@ -0,0 +1,35 @@ +# План: фикс стриминга ИИ + выбор модели в чате (ветка feat/cli-cloud-chat) + +## Фаза 1 — Диагностика стриминга +Файлы-кандидаты: +- `apps/frontend/src/hooks/useChat.ts` (редьюсер кадров: `message.part.delta` append `data.delta`, `message.part.updated` snapshot, `session.idle` финализация streamingText→messages, scope `frame.session` vs активный sessionId; бэкофф 1s→15s, AbortController) +- `apps/frontend/src/api/sessions-client.ts` (`sessionEventStream`/`streamSessionEvents`, SSE исключение без JSON-буферизации), `apps/frontend/src/hooks/useSessionEvents.ts`, `useSessionMessages.ts` +- `apps/backend/src/sessions/sessions.service.ts` (трансляция upstream v2 frames), `apps/backend/src/common/sse-relay.ts` (механика SSE, обрыв downstream → тихо в debug), `apps/backend/src/sessions/sessions.controller.ts` +- `packages/contracts/src/sessions/sessions.ts` + `sessions.schema.ts` (`SessionStreamFrame`, `SessionRunStatus`), upstream-эталон `contracts/opencode-stand-2.2.0.json` +Критерии готовности: таблица «upstream frame → бэкенд frame → фронт-действие» для delta/updated/idle; найден конкретный потерянный переход (scope? finalize? парсинг zod?); воспроизводится локально. +Риски: upstream v2 shape дрейфует от эталона; SSE-обрывы маскируются под «сломан»; пустое тело режется SDK (`stripEmptySlots`) — диагностировать через `fetchWithRetry`. + +## Фаза 2 — Фикс стриминга +Файлы: те же + `apps/frontend/src/hooks/__tests__/`. +Что сделать: scope кадров по `frame.session` (чужие игнор); delta — append; updated — snapshot-замена; idle — flush `streamingText` в `messages` + `loading=false`; `text:null` скип (уже есть в `toChatMessages`); бэкофф/Abort сохранить; логи только `AppLogger`-стиль на бэке, без стеков/секретов в normal path. +Критерии: ассистентский ответ достримовывается целиком, повторные промпты не смешиваются между сессиями, `stop()`/`reload()` корректны. +Риски: двойной flush (delta+updated) → дедуп по part/message id; кросс-ток при смене sessionId. + +## Фаза 3 — Контракт модели (YAML + package + бэкенд-проброс) +Файлы: `contracts/openapi.yaml` (components/schemas: `CreateSessionRequest`, `SendMessageRequest` + переиспользовать `SessionInfoModel{id,providerID,variant?}` как `ModelRef`), `packages/contracts/src/sessions/sessions.ts` + `sessions.schema.ts` (zod, поле-в-поле с YAML), `apps/backend/src/sessions/sessions.dto.ts` + `sessions.service.ts` (проброс `model` в upstream `create`/`prompt`), `apps/backend/src/sessions/sessions.e2e.ts`. +Что сделать: добавить optional `model?: {providerID,id,variant?}` в оба запроса; бэкенд пробрасывает как есть (null = серверный дефолт upstream, без выдумывания дефолта — запрет фолбэков); обход SDK-резки ключей через `fetchWithRetry` + `serveBasicAuthHeader` с непустым телом (прецедент `title`/`parentID`); ошибки upstream не маскировать (400/422→EXTERNAL_BAD_REQUEST, 404→EXTERNAL_NOT_FOUND, сбой→503+Retry-After:30). +Критерии: YAML↔package идентичны; e2e create+send с model проходят; без model поведение прежнее. +Риски: расхождение YAML↔package (баг пакета); SDK молча режет ключ — только raw fetch путь; deprecated `/api/opencode/*` не трогать (Forward-Only). + +## Фаза 4 — UI выбора модели в чате +Файлы: `apps/frontend/src/hooks/useChat.ts` (`send(text, opts?: {model})`, createSession с model), `apps/frontend/src/api/sessions-client.ts` (`createSession`, `sendSessionMessage` + model), компонент чата (селектор provider→model поверх доменного `GET /api/sessions/providers`; НЕ `/api/opencode/config/providers` — currently deprecated TODO card 6, переключать на доменный), `src/hooks/query-keys.ts` (ключ списка провайдеров), `src/hooks/useAiProviders.ts` (перевести на доменный при касании). +Что сделать: селектор в шапке/панели чата, персист выбора (стор или локальный стейт), placeholder/disabled пока модели грузятся; формат ошибок через `format-error` + `t` в `useMemo`, `queryFn` бросает raw `ApiClientError`. +Критерии: выбор уходит в create/prompt, смена модели между сообщениями работает, guard-тест зелёный (нет `@opencode-ai/sdk`, нет `/api/opencode/*` даже в комментах), `app/` остаётся тонкой композицией. +Риски: `useAiProviders` сейчас на deprecated-алиасе — scope-крип (переключить попутно или зафиксировать TODO); guard-тест ловит даже комментарии. + +## Фаза 5 — Тесты и гейты +- Юнит: редьюсер кадров useChat (delta-append, updated-snapshot, idle-flush, чужой session игнор); zod-парсинг новых полей контракта. +- Бэкенд e2e (`sessions.e2e.ts`): create/send с model + без model; скан секретов/форм как в `opencode-keys.e2e.ts` (перехват AppLogger, assert без `\n` в warn/error). +- Гейты: `bun run lint` (tsc --noEmit + biome), `bun run build` (фронт `next build --turbopack`); точечно `lint:affected`/`build:affected`. +- Guard: `no-opencode-transport.test.ts` обязан быть зелёным. +Риски: Next.js-блок в `apps/frontend/AGENTS.md` — писать код только после чтения `node_modules/next/dist/docs/`; mobile не трогать (standalone npm). diff --git a/.plans/ai-stream-model/epoch-01.md b/.plans/ai-stream-model/epoch-01.md new file mode 100644 index 0000000..86ff5d3 --- /dev/null +++ b/.plans/ai-stream-model/epoch-01.md @@ -0,0 +1,15 @@ +# Epoch 1: Coarse hypothesis +## Hypothesis +Стриминг сломан на одном из 3 уровней: фронт-редьюсер кадров (useChat frame.session scope, delta vs updated, session.idle финализация), бэкенд-трансляция v2 frames (sse-relay + sessions.service), upstream v2 event shape. Выбора модели нет т.к. CreateSessionRequest/SendMessageRequest без model. +## Decisions +- Диагностика первична, фикс после доказательств. +## Confirmed Plan Items +1. Диагностика стриминга — сравнить фронт-кадры vs бэкенд vs upstream +2. Фикс стриминга +3. Контракт модели YAML+package+бэкенд +4. UI выбора модели +5. Тесты и гейты +## Open Questions +- Какой кадр теряется: delta/updated/idle? +## Next Epoch Focus +- Evidence: прочитать useChat полностью, sse-relay, sessions.service SSE, openapi.yaml sessions diff --git a/.plans/ai-stream-model/epoch-02.md b/.plans/ai-stream-model/epoch-02.md new file mode 100644 index 0000000..b66863a --- /dev/null +++ b/.plans/ai-stream-model/epoch-02.md @@ -0,0 +1,14 @@ +# Epoch 2: Evidence gathering +## Evidence Found +- File: apps/frontend/src/hooks/useChat.ts (1-80) — useEffect+SSE исключение (wontfix, AGENTS.md), парсит delta/updated через zod-схемы из @rush-code/contracts, toChatMessages скипает text:null +- File: packages/contracts/src/sessions/sessions.ts — SessionInfoModel{id,providerID,variant?}, SessionInfo.model nullable, CreateSessionRequest{projectId,title?,parentID?} — model НЕТ +- File: apps/backend/src/sessions/sessions.service.ts (1-60) — UpstreamSession.model?{id,providerID,variant?}, relaySse через common/sse-relay +- Pattern: фронт ходит только через src/api/sessions-client.ts поверх client.ts request(); guard no-opencode-transport запрещает sdk и /api/opencode/* +## Decisions +- Decision: контракт модели добавлять как optional model{providerID,id(,variant?)} в Create + SendMessage, зеркально YAML<->package +- Alternatives: modelId string — rejected (теряется providerID, upstream требует пару) +## Open Questions +- Есть ли model в SendMessageRequest? проверить sessions.ts 61+ и schema + openapi.yaml +- Куда бэкенд кладёт model: session.create body vs session.prompt body (SDK v1 режет неизвестные ключи — обход через fetchWithRetry+serveBasicAuthHeader с непустым телом!) +## Next Epoch Focus +- Decision foundation: точки врезки model, диагностика SSE scope/finalize diff --git a/.plans/ai-stream-model/epoch-03.md b/.plans/ai-stream-model/epoch-03.md new file mode 100644 index 0000000..8e412cb --- /dev/null +++ b/.plans/ai-stream-model/epoch-03.md @@ -0,0 +1,15 @@ +# Epoch 3: Decision foundation +## Hypothesis +Фикс стриминга = scope кадров по frame.session + корректная склейка delta + snapshot updated + финализация по session.idle (+retry бэкофф уже есть 1s->15s). Модель = optional passthrough, дефолт null (серверный дефолт upstream), без тихих фолбэков. +## Decisions +- Decision: SSE scope обязателен — чужой session игнор, без него кросс-ток +- Decision: YAML источник правды; packages/contracts правится вторым; расхождение = баг пакета +- Decision: UI — селектор provider/model в чате (данные из GET /api/sessions/providers доменного, НЕ /api/opencode/config), значение уходит в send()/createSession; useChat остаётся useEffect (исключение зафиксировано) +## Confirmed Plan Items +1. Фаза 1 диагностика — файлы, готовность, риски (см PLAN.md) +2. Фаза 2 фикс стриминга +3. Фаза 3 контракт модели +4. Фаза 4 UI +5. Фаза 5 тесты/гейты +## Next Epoch Focus +- Refinement: точные файлы-кандидаты, критерии готовности, риски diff --git a/.plans/ai-stream-model/epoch-04.md b/.plans/ai-stream-model/epoch-04.md new file mode 100644 index 0000000..60f909c --- /dev/null +++ b/.plans/ai-stream-model/epoch-04.md @@ -0,0 +1,4 @@ +# Epoch 4: Refinement -> PLAN.md +См. PLAN.md — синтез. +## Next Epoch Focus +- done diff --git a/.plans/ai-stream-model/evolution-log.md b/.plans/ai-stream-model/evolution-log.md new file mode 100644 index 0000000..5cea271 --- /dev/null +++ b/.plans/ai-stream-model/evolution-log.md @@ -0,0 +1 @@ +# evolution-log: epoch1 coarse -> epoch2 evidence (useChat/SessionInfo/CreateSessionRequest без model, sse-relay) -> epoch3 decisions (scope обязателен, YAML источник правды, model optional passthrough, UI на доменных providers) -> epoch4 PLAN.md diff --git a/.plans/amber-phoenix-qt7/PLAN.md b/.plans/amber-phoenix-qt7/PLAN.md new file mode 100644 index 0000000..fe932c1 --- /dev/null +++ b/.plans/amber-phoenix-qt7/PLAN.md @@ -0,0 +1,204 @@ +# PLAN — Самовосстановление самописного useChat (все 5 пунктов) + +> Ветка: `feat/cli-cloud-chat`, base `c0dee12`. Только план, никакого кода. +> Non-negotiable: остаёмся на своём транспорте (`useChat.ts` + `sessions-client.ts`); Vercel `useChat` отклонён (guard `no-opencode-transport.test.ts`). +> Канон: фронт — `apps/frontend/AGENTS.md` (streaming-исключение `useEffect` с комментом-обоснованием, query-ключи из `query-keys.ts` не для SSE); бэк — `apps/backend/AGENTS.md` (только `AppLogger`, fail-fast без тихих фолбэков, C4-gate 404 без утечки); контракты — `packages/contracts/AGENTS.md` (зеркало `contracts/openapi.yaml` поле-в-поле). + +## Порядок и зависимости (root / branch / leaf) + +``` +C0 [root] heartbeat + stream.error + id: + └─ C1 [branch] cursor/Last-Event-ID (blocked by C0) + └─ C2 [branch] ?session= фильтр (blocked by C0) + └─ C3 [branch] транспорт fail-soft + watchdog-сигнал (blocked by C0, C2) + └─ C4 [branch] useChat self-healing (blocked by C3; e2e-догон — C1) + └─ C5 [leaf] persist URL (blocked by C4) + └─ C6 [leaf] ErrorState-политика + приёмка (blocked by C0–C5) +``` + +C1 и C2 независимы между собой, могут идти параллельно после C0. + +--- + +## C0 [root] — SSE heartbeat + терминальный error-кадр + `id:` на кадрах + +**Trello:** title `C0 SSE heartbeat + stream.error (relay)` · Blocked by: — · Blocks: C1, C2, C3 +**Покрывает ТЗ:** п.1 (heartbeat) + п.5-часть (терминальный error-кадр вместо тихого обрыва). +**Файлы:** +- `apps/backend/src/common/sse/sse-relay.ts` (таймер heartbeat, `id:` префикс, error-кадр + `res.end()`) +- `apps/backend/src/common/sse/__tests__/*` (юнит: ping присутствует, error-кадр формат) +- `packages/contracts/src/sessions/sessions.ts` + `sessions.schema.ts` (тип `stream.error`, narrow-схема optional) +- `contracts/openapi.yaml` (документация SSE: ping-коммент, `id:`, `stream.error`) + +**Чек-лист:** +- [ ] `relaySse` после `flushHeaders` стартует heartbeat-таймер (`HEARTBEAT_MS`, напр. 15s): пишет `: ping\n\n` при простое; таймер чистится в `finally`, не мешает `onClose`/abort. +- [ ] Каждый `data:` кадр пишется как `id: \nevent: message\ndata: {...}\n\n` (id — для `Last-Event-ID`; имя event — если уже есть конвенция, не ломать). +- [ ] Mid-stream failure (не-abort): вместо тихого `break` пишется терминальный `data: {id, type:'stream.error', data:{code?, message?}, session?}` затем `res.end()`; AbortError/disconnect — по-прежнему тихо (debug, без кадра). +- [ ] Логи только `AppLogger`, только count/строки (`heartbeat on`, `stream.error …`), без тел кадров/секретов; `droppedByFilter` поведение не меняется. +- [ ] Контракт: `stream.error` проходит envelope `{id,type,data,session?}`; openapi.yaml описывает ping + error-кадр; `tsc` зеркала ок. +- [ ] Юнит: heartbeat-коммент в потоке; error-кадр при инжектированной mid-stream ошибке; abort без error-кадра. + +**Complexity:** score `9/20` (транспорт + wire-контракт + тесты). +**Риск:** score `3/8`, факторы `[external]` (прокси-долгоживущие сокеты, тайминги; breaking нет — additive). +**Builder:** `build-smart` (wire-формат, задевает всех потребителей). +**Done:** прокси-idle держится ping; обрыв раннера = `stream.error` + конец стрима (не тишина); `bun run lint` + `build` зелёные. + +--- + +## C1 [branch] — Курсор / Last-Event-ID в replay-буфере harness + +**Trello:** title `C1 replay cursor Last-Event-ID (harness)` · Blocked by: C0 · Blocks: C4(e2e-догон) +**Покрывает ТЗ:** п.2 (курсор/Last-Event-ID в `session-harness.service.ts:1056-1073`). +**Файлы:** +- `apps/backend/src/processes/modules/ai/modules/sessions/session-harness.service.ts` (`streamEvents` subscribe/replay, cursor-поиск) +- `apps/backend/src/processes/modules/ai/modules/sessions/sessions.service.ts` (проброс cursor, если нужен) +- `apps/backend/src/processes/modules/ai/modules/sessions/__tests__/*` (replay с/без cursor) + +**Чек-лист:** +- [ ] `streamEvents` читает cursor из `Last-Event-ID` header (первично) + `?cursor=` fallback; ищет его в `localFrames` по `frame.id`. +- [ ] Replay отдаёт только кадры **после** cursor, отфильтрованные по `localSessionIds` (существующий предикат); неизвестный/пустой cursor → полный локальный replay (не пустой, не весь глобальный). +- [ ] Подтвердить монотонность `frame.id` в `localFrames`; если runner-id немонотонны — additive серверный `seq` (не ломая envelope), cursor по нему. +- [ ] `LOCAL_IDLE_MS`/`STREAM_CAP_MS`/`POLL_MS` семантика не меняется; cursor не продлевает мёртвый стрим. +- [ ] Логи: только count (`replay from cursor n/m`), без id-контента лишнего; `AppLogger` only. +- [ ] Юнит: redial с cursor не дублирует; без cursor — полный локальный replay; чужой cursor — фолбэк без утечки чужих сессий. + +**Complexity:** score `11/20` (буфер + идемпотентность replay + seq-вопрос). +**Риск:** score `5/8`, факторы `[data, external]` (дубли/потери середины треда при неверном cursor; silent-data-loss риск). +**Builder:** `build-smart`. +**Done:** повторный коннект догоняет только недостающее; дублей дельт нет; чужие сессии не утекают. + +--- + +## C2 [branch] — `?session=` фильтр в `GET /events` + +**Trello:** title `C2 ?session= filter GET /events` · Blocked by: C0 · Blocks: C3 +**Покрывает ТЗ:** п.3 (`sessions.controller.ts`, `filterFrame`). +**Файлы:** +- `apps/backend/src/processes/modules/ai/modules/sessions/sessions.controller.ts` (`@Query('session')`) +- `apps/backend/src/processes/modules/ai/modules/sessions/sessions.service.ts` + `session-harness.service.ts` (сужение `localSessionIds ∩ {session}`, `filterFrame` остаётся defense-in-depth) +- `contracts/openapi.yaml` (`GET /api/v1/sessions/events`: `session` optional query) +- `packages/contracts/...` (если появится query-DTO — зеркало; иначе только yaml) + +**Чек-лист:** +- [ ] `events()` принимает опциональный `session`; C4-gate (`projectId` + `assertProjectAccessById`) прежний и первый. +- [ ] Сервер сужает подписку до запрошенной сессии; существующий `filterFrame` (`frame.session ∈ local`) остаётся вторым рубежом. +- [ ] Чужой/пустой `session` → тихий пустой стрим (heartbeat идёт, кадров нет), **не 404/400** (не ликать существование — C4-конвенция). +- [ ] Без `session` — старое поведение (мультиплекс своих сессий), без breaking. +- [ ] openapi.yaml обновлён; swagger-описания 400/404/503 не меняются. +- [ ] Юнит/e2e: `?session=A` не получает кадров B; без параметра — как раньше. + +**Complexity:** score `7/20` (тонкий контроллер + фильтр). +**Риск:** score `3/8`, факторы `[security]` (изоляция сессий; breaking нет — optional). +**Builder:** `build-fast` (изолировано, additive). +**Done:** чужие сессии не будят чужой стрим; старые клиенты без `?session=` работают. + +--- + +## C3 [branch] — Транспорт fail-soft + Last-Event-ID + watchdog-сигнал + +**Trello:** title `C3 transport fail-soft + Last-Event-ID (sessions-client)` · Blocked by: C0, C2 · Blocks: C4 +**Покрывает ТЗ:** п.5-часть (fail-soft парсинг одного кадра) + подготовка п.1 (watchdog) и п.2–3 (cursor/session на wire). +**Файлы:** +- `apps/frontend/src/api/sessions-client.ts` (`sessionEventStream`: try/safeParse, heartbeat-skip, lastEventId) +- `apps/frontend/src/api/client.ts` (`streamSessionEvents`: `?session=`, `Last-Event-ID` header) +- `apps/frontend/src/api/__tests__/*` (битый кадр, heartbeat, query/header) + +**Чек-лист:** +- [ ] `sessionEventStream(projectId, signal, opts?: {sessionId?, lastEventId?})`: URL `?projectId=&session=` (когда есть), header `Last-Event-ID` (когда есть); guard-тест транспорта не нарушен. +- [ ] Парсинг чанка: `data:`-линии join (существующее) → `JSON.parse` в try + `sessionStreamFrameSchema.safeParse` (не `.parse`); битый чанк → счётчик + skip, генератор **живёт**; пустой/heartbeat (`: ping`, без `data:`) → skip + сигнал активности для watchdog. +- [ ] Генератор отдаёт `{frame, lastEventId}` или держит внутренний `lastId` + колбэк активности `onActivity?: () => void` (контракт для C4-watchdog; без `setError` внутри). +- [ ] Транспортные ошибки (fetch-throw, `!body`, abort-разрыв) по-прежнему throw наружу (C4 решит тихо redial vs терминал); парсинг-ошибки — **никогда** throw. +- [ ] Без логов тел кадров; `withAuth`/401-ротация не меняется; `parseBoundary` для REST не трогается. +- [ ] Юнит: поток `[good, broken-json, good, broken-schema, good, : ping]` → 3 good-кадра, стрим не умер; query/header уходят корректно. + +**Complexity:** score `10/20` (парсер + wire + тесты). +**Риск:** score `4/8`, факторы `[external]` (маскировка реальных разрывов при перегибе skip — лечится счётчиком + C4-watchdog). +**Builder:** `build-smart` (критический путь стрима). +**Done:** битый кадр скипается без ErrorState на весь тред; heartbeat не парсится как кадр; cursor/session уходят на сервер. + +--- + +## C4 [branch] — `useChat` self-healing: watchdog, тихий backoff, resync, разделение гардов + +**Trello:** title `C4 useChat self-healing (watchdog/resync/guards)` · Blocked by: C3 (C1 для e2e-догона) · Blocks: C5 +**Покрывает ТЗ:** п.5-часть (resync on online/visibilitychange + разделение sending-гард vs подписка + терминальный error) + п.1-часть (watchdog). +**Файлы:** +- `apps/frontend/src/hooks/useChat.ts` (SSE-loop, watchdog, backoff, resync, finalize, sending-страховка) +- `apps/frontend/src/hooks/__tests__/*` (моки `sessionEventStream`: обрыв, error-кадр, битый кадр, F5-догон) + +**Чек-лист:** +- [ ] Подписка **всегда активна** при `projectId` (+`sessionIdRef` когда есть): убрать `if (!sendingRef.current) continue` до session-фильтра; вместо этого: копление `streamingRef`/partLens всегда, `finalize()` (коммит assistant-строки) только когда `sendingRef` И терминатор своей сессии (`session.text.ended/execution.succeeded/step.ended`); `stop()` вводит эпоху/abort-turn чтобы поздние кадры прерванного turn не коммитились. +- [ ] Терминальный `stream.error` (C0): `setError` + `sending=false` + тред **сохраняется** (ошибка — отдельно, см. C6); транзиент (throw транспорта, watchdog-сработка) → тихий backoff-redial 1s→15s **без** `setError`. +- [ ] Watchdog: `onActivity` (кадр или `: ping` из C3) сбрасывает таймер (напр. `HEARTBEAT_MS*2 + запас`); просрочка → abort + тихий redial + `Last-Event-ID` = последний `frame.id`. +- [ ] Resync: `window.addEventListener('online')` + `visibilitychange→visible` → тихий `reload()`-лайт (REST `listSessionMessages` + nonce-redial), без `setError`; слушатели чистятся на unmount. +- [ ] Страховка вечного `sending`: если терминатор потерян — сверка по REST (история выросла → `finalize`-коммит и `sending=false`) и/или сверка `GET status`; `send()` поверх висящего sending по-прежнему guarded, но висеть вечно нельзя. +- [ ] `frameText`/`frameToolName` не меняются кроме пропуска `stream.error` мимо текстового тракта; streaming-исключение `useEffect` + коммент-обоснование сохраняется (AGENTS.md). +- [ ] Юнит: обрыв mid-turn → backoff без потери `streamingRef`; `stream.error` → error без затирания messages; F5 (sending=false) догоняет кадры своей сессии; чужая сессия игнорируется. + +**Complexity:** score `13/20` (состояние гонок: sending/эпохи/abort/resync). +**Риск:** score `5/8`, факторы `[data, external]` (потеря/дубль коммита, вечный sending, zombie-подписки). +**Builder:** `build-smart`. +**Done:** обрыв = тихое переподключение без потери треда и без вечного sending; F5-догон работает; `stop()` не воскрешается поздними кадрами. + +--- + +## C5 [leaf] — Persist `sessionId` (+`agentId`) в URL страницы чата + +**Trello:** title `C5 persist sessionId+agentId in URL` · Blocked by: C4 · Blocks: C6 +**Покрывает ТЗ:** п.4 (`features/chat/`). +**Файлы:** +- `apps/frontend/src/features/chat/chat-section.tsx` (синк `activeSessionId`/`agentId` ↔ URL) +- `apps/frontend/app/organizations/[orgId]/projects/[projectId]/sessions/[sessionId]/page.tsx` (чтение `?agent=`, проброс) +- (если есть список/creation-экран сессий — тот же роут, `router.replace` после create; без localStorage как источника правды) + +**Чек-лист:** +- [ ] Источник `sessionId` — path `sessions/[sessionId]`; после lazy-`createSession` — `router.replace(.../sessions/[newId]?agent=…)` без потери набранной истории (история уже в `useChat`, replace без reload страницы). +- [ ] `agentId`: инициализация `?agent=` → state (фолбэк `DEFAULT_AGENT_ID='ask'`), `setAgentId` пишет `?agent=` (replace, без скролла); F5 сохраняет и sessionId, и agentId. +- [ ] `ChatSection` остаётся тонкой сборкой (бизнес — в `useChat`); Next `useSearchParams/useRouter` только здесь, не в `useChat` (хук тестируем без роутера). +- [ ] Guard-транспорт не нарушен; `query-keys.ts` не трогается (SSE не на React Query). +- [ ] Тест: F5 на `sessions/abc?agent=ask` → тот же тред + тот же агент; создание с нуля → URL обновился. + +**Complexity:** score `8/20` (роутер-синк без гонок). +**Риск:** score `2/8`, факторы `[]` (UI-only; риск — replace-лупы, лечится guard на равенство). +**Builder:** `build-fast`. +**Done:** после F5 чат продолжается с тем же sessionId + догоняет историю (REST) + переподписывается (C4). + +--- + +## C6 [leaf] — Политика ErrorState + приёмка (транзиент ≠ терминал) + +**Trello:** title `C6 ErrorState policy + acceptance` · Blocked by: C0–C5 · Blocks: — +**Покрывает ТЗ:** критерии приёмки целиком. +**Файлы:** +- `apps/frontend/src/components/chat/chat-window/chat-window.tsx` (условный ErrorState) +- `apps/frontend/src/features/chat/chat-section.tsx` (проброс `retry=reload`, сохранение треда) +- `contracts/openapi.yaml` + `packages/contracts` (финальный sync wire-документации) +- `apps/frontend/src/__tests__/*`, `apps/backend/.../__tests__/*` (границы), ручной чек-лист приёмки + +**Чек-лист:** +- [ ] `ChatWindow`: `error` при **транзиенте отсутствует** (C4 не ставит) — ветка `if (error)` срабатывает только на терминал (`stream.error`, REST-история упала); тред (`messages` + `streamingText`) при ошибке **не затирается** — ErrorState рисуется рядом/поверх с retry, а не `return` вместо треда (уточнить дизайн: баннер над тредом vs замена; решение — баннер, тред видим). +- [ ] `onRetry=reload`: REST-история + redial SSE + сброс watchdog/backoff; повторный F5-цикл не дублирует коммиты. +- [ ] Документация wire (yaml + contracts-комменты): ping, `id:`/`Last-Event-ID`, `?session=`, `stream.error`, fail-soft — в одном месте. +- [ ] Приёмка (ручная, чек-лист в карточке): (1) F5 mid-turn → тот же sessionId + история + resubscribe; (2) kill-proxy/idle 60s → ping держит, watchdog молчит; (3) обрыв SSE → тихий backoff, тред цел, sending не вечный; (4) инжект битого кадра → skip без ErrorState; (5) две сессии → кадры B не будят стрим A (`?session=A` + client-фильтр). +- [ ] `bun run lint` (tsc+biome) + `build` + точечные спеки зелёные; `no-opencode-transport` guard зелёный. + +**Complexity:** score `7/20` (UI-политика + доки + приёмка). +**Риск:** score `2/8`, факторы `[]` (не меняет транспорт; риск — дизайн-спор баннер vs замена, решается ревью). +**Builder:** `build-fast`. +**Done:** все 5 критериев приёмки из ТЗ воспроизводятся; план закрыт. + +--- + +## Матрица traceability (пункт ТЗ → карточки) + +| Пункт ТЗ | Карточки | +|---|---| +| 1) heartbeat `: ping` + watchdog | C0 (server ping) → C3 (skip+activity) → C4 (watchdog) → C6 (idle-приёмка) | +| 2) курсор/Last-Event-ID replay `1056-1073` | C0 (`id:`) → C1 (cursor) → C3 (отправка) → C4 (догон) | +| 3) `?session=` в `GET /events` + `filterFrame` | C0 (база) → C2 (server) → C3 (client query) → C4 (client-фильтр) → C6 (изоляция) | +| 4) persist sessionId+agentId в URL | C4 (resubscribe) → C5 (URL) → C6 (F5-приёмка) | +| 5) error-кадр + fail-soft + resync + гарды | C0 (error-кадр) → C3 (fail-soft) → C4 (resync+гарды) → C6 (политика) | + +## Глобальные Done (закрытие плана) +- [ ] F5 → тот же sessionId + REST-догон + resubscribe; heartbeat держит прокси; обрыв → тихий backoff без потери треда и без вечного sending; битый кадр → skip; чужие сессии изолированы. +- [ ] `bun run lint` + `build` зелёные на затронутых пакетах; контракты ↔ yaml без drift; guard `no-opencode-transport` зелёный. diff --git a/.plans/amber-phoenix-qt7/epoch-01.md b/.plans/amber-phoenix-qt7/epoch-01.md new file mode 100644 index 0000000..03b9c74 --- /dev/null +++ b/.plans/amber-phoenix-qt7/epoch-01.md @@ -0,0 +1,25 @@ +# Epoch 1: Coarse hypothesis + +## Hypothesis +Самописный транспорт (`useChat.ts` + `sessions-client.ts` поверх `client.ts streamSessionEvents`) можно дотянуть до самовосстановления без Vercel `useChat`, добавив 5 пунктов ТЗ: heartbeat, курсор replay, `?session=` фильтр, persist в URL, терминальный error-кадр + fail-soft + resync + разделение sending-гарда. Бэк: `sse-relay.ts` (транспорт), `session-harness.service.ts:1056-1073` (replay-буфер), `sessions.controller.ts`/`sessions.service.ts` (`GET /events`), контракты `sessions.schema.ts` + `openapi.yaml`. + +## Evidence Found +- Факт ТЗ: ветка `feat/cli-cloud-chat`, base `c0dee12`, стрим прерывается и не восстанавливается, фронт ломается при живом бэке. +- Non-negotiable: Vercel useChat отклонён — остаёмся на своём транспорте. + +## Decisions +- Decision: планировать как Trello-карточки с порядком root/branch/leaf + complexity/риск под `classify_build`. +- Alternatives considered: Vercel useChat / React Query SSE — rejected (решение пользователя, guard-тест запрещает чужой транспорт). +- Rationale: 5 пунктов ТЗ уже привязаны к точным путям — декомпозиция по слоям транспорт→буфер→фильтр→клиент→хук→URL→политика ошибок. + +## Confirmed Plan Items +1. Карточки C0–C6 с файлами, чек-листами, зависимостями — причина: Trello + builder требуют атомарности. +2. Никакого кода, только план — причина: явное требование задачи. + +## Open Questions +- Текущий replay-буфер: размер, id-монотонность, ttl? (→ Epoch 2) +- Есть ли heartbeat сейчас? Как `sessionEventStream` реагирует на битый кадр? (→ Epoch 2) +- Где живёт страница чата для persist URL? (→ Epoch 2) + +## Next Epoch Focus +- Evidence gathering: прочитать `sse-relay`, `session-harness:1056+`, `sessions-client sessionEventStream`, `useChat SSE-loop`, `chat-section`, `chat-window`, `client.streamSessionEvents`, контракты. diff --git a/.plans/amber-phoenix-qt7/epoch-02.md b/.plans/amber-phoenix-qt7/epoch-02.md new file mode 100644 index 0000000..e118cc6 --- /dev/null +++ b/.plans/amber-phoenix-qt7/epoch-02.md @@ -0,0 +1,37 @@ +# Epoch 2: Evidence gathering + +## Hypothesis +Узкие места подтверждаются чтением исходников; план ляжет на реальные строки и паттерны. + +## Evidence Found +- File: `apps/backend/src/common/sse/sse-relay.ts` — heartbeat **отсутствует**: только `data:` кадры (`res.write data: ...\n\n`), есть `mapFrame/filterFrame`, `droppedByFilter` счётчик, `STREAM` без ping. Прокси с idle-timeout убьёт сокет. `filterFrame` уже есть (используется harness) — точка для `?session=`. +- File: `apps/backend/src/processes/modules/ai/modules/sessions/session-harness.service.ts:1056-1128` — replay = `frames.filter(localSessionIds)` + `cursor=frames.length` + live-merge с `POLL_MS=250`, `LOCAL_IDLE_MS=30s`, `STREAM_CAP_MS=300s`. **Курсора/Last-Event-ID нет**: replay отдаёт всё локальное с нуля при каждом коннекте (дубли после redial), id кадров — runner-ские, монотонность не гарантирована транспортом. +- File: `apps/backend/src/processes/modules/ai/modules/sessions/session-harness.service.ts:1129-1144` — `filterFrame` дропает чужие сессии по `frame.session ∈ localSessionIds`, `mapFrame=toStreamFrame` (re-key `data.sessionID→session`). Серверный фильтр есть, но **без `?session=`**: каждый клиент получает мультиплекс всех своих сессий и фильтрует в памяти. +- File: `apps/backend/src/processes/modules/ai/modules/sessions/sessions.controller.ts:296-311` — `GET events` принимает только `?projectId`, пробрасывает в `sessions.service.streamEvents→harness.streamEvents`. `?session=` отсутствует в контроллере/сервисе/ openapi. +- File: `apps/frontend/src/api/sessions-client.ts:194-255 sessionEventStream` — **FAIL LOUD**: `JSON.parse` без try + `sessionStreamFrameSchema.parse` (throw) → один битый кадр убивает весь генератор → `useChat` ловит как stream break + `setError` на весь тред. Heartbeat-комменты скипаются (`data:`-линии отсутствуют → continue) — точка для watchdog. `Last-Event-ID` не отправляется, `?session=` не строится. +- File: `apps/frontend/src/api/client.ts:324-354 streamSessionEvents` — SSE-исключение (открытый Response, без timeout), URL только `?projectId`. Точка вставки `?session=` + `Last-Event-ID` header. +- File: `apps/frontend/src/hooks/useChat.ts:305-459` — SSE-loop: `if (!sendingRef.current) continue` **до** проверки session (подписка глушится вне turn — чужой/поздний ответ не подхватится после F5), ошибка транспорта → `setError` (весь тред заменяется ErrorState в `chat-window`), backoff 1s→15s есть, `attemptRef` есть, но **watchdog нет**, `online/visibilitychange` resync нет, `sending` висит если `session.idle/step.ended` потерян (нет страховки через REST/status). +- File: `apps/frontend/src/features/chat/chat-section.tsx` — тонкая сборка `useChat({sessionId, projectId})`, без URL-синка. File: `apps/frontend/src/components/chat/chat-window/chat-window.tsx:107-113` — `if (error)` **заменяет весь тред** на ErrorState (транзиент = потеря контекста). File: `app/organizations/[orgId]/projects/[projectId]/sessions/[sessionId]/page.tsx` — sessionId из path-params, `agentId` нигде не persists. +- Pattern: граница строго zod (`parseBoundary`, `safeParse` для delta/updated в `frameText`), `withAuth` single-flight refresh, C4 project-gate 400/404, логи только `AppLogger`, тесты в `__tests__` рядом с кодом. + +## Decisions +- Decision: 7 карточек C0–C6, порядок root→branch→leaf (heartbeat+error-кадр первые — на них завязан watchdog и fail-soft контракт). +- Alternatives considered: один большой PR — rejected (риск отката всего стрима, Trello требует атомарности). +- Rationale: evidence показывает 4 независимые точки отказа (транспорт, буфер, клиент-парсинг, хук-гард) + 2 политики (URL, ErrorState) — каждая тестируется отдельно. + +## Confirmed Plan Items +1. C0 heartbeat + терминальный error-кадр в `sse-relay` + контракт — reason: без ping прокси рвёт сокет, без error-кадра обрыв неотличим от idle. +2. C1 курсор/Last-Event-ID в replay-буфере — reason: redial сейчас или дублирует всё, или теряет середину. +3. C2 `?session=` фильтр в `GET /events` — reason: чужие сессии будят чужой стрим. +4. C3 транспорт fail-soft + watchdog-заготовка — reason: битый кадр не должен убивать тред. +5. C4 `useChat` self-healing (resync, sending-гард) — reason: F5/обрыв без потери треда и без вечного sending. +6. C5 persist sessionId+agentId в URL — reason: F5 продолжает тот же sessionId. +7. C6 политика ErrorState + приёмка — reason: транзиент ≠ терминал. + +## Open Questions +- Формат id кадров harness (`localFrames`): монотонны ли? Нужен ли серверный seq поверх runner id? +- Имя терминального кадра: `stream.error` vs `session.error` vs `error`? Совместимость с `sessionStreamFrameSchema` (type: string — любое ок, но нужен narrow-контракт?). +- Где канонический URL после создания сессии: push `sessions/[sessionId]` + `?agent=` или path только? + +## Next Epoch Focus +- Decision foundation: зафиксировать контрактные решения (имена, query-параметры, header), разрешить конфликты (droppedByFilter vs ?session=, sending-гард vs подписка). diff --git a/.plans/amber-phoenix-qt7/epoch-03.md b/.plans/amber-phoenix-qt7/epoch-03.md new file mode 100644 index 0000000..409f979 --- /dev/null +++ b/.plans/amber-phoenix-qt7/epoch-03.md @@ -0,0 +1,33 @@ +# Epoch 3: Decision foundation + +## Hypothesis +Контрактные решения фиксируем до кодирования, чтобы карточки не разъехались. + +## Evidence Found +- Pattern: `sessionStreamFrameSchema = {id, type: string, data: record, session?}` — новый терминальный тип проходит envelope без миграции, но фронт должен различать его до `frameText`. +- Pattern: `filterFrame` применяется ПОСЛЕ `mapFrame` — `?session=` естественно ложится как server-side предикат поверх существующего `localSessionIds ∈` (не замена, а сужение). +- Pattern: `useChat frameText` уже знает терминалы `session.text.ended / session.execution.succeeded / session.step.ended → idle/finalize` — новый `stream.error` должен идти отдельным каналом (error, не finalize). +- Conflict: `if (!sendingRef.current) continue` стоит ДО `frame.session` проверки — после F5 (sending=false, тред жив) подписка глушит догоняющие кадры. Решение: разделить гарды. +- Conflict: `setError` на любую транспортную ошибку vs тихий backoff — решение: транзиент молча redial, ErrorState только на терминальный error-кадр / REST-историю. + +## Decisions +- Decision: heartbeat = SSE-коммент `: ping\n\n` каждые ~15s из `relaySse` (транспортный уровень, не кадр), фронт-watchdog: если ни кадра ни ping > N (напр. 30–45s) → тихий redial без `setError`. Alternatives: `data: heartbeat` кадр — rejected (загрязняет `sessionStreamFrameSchema`, будит `frameText`). +- Decision: терминальный кадр = `data: {id, type:'stream.error', data:{message?, code?}, session?}` + `res.end()` сразу после; фронт: fail-soft — показать ErrorState с retry, **тред не затирать** (ошибка отдельно от messages). Alternatives: тихий `res.end()` — rejected (неотличим от idle → вечный sending, это и есть текущий баг). +- Decision: курсор = `Last-Event-ID` request header + `?cursor=` fallback; сервер шлёт `id: ` на каждом `data:` (SSE-нативно) + replay начинает после cursor (по `localFrames` id, при неизвестном cursor — полный локальный replay, не пустой). Alternatives: кастомный `?since=` — rejected (ломаем SSE-семантику, прокси/клиенты знают `Last-Event-ID`). +- Decision: `?session=` — опциональный query `GET /events?projectId=&session=`; сервер: C4-gate прежний + сужение `localSessionIds ∩ {session}` + тот же `filterFrame` остаётся как defense-in-depth. Пустой/чужой session → тихий пустой стрим (не 404 — не ликать существование). Alternatives: обязательный session — rejected (ломает существующие подписки без session, мульти-чат экраны). +- Decision: fail-soft парсинг одного кадра: `JSON.parse` в try + `sessionStreamFrameSchema.safeParse` (не `.parse`); битый чанк → счётчик + skip, стрим живёт. Alternatives: FAIL LOUD — rejected (один битый кадр = смерть треда, текущий баг). +- Decision: sending-гард vs подписка: подписка **всегда активна** при `projectId` (копит `streamingRef`/partLens независимо от sending); `sending` влияет только на `finalize()`/индикаторы. `stop()` дропает через `abortedTurnRef`/эпоху, а не через глушение всей подписки. Alternatives: оставить `continue` при !sending — rejected (теряем догон после F5). +- Decision: persist URL: path `sessions/[sessionId]` остаётся источником `sessionId`; `agentId` → `?agent=` search-param (синк двусторонний: `setAgentId` пишет в URL, инициализация читает из URL с фолбэком `DEFAULT_AGENT_ID='ask'`); после `createSession` — `router.replace` на новый sessionId без потери истории. Alternatives: localStorage — rejected (не шарится ссылкой, ТЗ требует URL). +- Decision: resync триггеры: `window online` + `document visibilitychange→visible` → тихий `reload()` (REST-история + redial SSE, nonce++), без `setError`. +- Decision: Vercel useChat / React Query для SSE — **запрещены** (guard `no-opencode-transport.test.ts`, AGENTS.md streaming-исключение с комментом-обоснованием в `useChat`). + +## Confirmed Plan Items +1. Контракт heartbeat/error/cursor/session — reason: карточки C0–C3 пишут один wire-формат. +2. Разделение гардов и политика ошибок — reason: карточки C4/C6 без этого вернут баги. + +## Open Questions +- Точный heartbeat-интервал (15s vs 25s под конкретный прокси) — оставить константой `HEARTBEAT_MS` с тестом на наличие `: ping`. +- Нужен ли `Retry:` SSE-заголовок от сервера — опционально, фронт-backoff остаётся источником правды. + +## Next Epoch Focus +- Refinement: разложить по карточкам файлы/чек-листы/зависимости/complexity/риск/builder. diff --git a/.plans/amber-phoenix-qt7/epoch-04.md b/.plans/amber-phoenix-qt7/epoch-04.md new file mode 100644 index 0000000..0b21693 --- /dev/null +++ b/.plans/amber-phoenix-qt7/epoch-04.md @@ -0,0 +1,34 @@ +# Epoch 4: Refinement — карточки, зависимости, сложность + +## Hypothesis +7 карточек покрывают все 5 пунктов ТЗ + приёмку; порядок исключает гонки wire-формата. + +## Evidence Found +- File: `sse-relay.ts:89-94` — заголовки SSE ставятся до `flushHeaders` — heartbeat-таймер стартует после, чистится в `finally` (точка C0). +- File: `session-harness:1056-1073` — replay без cursor; `frames` = `this.localFrames` (in-memory) — cursor ищется по `frame.id` (точка C1). +- File: `sessions.controller.ts:303-311` — `events()` без `@Query('session')` (точка C2). +- File: `sessions-client.ts:219-239` — split `\n\n` + `parse` throw (точка C3). +- File: `useChat.ts:349-357` — sending-гард до session-фильтра (точка C4). +- File: `chat-section.tsx:41` + `sessions/[sessionId]/page.tsx:12-13` — нет URL-синка agent (точка C5). +- File: `chat-window.tsx:107-113` — error заменяет тред (точка C6). + +## Decisions +- Decision: порядок C0(root) → C1,C2(branch, после C0) → C3(branch, после C0+C2) → C4(branch, после C3) → C5(leaf, после C4) → C6(leaf, после всех). Alternatives: параллелить C4 раньше C3 — rejected (хук зависит от fail-soft/watchdog-сигналов транспорта). +- Decision: complexity (0-20) и риск (0-8) оценены по файлам/ветвлениям/внешним факторам; builder: score≤8+риск low → `build-fast`, иначе `build-smart`. +- Rationale: heartbeat+error (C0) меняют wire — все потребители после; URL (C5) только читает stabilised `sessionId/activeSessionId`. + +## Confirmed Plan Items +1. C0 root — heartbeat + `stream.error` + `id:` на кадрах (sse-relay, контракты, openapi). +2. C1 branch — cursor/Last-Event-ID в replay-буфере harness. +3. C2 branch — `?session=` в controller/service/harness-filter. +4. C3 branch — транспорт fail-soft + Last-Event-ID + watchdog-сигнал (sessions-client, client). +5. C4 branch — useChat self-healing (watchdog, backoff-тишина, resync, гарды, страховка sending). +6. C5 leaf — persist sessionId+agentId в URL. +7. C6 leaf — политика ErrorState + приёмка/e2e. + +## Open Questions +- Подтвердить монотонность `frame.id` в `localFrames` при имплементации C1 (если нет — серверный seq-обёртка, additive). +- Точный watchdog-таймаут (30s vs 45s) — финализировать в C4 с учётом HEARTBEAT_MS из C0. + +## Next Epoch Focus +- Validation: сверить каждую карточку с существующими паттернами (AppLogger, boundary-schemas, C4-gate, guard-тесты) + дописать критерии done. diff --git a/.plans/amber-phoenix-qt7/epoch-05.md b/.plans/amber-phoenix-qt7/epoch-05.md new file mode 100644 index 0000000..298ef84 --- /dev/null +++ b/.plans/amber-phoenix-qt7/epoch-05.md @@ -0,0 +1,27 @@ +# Epoch 5: Validation against patterns + +## Hypothesis +Карточки не нарушают каноны репо (логи, граница, скоупы, guard-тесты). + +## Evidence Found +- Pattern backend: только `AppLogger`, `console.*` запрещён; `filterFrame` логирует только count (`droppedByFilter`), не контент — C0–C2 обязаны так же (heartbeat/error без тел). +- Pattern: C4-gate `assertProjectAccessById` → 404 без утечки на каждый route — C2 `?session=` не вводит новых 404 (чужой session = пустой стрим, не ошибка). +- Pattern: контракты зеркалят `contracts/openapi.yaml` поле-в-поле — C0/C2 обязаны править оба (schema + yaml), иначе `shape_mismatch`/drift. +- Pattern: фронт `parseBoundary` + `ApiClientError`, токен никогда не логируется — C3/C4 без логов тел кадров. +- Pattern: `src/__tests__/no-opencode-transport.test.ts` — C3–C5 не смеют тянуть `@opencode-ai/sdk` или `/api/opencode/*` даже в комментариях. +- Pattern: тесты рядом `__tests__/*.spec.ts`, e2e через testcontainers — C6 кладёт юнит (heartbeat/error/fail-soft/filter) + ручную приёмку F5/обрыв. + +## Decisions +- Decision: каждая карточка несёт `Файлы`, `Чек-лист`, `Зависимости`, `Complexity/Risk/Builder`, `Done` — готово к Trello и `classify_build`. +- Alternatives considered: ужать до 5 карточек (по пунктам ТЗ 1:1) — rejected (п.5 ТЗ = 4 подзадачи: error-кадр + fail-soft + resync + гарды; сливание прячет риски). +- Rationale: 7 карточек = 7 Trello-карт с Blocked-by цепочкой; builder выбирается per-card. + +## Confirmed Plan Items +1. Валидировано: heartbeat — коммент, не кадр; error-кадр — envelope-совместим; cursor — SSE-нативен; session-фильтр — сужение, не замена. +2. Валидировано: ErrorState только на терминал; транзиент — тихий backoff. + +## Open Questions +- Нет открытых — финализировать PLAN.md + evolution-log.md. + +## Next Epoch Focus +- Finalize: собрать PLAN.md (карточки полностью) + evolution-log.md, доложить каталог. diff --git a/.plans/amber-phoenix-qt7/epoch-06.md b/.plans/amber-phoenix-qt7/epoch-06.md new file mode 100644 index 0000000..1bec097 --- /dev/null +++ b/.plans/amber-phoenix-qt7/epoch-06.md @@ -0,0 +1,26 @@ +# Epoch 6: Finalize + +## Hypothesis +PLAN.md + evolution-log.md синтезируют эпохи 1–5 в исполняемую последовательность без потери решений. + +## Evidence Found +- File: `epoch-01.md` — гипотеза и non-negotiable (свой транспорт). +- File: `epoch-02.md` — конкретные строки-доказательства по всем путям ТЗ. +- File: `epoch-03.md` — wire-решения (ping-коммент, stream.error, Last-Event-ID, ?session=, fail-soft, гарды, URL). +- File: `epoch-04.md` — 7 карточек и порядок. +- File: `epoch-05.md` — валидация против канонов (AppLogger, boundary, C4-gate, guard-тесты). + +## Decisions +- Decision: зафиксировать PLAN.md ниже как синтез (7 карточек C0–C6, только план, никакого кода). +- Alternatives considered: переоткрыть спор heartbeat-кадр vs коммент — rejected (решён в Epoch 3: коммент). +- Rationale: каждая эпоха grounded в предыдущей; история решений — в evolution-log.md, superseded нет. + +## Confirmed Plan Items +1. PLAN.md создан — reason: исполняемая последовательность для Trello + classify_build. +2. evolution-log.md создан — reason: трассируемость решений. + +## Open Questions +- Нет. Имплементация начинается с C0; вопросы монотонности id и точного watchdog-таймаута — внутри карточек. + +## Next Epoch Focus +- Исполнение: завести Trello-карточки C0–C6, далее build per-card (fast/smart по карточке). diff --git a/.plans/amber-phoenix-qt7/evolution-log.md b/.plans/amber-phoenix-qt7/evolution-log.md new file mode 100644 index 0000000..cc738c5 --- /dev/null +++ b/.plans/amber-phoenix-qt7/evolution-log.md @@ -0,0 +1,13 @@ +# Evolution log — amber-phoenix-qt7 + +| Epoch | Hypothesis → Evidence → Decision | Status | +|---|---|---| +| 01 Coarse hypothesis | Своим транспортом дотягиваем 5 пунктов; Trello-карточки + builder-метки | confirmed | +| 02 Evidence gathering | Прочитаны sse-relay (нет ping), harness 1056+ (нет cursor), controller (нет ?session=), sessions-client (FAIL LOUD parse), useChat (sending-гард до session-фильтра, setError на транзиент), chat-window (error заменяет тред), page (нет ?agent=) | confirmed | +| 03 Decision foundation | heartbeat=`: ping` коммент; error=`stream.error`+end; cursor=`Last-Event-ID`+`id:`; `?session=` optional+filter defense; fail-soft safeParse; подписка всегда, гарды разделены; URL path+`?agent=`; resync online/visibility | confirmed | +| 04 Refinement | 7 карточек C0–C6, порядок root→branch→leaf, complexity/риск/builder назначены | confirmed | +| 05 Validation | Сверено с AppLogger-only, boundary-schemas, C4-gate без утечки, yaml-зеркалом, no-opencode guard | confirmed | +| 06 Finalize | PLAN.md + evolution-log.md синтезированы | confirmed | + +Superseded: нет (первый проход, конфликтов с откатом решений не было). +Конфликты, разрешённые в Epoch 3: sending-гард vs подписка (разделены); транзиент vs терминал (тишина vs ErrorState); heartbeat-кадр vs коммент (коммент); ?session= обязательный vs optional (optional); cursor кастомный vs Last-Event-ID (Last-Event-ID). diff --git a/.plans/backend-domain-restructure/PLAN.md b/.plans/backend-domain-restructure/PLAN.md new file mode 100644 index 0000000..eed7935 --- /dev/null +++ b/.plans/backend-domain-restructure/PLAN.md @@ -0,0 +1,329 @@ +# План реструктуризации backend по scope: Common / Organization (⊃ Project) / Processes + +Статус: черновик v2 (правки: platform→common, crypto/keys→common, projects внутри organizations, ai+workers→processes), код не написан. Трекинг задач не используется. +Принцип: только перемещение и выделение границ, без изменения поведения. +Каждый этап — зелёные `bun run lint` + `bun run build`, e2e не краснеют. + +## 0. Зачем и что чиним (факт на 2026-11-01) + +Текущее дерево `apps/backend/src/` — историческое, не scope-ориентированное: + +``` +src/ +├─ main.ts, contracts.ts (deprecated-реэкспорт @rush-code/contracts) +├─ app/ — AppModule (DI-граф), app.setup.ts +├─ common/ — logger, env, validation, external, api-error, interceptors, sse-relay + common.module + db/ (schema.ts, db.module/service) +├─ health/ — GET /health +├─ users/ — users.module/service + auth/ (auth.module, jwt-auth.guard, token/password services, dto) +├─ organizations/ — organizations.module/service/controller + org-projects.controller +│ └─ modules/ — crypto/, keys/, projects/ (projects.module + modules/files,github,sessions,chats), registries/ (modules/docker,npm) +├─ repos/ — REPOS_ROOT реестр, jail (repos-git.util, assertInsideJail) +├─ workspaces/ — per-user surface (workspace-path/clone/submodules, clone-jobs.repository) +│ └─ modules/ — clone/, path/ (WorkspacePathService) +├─ storage/ — storage-unavailable.ts (единый 503-гейт без корня) +├─ ai/ — AiModule (агрегатор) +│ └─ modules/ — agents/, workers/, opencode/ (transport + mirror 18 роутов + modules/crypto,keys,billing,auth,client), sessions/ (доменные /api/sessions* 9 роутов) +└─ (legacy по ARCHITECTURE.md: api/, docker-registry/, npm-registry/ — сверять с фактом, часть уже переехала в organizations/modules/registries) +``` + +Проблемы: + +1. **Два места для одного scope.** Проекты живут в `organizations/modules/projects/`, а сессии/опенкод — в `ai/modules/`. Зависимость `organizations → ai` и `ai → organizations` неявная, риск цикла. +2. **`common/db` внутри `common/`.** БД — платформенная зависимость, её импортируют все. Лежит рядом с логгером и SSE — легко зацепить лишнее одним импортом `CommonModule`. +3. **Три jail-источника.** `repos/` (git-дерево), `workspaces/modules/path` (`WorkspacePathService`), `storage/` (503-гейт), плюс `PROJECTS_ROOT`/`REPOS_ROOT` в `env.ts`. Правило «REPOS_ROOT — единственный источник» (AGENTS.md) размазано по трём модулям. +4. **Секреты размазаны.** `OPENCODE_KEYS_*` (KEK active/previous + keyId), `JWT_*`, `GITHUB_*`, `DOCKER_*`, `NPM_*`, `OPENCODE_PASSWORD` — все в одном `common/env/env.ts` (~1200 строк). Нет деления «платформа / орг-уровень / проект-уровень». +5. **`users/auth` внутри `users/`.** Auth — платформенный механизм (JWT guard, C4-гейт `assertProjectAccessById`), а не часть user-профиля. Сейчас `AuthModule` вложен, `UsersModule` — global без импорта. + +Цель — три уровня scope с однонаправленными зависимостями. + +## 1. Три уровня scope + +| Scope | Что это | Что владеет | От кого зависит | +|---|---|---|---| +| **Common** | Кросс-каттинг, нет бизнес-смысла. Живёт без орг/проект понятий | `common/` (logger, env-контракт, validation, external/retry, фильтры, interceptors, sse-relay, `db/`, `storage/` 503-гейт, `crypto/` KEK, `keys/` rotation/store), `health/`, `users/` (профили) + `auth/` (JWT guard/token/password) как sibling | Только NestJS + `pg`/`drizzle` + `zod`. **Ни от кого из ниже не зависит** | +| **Organization** | Тенант. Владелец проектов, мемберства, реестров. Проект существует ТОЛЬКО внутри: `organizations/projects/` | `organizations/` (org CRUD, members, invites), `organizations/registries/` (docker/npm observe-only), `organizations/projects/` (см. §2: access, secrets-override, repository, files, github-link, chats, sessions-persistence) | Только от Common. **Ничего не знает о processes** | +| **Processes** | Выполнение по чужому вызову. Сам не стартует, без владения данными. Вызывается: (1) HTTP-клиентом (фронт) через `AppModule → ProcessesModule → controller` (`sessions/opencode/agents`); контроллер достаёт identity (guard) + `projectId`, проверяет доступ через `organizations/projects/access`, резолвит directory и идёт в runner; (2) `workers/` — событиями/очередью от проектов (пока scaffold, триггеры те же: project-контекст обязателен) | `processes/ai/` (agents, sessions-домен `/api/sessions*`, opencode-транспорт), `processes/workers/` (фоновые задачи, рядом с ai на одном уровне) | От Common + Organization (`projects/access` gate, `repository` путь, `ai-providers`/secrets конфиг). **Никто не зависит от Processes как от библиотеки; Processes зависит от вызова извне** | + +Правило чтения таблицы: зависимость идёт **только сверху вниз** (Processes → Organization → Common). Обратная стрелка — ошибка ревью. +Проекты не существуют сами по себе: путь всегда `organizations/projects/`, импорт всегда через `organizations/...`, отдельного верхнего `projects/` нет. +Процессы не существуют сами по себе: у `processes/*` нет входящих импортов из доменов (только `AppModule` монтирует модуль ради HTTP-роутов); вход — HTTP-запрос или событие с `projectId`, а не прямой вызов сервиса из `organizations/projects/*`. Связь `projects/chats → sessions` в текущем коде — это DB-persistence (`project_sessions.chatId`), а не вызов runner. + +## 2. Целевая структура + +``` +src/ +├─ main.ts — без изменений (dotenv-expand, setup, validateEnvWithWarnings) +├─ app/ # СЛОЙ СОХРАНЁН: композиционный корень, не растворяется по доменам +│ ├─ app.module.ts — только сборка графа: Common → Organization (⊃ Projects) → Processes +│ └─ app.setup.ts — без изменений: global prefix 'api', URI-versioning, CORS, Swagger, фильтры (состав сборки тот же) +├─ common/ # SCOPE: Common (бывший platform/, переименование обратно) +│ ├─ logger/ # AppLogger + serializeCause +│ ├─ env/ # env.ts, контракт; секреты — см. §4 +│ ├─ validation/ # ZodValidationPipe +│ ├─ external/ # ExternalClient, retry, EXTERNAL_* +│ ├─ http/ # api-error.filter, correlation/noindex interceptors + api/ (version, dto) +│ ├─ sse/ # sse-relay (probe→503, abort downstream, бэкофф) +│ ├─ db/ # schema.ts, db.module/service, integrity (остаётся в common/) +│ ├─ storage/ # storage-unavailable.ts (503-гейт) + jail (ex workspaces/modules/path) +│ ├─ crypto/ # KEK AES-256-GCM — переиспользуемый, вынос из organizations/modules/crypto/ +│ └─ keys/ # rotation/store opencode keys (+ reencrypt) — переиспользуемый, вынос из organizations/modules/keys/ +├─ health/ # без изменений (Common, ни от кого не зависит) +├─ users/ # Common: профили (UsersService, users.controller) +├─ auth/ # Common: sibling users/ (jwt-auth.guard, token/password, dto) — вынос из users/auth/ +├─ organizations/ # SCOPE: Organization (владелец projects) +│ ├─ organizations.{module,service,controller}.ts +│ ├─ members/ # вынос membership из organizations.service +│ ├─ invites/ # вынос invites +│ ├─ org-projects.controller.ts # тонкая проекция в projects (делегирует, см. §3.4) +│ ├─ registries/ # docker/ + npm/ (observe-only) — часть организаций +│ └─ projects/ # ПРОЕКТ ВНУТРИ ОРГАНИЗАЦИИ (не верхний уровень) +│ ├─ projects.{module,service,controller}.ts +│ ├─ access/ # assertProjectAccessById (C4-гейт) — единый импорт +│ ├─ secrets/ # scope=project, override поверх organizations/secrets +│ ├─ repository/ # git на диске: clone, tree, submodules, status, catalog (ex workspaces+repos) +│ ├─ files/ # файлы проекта (ex project-files) +│ ├─ github-link/ # репо GitHub ↔ проект (installation принадлежит орг) +│ ├─ chats/ # project_chats (FK cascade) +│ └─ sessions/ # project_sessions (+ chat SET NULL) — persistence +├─ processes/ # SCOPE: Processes (новое; ai и workers на одном уровне) +│ ├─ ai/ # runtime AI: sessions-домен /api/sessions*, opencode-транспорт, agents +│ │ ├─ sessions/ # доменные /api/sessions* (VERSION_NEUTRAL, 9 роутов) +│ │ ├─ opencode/ # OpencodeService dialUrl, SdkClient, billing/auth + deprecated-зеркало +│ │ └─ agents/ # контроллер агентов +│ └─ workers/ # фоновые задачи (ex ai/modules/workers/, sibling ai/) +├─ secrets/ # scope=organization (org-уровень, см. §4; переопределяется в organizations/projects/secrets/) +└─ (legacy: repos/, workspaces/ — схлопнуть в organizations/projects/repository/ + common/storage/ jail, см. фазы) +``` + +Что переезжает (механика — только `git mv` + правка импортов, логика 1:1): + +| Было | Станет | Примечание | +|---|---|---| +| `organizations/modules/crypto/` | `common/crypto/` | Переиспользуемый KEK; `KeysModule`+`auth` импортируют из common | +| `organizations/modules/keys/` | `common/keys/` | Rotation/store переиспользуемый; scope данных остаётся org/project (см. §4), модуль — в common | +| `organizations/modules/projects/` | `organizations/projects/` | Убрать лишний `modules/` уровень; проект внутри организации | +| `ai/modules/` | `processes/ai/` | Весь ai целиком; импорты `ai/**` → `processes/ai/**` | +| `ai/modules/workers/` | `processes/workers/` | На один уровень с ai внутри processes/ | +| `workspaces/modules/path` | `common/storage/` | Jail в common рядом с 503-гейтом | +| `common/api/` (version, dto) | `common/http/api/` | api как часть http-инфры common (бывший platform/http) | +| membership/invites внутри `organizations.service.ts` | `organizations/members/`, `organizations/invites/` | Выделение без смены SQL (таблицы те же) | + +Что НЕ переезжает в этом плане: `main.ts`, `contracts.ts` (deprecated-реэкспорт — удаляется только в SDK-миграции, см. `.plans/opencode-sdk-migration/PLAN.md`), `drizzle/` SQL-миграции, `packages/contracts` + `contracts/openapi.yaml` (только сверка имён после переезда). + +## 3. Правила зависимостей (ревью-гейт) + +0. **Слой `app/` сохраняется.** `app/app.module.ts` (DI-граф) + `app/app.setup.ts` (prefix, versioning, CORS, Swagger) остаются композиционным корнем, не растворяются по доменам. Фазы меняют только состав импортов внутри `AppModule`, сам слой не удаляется. +1. **Common ни от кого не импортирует.** `common/*`, `health`, `users`, `auth` — запрещены импорты из `organizations/`, `processes/`, `repos/`, `workspaces/`. Нарушение = `bun run lint` кастомное правило (см. фазу 8) или ручной grep-гейт `grep -r "from.*organizations" src/common/`. +2. **Organization — только Common.** `organizations/**` может импортировать `common/*`, `users`, `auth` (guard). Запрещены импорты из `processes/`. +3. **Processes — Common + Organization.** `processes/**` может импортировать всё ниже. Запрещено: `organizations/** → processes/**`, `common/** → любой домен`. +4. **`org-projects.controller.ts` — единственное исключение.** Тонкая проекция (делегирует в `ProjectsService` внутри `organizations/projects/`), помечается `// SCOPE-EXCEPTION: projection, delegates only, no logic`. +5. **Processes вызываются извне.** Запрещены прямые импорты `processes/*` из `organizations/**` (кроме монтирования в `AppModule`); вход в Processes — только HTTP (`sessions/opencode/agents` контроллеры) или событие/очередь (`workers/`) с обязательным `projectId` + gate через `organizations/projects/access`. `processes/*` не хранит строки без FK на проекты и не стартует сам. +6. **`WorkspacePathService` — stateless, предоставляется напрямую из `common/storage`.** Чтобы не тянуть `WorkspacesModule` целиком в Organization scope. +7. **C4-гейт единый.** Все проектные роуты идут через `organizations/projects/access/assertProjectAccessById`. Прямые запросы к `project_sessions`/`project_chats` без гейта — нарушение. +8. **Jail единый.** Чтение/запись диска — только через `common/storage` (assertInsideJail) + `REPOS_ROOT`. Прямой `fs` в `organizations/projects/files` или `processes/*` — нарушение (кроме `resolveGithubPrivateKey` в env). + +Таблица разрешённых импортов: + +| Импортёр \ Импортируемый | common | users/auth | storage/health | organizations (⊃projects) | processes | +|---|---|---|---|---|---| +| common | ✅ | ❌ | ✅ | ❌ | ❌ | +| organizations | ✅ | ✅ | ✅ | ✅ | ❌ (кроме org-projects проекции) | +| processes | ✅ | ✅ | ✅ | ✅ | ✅ | + +## 4. Секреты / провайдеры / лимиты + +Карта секретов (где живут сейчас → где должны проверяться после реструктуризации; значения не меняются): + +| Секрет / конфиг | Scope | Хранение | Поведение без значения (сохранить 1:1) | +|---|---|---|---| +| `OPENCODE_KEYS_ENCRYPTION_KEY` (+ `_PREVIOUS`, `ACTIVE_KEY_ID`, `PREVIOUS_KEY_ID`) | Organization (KEK для secrets) | `common/env` контракт, потребление в `common/crypto` | Пусто → WARN на boot + 500 `opencode_keys_unconfigured` на key-эндпоинтах; короткий explicit → ERROR (значение никогда в лог) | +| `OPENCODE_PASSWORD` / `OPENCODE_SERVER_PASSWORD` + `OPENCODE_URL`/`TOKEN` | Processes-транспорт (`processes/ai/opencode`) | `common/env`, потребление в `OpencodeService`/`OpencodeAuthService` | Пусто → WARN + upstream 401 (честный сигнал); dial `0.0.0.0 → 127.0.0.1` в `dialUrl` сохранить | +| `JWT_ACCESS_SECRET` / `JWT_REFRESH_SECRET` (+ TTL) | Common (`auth/`) | `common/env`, потребление в token service | Пусто → ephemeral dev secret + boot WARN; explicit < 32 → ERROR | +| `GITHUB_APP_ID` + `PRIVATE_KEY`/`PATH` (+ `INSTALLATION_ID` legacy, `SLUG`, `WEBHOOK_SECRET`, `API_URL`) | Project (`organizations/projects/github-link`, installation в орг) | `common/env`, потребление в github service | Половинчатая пара → ERROR; пусто → WARN + 401/503; legacy install → WARN deprecated | +| `DOCKER_REGISTRY_*` (URL/USER/PASSWORD/TOKEN/timeout/retry) | Organization (`organizations/registries/docker`) | `common/env`, потребление в docker module | Пусто URL → WARN + 503 + health `skipped`; половинчатая basic-пара → WARN + anonymous | +| `NPM_REGISTRY_*` (URL/TOKEN legacy `NPM_TOKEN`/USER/PASSWORD/SCOPE/timeout/retry) | Organization (`organizations/registries/npm`) | `common/env`, потребление в npm module | Пусто URL → WARN + 503 + `skipped`; приоритет TOKEN > basic > anonymous сохранить | +| `DATABASE_URL` / `POSTGRES_*` | Common (`common/db`) | `common/env` | Пусто → WARN + 503 `EXTERNAL_UNAVAILABLE` на pg-операциях; compose из `POSTGRES_*` сохранить | +| `REPOS_ROOT` (+ legacy `PROJECTS_ROOT`) | Common-гейт (`common/storage`), исполнение в `organizations/projects/repository/` | `common/env` | Пусто → boot ERROR-лог + reads 503 / creates 500; без fallback на `/repos` (fail-fast, см. AGENTS.md) | +| `CORS_ORIGINS`, `NEXT_PUBLIC_*`, `REQUEST_TIMEOUT_MS`, `EXTERNAL_RETRY_*`, `LOG_LEVEL` | Common | `common/env` | Дефолты-тюнинг чтения сохранить (см. env.ts readonly-исключения), мусор → ERROR/WARN как сейчас | + +Провайдеры (DI): + +| Провайдер | Scope | Доступ | +|---|---|---| +| `AppLogger` | Common | Global (через `common/logger` или `CommonModule`-совместимость на переход) | +| `DbService` (`DbModule`) | Common | Global/импорт везде; единственный доступ к `pg`/`drizzle` | +| `UsersService` (`UsersModule` global) | Common | Без импорта (как сейчас в `OrganizationsModule` — не импортировать, нет цикла) | +| `CryptoService` | Common (переиспользуемый) | Экспорт из `common/crypto`, импорт в `common/keys` + `auth` + `organizations/secrets` | +| `WorkspacePathService` | Common (`common/storage`) | `provided directly` (stateless), не тянет весь `WorkspacesModule` | +| `OpencodeService` / `OpencodeSdkClient` / `OpencodeBillingService` | Processes-транспорт (`processes/ai/opencode`) | Реэкспорт через `ProcessesModule`/`AiModule`; потребители — только Processes scope | + +Лимиты (не менять в этом плане, только сохранить проводку): + +- `REQUEST_TIMEOUT_MS` (default 10000), `EXTERNAL_RETRY_*` (3 / 200 / 2000), registry-таймауты (10000) и retry (3/200/2000) — дефолты и `retryInt`/`timeoutSchema` валидация 1:1. +- JWT TTL: access 900s / refresh 604800s. +- KEK: `MIN_*_LENGTH = 32`, `KEY_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_-]{0,31}$`. +- Логи: только `AppLogger`, normal path без стеков/секретов/PII/URL/body/Bearer; e2e-скан секретов (эталон `opencode-keys.e2e.ts`) обязан остаться зелёным. + +## 5. Фазы 0–9 + +### Фаза 0. Инвентаризация (read-only, без кода) + +- Снять фактический граф импортов: `graphify` / `scripts/graphify/run.sh` (`pattern: src/**/*.ts`) + ручной `grep` на `from.*\.\./` через границы scope. +- Сверить `ARCHITECTURE.md` с фактом (legacy `api/`, `docker-registry/`, `npm-registry/` — живы или уже переехали в `organizations/modules/registries`). +- Зафиксировать список контроллеров/роутов до переезда (swagger snapshot / `versioning.e2e.ts` ожидания). +- Выход: таблица «модуль → scope → переезжает/остаётся» + список циклических импортов (если есть). +- Гейт: `bun run lint` + `bun run build` зелёные до старта (база). + +### Фаза 1. Common: консолидация `common/` (без переименований в platform) + +- `common/crypto` ← `organizations/modules/crypto`, `common/keys` ← `organizations/modules/keys` (`git mv`, переиспользуемые). +- `common/storage` ← `workspaces/modules/path` (jail) + уже лежащий `storage-unavailable.ts` (503-гейт) рядом. +- `common/http/api` ← `common/api` (version, dto) — api как часть http-инфры. +- `app.module.ts` — проводка остаётся на `CommonModule` (без platform-шима, т.к. platform→common откат). +- Гейт: lint + build + `test:e2e:auth` (guard/validation затронуты). + +### Фаза 2. Common: `auth/` sibling + `storage/`/`health` фиксация + +- `git mv users/auth → auth/`; `AuthModule` импортируется в `AppModule` напрямую; `UsersModule` остаётся global. +- Проверить отсутствие цикла `auth ↔ users` (auth — только `DbService` + token/password, users — только `DbService`). +- `storage/`, `health/` — без переезда, добавить scope-комменты в module-файлы (`// SCOPE: Common`). +- Гейт: lint + build + `test:e2e:auth`. + +### Фаза 3. Organization: консолидация `organizations/` + +- Выделить `organizations/members/` и `organizations/invites/` из `organizations.service.ts` (сервисы + контроллерные методы переезжают, SQL/таблицы те же: `organization_members` partial unique single-maintainer, `organization_invites` token-PK single-use). +- `common/crypto`, `common/keys` — уже в common (фаза 1), добавить scope-комменты; `KeysModule` путь обновить в зависимых (совместимость с `.plans/opencode-sdk-migration` spike — только пути). +- `WorkspacePathService` — сохранить `provided directly`, задокументировать в module-комменте. +- Гейт: lint + build + `test:e2e:github` (install/membership задеты) + `test:e2e:opencode-keys` (KEK/keys). + +### Фаза 4. Organization⊃Project: консолидация `organizations/projects/` + +- `organizations/modules/projects → organizations/projects/` (убрать лишний `modules/` уровень; целиком: `projects.module/service/controller` + `files,github-link,sessions,chats,repository,access,secrets`). +- `organizations/org-projects.controller.ts` — ужать до проекции (делегация в `ProjectsService` внутри `organizations/projects/`, пометка `SCOPE-EXCEPTION`). +- `OrganizationsModule`: владеет `ProjectsModule` (проект внутри организации — допустимая стрелка вниз). Обратное (`ProjectsModule → OrganizationsModule` ради гейта) запрещено — gate живёт в `organizations/projects/access/`. +- Выделить `organizations/projects/access/` (C4-гейт) — все контроллеры `organizations/projects/*` идут через него. +- Гейт: lint + build + `test:e2e:projects` + `test:e2e:repos`. + +### Фаза 5. Исполнители: `processes/` + `organizations/projects/repository/` привязка + +- `ai/ → processes/ai/` (`git mv` целиком: sessions, opencode, agents); `ai/modules/workers/ → processes/workers/` (sibling ai внутри processes/). +- `repos/` + `workspaces/` → схлопнуть в `organizations/projects/repository/` (clone/tree/submodules/status/catalog) + jail в `common/storage`; зафиксировать jail-контракт: `REPOS_ROOT//workspace/`, `assertInsideJail` на каждый вход, `storage-unavailable` 503-гейт. +- Удалить прямые `fs`-доступы вне `repository/`/`common/storage/` (grep-гейт), кроме `resolveGithubPrivateKey` в env. +- `processes/ai`: ни один сервис не хранит строки без FK на `projects(id)` (сверить `project_sessions`/`session_messages` планы SDK-миграции — foreign keys `ON DELETE CASCADE`, `parent_session_id SET NULL`). +- Гейт: lint + build + `test:e2e:repos` + `test:e2e:opencode-keys` (скан секретов). + +### Фаза 6. Решения до старта (§6) — зафиксировать письменно + +- Закрыть все 7 вопросов из §6 до первого `git mv` (особенно направление `OrganizationsModule ↔ ProjectsModule` и судьба `CommonModule`-шима). +- Выход: апдейт этого PLAN.md (таблица решений: принято/дата) — без этого фаза 1 не начинается. + +### Фаза 7. Контракты и swagger-сверка + +- `packages/contracts` (12 пар) + `contracts/openapi.yaml` — только сверка: пути/DTO не меняются при переезде (переезд — внутренний, wire-контракт тот же). +- `contracts.ts` реэкспорт — не трогать (удаление — только в SDK-миграции). +- `versioning.e2e.ts` + `app.setup.ts` (prefix `api`, versioning) — без изменений; прогнать `test:e2e` полностью как сверку. +- Гейт: полный `bun run test:e2e` зелёный. + +### Фаза 8. Гейты: lint/build/e2e + grep-гейты границ + +- `bun run lint` (`tsc --noEmit` + `biome`) + `bun run build` — обязательно после каждой фазы. +- Добавить grep-гейты (временно руками, постоянные — по решению §6.7): + - `grep -rn "from.*organizations" src/common/` → пусто; + - `grep -rn "from.*processes" src/organizations/ --exclude=org-projects.controller.ts` → пусто; + - `grep -rn "from.*cwd.*repos\|__dirname.*repos" src/organizations src/processes` → пусто (jail-контракт). +- `db:check-integrity` (Drizzle schema-integrity) после фаз 1/4. +- Полный `bun run test` (юнит из `dist`) + `bun run test:e2e`. + +### Фаза 9. Чистка и документы + +- Удалить legacy `repos/`, `workspaces/`, `ai/` верхние dirs — только когда ноль импортов (`grep -rn "from.*repos/\|from.*workspaces/\|from.*ai/modules" src/ | wc -l == 0`). +- Обновить `apps/backend/ARCHITECTURE.md` (новое дерево `src/`) + `apps/backend/AGENTS.md` (scope-правила коротко) + корневой `AGENTS.md` при необходимости. +- Обновить `.plans/opencode-sdk-migration/PLAN.md` пути (`src/opencode` → `src/processes/ai/opencode`, `src/sessions` → `src/processes/ai/sessions`, `src/projects/sessions` → `src/organizations/projects/sessions`, `src/db` → `src/common/db`, `src/ai/modules/workers` → `src/processes/workers`) — только пути, без смены смысла. +- Финальный прогон: lint + build + test + test:e2e + `db:check-integrity`. + +## 6. Решения до старта (закрыть до фазы 1) + +| # | Вопрос | Опции | Дефолт (если не решат) | +|---|---|---|---| +| 6.1 | Вложенность `organizations/projects` | (a) Проект только внутри `organizations/projects/`; (b) верхний `projects/` | (a) — принято правкой v2 | +| 6.2 | Судьба `CommonModule` | (a) Оставить как есть (platform→common откат, шим не нужен); (b) шим-реэкспорт | (a) | +| 6.3 | Резать ли `env.ts` (~1200 строк) в этом плане | (a) Не резать — остаётся `common/env`; (b) разбить по scope-файлам | (a) — разбивка отдельным планом | +| 6.4 | `org-projects.controller.ts` — оставить или удалить | (a) Оставить проекцией с `SCOPE-EXCEPTION`; (b) удалить, фронт ходит напрямую в `/projects` | (a) — wire-контракт не меняем | +| 6.5 | `session_messages` / fork-поля — в этом плане? | (a) Нет — только в SDK-миграции; (b) да | (a) — схема БД здесь не меняется, миграции только в SDK-плане | +| 6.6 | `contracts.ts` + `packages/contracts` трогать? | (a) Нет, только сверка фазы 7; (b) чистить | (a) | +| 6.7 | Grep-гейты — руками или в CI | (a) Руками до фазы 9, затем решить; (b) сразу в `scripts/check` | (a) | + +### 6.8 Решения зафиксированы (2026-11-01, подтверждено пользователем) + +| # | Решение | Статус | +|---|---|---| +| 6.1 | Проект только внутри организаций: `organizations/modules/projects/` (CoC §2 требует `modules//`, поэтому уровень `modules/` сохранён) | Принято | +| 6.2 | `CommonModule` остаётся единственным модулем `common/`: DbService/CryptoService/OpencodeKeysService/HealthRegistry — его провайдеры, шим не вводится | Принято | +| 6.3 | `common/env/env.ts` в этом плане не режем | Принято | +| 6.4 | `org-projects.controller.ts` удалён: оба набора роутов объединены в один `ProjectsController` (один контроллер на модуль, по требованию пользователя) | Принято | +| 6.5 | `session_messages`/fork-поля — только в SDK-миграции; схема БД здесь не менялась | Принято | +| 6.6 | `contracts.ts` + `packages/contracts` не трогались (diff с checkpoint пустой) | Принято | +| 6.7 | Grep-гейты — руками до фазы 9, в CI не выносим | Принято | + +Дополнительные решения по ходу (не входили в §6): + +| Вопрос | Решение | Статус | +|---|---|---| +| `health/` импортировал `ai/opencode` + registries | инверсия через `common/health/health-registry.ts` (домены self-register в OnModuleInit) | Сделано | +| keys HTTP-поверхность в common | store/rotation в `common/keys`, HTTP (`/api/v1/key`, `/api/v1/usage`) в `processes/modules/ai/modules/opencode` | Сделано | +| `users/auth` | вынесен в `auth/` (sibling `users/`) | Сделано | +| members/invites | `organizations/modules/{members,invites}/` (Nest-модули по CoC §2) | Сделано | +| C4-гейт | `organizations/modules/projects/modules/project-access/` (ProjectAccessModule), projects больше не импортирует OrganizationsModule | Сделано | +| org-guard | `organizations.guard.ts` — реальный `CanActivate` (GET=member, мутации=maintainer, навешан на gated-роуты OrganizationsController; 410-заглушки исключены). Принятое изменение поведения: guard до pipe (битый body у не-member → 404/403 вместо 400) | Сделано | +| uuidv7 | генерация через `Bun.randomUUIDv7()` (runtime Bun), валидация — приватный хелпер в InvitesService | Сделано | +| `ai`/`workers` | `processes/modules/{ai,workers}` + `ProcessesModule` (CoC §2) | Сделано | +| `repos`/`workspaces` | `organizations/modules/projects/modules/repository/` (`modules/repos`, `modules/workspaces`, `utils/repos-git`, `utils/submodules`); мёртвый дубль `workspaces/modules/jobs` удалён | Сделано | +| прямые `fs` | единый jail: `ensureDir/removeDir/statPath/readDir` в `common/storage/workspace-path.service.ts`; прямой `node:fs` остался только в common/{env,db,storage} и `repository/**` | Сделано | + +### 6.9 Итог фаз + +Все фазы 0–9 пройдены: дерево `src/` соответствует §2, grep-гейты границ пустые, гейты (`lint`, `build`, `test`, полный `test:e2e`, `db:check-integrity`) зелёные, wire-контракт не менялся. + +## 7. Риски + +| Риск | Где | Митигация | +|---|---|---| +| Циклический импорт при выносе (`organizations ↔ projects`, `auth ↔ users`) | Фазы 2, 4 | `git mv` малыми коммитами (по одному scope за коммит), после каждого — `tsc --noEmit`; направление фиксировано в §6.1; `UsersService` global без импорта | +| Тихий fallback при резке env/jail | Фазы 1, 5 | `env.ts` не режем (§6.3); jail-grep-гейт фазы 8; без `REPOS_ROOT` — те же 503/500, e2e `storage-unconfigured` (`corrupted` на list/get) | +| Потеря KEK-проводки (`active/previous` keyId) | Фаза 3 | Таблицы/SQL не меняем; `keys:reencrypt` + `opencode-keys.e2e.ts` (скан секретов/форм логов) — гейт каждой фазы с keys | +| Сломан wire-контракт (фронт/mobile) | Фазы 4, 5, 7 | Роуты/DTO/swagger не меняем; фаза 7 — полный e2e + сверка `openapi.yaml` диффом `git diff --stat` (должен быть пустым по контрактам) | +| Конфликт с SDK-миграцией (параллельные переезды `ai/*`, `sessions`, `db/schema`) | Все фазы | Этот план — только `git mv` + границы, без логики; SDK-план — логика/БД. Пути SDK-плана обновить в фазе 9; не стартовать оба плана в одних файлах одновременно — сначала этот (границы), затем SDK (логика) | +| Раздутый `app.module.ts` / DI-граф | Фазы 1–2 | Импорты только верх→низ (§3); `WorkspacePathService` из `common/storage` напрямую; без `platform/`-шима | +| Потеря provenience (`contracts/opencode-stand-*.json`, `.env.example`) | Фаза 9 | `.env.example`/README правим сразу как код (по AGENTS.md); stand-артефакты не удаляем молча — архивировать | + +## 8. Критерии готовности + +- Дерево `src/` соответствует §2 (проверка `ls`: `common/crypto|keys|storage`, `auth/` sibling, `organizations/projects/`, `organizations/members|invites`, `processes/ai|workers`). +- Ноль импортов против стрелки (§3, три grep-гейта пустые). +- Legacy `repos/`, `workspaces/`, `ai/` удалены, ноль `from.*repos/|workspaces/|ai/modules` импортов. +- Wire-контракт не изменился: `git diff` по `packages/contracts/`, `contracts/openapi.yaml`, `contracts.ts` — пустой (кроме путей в комментах SDK-плана фазой 9). +- `bun run lint` + `bun run build` зелёные; `bun run test` + полный `bun run test:e2e` зелёные; `bun run db:check-integrity` зелёный; e2e-скан секретов чистый. +- `ARCHITECTURE.md` + `AGENTS.md` обновлены; пути в `.plans/opencode-sdk-migration/PLAN.md` актуализированы. +- Без `REPOS_ROOT` — те же 503/500 + `corrupted`; без `DATABASE_URL` — 503; без KEK — 500 `opencode_keys_unconfigured` (поведение 1:1, проверено e2e). + +## 9. Дальше (вне скоупа этого плана) + +- Разбивка `common/env/env.ts` по scope-файлам (отдельный план, высокий риск silent fallback). +- Постоянные lint-гейты границ (eslint-plugin-boundaries или кастом в `scripts/check/run.sh`). +- SDK-миграция (`.plans/opencode-sdk-migration/PLAN.md`): embedded host, свои сессии в Postgres, удаление HTTP-зеркала — стартует после этого плана (границы уже чистые). +- Удаление `contracts.ts`-реэкспорта и `contracts/opencode-stand-*.json` архивация — в SDK-плане, не здесь. +- CI-гейты scope (по решению §6.7). + +## Приложение A. Проверка после каждой фазы (шпаргалка) + +```bash +bun run lint +bun run build +bun run db:check-integrity +# точечные e2e по фазе: :auth / :projects / :repos / :github / :opencode-keys +bun run test:e2e:auth +# grep-гейты границ: +grep -rn "from.*organizations" apps/backend/src/common/ || echo OK-common +grep -rn "from.*processes" apps/backend/src/organizations/ --include="*.ts" | grep -v org-projects || echo OK-org +grep -rn "from.*common/" apps/backend/src/ | wc -l +``` diff --git a/.plans/backend-domain-restructure/evolution-log.md b/.plans/backend-domain-restructure/evolution-log.md new file mode 100644 index 0000000..84fc34f --- /dev/null +++ b/.plans/backend-domain-restructure/evolution-log.md @@ -0,0 +1,10 @@ +# Evolution log — backend-domain-restructure + +- 2026-11-01 — создан PLAN.md (v1, черновик, код не написан). Границы: Platform / Organization / Project, фазы 0–9, решения §6 открыты. +- 2026-11-01 — Фаза 3 (CoC v2): members/invites вынесены из organizations.service в корневые MembersService/InvitesService + OrgGuardService; pure-хелперы в utils/{uuid-v7,pg-error,organization-member}; публичный API OrganizationsService сохранён делегированием; SQL/таблицы 1:1. +- 2026-11-01 — Фаза 3 (правка по ревью): organizations.guard.ts — реальный CanActivate (member для GET, maintainer для мутаций, навешан на gated-роуты OrganizationsController; 410-заглушки исключены); MembersModule/InvitesModule в organizations/modules/; randomUuidV7 через Bun.randomUUIDv7. +- 2026-11-01 — uuid-v7 util удалён: генерация через `Bun.randomUUIDv7()` напрямую (Bun runtime), валидация v7 — приватный хелпер в InvitesService; тесты валидатора перенесены в invites spec. +- 2026-11-01 — Фаза 4 (CoC v2): C4-гейт вынесен в organizations/modules/projects/modules/project-access (ProjectAccessModule); projects/chats/sessions/files больше не импортируют OrganizationsModule; webhook-util -> github/utils/webhook; optional DI deps readonly. +- 2026-11-01 — Фаза 5A (CoC v2): ai -> processes/modules/ai, workers -> processes/modules/workers, добавлен ProcessesModule (AppModule монтирует его); маршруты/DTO не менялись. +- 2026-11-01 — Фаза 5B (CoC v2): repos/ + workspaces/ -> organizations/modules/projects/modules/repository (modules/repos, modules/workspaces, utils/repos-git, utils/submodules); dead duplicate jobs/ удалён; единый jail: fs-примитивы в common/storage, прямой node:fs убран из projects/files/organizations. +- 2026-11-01 — Фазы 6–9: решения §6.8/6.9 зафиксированы; ARCHITECTURE/AGENTS обновлены; пути SDK-плана актуализированы; контракты не менялись (diff пустой); финальные гейты: lint, build, test (238 ok), полный test:e2e, db:check-integrity — PASS. diff --git a/.plans/brisk-otter-p8/PLAN.md b/.plans/brisk-otter-p8/PLAN.md new file mode 100644 index 0000000..358e3f1 --- /dev/null +++ b/.plans/brisk-otter-p8/PLAN.md @@ -0,0 +1,106 @@ +# PLAN — Сортировка чатов rush-code по последней активности (`updatedAt`) + +Source: Stanza card `cmw68mpt8000mp90zy3jfvm0e` +«Сделать сортировку чатов в rush-code от нового к старым» +Tag: `web2bizz/rush-code` (`cmw68o533000tp90zd4mri4il`), column `planned`. +Branch: `feat/cli-cloud-chat`. + +## Goal +`GET /api/v1/sessions` отдаёт `updatedAt` (ISO-8601) и сортирует по нему +`DESC`; новое сообщение поднимает чат наверх; фронтовый список и подпись +времени используют `updatedAt`; openapi ↔ contracts ↔ backend ↔ frontend +согласованы. + +## Non-goals +- Миграция БД (колонка `project_sessions.updated_at` уже есть). +- Мобильное приложение (использует upstream `Session`, не `SessionInfo`). +- `running-sessions-tab` (времени не рисует). +- Смена агента как активность (bump только на сообщениях). + +## Decisions (final) +1. `updatedAt` — **required** во всех трёх контрактах (не optional). +2. Backend order: `updated_at DESC, created_at DESC` (детерминированный tie-break). +3. Bump — в `appendMessage`, тем же `try/catch`; **uuid-guard** обязателен, + иначе `ses_*` даёт Postgres `22P02` → 503. +4. `create` — единственный литерал `SessionInfo` получает `updatedAt`. +5. Frontend сортирует копию в `useSessions`, sidebar рисует `updatedAt`. +6. Тесты входят в изменение: fake-drizzle учится `desc(updated_at)` и `id`, + e2e-фикстуры получают явный `updatedAt`. + +## Complexity / risk +- complexity: **high** (score 14.7; cards 4, files 11, deps 4, type update). +- risk: **low** (1/8; `breaking` 1 — аддитивное, но required поле публичного + контракта; data/security/external 0). +- route: **build-smart**; complex → 4-factor matrix соблюдена (см. epoch-03). + +## Card sequence + +### 1. Contracts — `Добавить updatedAt в SessionInfo (openapi + zod)` +- **Layer:** shared · **Nesting:** root · **Blocked by:** — +- **Files:** `contracts/openapi.yaml`, `packages/contracts/src/sessions/sessions.ts`, + `packages/contracts/src/sessions/sessions.schema.ts` +- **Checklist:** + - openapi `SessionInfo`: required + property `updatedAt` (`date-time`, описание «последняя активность») + - `sessions.ts`: поле `updatedAt: string` + doc + - `sessions.schema.ts`: `z.iso.datetime` с тем же сообщением, что у `createdAt` + - `cd packages/contracts && bun run lint` + +### 2. Backend — `Сортировать сессии по updatedAt desc и бампать при сообщении` +- **Layer:** service · **Nesting:** branch · **Blocked by:** card 1 +- **Files:** `apps/backend/src/processes/modules/ai/modules/sessions/session-history.repository.ts`, + `.../__tests__/session-history.repository.spec.ts`, + `.../session-harness.service.ts`, `.../__tests__/sessions.e2e.ts` +- **Checklist:** + - `listLocalSessions`: select `updatedAt`, `orderBy(desc(updatedAt), desc(createdAt))` + - `toSessionInfo`: `updatedAt.toISOString()` + - `appendMessage`: uuid-guard + `update project_sessions set updated_at = now()` после insert + - `create`: `updatedAt: new Date().toISOString()` + - fake-drizzle: `id` в `filterRows`, разбор `desc` в `orderBy`, 3 новых теста (порядок / bump / `ses_*` no-op) + - e2e: явный `updatedAt` в фикстурах (B новее A → порядок отличается от `createdAt asc`), assert ISO + - `bunx nx run backend:build && bun dist/.../session-history.repository.spec.js` + - `bun scripts/e2e.ts sessions.e2e` (Docker) — если доступен + +### 3. Frontend — `Сортировать чаты по updatedAt и показывать последнюю активность` +- **Layer:** widgets (+ shared hook) · **Nesting:** branch · **Blocked by:** card 2 +- **Files:** `apps/frontend/src/hooks/useSessions.ts`, + `apps/frontend/src/components/projects/sessions-sidebar/sessions-sidebar.tsx`, + `apps/frontend/src/components/projects/__tests__/sessions-sidebar.test.tsx`, + `apps/frontend/src/api/__tests__/sessions-client.test.ts` +- **Checklist:** + - `useSessions`: `useMemo` → копия, `updatedAt desc`, tie `createdAt desc`/`id` + - sidebar: `formatRelativeTime(s.updatedAt)` + `