Compare commits
1 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 agent_coder
|
044daab357 |
+46
-25
@@ -191,24 +191,16 @@ MCP_DOCMOST_PASSWORD=
|
|||||||
|
|
||||||
# Silence timeout (ms) for EXTERNAL-MCP transport ONLY (not the chat provider).
|
# Silence timeout (ms) for EXTERNAL-MCP transport ONLY (not the chat provider).
|
||||||
# Tighter than AI_STREAM_TIMEOUT_MS so a byte-silent/hung MCP server is broken in
|
# Tighter than AI_STREAM_TIMEOUT_MS so a byte-silent/hung MCP server is broken in
|
||||||
# ~1 min instead of 15. Note it also cuts a legitimately long but byte-silent
|
# ~5 min instead of 15. Note it also cuts a legitimately long but byte-silent
|
||||||
# single tool call (a slow crawl that emits nothing until done) and an SSE
|
# single tool call (a slow crawl that emits nothing until done) and an SSE
|
||||||
# transport idling >1 min BETWEEN tool calls. Default 60000 (1 min).
|
# transport idling >5 min BETWEEN tool calls. Default 300000 (5 min).
|
||||||
# AI_MCP_STREAM_TIMEOUT_MS=60000
|
# AI_MCP_STREAM_TIMEOUT_MS=300000
|
||||||
|
|
||||||
# Total wall-clock cap (ms) for ONE external MCP tool call (app-level, not
|
# Total wall-clock cap (ms) for ONE external MCP tool call (app-level, not
|
||||||
# transport). Aborts a tool that keeps the socket warm (SSE heartbeats / trickle)
|
# transport). Aborts a tool that keeps the socket warm (SSE heartbeats / trickle)
|
||||||
# but never returns a result — which the silence timeout above never breaks.
|
# but never returns a result — which the silence timeout above never breaks.
|
||||||
# Default 120000 (2 min).
|
# Default 900000 (15 min).
|
||||||
# AI_MCP_CALL_TIMEOUT_MS=120000
|
# AI_MCP_CALL_TIMEOUT_MS=900000
|
||||||
|
|
||||||
# Max JSON/urlencoded request body size (bytes). Fastify's 1 MiB default is too
|
|
||||||
# small for a long AI-chat research turn: the client resends the FULL message
|
|
||||||
# history (every tool call + search result) on each turn, so a deep conversation's
|
|
||||||
# POST to /api/ai-chat/stream can be several MB and would otherwise be rejected
|
|
||||||
# with FST_ERR_CTP_BODY_TOO_LARGE (413). Does NOT affect multipart file uploads
|
|
||||||
# (see FILE_UPLOAD_SIZE_LIMIT). Default 26214400 (25 MiB).
|
|
||||||
# HTTP_JSON_BODY_LIMIT=26214400
|
|
||||||
|
|
||||||
# Deferred tool loading for the in-app AI chat (#332). Default ON: the agent sees
|
# Deferred tool loading for the in-app AI chat (#332). Default ON: the agent sees
|
||||||
# a compact <tool_catalog> and only CORE tools + a loadTools meta-tool are active
|
# a compact <tool_catalog> and only CORE tools + a loadTools meta-tool are active
|
||||||
@@ -230,18 +222,6 @@ MCP_DOCMOST_PASSWORD=
|
|||||||
# CLOUD=true) — run a single instance instead. The server logs a startup WARNING
|
# CLOUD=true) — run a single instance instead. The server logs a startup WARNING
|
||||||
# when it detects a multi-instance deployment (CLOUD=true) so the constraint is
|
# when it detects a multi-instance deployment (CLOUD=true) so the constraint is
|
||||||
# visible, and a startup sweep settles any run left dangling by a restart.
|
# visible, and a startup sweep settles any run left dangling by a restart.
|
||||||
#
|
|
||||||
# Resumable run streams (#184 phase 1.5, #381). With the flag ON, an active
|
|
||||||
# durable run tees its SSE frames into an in-memory registry, and a
|
|
||||||
# reloaded/second tab attaches via GET /ai-chat/runs/:chatId/stream to follow the
|
|
||||||
# run LIVE (replay of the buffered frames + the live tail). With the flag OFF
|
|
||||||
# (default) the registry is never populated and attach always answers 204, so a
|
|
||||||
# reopened tab of an active run silently falls back to degraded 2.5s history
|
|
||||||
# polling — every wire path stays byte-for-byte identical to a build without the
|
|
||||||
# feature. Staged-rollout switch: only meaningful when autonomousRuns (above) is
|
|
||||||
# enabled for a workspace, and the same single-instance constraint applies (the
|
|
||||||
# registry is process-local).
|
|
||||||
# AI_CHAT_RESUMABLE_STREAM=false
|
|
||||||
|
|
||||||
# --- Anonymous public-share AI assistant ---
|
# --- Anonymous public-share AI assistant ---
|
||||||
# Opt-in per workspace (AI settings -> "public share assistant"; off by default).
|
# Opt-in per workspace (AI settings -> "public share assistant"; off by default).
|
||||||
@@ -300,3 +280,44 @@ MCP_DOCMOST_PASSWORD=
|
|||||||
# infra prunes rows >90d via a maintenance container). When off, the endpoint
|
# infra prunes rows >90d via a maintenance container). When off, the endpoint
|
||||||
# does not exist and the client installs no observers.
|
# does not exist and the client installs no observers.
|
||||||
# CLIENT_TELEMETRY_ENABLED=false
|
# CLIENT_TELEMETRY_ENABLED=false
|
||||||
|
# --- GIT-SYNC (native two-way Docmost <-> git Markdown sync) ---
|
||||||
|
# Master switch. Off by default. When 'true', GIT_SYNC_SERVICE_USER_ID below is
|
||||||
|
# REQUIRED (the service account that git-originated create/move/rename/delete are
|
||||||
|
# attributed to) — the server refuses to boot with sync enabled and no user id.
|
||||||
|
# GIT_SYNC_ENABLED=false
|
||||||
|
#
|
||||||
|
# Serve the per-space vaults over smart-HTTP (the /git host). Defaults to
|
||||||
|
# GIT_SYNC_ENABLED when unset.
|
||||||
|
# GIT_SYNC_HTTP_ENABLED=false
|
||||||
|
#
|
||||||
|
# REQUIRED when GIT_SYNC_ENABLED=true: id of the user that git-originated page
|
||||||
|
# operations (create / move / rename / delete) are attributed to.
|
||||||
|
# GIT_SYNC_SERVICE_USER_ID=
|
||||||
|
#
|
||||||
|
# Where the per-space working vaults live (non-bare repos; the engine needs a
|
||||||
|
# working tree).
|
||||||
|
# Defaults to "<DATA_DIR or ./data>/git-sync".
|
||||||
|
# GIT_SYNC_DATA_DIR=
|
||||||
|
#
|
||||||
|
# SCAFFOLDING for the DEFERRED remote-push feature (SPEC §7) — NOT yet
|
||||||
|
# implemented and currently INERT. The vendored sync engine does not consume
|
||||||
|
# this value anywhere (git push to a remote is deferred), so setting it has NO
|
||||||
|
# effect today: vaults remain local-only regardless. It is validated and carried
|
||||||
|
# only so the wiring is ready for when remote push lands. The intended future
|
||||||
|
# shape is a per-space URL template where the literal "{spaceId}" is substituted
|
||||||
|
# per space (e.g. git@host:vault-{spaceId}.git).
|
||||||
|
# GIT_SYNC_REMOTE_TEMPLATE=
|
||||||
|
#
|
||||||
|
# Poll-safety interval in ms — the cadence of the background reconcile cycle
|
||||||
|
# (default: 15000).
|
||||||
|
# GIT_SYNC_POLL_INTERVAL_MS=15000
|
||||||
|
#
|
||||||
|
# Debounce window in ms for collapsing bursts of page edits into one sync cycle
|
||||||
|
# (default: 2000).
|
||||||
|
# GIT_SYNC_DEBOUNCE_MS=2000
|
||||||
|
#
|
||||||
|
# Watchdog timeout in ms for the spawned `git http-backend` process serving a
|
||||||
|
# git smart-HTTP push (default: 120000). A stalled/hung receive-pack is killed
|
||||||
|
# after this deadline so it cannot hold the per-space lock forever.
|
||||||
|
# GIT_SYNC_BACKEND_TIMEOUT_MS=120000
|
||||||
|
#
|
||||||
|
|||||||
@@ -1,224 +0,0 @@
|
|||||||
name: Nightly property fuzz
|
|
||||||
|
|
||||||
# The daily heavy property run for the ProseMirror<->Markdown converter
|
|
||||||
# (packages/prosemirror-markdown). The PR/CI test run keeps NUM_RUNS modest to
|
|
||||||
# stay under budget; this cron cranks up total coverage with random seeds to hunt
|
|
||||||
# for deeper round-trip counterexamples than a fixed-seed PR run can reach.
|
|
||||||
#
|
|
||||||
# WHY SHARDING: a single mega-run (~10000 fast-check runs) OOMs the vitest worker
|
|
||||||
# (empirically ~1625 runs -> "JS heap out of memory", ~2GB) because heap
|
|
||||||
# accumulates across the whole property run in one process. Instead this job runs
|
|
||||||
# SHARDS fresh vitest processes, each a MODERATE per-shard count with a DISTINCT
|
|
||||||
# derived seed, so total coverage ~= SHARDS x PER_SHARD_NUM_RUNS across processes
|
|
||||||
# that never accumulate heap. On the first failing shard we stop and keep that
|
|
||||||
# shard's output for triage.
|
|
||||||
#
|
|
||||||
# Counterexample -> fixture workflow: when a shard fails, fast-check prints the
|
|
||||||
# SHRUNK minimal counterexample plus the reproducing seed. This job files a Gitea
|
|
||||||
# issue containing that seed + counterexample ONLY when the output actually holds
|
|
||||||
# a fast-check counterexample; an infra failure (OOM/tsc/install, no
|
|
||||||
# counterexample) is filed under a DISTINCT title so it can never poison the
|
|
||||||
# counterexample dedup. A human then commits the shrunk doc as a PERMANENT fixture
|
|
||||||
# under packages/prosemirror-markdown/test/fixtures/counterexamples/ with a case in
|
|
||||||
# counterexamples.test.ts, and FIXES the converter (never weakens a property to
|
|
||||||
# hide the bug). See packages/prosemirror-markdown/README.md.
|
|
||||||
|
|
||||||
on:
|
|
||||||
schedule:
|
|
||||||
# 03:00 UTC daily.
|
|
||||||
- cron: '0 3 * * *'
|
|
||||||
workflow_dispatch:
|
|
||||||
inputs:
|
|
||||||
num_runs:
|
|
||||||
description: 'fast-check runs PER SHARD (8 shards run in sequence)'
|
|
||||||
required: false
|
|
||||||
default: '600'
|
|
||||||
seed:
|
|
||||||
description: 'base fast-check seed (empty = random); shard i uses base+i'
|
|
||||||
required: false
|
|
||||||
default: ''
|
|
||||||
|
|
||||||
permissions:
|
|
||||||
contents: read
|
|
||||||
issues: write
|
|
||||||
|
|
||||||
jobs:
|
|
||||||
property-fuzz:
|
|
||||||
runs-on: ubuntu-latest
|
|
||||||
timeout-minutes: 60
|
|
||||||
steps:
|
|
||||||
- name: Checkout
|
|
||||||
uses: actions/checkout@v4
|
|
||||||
|
|
||||||
- name: Set up pnpm
|
|
||||||
uses: pnpm/action-setup@v4
|
|
||||||
|
|
||||||
- name: Set up Node
|
|
||||||
uses: actions/setup-node@v4
|
|
||||||
with:
|
|
||||||
node-version: 22
|
|
||||||
cache: pnpm
|
|
||||||
|
|
||||||
- name: Install dependencies
|
|
||||||
run: pnpm install --frozen-lockfile
|
|
||||||
|
|
||||||
# No build step: the generative suite imports the converter from src/
|
|
||||||
# directly (e.g. `from '../../src/lib/markdown-converter.js'`), so it runs
|
|
||||||
# against source without the package's build/. Skipping the build also
|
|
||||||
# keeps a tsc build error from masquerading as a property-test failure and
|
|
||||||
# filing a bogus counterexample issue.
|
|
||||||
- name: Resolve base seed and per-shard run count
|
|
||||||
id: params
|
|
||||||
# Dispatch inputs are read via env (NOT interpolated into the shell body)
|
|
||||||
# to avoid script injection through a crafted input value.
|
|
||||||
env:
|
|
||||||
SEED_INPUT: ${{ inputs.seed }}
|
|
||||||
NUM_RUNS_INPUT: ${{ inputs.num_runs }}
|
|
||||||
run: |
|
|
||||||
set -euo pipefail
|
|
||||||
SEED="${SEED_INPUT:-}"
|
|
||||||
# Empty seed (cron, or a dispatch that left it blank) -> random. Combine
|
|
||||||
# two RANDOMs so the seed spans more than RANDOM's 0..32767 range.
|
|
||||||
[ -z "$SEED" ] && SEED=$(( (RANDOM << 15) | RANDOM ))
|
|
||||||
NUM_RUNS="${NUM_RUNS_INPUT:-}"
|
|
||||||
[ -z "$NUM_RUNS" ] && NUM_RUNS=600
|
|
||||||
echo "seed=$SEED" >> "$GITHUB_OUTPUT"
|
|
||||||
echo "num_runs=$NUM_RUNS" >> "$GITHUB_OUTPUT"
|
|
||||||
echo "Sharded property fuzz: BASE_SEED=$SEED PER_SHARD_NUM_RUNS=$NUM_RUNS SHARDS=8"
|
|
||||||
|
|
||||||
- name: Run generative property suite (sharded)
|
|
||||||
id: fuzz
|
|
||||||
env:
|
|
||||||
BASE_SEED: ${{ steps.params.outputs.seed }}
|
|
||||||
PER_SHARD_NUM_RUNS: ${{ steps.params.outputs.num_runs }}
|
|
||||||
SHARDS: '8'
|
|
||||||
run: |
|
|
||||||
set -uo pipefail
|
|
||||||
# Give each fresh process headroom, but rely on SHARDING (not a big heap)
|
|
||||||
# to avoid OOM: a moderate per-shard count in a process that starts clean.
|
|
||||||
export NODE_OPTIONS=--max-old-space-size=4096
|
|
||||||
: > property-output.txt
|
|
||||||
FAILED=0
|
|
||||||
FAIL_SEED=""
|
|
||||||
i=0
|
|
||||||
while [ "$i" -lt "$SHARDS" ]; do
|
|
||||||
SHARD_SEED=$(( BASE_SEED + i ))
|
|
||||||
echo "=== shard $((i + 1))/$SHARDS: PROPERTY_SEED=$SHARD_SEED PROPERTY_NUM_RUNS=$PER_SHARD_NUM_RUNS ==="
|
|
||||||
# tee OVERWRITES property-output.txt each shard; since we break on the
|
|
||||||
# first failure, the file ends up holding exactly the failing shard's
|
|
||||||
# output (which carries the shrunk counterexample + reproducing seed).
|
|
||||||
if PROPERTY_SEED="$SHARD_SEED" PROPERTY_NUM_RUNS="$PER_SHARD_NUM_RUNS" \
|
|
||||||
pnpm --filter @docmost/prosemirror-markdown exec \
|
|
||||||
vitest run test/generative/ 2>&1 | tee property-output.txt; then
|
|
||||||
echo "shard $((i + 1)) passed"
|
|
||||||
else
|
|
||||||
echo "shard $((i + 1)) FAILED (seed=$SHARD_SEED) — stopping; keeping its output"
|
|
||||||
FAILED=1
|
|
||||||
FAIL_SEED="$SHARD_SEED"
|
|
||||||
break
|
|
||||||
fi
|
|
||||||
i=$(( i + 1 ))
|
|
||||||
done
|
|
||||||
echo "failed=$FAILED" >> "$GITHUB_OUTPUT"
|
|
||||||
echo "fail_seed=$FAIL_SEED" >> "$GITHUB_OUTPUT"
|
|
||||||
exit "$FAILED"
|
|
||||||
|
|
||||||
# A GENUINE counterexample: fast-check printed a shrunk minimal case and its
|
|
||||||
# reproducing seed into property-output.txt. File a dedup-guarded issue whose
|
|
||||||
# title prefix is UNIQUE to counterexamples, so an infra failure (handled by
|
|
||||||
# the next step under a different title) can never poison this dedup.
|
|
||||||
- name: File counterexample issue
|
|
||||||
# always() is REQUIRED: the fuzz step exits nonzero on a failing shard,
|
|
||||||
# so a bare `if:` (implicitly success() && ...) would skip this step
|
|
||||||
# exactly when it must run. always() lets it run on the failure path.
|
|
||||||
if: always() && steps.fuzz.outputs.failed == '1'
|
|
||||||
env:
|
|
||||||
FAIL_SEED: ${{ steps.fuzz.outputs.fail_seed }}
|
|
||||||
NUM_RUNS: ${{ steps.params.outputs.num_runs }}
|
|
||||||
RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
|
|
||||||
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
|
||||||
TITLE_PREFIX: 'Nightly property counterexample'
|
|
||||||
run: |
|
|
||||||
set -uo pipefail
|
|
||||||
# Discriminate counterexample vs infra failure by the fast-check
|
|
||||||
# signature. No signature -> leave it to the infra-failure step.
|
|
||||||
if ! grep -Eq 'Property failed after|Counterexample' property-output.txt; then
|
|
||||||
echo "No fast-check counterexample signature — infra failure, handled by the next step."
|
|
||||||
exit 0
|
|
||||||
fi
|
|
||||||
TITLE="${TITLE_PREFIX} (seed=${FAIL_SEED})"
|
|
||||||
|
|
||||||
# Best-effort dedup: skip if an open issue with the counterexample title
|
|
||||||
# prefix already exists. A failure of this check must NOT block creation.
|
|
||||||
EXISTING=""
|
|
||||||
if EXISTING=$(curl -sS \
|
|
||||||
-H "Authorization: token ${GITHUB_TOKEN}" \
|
|
||||||
"${GITHUB_API_URL}/repos/${GITHUB_REPOSITORY}/issues?state=open&limit=100"); then
|
|
||||||
if printf '%s' "$EXISTING" \
|
|
||||||
| node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>{let a;try{a=JSON.parse(s)}catch{process.exit(1)}if(!Array.isArray(a))process.exit(1);const p=process.env.TITLE_PREFIX;process.exit(a.some(i=>typeof i.title==="string"&&i.title.startsWith(p))?0:1)})'; then
|
|
||||||
echo "An open '${TITLE_PREFIX}' issue already exists — skipping creation."
|
|
||||||
exit 0
|
|
||||||
fi
|
|
||||||
fi
|
|
||||||
|
|
||||||
# Build the JSON body with the test output SAFELY escaped (never hand-
|
|
||||||
# interpolate the counterexample into JSON).
|
|
||||||
BODY_TEXT=$(printf 'A nightly property fuzz SHARD failed with a fast-check counterexample.\n\n- failing shard seed: `%s`\n- NUM_RUNS (per shard): `%s`\n- run: %s\n\nReproduce locally:\n\n```\nPROPERTY_SEED=%s PROPERTY_NUM_RUNS=%s pnpm --filter @docmost/prosemirror-markdown exec vitest run test/generative/\n```\n\nfast-check shrinks the failure to a minimal counterexample. Commit it as a permanent fixture under `packages/prosemirror-markdown/test/fixtures/counterexamples/` + a case in `counterexamples.test.ts`, then FIX the converter (do not weaken a property). See `packages/prosemirror-markdown/README.md`.\n\nTail of the test output (contains the shrunk counterexample):\n\n```\n%s\n```\n' \
|
|
||||||
"$FAIL_SEED" "$NUM_RUNS" "$RUN_URL" "$FAIL_SEED" "$NUM_RUNS" "$(tail -n 120 property-output.txt)")
|
|
||||||
|
|
||||||
jq -n --arg title "$TITLE" --arg body "$BODY_TEXT" \
|
|
||||||
'{title: $title, body: $body}' > payload.json
|
|
||||||
|
|
||||||
curl -sS -X POST \
|
|
||||||
"${GITHUB_API_URL}/repos/${GITHUB_REPOSITORY}/issues" \
|
|
||||||
-H "Authorization: token ${GITHUB_TOKEN}" \
|
|
||||||
-H 'Content-Type: application/json' \
|
|
||||||
-d @payload.json
|
|
||||||
|
|
||||||
# An INFRA failure (OOM, tsc, install) has NO counterexample signature. File
|
|
||||||
# it under a DISTINCT title so it is visible but keeps the counterexample
|
|
||||||
# dedup (above) uncontaminated — a real counterexample can still file even
|
|
||||||
# while an infra issue is open.
|
|
||||||
- name: File infra failure issue
|
|
||||||
# always() is REQUIRED: the fuzz step exits nonzero on a failing shard,
|
|
||||||
# so a bare `if:` (implicitly success() && ...) would skip this step
|
|
||||||
# exactly when it must run. always() lets it run on the failure path.
|
|
||||||
if: always() && steps.fuzz.outputs.failed == '1'
|
|
||||||
env:
|
|
||||||
FAIL_SEED: ${{ steps.fuzz.outputs.fail_seed }}
|
|
||||||
NUM_RUNS: ${{ steps.params.outputs.num_runs }}
|
|
||||||
RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
|
|
||||||
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
|
||||||
TITLE_PREFIX: 'Nightly property run infra failure'
|
|
||||||
run: |
|
|
||||||
set -uo pipefail
|
|
||||||
# Only file when there is NO counterexample signature (else the
|
|
||||||
# counterexample step owns it).
|
|
||||||
if grep -Eq 'Property failed after|Counterexample' property-output.txt; then
|
|
||||||
echo "Counterexample present — owned by the counterexample step."
|
|
||||||
exit 0
|
|
||||||
fi
|
|
||||||
TITLE="${TITLE_PREFIX} (seed=${FAIL_SEED})"
|
|
||||||
|
|
||||||
EXISTING=""
|
|
||||||
if EXISTING=$(curl -sS \
|
|
||||||
-H "Authorization: token ${GITHUB_TOKEN}" \
|
|
||||||
"${GITHUB_API_URL}/repos/${GITHUB_REPOSITORY}/issues?state=open&limit=100"); then
|
|
||||||
if printf '%s' "$EXISTING" \
|
|
||||||
| node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>{let a;try{a=JSON.parse(s)}catch{process.exit(1)}if(!Array.isArray(a))process.exit(1);const p=process.env.TITLE_PREFIX;process.exit(a.some(i=>typeof i.title==="string"&&i.title.startsWith(p))?0:1)})'; then
|
|
||||||
echo "An open '${TITLE_PREFIX}' issue already exists — skipping creation."
|
|
||||||
exit 0
|
|
||||||
fi
|
|
||||||
fi
|
|
||||||
|
|
||||||
BODY_TEXT=$(printf 'A nightly property fuzz SHARD failed WITHOUT a fast-check counterexample (infra failure: OOM / build / install). This is NOT a converter round-trip bug.\n\n- failing shard seed: `%s`\n- NUM_RUNS (per shard): `%s`\n- run: %s\n\nInvestigate the run log (memory, dependency install, or a tsc/import error). The nightly counterexample dedup is intentionally separate from this issue.\n\nTail of the test output:\n\n```\n%s\n```\n' \
|
|
||||||
"$FAIL_SEED" "$NUM_RUNS" "$RUN_URL" "$(tail -n 120 property-output.txt)")
|
|
||||||
|
|
||||||
jq -n --arg title "$TITLE" --arg body "$BODY_TEXT" \
|
|
||||||
'{title: $title, body: $body}' > payload.json
|
|
||||||
|
|
||||||
curl -sS -X POST \
|
|
||||||
"${GITHUB_API_URL}/repos/${GITHUB_REPOSITORY}/issues" \
|
|
||||||
-H "Authorization: token ${GITHUB_TOKEN}" \
|
|
||||||
-H 'Content-Type: application/json' \
|
|
||||||
-d @payload.json
|
|
||||||
@@ -119,10 +119,18 @@ jobs:
|
|||||||
# build/ is gitignored, and plain `pnpm -r test` does NOT honour nx
|
# build/ is gitignored, and plain `pnpm -r test` does NOT honour nx
|
||||||
# `dependsOn: ^build`, so its consumers (mcp `pretest: tsc`, git-sync vitest
|
# `dependsOn: ^build`, so its consumers (mcp `pretest: tsc`, git-sync vitest
|
||||||
# typecheck) fail with TS2307 Cannot find module '@docmost/prosemirror-markdown'
|
# typecheck) fail with TS2307 Cannot find module '@docmost/prosemirror-markdown'
|
||||||
# unless it is built first. Build it before the recursive test run.
|
# unless it is built first. Build it BEFORE git-sync/mcp (which import it).
|
||||||
- name: Build prosemirror-markdown
|
- name: Build prosemirror-markdown
|
||||||
run: pnpm --filter @docmost/prosemirror-markdown build
|
run: pnpm --filter @docmost/prosemirror-markdown build
|
||||||
|
|
||||||
|
# git-sync and mcp are no longer committed in built form (build/ is
|
||||||
|
# gitignored), so CI must compile them: the server resolves both via their
|
||||||
|
# built build/index.js (git-sync's runtime consumer lands on this branch,
|
||||||
|
# #119). The server pretest also builds them, but building here keeps it
|
||||||
|
# explicit and independent of pnpm lifecycle ordering.
|
||||||
|
- name: Build git-sync and mcp
|
||||||
|
run: pnpm --filter @docmost/git-sync build && pnpm --filter @docmost/mcp build
|
||||||
|
|
||||||
- name: Run unit tests
|
- name: Run unit tests
|
||||||
run: pnpm -r test
|
run: pnpm -r test
|
||||||
|
|
||||||
|
|||||||
+7
-10
@@ -4,19 +4,16 @@
|
|||||||
data
|
data
|
||||||
# compiled output
|
# compiled output
|
||||||
/dist
|
/dist
|
||||||
node_modules
|
/node_modules
|
||||||
|
# workspace package node_modules (pnpm symlinks — never commit; they bake
|
||||||
|
# machine-local store paths).
|
||||||
|
packages/*/node_modules/
|
||||||
|
|
||||||
# git-sync compiled output (built in CI/Docker via `pnpm build`, never committed,
|
# Compiled package output: build/ is gitignored for every workspace package
|
||||||
# so src/ and prod can never silently diverge).
|
# (built in CI/Docker via `pnpm build`, never committed, so src/ and prod can
|
||||||
|
# never silently diverge). Private packages are rebuilt at deploy.
|
||||||
packages/git-sync/build/
|
packages/git-sync/build/
|
||||||
|
|
||||||
# prosemirror-markdown compiled output (built in CI/Docker via `pnpm build`,
|
|
||||||
# never committed, so src/ and prod can never silently diverge).
|
|
||||||
packages/prosemirror-markdown/build/
|
packages/prosemirror-markdown/build/
|
||||||
|
|
||||||
# mcp compiled output (built in CI/Docker via `pnpm build`, never committed, so
|
|
||||||
# src/ and prod can never silently diverge). Matches the git-sync/prosemirror-
|
|
||||||
# markdown convention; the package is private and rebuilt at deploy.
|
|
||||||
packages/mcp/build/
|
packages/mcp/build/
|
||||||
|
|
||||||
# Logs
|
# Logs
|
||||||
|
|||||||
@@ -193,7 +193,7 @@ authenticated in-process, so no `tea`/`curl` and no keychain lookup are needed.
|
|||||||
|
|
||||||
## Monorepo layout
|
## Monorepo layout
|
||||||
|
|
||||||
pnpm workspace (`pnpm@10.4.0`) orchestrated by **Nx**. Four workspace packages:
|
pnpm workspace (`pnpm@10.4.0`) orchestrated by **Nx**. Five workspace packages:
|
||||||
|
|
||||||
| Path | Name | Stack | Role |
|
| Path | Name | Stack | Role |
|
||||||
| --- | --- | --- | --- |
|
| --- | --- | --- | --- |
|
||||||
@@ -202,6 +202,7 @@ pnpm workspace (`pnpm@10.4.0`) orchestrated by **Nx**. Four workspace packages:
|
|||||||
| `packages/editor-ext` | `@docmost/editor-ext` | Tiptap/ProseMirror | Shared Tiptap node/mark extensions, imported by both the client and the server |
|
| `packages/editor-ext` | `@docmost/editor-ext` | Tiptap/ProseMirror | Shared Tiptap node/mark extensions, imported by both the client and the server |
|
||||||
| `packages/mcp` | `@docmost/mcp` | MCP SDK, Tiptap, Yjs | Standalone MCP server, also bundled into the server at `/mcp`. Consumes the shared converter/schema from `@docmost/prosemirror-markdown` (#293) — it no longer carries its own vendored converter/schema copy |
|
| `packages/mcp` | `@docmost/mcp` | MCP SDK, Tiptap, Yjs | Standalone MCP server, also bundled into the server at `/mcp`. Consumes the shared converter/schema from `@docmost/prosemirror-markdown` (#293) — it no longer carries its own vendored converter/schema copy |
|
||||||
| `packages/prosemirror-markdown` | `@docmost/prosemirror-markdown` | Tiptap, marked, jsdom | The single, canonical ProseMirror↔Markdown converter + Docmost schema mirror (#293). Consumed by `mcp`, `git-sync`, AND `apps/server` (server-side markdown import/export, #345); there is exactly ONE copy of the converter now |
|
| `packages/prosemirror-markdown` | `@docmost/prosemirror-markdown` | Tiptap, marked, jsdom | The single, canonical ProseMirror↔Markdown converter + Docmost schema mirror (#293). Consumed by `mcp`, `git-sync`, AND `apps/server` (server-side markdown import/export, #345); there is exactly ONE copy of the converter now |
|
||||||
|
| `packages/git-sync` | `@docmost/git-sync` | Tiptap/ProseMirror, Yjs, git | The two-way Docmost↔git Markdown sync **engine** (vault layout, git orchestration, reconcile). Consumes the ProseMirror↔Markdown converter from `@docmost/prosemirror-markdown` (#293) — no longer carries its own converter copy. Bundled into the server (loaded over the ESM bridge), built in CI and the Dockerfile. |
|
||||||
|
|
||||||
`build` targets are Nx-cached and dependency-ordered (`dependsOn: ["^build"]`), so `editor-ext` builds before the apps. `nx.json` sets `affected.defaultBase: main`.
|
`build` targets are Nx-cached and dependency-ordered (`dependsOn: ["^build"]`), so `editor-ext` builds before the apps. `nx.json` sets `affected.defaultBase: main`.
|
||||||
|
|
||||||
@@ -290,8 +291,10 @@ Migration files live in `apps/server/src/database/migrations/` and are named `YY
|
|||||||
|
|
||||||
The API server is a Fastify app with a global `/api` prefix (`main.ts` excludes `robots.txt`, public share pages, and `mcp` from the prefix). A `preHandler` hook enforces that a resolved `workspaceId` exists for most `/api` routes (multi-tenant by hostname/subdomain via `DomainMiddleware`). `GET /api/sb/:id` (the anonymous blob-sandbox read route) is listed in that preHandler's `excludedPaths`, so it is exempt from workspace resolution and carries no session auth at all (its capability is the unguessable UUID + TTL + TLS) — unlike `/api/files/public/...`, which still resolves a workspace and requires a workspace-bound attachment JWT. Auth is JWT (cookie + bearer); authorization is **CASL** (`core/casl`) — every data access is scoped to the user's abilities.
|
The API server is a Fastify app with a global `/api` prefix (`main.ts` excludes `robots.txt`, public share pages, and `mcp` from the prefix). A `preHandler` hook enforces that a resolved `workspaceId` exists for most `/api` routes (multi-tenant by hostname/subdomain via `DomainMiddleware`). `GET /api/sb/:id` (the anonymous blob-sandbox read route) is listed in that preHandler's `excludedPaths`, so it is exempt from workspace resolution and carries no session auth at all (its capability is the unguessable UUID + TTL + TLS) — unlike `/api/files/public/...`, which still resolves a workspace and requires a workspace-bound attachment JWT. Auth is JWT (cookie + bearer); authorization is **CASL** (`core/casl`) — every data access is scoped to the user's abilities.
|
||||||
|
|
||||||
|
Two routes are mounted **outside** the `/api` prefix at the root, as raw Fastify routes that bypass the Nest pipeline (so neither `DomainMiddleware` nor `ThrottlerGuard` runs for them — each resolves the workspace and throttles itself): `/mcp` (the embedded MCP server, see below) and `/git/<spaceId>.git/...` (the git-sync smart-HTTP host, see below). Both share `mcp-auth.helpers.ts` (HTTP-Basic parsing, `FailedLoginLimiter`, `clientIp`) and the common `resolveRequestWorkspace` helper.
|
||||||
|
|
||||||
### Module structure (server)
|
### Module structure (server)
|
||||||
`AppModule` wires integration modules (`integrations/*`: storage [local/S3/Azure], mail, queue [BullMQ on Redis], security, telemetry, throttle, `mcp`, `ai`) plus `CoreModule`, `DatabaseModule`, and `CollaborationModule`. `CoreModule` (`core/*`) holds the domain modules: `page`, `space`, `comment`, `workspace`, `user`, `auth`, `group`, `attachment`, `search`, `share`, `ai-chat`, etc. Each domain module follows NestJS controller → service → repo layering; DB repos live under `database/repos` and are injected app-wide from the global `DatabaseModule`.
|
`AppModule` wires integration modules (`integrations/*`: storage [local/S3/Azure], mail, queue [BullMQ on Redis], security, telemetry, throttle, `mcp`, `ai`, `git-sync`) plus `CoreModule`, `DatabaseModule`, and `CollaborationModule`. `CoreModule` (`core/*`) holds the domain modules: `page`, `space`, `comment`, `workspace`, `user`, `auth`, `group`, `attachment`, `search`, `share`, `ai-chat`, etc. Each domain module follows NestJS controller → service → repo layering; DB repos live under `database/repos` and are injected app-wide from the global `DatabaseModule`.
|
||||||
|
|
||||||
**EE removal artifact:** `app.module.ts` still contains a `try/require('./ee/ee.module')` stub. That path no longer exists, so the require fails and is swallowed (it only hard-exits when `CLOUD === 'true'`). Treat EE as gone — do not add code that depends on it.
|
**EE removal artifact:** `app.module.ts` still contains a `try/require('./ee/ee.module')` stub. That path no longer exists, so the require fails and is swallowed (it only hard-exits when `CLOUD === 'true'`). Treat EE as gone — do not add code that depends on it.
|
||||||
|
|
||||||
@@ -308,10 +311,16 @@ The API server is a Fastify app with a global `/api` prefix (`main.ts` excludes
|
|||||||
- `core/ai-chat/external-mcp/` — admins can attach external MCP servers (e.g. Tavily) to give the agent web access. **`ssrf-guard.ts` validates outbound MCP URLs against SSRF** — keep that guard in the path when touching external-MCP connection logic.
|
- `core/ai-chat/external-mcp/` — admins can attach external MCP servers (e.g. Tavily) to give the agent web access. **`ssrf-guard.ts` validates outbound MCP URLs against SSRF** — keep that guard in the path when touching external-MCP connection logic.
|
||||||
- `core/ai-chat/ai-chat-run.service.ts` + `ai_chat_runs` — **detached/autonomous agent runs** (`#184`), behind the per-workspace `settings.ai.autonomousRuns` flag (off by default). When on, a turn becomes a server-side RUN that survives a browser disconnect; only an explicit `POST /ai-chat/stop` ends it, and a client reconnects/live-follows via `POST /ai-chat/run`. **DEPLOY CONSTRAINT — single-instance only in phase 1:** Stop and the AbortController that backs it are process-local, so a Stop only aborts a run executing on the **same** replica that owns it (cross-instance pub/sub stop is phase 2). Do **not** enable `autonomousRuns` on a horizontally-scaled deployment (multiple replicas behind a load balancer, or Docmost cloud `CLOUD=true`) — run a single instance instead. The server logs a startup WARNING when it detects a multi-instance deployment (`CLOUD=true`) so the constraint is visible. The startup sweep settles any run left dangling by a restart.
|
- `core/ai-chat/ai-chat-run.service.ts` + `ai_chat_runs` — **detached/autonomous agent runs** (`#184`), behind the per-workspace `settings.ai.autonomousRuns` flag (off by default). When on, a turn becomes a server-side RUN that survives a browser disconnect; only an explicit `POST /ai-chat/stop` ends it, and a client reconnects/live-follows via `POST /ai-chat/run`. **DEPLOY CONSTRAINT — single-instance only in phase 1:** Stop and the AbortController that backs it are process-local, so a Stop only aborts a run executing on the **same** replica that owns it (cross-instance pub/sub stop is phase 2). Do **not** enable `autonomousRuns` on a horizontally-scaled deployment (multiple replicas behind a load balancer, or Docmost cloud `CLOUD=true`) — run a single instance instead. The server logs a startup WARNING when it detects a multi-instance deployment (`CLOUD=true`) so the constraint is visible. The startup sweep settles any run left dangling by a restart.
|
||||||
|
|
||||||
|
### Git-sync (native two-way Docmost ↔ git Markdown sync)
|
||||||
|
`integrations/git-sync/` (`GitSyncModule`) + the vendored pure engine in `packages/git-sync`. Off by default; gated by the `GIT_SYNC_ENABLED` master switch (and `GIT_SYNC_SERVICE_USER_ID`, the account git-originated writes are attributed to). Per-space opt-in via `space.settings.gitSync.enabled`, with a second per-space toggle `space.settings.gitSync.autoMergeConflicts` that changes PUSH behavior for a still-conflicted page (one carrying `<<<<<<<`/`>>>>>>>` markers): **off (the safe default)** records a per-page failure and holds the refs so the user resolves the git conflict first (markers never reach Docmost); **on** strips the marker lines and pushes both sides' content. Each enabled space gets an on-disk working "vault" repo; the `GitSyncOrchestrator` runs a debounced + poll-backstop reconcile cycle (PULL Docmost→vault, PUSH vault→Docmost) under a per-space Redis leader lock + in-process mutex (`SpaceLockService`). Writes go through the collaboration layer (so concurrent human edits aren't clobbered) and are stamped `lastUpdatedSource = 'git-sync'` for the listener loop-guard. The in-process `setInterval` orchestration + best-effort lock (no fencing tokens) is a known multi-replica limitation — BullMQ + fencing is the documented future direction.
|
||||||
|
|
||||||
|
- **`/git` smart-HTTP host** (`integrations/git-sync/http/`, gated additionally by `GIT_SYNC_HTTP_ENABLED`, which defaults to `GIT_SYNC_ENABLED`): a raw root-mounted Fastify route `/git/<spaceId>.git/...` (registered in `main.ts`, NOT under `/api`) that bridges `git clone`/`fetch`/`push` to `git http-backend`. It authenticates HTTP Basic against `AuthService` (throttled by a `FailedLoginLimiter` mirroring the `/mcp` path), authorizes via `SpaceAbilityFactory` (read = fetch, Manage = push), and gates existence so a non-member gets the SAME 404 as a missing/sync-disabled space (never 403 — that would leak space existence). A push runs the receive-pack under the space lock, then a reconcile cycle.
|
||||||
|
- **Schema mirror:** git-sync no longer carries its own schema copy — it consumes the Docmost schema mirror from `@docmost/prosemirror-markdown` (#293), which is itself mirrored from the canonical `editor-ext` and guarded by the serializer-contract test. There is no longer a per-package hand-synced copy to keep in lockstep.
|
||||||
|
|
||||||
### Client structure
|
### Client structure
|
||||||
Vite SPA. Code is organized by feature under `apps/client/src/features/*` (mirrors the server domains: `page`, `space`, `comment`, `ai-chat`, `editor`, …). Conventions:
|
Vite SPA. Code is organized by feature under `apps/client/src/features/*` (mirrors the server domains: `page`, `space`, `comment`, `ai-chat`, `editor`, …). Conventions:
|
||||||
- **TanStack Query** for server state (one `queries/` file per feature), **Jotai** atoms for local/shared UI state, **Mantine 8** + CSS modules (`*.module.css`) + `postcss-preset-mantine` for UI.
|
- **TanStack Query** for server state (one `queries/` file per feature), **Jotai** atoms for local/shared UI state, **Mantine 8** + CSS modules (`*.module.css`) + `postcss-preset-mantine` for UI.
|
||||||
- The editor is Tiptap; shared node/mark extensions live in `packages/editor-ext` and are imported by **both the client and the server** (collaboration, schema, `canonicalizeFootnotes`) — editor schema changes often need to be made in `editor-ext`, not just the client. Server-side markdown import/export no longer lives in `editor-ext`: it goes through the canonical converter (#345, see below). The ProseMirror↔Markdown converter and its Docmost schema mirror now live in a SINGLE package, `@docmost/prosemirror-markdown` (#293), consumed by `mcp`, `git-sync`, and `apps/server` (#345) — do NOT reintroduce a per-package copy. `editor-ext` is the upstream source of the Tiptap schema; the package's `docmost-schema.ts` mirrors it and a serializer-contract test (`packages/prosemirror-markdown/test/serializer-contract.test.ts`) guards the boundary (every schema node must have a converter case), so a drift surfaces as a failing test rather than silent divergence. For the converter's property-testing and counterexample→fixture process (P1–P4 invariants, the `PROPERTY_SEED`/`PROPERTY_NUM_RUNS` knobs, and the nightly fuzz workflow), see `packages/prosemirror-markdown/README.md`.
|
- The editor is Tiptap; shared node/mark extensions live in `packages/editor-ext` and are imported by **both the client and the server** (collaboration, schema, `canonicalizeFootnotes`) — editor schema changes often need to be made in `editor-ext`, not just the client. Server-side markdown import/export no longer lives in `editor-ext`: it goes through the canonical converter (#345, see below). The ProseMirror↔Markdown converter and its Docmost schema mirror now live in a SINGLE package, `@docmost/prosemirror-markdown` (#293), consumed by `mcp`, `git-sync`, and `apps/server` (#345) — do NOT reintroduce a per-package copy. `editor-ext` is the upstream source of the Tiptap schema; the package's `docmost-schema.ts` mirrors it and a serializer-contract test (`packages/prosemirror-markdown/test/serializer-contract.test.ts`) guards the boundary (every schema node must have a converter case), so a drift surfaces as a failing test rather than silent divergence.
|
||||||
- API access goes through `apps/client/src/lib/api-client.ts` (axios). The `@` alias maps to `apps/client/src`.
|
- API access goes through `apps/client/src/lib/api-client.ts` (axios). The `@` alias maps to `apps/client/src`.
|
||||||
- Runtime config is injected at build time by `vite.config.ts` via `define` (`APP_URL`, `COLLAB_URL`, `APP_VERSION`, …) — these come from the root `.env`, not from `import.meta.env`.
|
- Runtime config is injected at build time by `vite.config.ts` via `define` (`APP_URL`, `COLLAB_URL`, `APP_VERSION`, …) — these come from the root `.env`, not from `import.meta.env`.
|
||||||
|
|
||||||
|
|||||||
@@ -12,6 +12,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
|||||||
|
|
||||||
### Added
|
### Added
|
||||||
|
|
||||||
|
- **Native two-way Docmost ↔ git Markdown sync.** Opt-in per space (Space
|
||||||
|
settings → a git-sync toggle, plus an `autoMergeConflicts` toggle that controls
|
||||||
|
whether a still-conflicted page is held back or pushed with its conflict
|
||||||
|
markers stripped): each enabled space is mirrored to an on-disk git "vault" of
|
||||||
|
Markdown files and reconciled in both directions (Docmost → vault and vault →
|
||||||
|
Docmost) on a debounced + poll-backstop cycle, under a per-space lock, writing
|
||||||
|
through the collaboration layer so concurrent human edits aren't clobbered.
|
||||||
|
Git-originated changes are attributed to a configurable service account and
|
||||||
|
carry a "git-sync" provenance badge in page history. Optionally exposes a `/git`
|
||||||
|
smart-HTTP host so you can `git clone`/`fetch`/`push` a space directly (HTTP
|
||||||
|
Basic auth, space-permission authorized). Off by default and configured via the
|
||||||
|
`GIT_SYNC_*` environment variables, including `GIT_SYNC_ENABLED`,
|
||||||
|
`GIT_SYNC_SERVICE_USER_ID`, and `GIT_SYNC_HTTP_ENABLED` (see `.env.example`).
|
||||||
|
(#119)
|
||||||
- **Place several images side by side in a row.** A new "Inline (side by
|
- **Place several images side by side in a row.** A new "Inline (side by
|
||||||
side)" alignment mode in the image bubble menu renders consecutive inline
|
side)" alignment mode in the image bubble menu renders consecutive inline
|
||||||
images as a row that wraps onto the next line on narrow screens. The row is
|
images as a row that wraps onto the next line on narrow screens. The row is
|
||||||
|
|||||||
+14
-7
@@ -24,8 +24,9 @@ RUN pnpm build
|
|||||||
|
|
||||||
FROM base AS installer
|
FROM base AS installer
|
||||||
|
|
||||||
|
# git: required by the git-sync VaultGit (shells out to git)
|
||||||
RUN apt-get update \
|
RUN apt-get update \
|
||||||
&& apt-get install -y --no-install-recommends curl bash \
|
&& apt-get install -y --no-install-recommends curl bash git \
|
||||||
&& rm -rf /var/lib/apt/lists/*
|
&& rm -rf /var/lib/apt/lists/*
|
||||||
|
|
||||||
WORKDIR /app
|
WORKDIR /app
|
||||||
@@ -45,14 +46,20 @@ COPY --from=builder /app/packages/editor-ext/dist /app/packages/editor-ext/dist
|
|||||||
COPY --from=builder /app/packages/editor-ext/package.json /app/packages/editor-ext/package.json
|
COPY --from=builder /app/packages/editor-ext/package.json /app/packages/editor-ext/package.json
|
||||||
COPY --from=builder /app/packages/mcp/build /app/packages/mcp/build
|
COPY --from=builder /app/packages/mcp/build /app/packages/mcp/build
|
||||||
COPY --from=builder /app/packages/mcp/package.json /app/packages/mcp/package.json
|
COPY --from=builder /app/packages/mcp/package.json /app/packages/mcp/package.json
|
||||||
# mcp now depends on @docmost/prosemirror-markdown (workspace:*) and eager-imports
|
# @docmost/prosemirror-markdown is the shared converter (#293/#326). Both mcp and
|
||||||
# it at runtime (the in-app ai-chat DocmostClient loads build/index.js -> lib/
|
# git-sync depend on it (workspace:*) and load it at runtime, so the built package +
|
||||||
# markdown-converter.js). Ship the built package + its manifest, or the prod
|
# its manifest must be shipped or the prod install resolves a broken workspace
|
||||||
# install resolves a broken workspace symlink and every ai-chat tool dies with
|
# symlink and every consumer dies with ERR_MODULE_NOT_FOUND.
|
||||||
# ERR_MODULE_NOT_FOUND (#293/#326 step 5). (git-sync has no runtime consumer yet;
|
|
||||||
# revisit at step 6 when #119 lands.)
|
|
||||||
COPY --from=builder /app/packages/prosemirror-markdown/build /app/packages/prosemirror-markdown/build
|
COPY --from=builder /app/packages/prosemirror-markdown/build /app/packages/prosemirror-markdown/build
|
||||||
COPY --from=builder /app/packages/prosemirror-markdown/package.json /app/packages/prosemirror-markdown/package.json
|
COPY --from=builder /app/packages/prosemirror-markdown/package.json /app/packages/prosemirror-markdown/package.json
|
||||||
|
# git-sync: the server loads @docmost/git-sync at runtime via the loader
|
||||||
|
# (git-sync.loader.ts), which deliberately does NOT `require()` it — the package is
|
||||||
|
# ESM-only, so the loader uses `require.resolve` + a dynamic `import()`. Without
|
||||||
|
# these copied build artifacts that resolve/import fails and the server crashes on
|
||||||
|
# first use. Built fresh by the builder's `pnpm build` (nx builds the package's tsc
|
||||||
|
# `build` target). This branch (#119) is where git-sync gains its runtime consumer.
|
||||||
|
COPY --from=builder /app/packages/git-sync/build /app/packages/git-sync/build
|
||||||
|
COPY --from=builder /app/packages/git-sync/package.json /app/packages/git-sync/package.json
|
||||||
|
|
||||||
# Copy root package files
|
# Copy root package files
|
||||||
COPY --from=builder /app/package.json /app/package.json
|
COPY --from=builder /app/package.json /app/package.json
|
||||||
|
|||||||
@@ -125,32 +125,6 @@ Gitmost follows the upstream Docmost setup. See the Docmost
|
|||||||
[documentation](https://docmost.com/docs) for self-hosting and development instructions; replace the
|
[documentation](https://docmost.com/docs) for self-hosting and development instructions; replace the
|
||||||
`docmost/docmost` image with `ghcr.io/vvzvlad/gitmost` where applicable.
|
`docmost/docmost` image with `ghcr.io/vvzvlad/gitmost` where applicable.
|
||||||
|
|
||||||
### Reverse proxy: SSE streaming paths
|
|
||||||
|
|
||||||
The AI agent streams its answers over Server-Sent Events. These endpoints produce a
|
|
||||||
long-lived `text/event-stream` response and **must bypass response buffering AND response
|
|
||||||
compression** at every proxy in front of the app:
|
|
||||||
|
|
||||||
- `POST /api/ai-chat/stream` — the live agent turn stream
|
|
||||||
- `GET /api/ai-chat/runs/<chatId>/stream` — attach/resume of a detached agent run
|
|
||||||
(`AI_CHAT_RESUMABLE_STREAM`)
|
|
||||||
- `POST /api/shares/ai/stream` — the anonymous public-share assistant
|
|
||||||
|
|
||||||
A buffering or compressing proxy does not break these with an error — it silently ruins them:
|
|
||||||
the request hangs in `pending`, tokens stop streaming and arrive in one burst when the turn
|
|
||||||
ends, or a reloaded tab falls back to coarse polling. The tell in DevTools is a
|
|
||||||
`Content-Encoding: gzip/zstd` response header on a `text/event-stream` response.
|
|
||||||
|
|
||||||
The server already sends `X-Accel-Buffering: no` (honored by nginx unless ignored), but
|
|
||||||
compression middleware is applied by proxy configuration, not headers:
|
|
||||||
|
|
||||||
- **nginx** — `proxy_buffering off; proxy_cache off; gzip off;` for these locations, e.g.
|
|
||||||
`location ~ ^/api/(ai-chat/(stream$|runs/.+/stream$)|shares/ai/) { ... }`
|
|
||||||
- **Traefik** — route these paths through a dedicated router **without** the `compress`
|
|
||||||
middleware (a `compress` middleware buffers SSE frames until the response closes), e.g.
|
|
||||||
``PathPrefix(`/api/ai-chat/stream`) || PathPrefix(`/api/ai-chat/runs/`)``. Belt-and-braces:
|
|
||||||
`traefik.http.middlewares.<name>.compress.excludedcontenttypes: text/event-stream`.
|
|
||||||
|
|
||||||
## Migration from Docmost
|
## Migration from Docmost
|
||||||
|
|
||||||
Gitmost's database schema is a **strict superset** of Docmost's. Every Gitmost-specific migration
|
Gitmost's database schema is a **strict superset** of Docmost's. Every Gitmost-specific migration
|
||||||
|
|||||||
@@ -126,32 +126,6 @@ Gitmost повторяет процесс установки upstream-Docmost.
|
|||||||
смотрите в [документации](https://docmost.com/docs) Docmost; где это применимо, заменяйте образ
|
смотрите в [документации](https://docmost.com/docs) Docmost; где это применимо, заменяйте образ
|
||||||
`docmost/docmost` на `ghcr.io/vvzvlad/gitmost`.
|
`docmost/docmost` на `ghcr.io/vvzvlad/gitmost`.
|
||||||
|
|
||||||
### Reverse proxy: SSE-стриминговые пути
|
|
||||||
|
|
||||||
AI-агент стримит ответы через Server-Sent Events. Эти эндпоинты отдают долгоживущий
|
|
||||||
`text/event-stream`-ответ и **обязаны обходить буферизацию И сжатие ответов** на каждом
|
|
||||||
прокси перед приложением:
|
|
||||||
|
|
||||||
- `POST /api/ai-chat/stream` — живой стрим хода агента
|
|
||||||
- `GET /api/ai-chat/runs/<chatId>/stream` — подключение/резюм detached-рана
|
|
||||||
(`AI_CHAT_RESUMABLE_STREAM`)
|
|
||||||
- `POST /api/shares/ai/stream` — анонимный ассистент публичных шар
|
|
||||||
|
|
||||||
Буферизующий или сжимающий прокси не ломает эти пути с ошибкой — он тихо их портит:
|
|
||||||
запрос висит в `pending`, токены не стримятся и вываливаются одним куском в конце хода,
|
|
||||||
а перезагруженная вкладка падает в грубый поллинг. Диагностический признак в DevTools —
|
|
||||||
заголовок `Content-Encoding: gzip/zstd` на ответе с `text/event-stream`.
|
|
||||||
|
|
||||||
Сервер уже шлёт `X-Accel-Buffering: no` (nginx учитывает его по умолчанию), но
|
|
||||||
compression-мидлвари управляются конфигом прокси, а не заголовками:
|
|
||||||
|
|
||||||
- **nginx** — `proxy_buffering off; proxy_cache off; gzip off;` для этих location,
|
|
||||||
например `location ~ ^/api/(ai-chat/(stream$|runs/.+/stream$)|shares/ai/) { ... }`
|
|
||||||
- **Traefik** — вести эти пути через отдельный роутер **без** `compress`-мидлвари
|
|
||||||
(compress буферизует SSE-кадры до закрытия ответа), например
|
|
||||||
``PathPrefix(`/api/ai-chat/stream`) || PathPrefix(`/api/ai-chat/runs/`)``. Для надёжности:
|
|
||||||
`traefik.http.middlewares.<name>.compress.excludedcontenttypes: text/event-stream`.
|
|
||||||
|
|
||||||
## Миграция с Docmost
|
## Миграция с Docmost
|
||||||
|
|
||||||
Схема БД Gitmost — это **строгий superset** схемы Docmost. Все Gitmost-специфичные миграции только
|
Схема БД Gitmost — это **строгий superset** схемы Docmost. Все Gitmost-специфичные миграции только
|
||||||
|
|||||||
@@ -16,272 +16,114 @@ roles:
|
|||||||
whatever language is most effective, but deliver the report in English.
|
whatever language is most effective, but deliver the report in English.
|
||||||
|
|
||||||
═══════════════════════════════════════════════
|
═══════════════════════════════════════════════
|
||||||
THE BUDGET: PAGES READ, NOT SEARCHES
|
STEP 0. PLAN (always do this first)
|
||||||
═══════════════════════════════════════════════
|
═══════════════════════════════════════════════
|
||||||
The unit of research work is a PAGE READ IN FULL — opening a source with the
|
Before searching for anything, draft and show a research plan:
|
||||||
page-reading/extraction tool and actually reading it. Search queries are free
|
- Break down the query: what exactly is needed, what sub-questions are
|
||||||
and unlimited: they are navigation, not research. A search result snippet is a
|
inside it, which terms are ambiguous or have synonyms/jargon.
|
||||||
POINTER, never a source. Nothing learned only from a snippet may enter the
|
- Formulate 5–10 search directions, including adjacent perspectives that
|
||||||
report.
|
may prove useful even if the user did not ask about them directly.
|
||||||
|
- Set a "research budget" — roughly how many searches the task's complexity
|
||||||
- If the user named a budget (e.g. "budget 100"), that is 100 pages read, and
|
warrants (a simple fact: under 5; a medium task: 5–15; a hard task: more).
|
||||||
it is BINDING — a floor you MUST reach. Spend it in full even past the point
|
- Decide which languages it makes sense to search in (see below).
|
||||||
where the topic feels covered (see BUDGET REMAINDER PROTOCOL below).
|
|
||||||
- If no budget is given, default to about 50 pages read; fewer only for a
|
|
||||||
single trivial fact, well over 50 for a hard, broad task. Absent an explicit
|
|
||||||
budget, stop only at genuine saturation — when further reading stops
|
|
||||||
yielding new relevant information — not when it "seems like enough".
|
|
||||||
- A page counts toward the budget only if you read it and extracted something
|
|
||||||
(a finding, a dead-end note, a contradiction). Skimming a snippet does not
|
|
||||||
count. Re-opening the same page does not count twice.
|
|
||||||
- Rule of thumb: for every search that surfaces relevant hits, open and read
|
|
||||||
at least 2–3 of the most promising results BEFORE running the next search.
|
|
||||||
Chaining searches with no page reads in between is a critical failure —
|
|
||||||
snippets carry ~5 % of the available content and reading pages is the whole
|
|
||||||
job. If you catch yourself doing it, stop and go read what you already
|
|
||||||
found.
|
|
||||||
|
|
||||||
BUDGET REMAINDER PROTOCOL. When the topic already feels covered but budget
|
|
||||||
remains, do NOT pad with junk or near-duplicate reads. Spend the remainder in
|
|
||||||
this priority order:
|
|
||||||
1. ADVERSARIAL VERIFICATION — for each key claim in the document, run
|
|
||||||
searches deliberately trying to REFUTE it or find a competing version;
|
|
||||||
read what you find. Results go into the "Contradictions" section (or
|
|
||||||
strengthen the claim's footnote).
|
|
||||||
2. PRIMARY SOURCES — for every important claim currently backed by a
|
|
||||||
retelling, aggregator, or news piece, hunt down and read the original:
|
|
||||||
the study, spec, dataset, filing, repository, interview.
|
|
||||||
3. LATERAL EXPANSION — adjacent disciplines, industries with the same
|
|
||||||
problem, historical analogues, criticism and opposing schools.
|
|
||||||
Every remainder read must still be a genuine attempt to learn or verify
|
|
||||||
something.
|
|
||||||
|
|
||||||
═══════════════════════════════════════════════
|
═══════════════════════════════════════════════
|
||||||
THE DOCUMENT IS YOUR WORKING MEMORY
|
WHERE TO WRITE THE RESULT
|
||||||
═══════════════════════════════════════════════
|
═══════════════════════════════════════════════
|
||||||
Your context window is small and lossy; the document is not. Treat the
|
- If the user explicitly asks to work in the current/already-open document,
|
||||||
document — not your head — as the single source of truth and your external
|
work in it.
|
||||||
memory. You are not "taking notes to compile later"; you are building the
|
- If this is not specified, create a NEW document for the report.
|
||||||
report itself, live, from the first minute.
|
- Keep a working draft in the document or in notes: fact → source →
|
||||||
|
reliability assessment. Update the structure as you go.
|
||||||
SETUP. Create/claim the document at the VERY START, before any searches.
|
|
||||||
Reuse the currently open document ONLY if (a) the user explicitly asked to
|
|
||||||
work in it, or (b) it is empty or near-empty AND its title matches the topic.
|
|
||||||
Otherwise create a new one.
|
|
||||||
|
|
||||||
Seed it immediately with:
|
|
||||||
- the user's query, restated;
|
|
||||||
- the RESEARCH PLAN (see below) — the plan lives in the document, not in
|
|
||||||
chat; do not wait for approval, write it and proceed;
|
|
||||||
- a skeleton of the report sections you expect to fill;
|
|
||||||
- a "Log" section (working log) and an "Open Questions" section.
|
|
||||||
|
|
||||||
RESEARCH PLAN (written into the document before searching):
|
|
||||||
- Break down the query: what exactly is needed, what sub-questions are
|
|
||||||
inside it, which terms are ambiguous or have synonyms/jargon.
|
|
||||||
- 5–10 search directions, including adjacent angles the user did not ask
|
|
||||||
about directly.
|
|
||||||
- The budget (user-given or default) and how you expect to allocate it
|
|
||||||
across directions — a rough split, revisable.
|
|
||||||
- Which languages to search in.
|
|
||||||
|
|
||||||
THE LOG. In the "Log" section keep a numbered list of pages read:
|
|
||||||
`N. [query →] source — what I took / empty / contradiction`. One line each.
|
|
||||||
This is your budget counter and your flush-cadence counter — count by the log,
|
|
||||||
not from memory. Dead ends and paywalls go in the log too (they count toward
|
|
||||||
the budget only if you actually read a cached/alternative copy; a hard dead
|
|
||||||
end is logged but not counted).
|
|
||||||
|
|
||||||
FLUSH CADENCE — HARD RULE. Never read more than ~8–10 pages without writing
|
|
||||||
everything gathered since the last flush into the report sections. Check the
|
|
||||||
log: if the last flush was 10 reads ago, the next action is writing, not
|
|
||||||
reading. Frequent small updates are the norm; a long streak of reads with
|
|
||||||
nothing written is a mistake to correct immediately.
|
|
||||||
|
|
||||||
CONTEXT DISCIPLINE. After flushing a finding into the document, compress it in
|
|
||||||
your head to 2–3 sentences of conclusions and let the raw page text go. Do not
|
|
||||||
carry full page contents forward in context. When you need to re-orient — and
|
|
||||||
ALWAYS before deciding what to research next after a flush — RE-READ the
|
|
||||||
document (at minimum: the skeleton, "Open Questions", and the sections you
|
|
||||||
touched). The document you re-read, not your memory of it, defines the current
|
|
||||||
state of the research.
|
|
||||||
|
|
||||||
═══════════════════════════════════════════════
|
═══════════════════════════════════════════════
|
||||||
WORK LOOP
|
WORK LOOP (repeat until saturation)
|
||||||
═══════════════════════════════════════════════
|
═══════════════════════════════════════════════
|
||||||
Iterate observe → orient → decide → act:
|
Work iteratively through an observe → orient → decide → act loop:
|
||||||
1. Observe: re-read the relevant parts of the DOCUMENT — what is filled,
|
1. Observe: what has been gathered, what is still missing, what tools exist.
|
||||||
what is thin, what "Open Questions" lists.
|
2. Orient: which query or source would best close the gap; update your
|
||||||
2. Orient: which query or source best closes the biggest gap; update the
|
understanding of the topic based on what you've found.
|
||||||
plan section if your understanding of the topic has shifted.
|
3. Decide: choose a specific next action.
|
||||||
3. Decide: pick one concrete next action.
|
4. Act: run the search or open the source.
|
||||||
4. Act: search, then READ the promising results in full.
|
After EVERY result, reason about it: what you learned, what new questions
|
||||||
After every page read, reason: what you learned, what new questions arose,
|
arose, what to search next. Maintain an internal list of open questions and
|
||||||
what to read next. Add new questions to "Open Questions"; strike out closed
|
gaps, and close them.
|
||||||
ones. Flush per the cadence above.
|
|
||||||
|
|
||||||
═══════════════════════════════════════════════
|
|
||||||
CRITICAL REVIEW PASS (mandatory, after the main pass)
|
|
||||||
═══════════════════════════════════════════════
|
|
||||||
When the planned directions are covered (or ~70 % of the budget is spent,
|
|
||||||
whichever comes first), STOP researching and switch roles: re-read the ENTIRE
|
|
||||||
document as a hostile reviewer who did not do the research. Write the result
|
|
||||||
into a "Revision" block in the document:
|
|
||||||
- GAPS: sub-questions from the plan that are answered thinly or not at all;
|
|
||||||
sections that are compilation without analysis; places where the report
|
|
||||||
says "widely known" instead of citing.
|
|
||||||
- WEAK CLAIMS: key statements resting on a single source, on a secondary
|
|
||||||
source, on marketing material, or on an old date.
|
|
||||||
- CONTRADICTIONS: places where the document disagrees with itself.
|
|
||||||
- MISSING ANGLES: what a domain expert would immediately ask that the
|
|
||||||
report does not address.
|
|
||||||
Then convert this list into a targeted second pass: spend the remaining
|
|
||||||
budget closing the gaps and hardening the weak claims, in priority order.
|
|
||||||
If budget remains after that, apply the BUDGET REMAINDER PROTOCOL. Repeat the
|
|
||||||
review → targeted pass cycle until the budget is spent (mandatory budget) or
|
|
||||||
saturation is genuine (no budget given). A report that got only one linear
|
|
||||||
pass and no revision is not finished.
|
|
||||||
|
|
||||||
═══════════════════════════════════════════════
|
═══════════════════════════════════════════════
|
||||||
HOW TO SEARCH
|
HOW TO SEARCH
|
||||||
═══════════════════════════════════════════════
|
═══════════════════════════════════════════════
|
||||||
|
VOLUME. Execute a MINIMUM of 15 distinct searches, more for complex tasks.
|
||||||
|
Do not stop at the first plausible answer. Stop only when further searches
|
||||||
|
stop yielding new relevant information (saturation / diminishing returns) —
|
||||||
|
not when it "seems like enough" or when you get tired.
|
||||||
|
|
||||||
WIDE → NARROW. Start with short, broad queries (2–5 words), survey the
|
WIDE → NARROW. Start with short, broad queries (2–5 words), survey the
|
||||||
landscape, then narrow. Scarce results → broaden the phrasing; abundant →
|
landscape, then narrow. If results are scarce, broaden the phrasing; if
|
||||||
narrow it.
|
they're abundant, narrow it.
|
||||||
|
|
||||||
REFORMULATE. Don't repeat the same query. Approach from different angles:
|
REFORMULATE. Don't repeat the same query. Approach from different angles:
|
||||||
synonyms, the professional jargon of the field, alternative and historical
|
synonyms, the professional jargon of the target field, alternative terms,
|
||||||
terms.
|
historical names.
|
||||||
|
|
||||||
OTHER LANGUAGES. Actively search in the languages where the primary sources
|
OTHER LANGUAGES. Actively search in the languages where the primary source
|
||||||
or core expertise likely live (German-law topic in German, Japanese-technology
|
or the core expertise on the topic is likely to live (e.g. a German-law
|
||||||
topic in Japanese, medical reviews in non-English databases). Translate key
|
topic in German, a Japanese-technology topic in Japanese, medical reviews
|
||||||
terms into the target language and search with them. Render anything found
|
in non-English databases). For many topics a significant share of relevant
|
||||||
into English in the report.
|
primary sources is absent from Russian- and English-language results.
|
||||||
|
Translate key terms into the target language and search with them. Render
|
||||||
|
anything found in other languages into English in the report.
|
||||||
|
|
||||||
NOT THE FIRST PAGE. The first results are the most obvious and often the most
|
NOT THE FIRST PAGE. The first results are the most obvious and often the
|
||||||
superficial. Deliberately dig deeper.
|
most superficial. Deliberately dig out what lies deeper.
|
||||||
|
|
||||||
LATERAL SEARCH. Don't fixate on the narrow phrasing. Regularly ask: "What
|
FULL PAGES, NOT SNIPPETS. Open and read sources in full rather than relying
|
||||||
sits right next to the scope and might turn out to be important?" Capture
|
on search-result fragments.
|
||||||
valuable unexpected findings — they feed the "Adjacent & non-obvious" section.
|
|
||||||
|
PRIMARY SOURCES. Go to the originals: studies, documents, data, specs,
|
||||||
|
reports, repositories, interviews. Prefer primary sources over news
|
||||||
|
aggregators and retellings. If someone cites a source — find the source
|
||||||
|
itself.
|
||||||
|
|
||||||
|
LATERAL SEARCH. Don't fixate on the narrow phrasing. Move into adjacent
|
||||||
|
areas that may be useful: neighboring disciplines and industries that faced
|
||||||
|
a similar problem, historical analogues, opposing viewpoints and criticism,
|
||||||
|
non-obvious connections between topics. Regularly ask yourself: "What sits
|
||||||
|
right next to the scope and might turn out to be important?" Capture
|
||||||
|
valuable unexpected findings.
|
||||||
|
|
||||||
═══════════════════════════════════════════════
|
═══════════════════════════════════════════════
|
||||||
EVALUATING SOURCES AND FACTS
|
EVALUATING SOURCES AND FACTS
|
||||||
═══════════════════════════════════════════════
|
═══════════════════════════════════════════════
|
||||||
SOURCE HIERARCHY (when sources conflict, higher beats lower, then recency):
|
CRITICAL APPRAISAL. Watch for signs of problematic sources: aggregators
|
||||||
1. Primary documents: studies, specs, standards, datasets, filings, code
|
instead of the original, false authority, nameless sources paired with
|
||||||
repositories, official statistics, court records, first-person
|
passive voice, general qualifiers without specifics, unconfirmed reports,
|
||||||
interviews.
|
|
||||||
2. Peer-reviewed literature and systematic reviews.
|
|
||||||
3. Official documentation and statements of the responsible organization.
|
|
||||||
4. Quality journalism with named authors and named sources.
|
|
||||||
5. Expert blogs and conference talks (judge the author, not the venue).
|
|
||||||
6. Aggregators, content farms, forums, anonymous retellings — pointers
|
|
||||||
only; never the sole support for a claim in the report.
|
|
||||||
|
|
||||||
CRITICAL APPRAISAL. Watch for: aggregators instead of the original, false
|
|
||||||
authority, nameless sources with passive voice, qualifiers without specifics,
|
|
||||||
marketing language, speculation, cherry-picked data. Do not present such
|
marketing language, speculation, cherry-picked data. Do not present such
|
||||||
material as established fact — flag it. Present speculation about the future
|
results as established fact — flag the issue. Present speculation about the
|
||||||
as speculation.
|
future as speculation, not as something that has happened.
|
||||||
|
|
||||||
LATERAL READING. To judge an unfamiliar source, don't burrow into it — check
|
LATERAL READING. To judge an unfamiliar source, don't burrow into the
|
||||||
what other reliable sources say about it and its author.
|
source itself — see what other reliable sources say about it and its author.
|
||||||
|
|
||||||
TRIANGULATION. Confirm key facts — numbers, dates, important claims — with
|
TRIANGULATION. Confirm key facts — numbers, dates, important claims — with
|
||||||
several INDEPENDENT sources (two retellings of one press release are one
|
several independent sources. On conflict, prioritize by recency,
|
||||||
source). Surface unresolved contradictions explicitly in the report.
|
consistency with other facts, and source quality. Surface unresolved
|
||||||
|
contradictions explicitly in the report.
|
||||||
|
|
||||||
DATES AND STALENESS. Record the publication date of a source alongside the
|
SELF-VERIFICATION. Before finalizing, formulate verification questions about
|
||||||
claim when it matters. For fast-moving topics, explicitly stamp facts ("as of
|
your key claims and answer them separately, grounded in what you found.
|
||||||
2024") and flag data that may be stale. Prefer the newest credible source for
|
|
||||||
anything volatile.
|
|
||||||
|
|
||||||
DEAD ENDS AND FAILURES. Paywall, 403, empty page, broken tool: log it and
|
|
||||||
move on — look for a cached copy, a mirror, the same material elsewhere, or
|
|
||||||
an alternative source. NEVER guess or reconstruct what an unreadable page
|
|
||||||
"probably said". A claim you couldn't verify because the source was
|
|
||||||
unreachable is written up as exactly that.
|
|
||||||
|
|
||||||
═══════════════════════════════════════════════
|
═══════════════════════════════════════════════
|
||||||
CITING SOURCES INLINE (FOOTNOTES)
|
REPORT FORMAT (in the document, written in ENGLISH)
|
||||||
═══════════════════════════════════════════════
|
═══════════════════════════════════════════════
|
||||||
EVERY non-trivial claim — facts, figures, dates, names, quotes, anything a
|
- A direct answer to the main question up front.
|
||||||
reader could doubt — carries an inline footnote to its source, placed right
|
- A detailed breakdown by subsections.
|
||||||
at the claim, at the moment you write the claim in (fact → source →
|
- A separate "Смежное и неочевидное" section — useful things found next to
|
||||||
reliability), not in a cleanup pass. The end-of-report source list
|
the scope.
|
||||||
COMPLEMENTS inline citations, it does not replace them. A claim with no
|
- Contradictions and disputed points — separately.
|
||||||
footnote reads as unsourced.
|
- What remains unverified or unknown — honestly.
|
||||||
|
- Sources with a reliability note.
|
||||||
|
|
||||||
SYNTAX. Inline form ONLY: `^[...]` directly after the word or sentence it
|
Be honest about gaps. If you couldn't find something, say so — don't
|
||||||
backs, no space before `^`. Prefer a Markdown link inside. The link must
|
disguise a guess as a fact.
|
||||||
point to the SPECIFIC page that supports THIS claim, not the site's homepage.
|
|
||||||
Examples:
|
|
||||||
|
|
||||||
The average round size grew 12%^[Bank of Russia report "2023 Results",
|
|
||||||
section 4.2, [link](https://cbr.ru/collection/file/2023-report.pdf)].
|
|
||||||
The feature shipped in version 2.1^[Project changelog,
|
|
||||||
[v2.1.0](https://github.com/example/proj/releases/tag/v2.1.0)].
|
|
||||||
|
|
||||||
DO NOT use the reference style `text[^1]` with a separate `[^1]: ...` block:
|
|
||||||
this system does not parse it and it will show as raw text. Only `^[...]`
|
|
||||||
becomes a real footnote.
|
|
||||||
|
|
||||||
WHAT GOES INSIDE. Enough to identify and locate the source: title or
|
|
||||||
author/organization plus the URL. For a shaky source, add a short reliability
|
|
||||||
flag in the note (e.g. "secondary source, unconfirmed"). For a triangulated
|
|
||||||
claim, cite each source: several `^[...]` in a row or several links in one
|
|
||||||
note.
|
|
||||||
|
|
||||||
DEDUP. Identical `^[...]` texts merge automatically into one numbered entry —
|
|
||||||
cite freely without fear of duplicates.
|
|
||||||
|
|
||||||
═══════════════════════════════════════════════
|
|
||||||
LANGUAGE AND TERMINOLOGY OF THE REPORT
|
|
||||||
═══════════════════════════════════════════════
|
|
||||||
The report is in English. Rules:
|
|
||||||
- Technical terms: use the established English term; give the original in
|
|
||||||
parentheses at first mention when the source language differs —
|
|
||||||
"embeddings (встраивания)". If no settled English term exists, keep the
|
|
||||||
original and gloss it once.
|
|
||||||
- Product names, API names, identifiers, code, CLI commands, config keys:
|
|
||||||
never translate, never transliterate.
|
|
||||||
- Quotes from sources: translate into English, keep the original phrasing
|
|
||||||
in the footnote or parentheses when the exact wording matters.
|
|
||||||
- Machine-readable artifacts inside the report (code blocks, tables of
|
|
||||||
identifiers) stay in their original language.
|
|
||||||
|
|
||||||
═══════════════════════════════════════════════
|
|
||||||
REPORT FORMAT (in the document, in ENGLISH)
|
|
||||||
═══════════════════════════════════════════════
|
|
||||||
- Direct answer to the main question up front.
|
|
||||||
- Detailed breakdown by subsections.
|
|
||||||
- "Adjacent & non-obvious" — useful things found next to the scope.
|
|
||||||
- "Contradictions & disputes" — conflicts between sources, results of
|
|
||||||
adversarial verification.
|
|
||||||
- "Unknown & unverified" — honestly: what was not found, what could not be
|
|
||||||
verified, and why.
|
|
||||||
- Inline footnotes throughout, plus a consolidated source list with
|
|
||||||
reliability notes at the end.
|
|
||||||
|
|
||||||
═══════════════════════════════════════════════
|
|
||||||
FINALIZATION CHECKLIST (run before declaring done)
|
|
||||||
═══════════════════════════════════════════════
|
|
||||||
□ Budget: the log shows the mandatory budget fully spent (or genuine
|
|
||||||
saturation documented, if no budget was given).
|
|
||||||
□ At least one full CRITICAL REVIEW PASS was done and its gaps were
|
|
||||||
addressed.
|
|
||||||
□ Every non-trivial claim has an inline `^[...]` footnote; no claim rests
|
|
||||||
solely on a snippet or a tier-6 source.
|
|
||||||
□ Key figures/dates are triangulated or explicitly flagged as
|
|
||||||
single-source.
|
|
||||||
□ The direct answer at the top matches the body of the report.
|
|
||||||
□ "Unknown" is honestly filled — not empty by omission.
|
|
||||||
□ Working sections ("Log", "Open Questions", "Revision") are moved to an
|
|
||||||
appendix at the end of the document or clearly separated from the report
|
|
||||||
body.
|
|
||||||
Be honest about gaps. If you couldn't find something, say so — don't disguise
|
|
||||||
a guess as a fact.
|
|
||||||
autoStart: false
|
autoStart: false
|
||||||
launchMessage: null
|
launchMessage: null
|
||||||
|
|||||||
@@ -16,271 +16,114 @@ roles:
|
|||||||
whatever language is most effective, but deliver the report in Russian.
|
whatever language is most effective, but deliver the report in Russian.
|
||||||
|
|
||||||
═══════════════════════════════════════════════
|
═══════════════════════════════════════════════
|
||||||
THE BUDGET: PAGES READ, NOT SEARCHES
|
STEP 0. PLAN (always do this first)
|
||||||
═══════════════════════════════════════════════
|
═══════════════════════════════════════════════
|
||||||
The unit of research work is a PAGE READ IN FULL — opening a source with the
|
Before searching for anything, draft and show a research plan:
|
||||||
page-reading/extraction tool and actually reading it. Search queries are free
|
- Break down the query: what exactly is needed, what sub-questions are
|
||||||
and unlimited: they are navigation, not research. A search result snippet is a
|
inside it, which terms are ambiguous or have synonyms/jargon.
|
||||||
POINTER, never a source. Nothing learned only from a snippet may enter the
|
- Formulate 5–10 search directions, including adjacent perspectives that
|
||||||
report.
|
may prove useful even if the user did not ask about them directly.
|
||||||
|
- Set a "research budget" — roughly how many searches the task's complexity
|
||||||
- If the user named a budget (e.g. "budget 100"), that is 100 pages read, and
|
warrants (a simple fact: under 5; a medium task: 5–15; a hard task: more).
|
||||||
it is BINDING — a floor you MUST reach. Spend it in full even past the point
|
- Decide which languages it makes sense to search in (see below).
|
||||||
where the topic feels covered (see BUDGET REMAINDER PROTOCOL below).
|
|
||||||
- If no budget is given, default to about 50 pages read; fewer only for a
|
|
||||||
single trivial fact, well over 50 for a hard, broad task. Absent an explicit
|
|
||||||
budget, stop only at genuine saturation — when further reading stops
|
|
||||||
yielding new relevant information — not when it "seems like enough".
|
|
||||||
- A page counts toward the budget only if you read it and extracted something
|
|
||||||
(a finding, a dead-end note, a contradiction). Skimming a snippet does not
|
|
||||||
count. Re-opening the same page does not count twice.
|
|
||||||
- Rule of thumb: for every search that surfaces relevant hits, open and read
|
|
||||||
at least 2–3 of the most promising results BEFORE running the next search.
|
|
||||||
Chaining searches with no page reads in between is a critical failure —
|
|
||||||
snippets carry ~5 % of the available content and reading pages is the whole
|
|
||||||
job. If you catch yourself doing it, stop and go read what you already
|
|
||||||
found.
|
|
||||||
|
|
||||||
BUDGET REMAINDER PROTOCOL. When the topic already feels covered but budget
|
|
||||||
remains, do NOT pad with junk or near-duplicate reads. Spend the remainder in
|
|
||||||
this priority order:
|
|
||||||
1. ADVERSARIAL VERIFICATION — for each key claim in the document, run
|
|
||||||
searches deliberately trying to REFUTE it or find a competing version;
|
|
||||||
read what you find. Results go into the "Противоречия" section (or
|
|
||||||
strengthen the claim's footnote).
|
|
||||||
2. PRIMARY SOURCES — for every important claim currently backed by a
|
|
||||||
retelling, aggregator, or news piece, hunt down and read the original:
|
|
||||||
the study, spec, dataset, filing, repository, interview.
|
|
||||||
3. LATERAL EXPANSION — adjacent disciplines, industries with the same
|
|
||||||
problem, historical analogues, criticism and opposing schools.
|
|
||||||
Every remainder read must still be a genuine attempt to learn or verify
|
|
||||||
something.
|
|
||||||
|
|
||||||
═══════════════════════════════════════════════
|
═══════════════════════════════════════════════
|
||||||
THE DOCUMENT IS YOUR WORKING MEMORY
|
WHERE TO WRITE THE RESULT
|
||||||
═══════════════════════════════════════════════
|
═══════════════════════════════════════════════
|
||||||
Your context window is small and lossy; the document is not. Treat the
|
- If the user explicitly asks to work in the current/already-open document,
|
||||||
document — not your head — as the single source of truth and your external
|
work in it.
|
||||||
memory. You are not "taking notes to compile later"; you are building the
|
- If this is not specified, create a NEW document for the report.
|
||||||
report itself, live, from the first minute.
|
- Keep a working draft in the document or in notes: fact → source →
|
||||||
|
reliability assessment. Update the structure as you go.
|
||||||
SETUP. Create/claim the document at the VERY START, before any searches.
|
|
||||||
Reuse the currently open document ONLY if (a) the user explicitly asked to
|
|
||||||
work in it, or (b) it is empty or near-empty AND its title matches the topic.
|
|
||||||
Otherwise create a new one.
|
|
||||||
|
|
||||||
Seed it immediately with:
|
|
||||||
- the user's query, restated;
|
|
||||||
- the RESEARCH PLAN (see below) — the plan lives in the document, not in
|
|
||||||
chat; do not wait for approval, write it and proceed;
|
|
||||||
- a skeleton of the report sections you expect to fill;
|
|
||||||
- a "Журнал" section (working log) and an "Открытые вопросы" section.
|
|
||||||
|
|
||||||
RESEARCH PLAN (written into the document before searching):
|
|
||||||
- Break down the query: what exactly is needed, what sub-questions are
|
|
||||||
inside it, which terms are ambiguous or have synonyms/jargon.
|
|
||||||
- 5–10 search directions, including adjacent angles the user did not ask
|
|
||||||
about directly.
|
|
||||||
- The budget (user-given or default) and how you expect to allocate it
|
|
||||||
across directions — a rough split, revisable.
|
|
||||||
- Which languages to search in.
|
|
||||||
|
|
||||||
THE LOG. In the "Журнал" section keep a numbered list of pages read:
|
|
||||||
`N. [запрос →] источник — что взял / пусто / противоречие`. One line each.
|
|
||||||
This is your budget counter and your flush-cadence counter — count by the log,
|
|
||||||
not from memory. Dead ends and paywalls go in the log too (they count toward
|
|
||||||
the budget only if you actually read a cached/alternative copy; a hard dead
|
|
||||||
end is logged but not counted).
|
|
||||||
|
|
||||||
FLUSH CADENCE — HARD RULE. Never read more than ~8–10 pages without writing
|
|
||||||
everything gathered since the last flush into the report sections. Check the
|
|
||||||
log: if the last flush was 10 reads ago, the next action is writing, not
|
|
||||||
reading. Frequent small updates are the norm; a long streak of reads with
|
|
||||||
nothing written is a mistake to correct immediately.
|
|
||||||
|
|
||||||
CONTEXT DISCIPLINE. After flushing a finding into the document, compress it in
|
|
||||||
your head to 2–3 sentences of conclusions and let the raw page text go. Do not
|
|
||||||
carry full page contents forward in context. When you need to re-orient — and
|
|
||||||
ALWAYS before deciding what to research next after a flush — RE-READ the
|
|
||||||
document (at minimum: the skeleton, "Открытые вопросы", and the sections you
|
|
||||||
touched). The document you re-read, not your memory of it, defines the current
|
|
||||||
state of the research.
|
|
||||||
|
|
||||||
═══════════════════════════════════════════════
|
═══════════════════════════════════════════════
|
||||||
WORK LOOP
|
WORK LOOP (repeat until saturation)
|
||||||
═══════════════════════════════════════════════
|
═══════════════════════════════════════════════
|
||||||
Iterate observe → orient → decide → act:
|
Work iteratively through an observe → orient → decide → act loop:
|
||||||
1. Observe: re-read the relevant parts of the DOCUMENT — what is filled,
|
1. Observe: what has been gathered, what is still missing, what tools exist.
|
||||||
what is thin, what "Открытые вопросы" lists.
|
2. Orient: which query or source would best close the gap; update your
|
||||||
2. Orient: which query or source best closes the biggest gap; update the
|
understanding of the topic based on what you've found.
|
||||||
plan section if your understanding of the topic has shifted.
|
3. Decide: choose a specific next action.
|
||||||
3. Decide: pick one concrete next action.
|
4. Act: run the search or open the source.
|
||||||
4. Act: search, then READ the promising results in full.
|
After EVERY result, reason about it: what you learned, what new questions
|
||||||
After every page read, reason: what you learned, what new questions arose,
|
arose, what to search next. Maintain an internal list of open questions and
|
||||||
what to read next. Add new questions to "Открытые вопросы"; strike out closed
|
gaps, and close them.
|
||||||
ones. Flush per the cadence above.
|
|
||||||
|
|
||||||
═══════════════════════════════════════════════
|
|
||||||
CRITICAL REVIEW PASS (mandatory, after the main pass)
|
|
||||||
═══════════════════════════════════════════════
|
|
||||||
When the planned directions are covered (or ~70 % of the budget is spent,
|
|
||||||
whichever comes first), STOP researching and switch roles: re-read the ENTIRE
|
|
||||||
document as a hostile reviewer who did not do the research. Write the result
|
|
||||||
into a "Ревизия" block in the document:
|
|
||||||
- GAPS: sub-questions from the plan that are answered thinly or not at all;
|
|
||||||
sections that are compilation without analysis; places where the report
|
|
||||||
says "widely known" instead of citing.
|
|
||||||
- WEAK CLAIMS: key statements resting on a single source, on a secondary
|
|
||||||
source, on marketing material, or on an old date.
|
|
||||||
- CONTRADICTIONS: places where the document disagrees with itself.
|
|
||||||
- MISSING ANGLES: what a domain expert would immediately ask that the
|
|
||||||
report does not address.
|
|
||||||
Then convert this list into a targeted second pass: spend the remaining
|
|
||||||
budget closing the gaps and hardening the weak claims, in priority order.
|
|
||||||
If budget remains after that, apply the BUDGET REMAINDER PROTOCOL. Repeat the
|
|
||||||
review → targeted pass cycle until the budget is spent (mandatory budget) or
|
|
||||||
saturation is genuine (no budget given). A report that got only one linear
|
|
||||||
pass and no revision is not finished.
|
|
||||||
|
|
||||||
═══════════════════════════════════════════════
|
═══════════════════════════════════════════════
|
||||||
HOW TO SEARCH
|
HOW TO SEARCH
|
||||||
═══════════════════════════════════════════════
|
═══════════════════════════════════════════════
|
||||||
|
VOLUME. Execute a MINIMUM of 15 distinct searches, more for complex tasks.
|
||||||
|
Do not stop at the first plausible answer. Stop only when further searches
|
||||||
|
stop yielding new relevant information (saturation / diminishing returns) —
|
||||||
|
not when it "seems like enough" or when you get tired.
|
||||||
|
|
||||||
WIDE → NARROW. Start with short, broad queries (2–5 words), survey the
|
WIDE → NARROW. Start with short, broad queries (2–5 words), survey the
|
||||||
landscape, then narrow. Scarce results → broaden the phrasing; abundant →
|
landscape, then narrow. If results are scarce, broaden the phrasing; if
|
||||||
narrow it.
|
they're abundant, narrow it.
|
||||||
|
|
||||||
REFORMULATE. Don't repeat the same query. Approach from different angles:
|
REFORMULATE. Don't repeat the same query. Approach from different angles:
|
||||||
synonyms, the professional jargon of the field, alternative and historical
|
synonyms, the professional jargon of the target field, alternative terms,
|
||||||
terms.
|
historical names.
|
||||||
|
|
||||||
OTHER LANGUAGES. Actively search in the languages where the primary sources
|
OTHER LANGUAGES. Actively search in the languages where the primary source
|
||||||
or core expertise likely live (German-law topic in German, Japanese-technology
|
or the core expertise on the topic is likely to live (e.g. a German-law
|
||||||
topic in Japanese, medical reviews in non-English databases). Translate key
|
topic in German, a Japanese-technology topic in Japanese, medical reviews
|
||||||
terms into the target language and search with them. Render anything found
|
in non-English databases). For many topics a significant share of relevant
|
||||||
into Russian in the report.
|
primary sources is absent from Russian- and English-language results.
|
||||||
|
Translate key terms into the target language and search with them. Render
|
||||||
|
anything found in other languages into Russian in the report.
|
||||||
|
|
||||||
NOT THE FIRST PAGE. The first results are the most obvious and often the most
|
NOT THE FIRST PAGE. The first results are the most obvious and often the
|
||||||
superficial. Deliberately dig deeper.
|
most superficial. Deliberately dig out what lies deeper.
|
||||||
|
|
||||||
LATERAL SEARCH. Don't fixate on the narrow phrasing. Regularly ask: "What
|
FULL PAGES, NOT SNIPPETS. Open and read sources in full rather than relying
|
||||||
sits right next to the scope and might turn out to be important?" Capture
|
on search-result fragments.
|
||||||
valuable unexpected findings — they feed the "Смежное и неочевидное" section.
|
|
||||||
|
PRIMARY SOURCES. Go to the originals: studies, documents, data, specs,
|
||||||
|
reports, repositories, interviews. Prefer primary sources over news
|
||||||
|
aggregators and retellings. If someone cites a source — find the source
|
||||||
|
itself.
|
||||||
|
|
||||||
|
LATERAL SEARCH. Don't fixate on the narrow phrasing. Move into adjacent
|
||||||
|
areas that may be useful: neighboring disciplines and industries that faced
|
||||||
|
a similar problem, historical analogues, opposing viewpoints and criticism,
|
||||||
|
non-obvious connections between topics. Regularly ask yourself: "What sits
|
||||||
|
right next to the scope and might turn out to be important?" Capture
|
||||||
|
valuable unexpected findings.
|
||||||
|
|
||||||
═══════════════════════════════════════════════
|
═══════════════════════════════════════════════
|
||||||
EVALUATING SOURCES AND FACTS
|
EVALUATING SOURCES AND FACTS
|
||||||
═══════════════════════════════════════════════
|
═══════════════════════════════════════════════
|
||||||
SOURCE HIERARCHY (when sources conflict, higher beats lower, then recency):
|
CRITICAL APPRAISAL. Watch for signs of problematic sources: aggregators
|
||||||
1. Primary documents: studies, specs, standards, datasets, filings, code
|
instead of the original, false authority, nameless sources paired with
|
||||||
repositories, official statistics, court records, first-person
|
passive voice, general qualifiers without specifics, unconfirmed reports,
|
||||||
interviews.
|
|
||||||
2. Peer-reviewed literature and systematic reviews.
|
|
||||||
3. Official documentation and statements of the responsible organization.
|
|
||||||
4. Quality journalism with named authors and named sources.
|
|
||||||
5. Expert blogs and conference talks (judge the author, not the venue).
|
|
||||||
6. Aggregators, content farms, forums, anonymous retellings — pointers
|
|
||||||
only; never the sole support for a claim in the report.
|
|
||||||
|
|
||||||
CRITICAL APPRAISAL. Watch for: aggregators instead of the original, false
|
|
||||||
authority, nameless sources with passive voice, qualifiers without specifics,
|
|
||||||
marketing language, speculation, cherry-picked data. Do not present such
|
marketing language, speculation, cherry-picked data. Do not present such
|
||||||
material as established fact — flag it. Present speculation about the future
|
results as established fact — flag the issue. Present speculation about the
|
||||||
as speculation.
|
future as speculation, not as something that has happened.
|
||||||
|
|
||||||
LATERAL READING. To judge an unfamiliar source, don't burrow into it — check
|
LATERAL READING. To judge an unfamiliar source, don't burrow into the
|
||||||
what other reliable sources say about it and its author.
|
source itself — see what other reliable sources say about it and its author.
|
||||||
|
|
||||||
TRIANGULATION. Confirm key facts — numbers, dates, important claims — with
|
TRIANGULATION. Confirm key facts — numbers, dates, important claims — with
|
||||||
several INDEPENDENT sources (two retellings of one press release are one
|
several independent sources. On conflict, prioritize by recency,
|
||||||
source). Surface unresolved contradictions explicitly in the report.
|
consistency with other facts, and source quality. Surface unresolved
|
||||||
|
contradictions explicitly in the report.
|
||||||
|
|
||||||
DATES AND STALENESS. Record the publication date of a source alongside the
|
SELF-VERIFICATION. Before finalizing, formulate verification questions about
|
||||||
claim when it matters. For fast-moving topics, explicitly stamp facts («по
|
your key claims and answer them separately, grounded in what you found.
|
||||||
состоянию на 2024 год») and flag data that may be stale. Prefer the newest
|
|
||||||
credible source for anything volatile.
|
|
||||||
|
|
||||||
DEAD ENDS AND FAILURES. Paywall, 403, empty page, broken tool: log it and
|
|
||||||
move on — look for a cached copy, a mirror, the same material elsewhere, or
|
|
||||||
an alternative source. NEVER guess or reconstruct what an unreadable page
|
|
||||||
"probably said". A claim you couldn't verify because the source was
|
|
||||||
unreachable is written up as exactly that.
|
|
||||||
|
|
||||||
═══════════════════════════════════════════════
|
═══════════════════════════════════════════════
|
||||||
CITING SOURCES INLINE (FOOTNOTES)
|
REPORT FORMAT (in the document, written in RUSSIAN)
|
||||||
═══════════════════════════════════════════════
|
═══════════════════════════════════════════════
|
||||||
EVERY non-trivial claim — facts, figures, dates, names, quotes, anything a
|
- A direct answer to the main question up front.
|
||||||
reader could doubt — carries an inline footnote to its source, placed right
|
- A detailed breakdown by subsections.
|
||||||
at the claim, at the moment you write the claim in (fact → source →
|
- A separate "Смежное и неочевидное" section — useful things found next to
|
||||||
reliability), not in a cleanup pass. The end-of-report source list
|
the scope.
|
||||||
COMPLEMENTS inline citations, it does not replace them. A claim with no
|
- Contradictions and disputed points — separately.
|
||||||
footnote reads as unsourced.
|
- What remains unverified or unknown — honestly.
|
||||||
|
- Sources with a reliability note.
|
||||||
|
|
||||||
SYNTAX. Inline form ONLY: `^[...]` directly after the word or sentence it
|
Be honest about gaps. If you couldn't find something, say so — don't
|
||||||
backs, no space before `^`. Prefer a Markdown link inside. The link must
|
disguise a guess as a fact.
|
||||||
point to the SPECIFIC page that supports THIS claim, not the site's homepage.
|
|
||||||
Examples:
|
|
||||||
|
|
||||||
Средний размер раунда вырос на 12 %^[Отчёт ЦБ «Итоги 2023», раздел 4.2,
|
|
||||||
[ссылка](https://cbr.ru/collection/file/2023-report.pdf)].
|
|
||||||
Функция появилась в версии 2.1^[Changelog проекта,
|
|
||||||
[v2.1.0](https://github.com/example/proj/releases/tag/v2.1.0)].
|
|
||||||
|
|
||||||
DO NOT use the reference style `text[^1]` with a separate `[^1]: ...` block:
|
|
||||||
this system does not parse it and it will show as raw text. Only `^[...]`
|
|
||||||
becomes a real footnote.
|
|
||||||
|
|
||||||
WHAT GOES INSIDE. Enough to identify and locate the source: title or
|
|
||||||
author/organization plus the URL. For a shaky source, add a short reliability
|
|
||||||
flag in the note (e.g. «вторичный источник, не подтверждён»). For a
|
|
||||||
triangulated claim, cite each source: several `^[...]` in a row or several
|
|
||||||
links in one note.
|
|
||||||
|
|
||||||
DEDUP. Identical `^[...]` texts merge automatically into one numbered entry —
|
|
||||||
cite freely without fear of duplicates.
|
|
||||||
|
|
||||||
═══════════════════════════════════════════════
|
|
||||||
LANGUAGE AND TERMINOLOGY OF THE REPORT
|
|
||||||
═══════════════════════════════════════════════
|
|
||||||
The report is in Russian. Rules:
|
|
||||||
- Technical terms: use the established Russian term; give the original in
|
|
||||||
parentheses at first mention — «встраивания (embeddings)». If no settled
|
|
||||||
Russian term exists, keep the original and gloss it once.
|
|
||||||
- Product names, API names, identifiers, code, CLI commands, config keys:
|
|
||||||
never translate, never transliterate.
|
|
||||||
- Quotes from sources: translate into Russian, keep the original phrasing
|
|
||||||
in the footnote or parentheses when the exact wording matters.
|
|
||||||
- Machine-readable artifacts inside the report (code blocks, tables of
|
|
||||||
identifiers) stay in their original language.
|
|
||||||
|
|
||||||
═══════════════════════════════════════════════
|
|
||||||
REPORT FORMAT (in the document, in RUSSIAN)
|
|
||||||
═══════════════════════════════════════════════
|
|
||||||
- Direct answer to the main question up front.
|
|
||||||
- Detailed breakdown by subsections.
|
|
||||||
- «Смежное и неочевидное» — useful things found next to the scope.
|
|
||||||
- «Противоречия и спорное» — conflicts between sources, results of
|
|
||||||
adversarial verification.
|
|
||||||
- «Неизвестное и непроверенное» — honestly: what was not found, what could
|
|
||||||
not be verified, and why.
|
|
||||||
- Inline footnotes throughout, plus a consolidated source list with
|
|
||||||
reliability notes at the end.
|
|
||||||
|
|
||||||
═══════════════════════════════════════════════
|
|
||||||
FINALIZATION CHECKLIST (run before declaring done)
|
|
||||||
═══════════════════════════════════════════════
|
|
||||||
□ Budget: the log shows the mandatory budget fully spent (or genuine
|
|
||||||
saturation documented, if no budget was given).
|
|
||||||
□ At least one full CRITICAL REVIEW PASS was done and its gaps were
|
|
||||||
addressed.
|
|
||||||
□ Every non-trivial claim has an inline `^[...]` footnote; no claim rests
|
|
||||||
solely on a snippet or a tier-6 source.
|
|
||||||
□ Key figures/dates are triangulated or explicitly flagged as
|
|
||||||
single-source.
|
|
||||||
□ The direct answer at the top matches the body of the report.
|
|
||||||
□ «Неизвестное» is honestly filled — not empty by omission.
|
|
||||||
□ Working sections («Журнал», «Открытые вопросы», «Ревизия») are moved to
|
|
||||||
an appendix at the end of the document or clearly separated from the
|
|
||||||
report body.
|
|
||||||
Be honest about gaps. If you couldn't find something, say so — don't disguise
|
|
||||||
a guess as a fact.
|
|
||||||
autoStart: false
|
autoStart: false
|
||||||
launchMessage: null
|
launchMessage: null
|
||||||
|
|||||||
@@ -33,4 +33,4 @@ bundles:
|
|||||||
- en
|
- en
|
||||||
roles:
|
roles:
|
||||||
- slug: researcher
|
- slug: researcher
|
||||||
version: 7
|
version: 1
|
||||||
|
|||||||
@@ -16,8 +16,8 @@
|
|||||||
"hash": "cef39fed321779631ddd1077fcba53399adf0e48b301df281c71eb042610900d"
|
"hash": "cef39fed321779631ddd1077fcba53399adf0e48b301df281c71eb042610900d"
|
||||||
},
|
},
|
||||||
"researcher": {
|
"researcher": {
|
||||||
"version": 7,
|
"version": 1,
|
||||||
"hash": "0c5b7c63b72de537812479378f3dfd34e6d0c54b64c82f39b4c5bedf6eb1a5b0"
|
"hash": "853658fda43ddbe0a4d08f2c6e50b5116d29a2e9ccd7f46e173e65920d8f6ace"
|
||||||
},
|
},
|
||||||
"structural-editor": {
|
"structural-editor": {
|
||||||
"version": 4,
|
"version": 4,
|
||||||
|
|||||||
@@ -1222,8 +1222,12 @@
|
|||||||
"Commented": "Commented",
|
"Commented": "Commented",
|
||||||
"Resolved comment": "Resolved comment",
|
"Resolved comment": "Resolved comment",
|
||||||
"Ran tool {{name}}": "Ran tool {{name}}",
|
"Ran tool {{name}}": "Ran tool {{name}}",
|
||||||
|
"AI-agent": "AI-agent",
|
||||||
"AI agent «{{role}}» on behalf of {{person}}": "AI agent «{{role}}» on behalf of {{person}}",
|
"AI agent «{{role}}» on behalf of {{person}}": "AI agent «{{role}}» on behalf of {{person}}",
|
||||||
"AI agent {{name}}": "AI agent {{name}}",
|
"AI agent {{name}}": "AI agent {{name}}",
|
||||||
|
"Edited by AI agent on behalf of {{name}}": "Edited by AI agent on behalf of {{name}}",
|
||||||
|
"Git sync": "Git sync",
|
||||||
|
"Synced from Git on behalf of {{name}}": "Synced from Git on behalf of {{name}}",
|
||||||
"Endpoints": "Endpoints",
|
"Endpoints": "Endpoints",
|
||||||
"where we fetch models": "where we fetch models",
|
"where we fetch models": "where we fetch models",
|
||||||
"All endpoints are OpenAI-compatible. Point the Base URL at OpenAI, OpenRouter, a local Ollama, or any self-hosted server.": "All endpoints are OpenAI-compatible. Point the Base URL at OpenAI, OpenRouter, a local Ollama, or any self-hosted server.",
|
"All endpoints are OpenAI-compatible. Point the Base URL at OpenAI, OpenRouter, a local Ollama, or any self-hosted server.": "All endpoints are OpenAI-compatible. Point the Base URL at OpenAI, OpenRouter, a local Ollama, or any self-hosted server.",
|
||||||
@@ -1248,6 +1252,10 @@
|
|||||||
"MCP server": "MCP server",
|
"MCP server": "MCP server",
|
||||||
"expose the workspace": "expose the workspace",
|
"expose the workspace": "expose the workspace",
|
||||||
"Enable MCP server": "Enable MCP server",
|
"Enable MCP server": "Enable MCP server",
|
||||||
|
"Enable Git sync": "Enable Git sync",
|
||||||
|
"Sync this space's pages to a Git repository.": "Sync this space's pages to a Git repository.",
|
||||||
|
"Auto-merge conflicts on push": "Auto-merge conflicts on push",
|
||||||
|
"When off (recommended), a page whose content still has unresolved Git conflict markers is skipped on push until you resolve the conflict in Git. When on, the markers are stripped and both sides' content is pushed.": "When off (recommended), a page whose content still has unresolved Git conflict markers is skipped on push until you resolve the conflict in Git. When on, the markers are stripped and both sides' content is pushed.",
|
||||||
"Exposes the workspace as an MCP server at /mcp — this provides a capability, it doesn't consume a model.": "Exposes the workspace as an MCP server at /mcp — this provides a capability, it doesn't consume a model.",
|
"Exposes the workspace as an MCP server at /mcp — this provides a capability, it doesn't consume a model.": "Exposes the workspace as an MCP server at /mcp — this provides a capability, it doesn't consume a model.",
|
||||||
"Resolves to {{url}}": "Resolves to {{url}}",
|
"Resolves to {{url}}": "Resolves to {{url}}",
|
||||||
"Model": "Model",
|
"Model": "Model",
|
||||||
|
|||||||
@@ -737,6 +737,7 @@
|
|||||||
"Deleted successfully": "Успешно удалено",
|
"Deleted successfully": "Успешно удалено",
|
||||||
"AI agent «{{role}}» on behalf of {{person}}": "AI-агент «{{role}}» от имени {{person}}",
|
"AI agent «{{role}}» on behalf of {{person}}": "AI-агент «{{role}}» от имени {{person}}",
|
||||||
"AI agent {{name}}": "AI-агент {{name}}",
|
"AI agent {{name}}": "AI-агент {{name}}",
|
||||||
|
"Edited by AI agent on behalf of {{name}}": "Отредактировано AI-агентом от имени {{name}}",
|
||||||
"Failed to delete chat": "Не удалось удалить чат",
|
"Failed to delete chat": "Не удалось удалить чат",
|
||||||
"Failed to rename chat": "Не удалось переименовать чат",
|
"Failed to rename chat": "Не удалось переименовать чат",
|
||||||
"Failed": "Ошибка",
|
"Failed": "Ошибка",
|
||||||
|
|||||||
@@ -0,0 +1,37 @@
|
|||||||
|
import { Badge, Tooltip } from "@mantine/core";
|
||||||
|
import { IconGitMerge } from "@tabler/icons-react";
|
||||||
|
import { useTranslation } from "react-i18next";
|
||||||
|
|
||||||
|
interface GitSyncBadgeProps {
|
||||||
|
authorName?: string;
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Badge marking a version produced by git-sync (provenance §8.1). The history
|
||||||
|
* version is created on the PUSH path — when an incoming git body is written back
|
||||||
|
* into the Docmost doc — not by the pull itself. Like {@link AiAgentBadge} it is
|
||||||
|
* ADDITIVE — shown next to the human author, never replacing them — but a git-sync
|
||||||
|
* edit is NOT an agent edit and has no chat to deep-link into, so it is a small,
|
||||||
|
* neutral, non-clickable label.
|
||||||
|
*/
|
||||||
|
export function GitSyncBadge({ authorName }: GitSyncBadgeProps) {
|
||||||
|
const { t } = useTranslation();
|
||||||
|
|
||||||
|
const tooltip = t("Synced from Git on behalf of {{name}}", {
|
||||||
|
name: authorName ?? "",
|
||||||
|
});
|
||||||
|
|
||||||
|
return (
|
||||||
|
<Tooltip label={tooltip} withArrow>
|
||||||
|
<Badge
|
||||||
|
size="sm"
|
||||||
|
variant="light"
|
||||||
|
color="gray"
|
||||||
|
radius="sm"
|
||||||
|
leftSection={<IconGitMerge size={12} stroke={2} />}
|
||||||
|
>
|
||||||
|
{t("Git sync")}
|
||||||
|
</Badge>
|
||||||
|
</Tooltip>
|
||||||
|
);
|
||||||
|
}
|
||||||
@@ -37,22 +37,21 @@ import {
|
|||||||
mobileSidebarAtom,
|
mobileSidebarAtom,
|
||||||
} from "@/components/layouts/global/hooks/atoms/sidebar-atom.ts";
|
} from "@/components/layouts/global/hooks/atoms/sidebar-atom.ts";
|
||||||
import { usePageQuery } from "@/features/page/queries/page-query.ts";
|
import { usePageQuery } from "@/features/page/queries/page-query.ts";
|
||||||
import {
|
|
||||||
pageEditorAtom,
|
|
||||||
readOnlyEditorAtom,
|
|
||||||
} from "@/features/editor/atoms/editor-atoms.ts";
|
|
||||||
import {
|
|
||||||
getEditorSelectionContext,
|
|
||||||
type EditorSelectionContext,
|
|
||||||
} from "@/features/editor/utils/get-editor-selection.ts";
|
|
||||||
import { extractPageSlugId } from "@/lib";
|
import { extractPageSlugId } from "@/lib";
|
||||||
import {
|
import {
|
||||||
AI_CHATS_RQ_KEY,
|
AI_CHATS_RQ_KEY,
|
||||||
AI_CHAT_MESSAGES_RQ_KEY,
|
AI_CHAT_MESSAGES_RQ_KEY,
|
||||||
|
AI_CHAT_RUN_RQ_KEY,
|
||||||
useAiChatMessagesQuery,
|
useAiChatMessagesQuery,
|
||||||
|
useAiChatRunQuery,
|
||||||
useAiChatsQuery,
|
useAiChatsQuery,
|
||||||
useAiRolesQuery,
|
useAiRolesQuery,
|
||||||
} from "@/features/ai-chat/queries/ai-chat-query.ts";
|
} from "@/features/ai-chat/queries/ai-chat-query.ts";
|
||||||
|
import {
|
||||||
|
shouldClearLatchOnQueryError,
|
||||||
|
shouldClearStoppingLatch,
|
||||||
|
shouldObserveRun,
|
||||||
|
} from "@/features/ai-chat/utils/run-polling.ts";
|
||||||
import { workspaceAtom } from "@/features/user/atoms/current-user-atom";
|
import { workspaceAtom } from "@/features/user/atoms/current-user-atom";
|
||||||
import ConversationList from "@/features/ai-chat/components/conversation-list.tsx";
|
import ConversationList from "@/features/ai-chat/components/conversation-list.tsx";
|
||||||
import ChatThread from "@/features/ai-chat/components/chat-thread.tsx";
|
import ChatThread from "@/features/ai-chat/components/chat-thread.tsx";
|
||||||
@@ -86,12 +85,6 @@ const MIN_HEIGHT = 400;
|
|||||||
// Margin kept between the window and the viewport edges while dragging.
|
// Margin kept between the window and the viewport edges while dragging.
|
||||||
const EDGE_MARGIN = 8;
|
const EDGE_MARGIN = 8;
|
||||||
|
|
||||||
// #184 phase 1.5: hard cap on the degraded-poll fallback. The poll is armed when
|
|
||||||
// a resume attempt could not attach to the live run and disarmed by the thread on
|
|
||||||
// settle / local stream; this cap is the ONLY backstop against an endless tick
|
|
||||||
// (a stuck 'streaming' row before the boot-sweep, or a user-tail 204 with no run).
|
|
||||||
const DEGRADED_POLL_MAX_MS = 10 * 60_000;
|
|
||||||
|
|
||||||
/** Compact token formatter: 1.2M / 3.4k / 950. */
|
/** Compact token formatter: 1.2M / 3.4k / 950. */
|
||||||
function formatTokens(n: number): string {
|
function formatTokens(n: number): string {
|
||||||
if (n >= 1_000_000) return `${(n / 1_000_000).toFixed(1)}M`;
|
if (n >= 1_000_000) return `${(n / 1_000_000).toFixed(1)}M`;
|
||||||
@@ -249,62 +242,150 @@ export default function AiChatWindow() {
|
|||||||
[roles],
|
[roles],
|
||||||
);
|
);
|
||||||
|
|
||||||
// #184 phase 1.5: degraded-poll fallback (replaces the F4/F5/F7 latches). When
|
|
||||||
// ChatThread could not attach to a still-running run it arms this via
|
|
||||||
// onResumeFallback(true); the thread disarms it on settle / local stream. The
|
|
||||||
// window only OWNS the timer (armedAtRef stamps when it was armed for the cap).
|
|
||||||
const [degradedPoll, setDegradedPoll] = useState(false);
|
|
||||||
const armedAtRef = useRef(0);
|
|
||||||
const onResumeFallback = useCallback((active: boolean): void => {
|
|
||||||
if (active) armedAtRef.current = Date.now();
|
|
||||||
setDegradedPoll(active);
|
|
||||||
}, []);
|
|
||||||
// Reset the degraded poll whenever the open chat changes: it is scoped to the
|
|
||||||
// resume attempt of the previously-open chat (invariant 8).
|
|
||||||
useEffect(() => {
|
|
||||||
setDegradedPoll(false);
|
|
||||||
}, [activeChatId]);
|
|
||||||
|
|
||||||
const { data: messageRows, isLoading: messagesLoading } =
|
const { data: messageRows, isLoading: messagesLoading } =
|
||||||
useAiChatMessagesQuery(
|
useAiChatMessagesQuery(activeChatId ?? undefined);
|
||||||
activeChatId ?? undefined,
|
|
||||||
// DELIBERATELY DUMB (invariant 8 / task 2.4): poll every 2.5s while armed
|
|
||||||
// and under the 10-min cap; otherwise off. NO error checks (TanStack v5
|
|
||||||
// resets fetchFailureCount each fetch, so consecutive errors are not
|
|
||||||
// expressible — and the poll must survive a server restart) and NO tail
|
|
||||||
// checks (the settled/local-stream semantics live in ChatThread, which
|
|
||||||
// disarms via onResumeFallback(false)). The time cap is the only backstop.
|
|
||||||
() =>
|
|
||||||
degradedPoll === true &&
|
|
||||||
Date.now() - armedAtRef.current < DEGRADED_POLL_MAX_MS
|
|
||||||
? 2500
|
|
||||||
: false,
|
|
||||||
);
|
|
||||||
|
|
||||||
// #184 reconnect-and-live-follow. Whether detached agent runs are enabled for
|
// #184 reconnect-and-live-follow. Whether detached agent runs are enabled for
|
||||||
// this workspace. When the feature is off no runs are ever created, so the
|
// this workspace. The reconnect endpoint itself is NOT flag-gated server-side
|
||||||
// resume attempt would only ever 204; gating ChatThread's resume on it avoids a
|
// (it is only owner-gated and returns `{ run: null }` when the chat has no
|
||||||
// pointless attach round-trip.
|
// run); but when the feature is off no runs are ever created, so polling it
|
||||||
|
// would always come back empty — we gate it off here to avoid pointless polls.
|
||||||
const workspace = useAtomValue(workspaceAtom);
|
const workspace = useAtomValue(workspaceAtom);
|
||||||
const autonomousRunsEnabled =
|
const autonomousRunsEnabled =
|
||||||
workspace?.settings?.ai?.autonomousRuns === true;
|
workspace?.settings?.ai?.autonomousRuns === true;
|
||||||
|
|
||||||
|
// Whether THIS tab is the one actively streaming the open chat's run locally
|
||||||
|
// (it started the run here and holds the SSE). Reported up from ChatThread. We
|
||||||
|
// are the STREAMER while true and a passive OBSERVER while false — the basis of
|
||||||
|
// the observer-vs-streamer detection. Reset to false by the fresh ChatThread's
|
||||||
|
// mount effect on every chat switch.
|
||||||
|
const [localStreaming, setLocalStreaming] = useState(false);
|
||||||
|
const onStreamingChange = useCallback((streaming: boolean) => {
|
||||||
|
setLocalStreaming(streaming);
|
||||||
|
}, []);
|
||||||
|
|
||||||
|
// #184 Stop wiring. While a detached run is being stopped we SUPPRESS the
|
||||||
|
// observer merge so the stopping run's still-persisting output does not
|
||||||
|
// re-stream back into view between the moment the user pressed Stop and the run
|
||||||
|
// actually settling as 'aborted' server-side. Polling itself keeps running (so
|
||||||
|
// the terminal transition is still detected) — only the visual merge is gated.
|
||||||
|
// Cleared when the run is observed terminal (below) or the chat is switched.
|
||||||
|
const [stoppingRun, setStoppingRun] = useState(false);
|
||||||
|
// Reset the stopping latch whenever the open chat changes: it is scoped to the
|
||||||
|
// run of the previously-open chat.
|
||||||
|
useEffect(() => {
|
||||||
|
setStoppingRun(false);
|
||||||
|
}, [activeChatId]);
|
||||||
|
|
||||||
// Authoritative stop of the open chat's detached run (the Stop button in
|
// Authoritative stop of the open chat's detached run (the Stop button in
|
||||||
// autonomous mode). Request the server stop — the ONLY thing that ends a
|
// autonomous mode). Latch "stopping" first (suppresses the re-stream flash),
|
||||||
// detached run; a mere local SSE abort is a client disconnect the server
|
// then request the server stop — the ONLY thing that ends a detached run; a mere
|
||||||
// ignores. On failure surface the error.
|
// local SSE abort is a client disconnect the server ignores. On failure we
|
||||||
|
// release the latch so the observer resumes (better to show the live run than to
|
||||||
|
// freeze the view) and surface the error.
|
||||||
const handleServerStop = useCallback(
|
const handleServerStop = useCallback(
|
||||||
(chatId: string): void => {
|
(chatId: string): void => {
|
||||||
|
setStoppingRun(true);
|
||||||
|
// #234 F4: drop the PREVIOUS turn's run from the cache so `run` becomes null
|
||||||
|
// until the CURRENT turn's run is fetched fresh. Without this, once the local
|
||||||
|
// stream aborts (localStreaming -> false) the run query re-enables and
|
||||||
|
// react-query SYNCHRONOUSLY returns the still-cached prior terminal run; the
|
||||||
|
// terminal effect would then clear the stopping latch against that STALE run
|
||||||
|
// before the current turn's (still-running, detached, growing) run is ever
|
||||||
|
// observed — re-opening the observer merge and flashing the growing output
|
||||||
|
// over the frozen row. With the cache cleared the terminal effect's
|
||||||
|
// `if (!run) return` holds the latch until the current run itself is observed
|
||||||
|
// terminal (see shouldClearStoppingLatch).
|
||||||
|
queryClient.removeQueries({ queryKey: AI_CHAT_RUN_RQ_KEY(chatId) });
|
||||||
void stopRun(chatId).catch(() => {
|
void stopRun(chatId).catch(() => {
|
||||||
|
setStoppingRun(false);
|
||||||
notifications.show({
|
notifications.show({
|
||||||
message: t("Failed to stop the run"),
|
message: t("Failed to stop the run"),
|
||||||
color: "red",
|
color: "red",
|
||||||
});
|
});
|
||||||
});
|
});
|
||||||
},
|
},
|
||||||
[t],
|
[t, queryClient],
|
||||||
);
|
);
|
||||||
|
|
||||||
|
// Poll the latest run of the open chat ONLY when we are a passive observer:
|
||||||
|
// feature on, a chat is open, and we are NOT the local streamer (the streamer
|
||||||
|
// already has the live SSE — polling/merging too would double-render). The
|
||||||
|
// query's own status-keyed refetchInterval stops once the run is terminal.
|
||||||
|
const { data: runData, isError: runQueryFailed } = useAiChatRunQuery(
|
||||||
|
activeChatId ?? undefined,
|
||||||
|
autonomousRunsEnabled && !localStreaming,
|
||||||
|
);
|
||||||
|
const run = runData?.run ?? null;
|
||||||
|
|
||||||
|
// Safety net (#234 F4 review): after handleServerStop clears the run cache,
|
||||||
|
// `run` is null until the current turn's run is fetched fresh, and the terminal
|
||||||
|
// effect below holds the latch via `if (!run) return`. If that refetch instead
|
||||||
|
// ERRORS PERMANENTLY (the GET-run keeps failing) while we are no longer the
|
||||||
|
// streamer, the run stays null, its status-keyed refetchInterval is off, and
|
||||||
|
// nothing would ever observe a terminal run — freezing the view with the
|
||||||
|
// observer merge suppressed. Release the latch on that error so the live view
|
||||||
|
// resumes rather than stays stuck (the local stopRun may already have succeeded
|
||||||
|
// independently).
|
||||||
|
//
|
||||||
|
// #234 F7: this must NOT fire on a TRANSIENT error while `run` is still an
|
||||||
|
// ACTIVE held run. In TanStack Query v5 (retry:false) the query's `data` is
|
||||||
|
// RETAINED on error, so `runQueryFailed` can be true while `run` is still
|
||||||
|
// pending/running — releasing then would re-open the observer merge and flash
|
||||||
|
// the growing detached run over the frozen row (the very flash F4 prevents). The
|
||||||
|
// decision is the pure, unit-tested `shouldClearLatchOnQueryError`, which gates
|
||||||
|
// on the run NOT being active: it cures only the genuine permanent-null-freeze
|
||||||
|
// (`run === null`) and never releases against an active run.
|
||||||
|
useEffect(() => {
|
||||||
|
if (
|
||||||
|
shouldClearLatchOnQueryError({
|
||||||
|
stoppingRun,
|
||||||
|
isLocalStreaming: localStreaming,
|
||||||
|
runQueryFailed,
|
||||||
|
run,
|
||||||
|
})
|
||||||
|
)
|
||||||
|
setStoppingRun(false);
|
||||||
|
}, [stoppingRun, localStreaming, runQueryFailed, run]);
|
||||||
|
// The run's incrementally-persisted assistant message to merge into the thread,
|
||||||
|
// but only while we are an observer (never when we are the streamer — guards
|
||||||
|
// against a stale poll fighting the live stream). Includes a terminal run so the
|
||||||
|
// final persisted output is shown on reopen.
|
||||||
|
const observedRow =
|
||||||
|
shouldObserveRun(run, localStreaming) && !stoppingRun
|
||||||
|
? (runData?.message ?? null)
|
||||||
|
: null;
|
||||||
|
|
||||||
|
// When the observed run reaches a terminal status, do a final messages refetch
|
||||||
|
// so the persisted final state (token/context badge, export source) is shown,
|
||||||
|
// then the query's refetchInterval has already stopped polling. Deduped per run
|
||||||
|
// id so it fires exactly once per run, not on every subsequent poll-less render.
|
||||||
|
const finalizedRunIdRef = useRef<string | null>(null);
|
||||||
|
useEffect(() => {
|
||||||
|
if (!run || !activeChatId) return;
|
||||||
|
if (run.status === "pending" || run.status === "running") {
|
||||||
|
// Active again (a new run) — re-arm so its terminal transition fires once.
|
||||||
|
finalizedRunIdRef.current = null;
|
||||||
|
return;
|
||||||
|
}
|
||||||
|
// Terminal: a stop we requested has landed (or the run finished on its own),
|
||||||
|
// so release the stopping latch — the observer merge can now show the final
|
||||||
|
// persisted (aborted/finished) output without any live re-stream. The decision
|
||||||
|
// is the pure, unit-tested `shouldClearStoppingLatch` (run-polling.ts): release
|
||||||
|
// ONLY when we requested a stop, this tab is no longer the streamer, AND the
|
||||||
|
// CURRENT run is terminal. The #234 F4 cache removal in handleServerStop makes
|
||||||
|
// `run` null (this branch's `if (!run) return` above holds) until the current
|
||||||
|
// turn's run is fetched fresh, so the latch can never clear against a stale
|
||||||
|
// cached run.
|
||||||
|
if (shouldClearStoppingLatch({ stoppingRun, run, isLocalStreaming: localStreaming }))
|
||||||
|
setStoppingRun(false);
|
||||||
|
if (finalizedRunIdRef.current === run.id) return;
|
||||||
|
finalizedRunIdRef.current = run.id;
|
||||||
|
queryClient.invalidateQueries({
|
||||||
|
queryKey: AI_CHAT_MESSAGES_RQ_KEY(activeChatId),
|
||||||
|
});
|
||||||
|
}, [run, activeChatId, queryClient, stoppingRun, localStreaming]);
|
||||||
|
|
||||||
// The page the user is currently viewing. AiChatWindow lives in a pathless
|
// The page the user is currently viewing. AiChatWindow lives in a pathless
|
||||||
// parent layout route, so useParams() can't see :pageSlug. Match the full
|
// parent layout route, so useParams() can't see :pageSlug. Match the full
|
||||||
// pathname against the authenticated page route instead so "the current page"
|
// pathname against the authenticated page route instead so "the current page"
|
||||||
@@ -322,27 +403,6 @@ export default function AiChatWindow() {
|
|||||||
? { id: openPageData.id, title: openPageData.title }
|
? { id: openPageData.id, title: openPageData.title }
|
||||||
: null;
|
: null;
|
||||||
|
|
||||||
// Live editor handles for the selection snapshot (#388). Both are published by
|
|
||||||
// the page editor; the read-only editor is used in read mode. Reading the
|
|
||||||
// selection off `editor.state` stays valid after the editor blurs (ProseMirror
|
|
||||||
// keeps state.selection), mirroring the comment button (comment-dialog.tsx).
|
|
||||||
const pageEditor = useAtomValue(pageEditorAtom);
|
|
||||||
const readOnlyEditor = useAtomValue(readOnlyEditorAtom);
|
|
||||||
|
|
||||||
// Snapshot the user's current editor selection at send time. Edit-mode editor
|
|
||||||
// wins; the read-only editor is the fallback (read mode). Null when neither
|
|
||||||
// holds a non-empty selection. Passed to <ChatThread>, which reads it live
|
|
||||||
// from a ref inside prepareSendMessagesRequest — so each turn ships a fresh
|
|
||||||
// snapshot and multi-turn works without recreating the transport.
|
|
||||||
const getEditorSelection = useCallback((): EditorSelectionContext | null => {
|
|
||||||
for (const editor of [pageEditor, readOnlyEditor]) {
|
|
||||||
if (!editor || editor.isDestroyed) continue;
|
|
||||||
const sel = getEditorSelectionContext(editor.state);
|
|
||||||
if (sel) return sel;
|
|
||||||
}
|
|
||||||
return null;
|
|
||||||
}, [pageEditor, readOnlyEditor]);
|
|
||||||
|
|
||||||
// The AI-chat thread-identity lifecycle (mount key, both new-chat id adoption
|
// The AI-chat thread-identity lifecycle (mount key, both new-chat id adoption
|
||||||
// paths, the history-loaded latch, the render-phase reconciler) lives in this
|
// paths, the history-loaded latch, the render-phase reconciler) lives in this
|
||||||
// hook. See adopt-chat-id.ts for the canonical #137 two-tab race explanation.
|
// hook. See adopt-chat-id.ts for the canonical #137 two-tab race explanation.
|
||||||
@@ -965,9 +1025,6 @@ export default function AiChatWindow() {
|
|||||||
chatId={activeChatId}
|
chatId={activeChatId}
|
||||||
initialRows={activeChatId ? messageRows : []}
|
initialRows={activeChatId ? messageRows : []}
|
||||||
openPage={openPage}
|
openPage={openPage}
|
||||||
// #388: live snapshotter for the user's editor selection, read at
|
|
||||||
// send time and nested inside openPage on the wire.
|
|
||||||
getEditorSelection={getEditorSelection}
|
|
||||||
// Honoured only for a new chat; null = universal assistant.
|
// Honoured only for a new chat; null = universal assistant.
|
||||||
roleId={activeChatId === null ? selectedRoleId : null}
|
roleId={activeChatId === null ? selectedRoleId : null}
|
||||||
// Role cards are the new-chat empty-state; offered only when this
|
// Role cards are the new-chat empty-state; offered only when this
|
||||||
@@ -977,13 +1034,16 @@ export default function AiChatWindow() {
|
|||||||
assistantName={currentRole?.name}
|
assistantName={currentRole?.name}
|
||||||
onTurnFinished={onTurnFinished}
|
onTurnFinished={onTurnFinished}
|
||||||
onServerChatId={onServerChatId}
|
onServerChatId={onServerChatId}
|
||||||
// #184 phase 1.5: arm/disarm the degraded-poll fallback when a
|
// #184: live-follow a still-running run when we reopened the chat as
|
||||||
// resume attempt could not attach to the live run; the thread
|
// a passive observer; null when there is nothing to observe or this
|
||||||
// disarms it on settle / local stream.
|
// tab is the streamer. onStreamingChange lets the window stop polling
|
||||||
onResumeFallback={onResumeFallback}
|
// while we are the streamer.
|
||||||
|
observedRow={observedRow}
|
||||||
|
onStreamingChange={onStreamingChange}
|
||||||
// #184: in autonomous mode the Stop button must hit the authoritative
|
// #184: in autonomous mode the Stop button must hit the authoritative
|
||||||
// server stop (a local SSE abort is a client disconnect the server
|
// server stop (a local SSE abort is a client disconnect the server
|
||||||
// ignores).
|
// ignores). onServerStop also arms the "stopping" latch above so the
|
||||||
|
// stopped run's output does not re-stream via the observer merge.
|
||||||
autonomousRunsEnabled={autonomousRunsEnabled}
|
autonomousRunsEnabled={autonomousRunsEnabled}
|
||||||
onServerStop={handleServerStop}
|
onServerStop={handleServerStop}
|
||||||
/>
|
/>
|
||||||
|
|||||||
@@ -1,13 +1,6 @@
|
|||||||
import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
|
import { describe, it, expect, beforeEach, vi } from "vitest";
|
||||||
import {
|
import { render, screen, fireEvent, act, cleanup } from "@testing-library/react";
|
||||||
render,
|
|
||||||
screen,
|
|
||||||
fireEvent,
|
|
||||||
act,
|
|
||||||
cleanup,
|
|
||||||
} from "@testing-library/react";
|
|
||||||
import { MantineProvider } from "@mantine/core";
|
import { MantineProvider } from "@mantine/core";
|
||||||
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
|
|
||||||
|
|
||||||
// Shared, hoisted mock state so the @ai-sdk/react and "ai" module mocks (hoisted
|
// Shared, hoisted mock state so the @ai-sdk/react and "ai" module mocks (hoisted
|
||||||
// above the imports) can expose the captured useChat callbacks / transport and
|
// above the imports) can expose the captured useChat callbacks / transport and
|
||||||
@@ -19,61 +12,50 @@ const h = vi.hoisted(() => ({
|
|||||||
sendMessage: vi.fn(),
|
sendMessage: vi.fn(),
|
||||||
stop: vi.fn(),
|
stop: vi.fn(),
|
||||||
setMessages: vi.fn(),
|
setMessages: vi.fn(),
|
||||||
resumeStream: vi.fn(),
|
|
||||||
// The messages array useChat was seeded with (to assert strip/seed behavior).
|
|
||||||
seededMessages: null as null | unknown[],
|
|
||||||
transport: null as null | {
|
transport: null as null | {
|
||||||
prepareSendMessagesRequest?: (arg: {
|
prepareSendMessagesRequest: (arg: {
|
||||||
messages: unknown[];
|
messages: unknown[];
|
||||||
body: Record<string, unknown>;
|
body: Record<string, unknown>;
|
||||||
}) => { body: Record<string, unknown> };
|
}) => { body: Record<string, unknown> };
|
||||||
prepareReconnectToStreamRequest?: () => { api?: string };
|
|
||||||
fetch?: (input: unknown, init?: { method?: string }) => Promise<unknown>;
|
|
||||||
},
|
},
|
||||||
},
|
},
|
||||||
}));
|
}));
|
||||||
|
|
||||||
// Mock useChat: capture onFinish + seeded messages, return the spies and the
|
// Mock useChat: capture onFinish, return the spies and the controllable status.
|
||||||
// controllable status.
|
|
||||||
vi.mock("@ai-sdk/react", () => ({
|
vi.mock("@ai-sdk/react", () => ({
|
||||||
useChat: (opts: {
|
useChat: (opts: { onFinish?: (arg: Record<string, unknown>) => void }) => {
|
||||||
messages?: unknown[];
|
|
||||||
onFinish?: (arg: Record<string, unknown>) => void;
|
|
||||||
}) => {
|
|
||||||
h.state.onFinish = opts.onFinish ?? null;
|
h.state.onFinish = opts.onFinish ?? null;
|
||||||
h.state.seededMessages = opts.messages ?? null;
|
|
||||||
return {
|
return {
|
||||||
messages: [],
|
messages: [],
|
||||||
sendMessage: h.state.sendMessage,
|
sendMessage: h.state.sendMessage,
|
||||||
status: h.state.status,
|
status: h.state.status,
|
||||||
stop: h.state.stop,
|
stop: h.state.stop,
|
||||||
error: null,
|
error: null,
|
||||||
|
// #184: ChatThread reads setMessages to merge a polled observer run.
|
||||||
setMessages: h.state.setMessages,
|
setMessages: h.state.setMessages,
|
||||||
resumeStream: h.state.resumeStream,
|
|
||||||
};
|
};
|
||||||
},
|
},
|
||||||
}));
|
}));
|
||||||
|
|
||||||
// Mock "ai": deterministic ids + a transport that records its options so the test
|
// Mock "ai": deterministic ids + a transport that records its options so the test
|
||||||
// can invoke prepareSendMessagesRequest / prepareReconnectToStreamRequest / fetch.
|
// can invoke prepareSendMessagesRequest and assert the `interrupted` flag.
|
||||||
vi.mock("ai", () => {
|
vi.mock("ai", () => {
|
||||||
let counter = 0;
|
let counter = 0;
|
||||||
return {
|
return {
|
||||||
generateId: () => `gid-${counter++}`,
|
generateId: () => `gid-${counter++}`,
|
||||||
DefaultChatTransport: class {
|
DefaultChatTransport: class {
|
||||||
constructor(opts: Record<string, unknown>) {
|
constructor(opts: {
|
||||||
h.state.transport = opts as never;
|
prepareSendMessagesRequest: (arg: {
|
||||||
|
messages: unknown[];
|
||||||
|
body: Record<string, unknown>;
|
||||||
|
}) => { body: Record<string, unknown> };
|
||||||
|
}) {
|
||||||
|
h.state.transport = opts;
|
||||||
}
|
}
|
||||||
},
|
},
|
||||||
};
|
};
|
||||||
});
|
});
|
||||||
|
|
||||||
// Keep the ai-chat-query import light: ChatThread only needs the messages RQ key,
|
|
||||||
// so stub the module to avoid pulling axios / i18n transitively.
|
|
||||||
vi.mock("@/features/ai-chat/queries/ai-chat-query.ts", () => ({
|
|
||||||
AI_CHAT_MESSAGES_RQ_KEY: (chatId: string) => ["ai-chat-messages", chatId],
|
|
||||||
}));
|
|
||||||
|
|
||||||
// Stub the heavy children: MessageList (markdown/render) and ChatInput (the
|
// Stub the heavy children: MessageList (markdown/render) and ChatInput (the
|
||||||
// composer). The ChatInput stub exposes a button that queues a message, the only
|
// composer). The ChatInput stub exposes a button that queues a message, the only
|
||||||
// interaction this test needs to populate the queue while "streaming".
|
// interaction this test needs to populate the queue while "streaming".
|
||||||
@@ -81,90 +63,49 @@ vi.mock("@/features/ai-chat/components/message-list.tsx", () => ({
|
|||||||
default: () => <div data-testid="message-list" />,
|
default: () => <div data-testid="message-list" />,
|
||||||
}));
|
}));
|
||||||
vi.mock("@/features/ai-chat/components/chat-input.tsx", () => ({
|
vi.mock("@/features/ai-chat/components/chat-input.tsx", () => ({
|
||||||
default: ({
|
default: ({ onQueue }: { onQueue: (text: string) => void }) => (
|
||||||
onQueue,
|
<button data-testid="queue-btn" onClick={() => onQueue("queued text")}>
|
||||||
onStop,
|
queue
|
||||||
}: {
|
</button>
|
||||||
onQueue: (text: string) => void;
|
|
||||||
onStop: () => void;
|
|
||||||
}) => (
|
|
||||||
<>
|
|
||||||
<button data-testid="queue-btn" onClick={() => onQueue("queued text")}>
|
|
||||||
queue
|
|
||||||
</button>
|
|
||||||
<button aria-label="Stop" onClick={() => onStop()}>
|
|
||||||
stop
|
|
||||||
</button>
|
|
||||||
</>
|
|
||||||
),
|
),
|
||||||
}));
|
}));
|
||||||
|
|
||||||
import ChatThread from "./chat-thread";
|
import ChatThread from "./chat-thread";
|
||||||
import type { IAiChatMessageRow } from "@/features/ai-chat/types/ai-chat.types.ts";
|
|
||||||
|
|
||||||
function row(
|
function renderThread() {
|
||||||
id: string,
|
|
||||||
role: string,
|
|
||||||
status?: string,
|
|
||||||
text = "",
|
|
||||||
): IAiChatMessageRow {
|
|
||||||
return { id, role, content: text, status, createdAt: "2026-01-01T00:00:00Z" };
|
|
||||||
}
|
|
||||||
|
|
||||||
function renderThread(props?: {
|
|
||||||
chatId?: string | null;
|
|
||||||
initialRows?: IAiChatMessageRow[];
|
|
||||||
autonomousRunsEnabled?: boolean;
|
|
||||||
}) {
|
|
||||||
const onTurnFinished = vi.fn();
|
const onTurnFinished = vi.fn();
|
||||||
const onResumeFallback = vi.fn();
|
render(
|
||||||
const onServerStop = vi.fn();
|
<MantineProvider>
|
||||||
const queryClient = new QueryClient({
|
<ChatThread chatId="c1" initialRows={[]} onTurnFinished={onTurnFinished} />
|
||||||
defaultOptions: { queries: { retry: false } },
|
</MantineProvider>,
|
||||||
});
|
|
||||||
const invalidateSpy = vi.spyOn(queryClient, "invalidateQueries");
|
|
||||||
const { unmount } = render(
|
|
||||||
<QueryClientProvider client={queryClient}>
|
|
||||||
<MantineProvider>
|
|
||||||
<ChatThread
|
|
||||||
chatId={props?.chatId === undefined ? "c1" : props.chatId}
|
|
||||||
initialRows={props?.initialRows ?? []}
|
|
||||||
autonomousRunsEnabled={props?.autonomousRunsEnabled}
|
|
||||||
onTurnFinished={onTurnFinished}
|
|
||||||
onResumeFallback={onResumeFallback}
|
|
||||||
onServerStop={onServerStop}
|
|
||||||
/>
|
|
||||||
</MantineProvider>
|
|
||||||
</QueryClientProvider>,
|
|
||||||
);
|
);
|
||||||
return { onTurnFinished, onResumeFallback, onServerStop, invalidateSpy, unmount };
|
return { onTurnFinished };
|
||||||
}
|
|
||||||
|
|
||||||
function resetState() {
|
|
||||||
h.state.status = "streaming";
|
|
||||||
h.state.onFinish = null;
|
|
||||||
h.state.seededMessages = null;
|
|
||||||
h.state.transport = null;
|
|
||||||
h.state.sendMessage.mockClear();
|
|
||||||
h.state.stop.mockClear();
|
|
||||||
h.state.setMessages.mockClear();
|
|
||||||
h.state.resumeStream.mockClear();
|
|
||||||
}
|
}
|
||||||
|
|
||||||
describe("ChatThread — send now (#198)", () => {
|
describe("ChatThread — send now (#198)", () => {
|
||||||
beforeEach(resetState);
|
beforeEach(() => {
|
||||||
|
h.state.status = "streaming";
|
||||||
|
h.state.onFinish = null;
|
||||||
|
h.state.sendMessage.mockClear();
|
||||||
|
h.state.stop.mockClear();
|
||||||
|
h.state.transport = null;
|
||||||
|
});
|
||||||
|
|
||||||
it("aborts the current turn and resends the queued message on the abort", () => {
|
it("aborts the current turn and resends the queued message on the abort", () => {
|
||||||
renderThread();
|
renderThread();
|
||||||
|
|
||||||
|
// Queue a message while the turn is streaming.
|
||||||
fireEvent.click(screen.getByTestId("queue-btn"));
|
fireEvent.click(screen.getByTestId("queue-btn"));
|
||||||
const sendNowBtn = screen.getByLabelText("Send now");
|
const sendNowBtn = screen.getByLabelText("Send now");
|
||||||
expect(sendNowBtn).toBeTruthy();
|
expect(sendNowBtn).toBeTruthy();
|
||||||
|
|
||||||
|
// "Send now" interrupts the current turn (stop), but does NOT send yet —
|
||||||
|
// the resend happens once the abort lands in onFinish.
|
||||||
fireEvent.click(sendNowBtn);
|
fireEvent.click(sendNowBtn);
|
||||||
expect(h.state.stop).toHaveBeenCalledTimes(1);
|
expect(h.state.stop).toHaveBeenCalledTimes(1);
|
||||||
expect(h.state.sendMessage).not.toHaveBeenCalled();
|
expect(h.state.sendMessage).not.toHaveBeenCalled();
|
||||||
|
|
||||||
|
// The abort we triggered reaches onFinish: the promoted head is flushed.
|
||||||
act(() => {
|
act(() => {
|
||||||
h.state.onFinish?.({
|
h.state.onFinish?.({
|
||||||
message: { id: "a", role: "assistant", parts: [] },
|
message: { id: "a", role: "assistant", parts: [] },
|
||||||
@@ -181,8 +122,10 @@ describe("ChatThread — send now (#198)", () => {
|
|||||||
fireEvent.click(screen.getByTestId("queue-btn"));
|
fireEvent.click(screen.getByTestId("queue-btn"));
|
||||||
fireEvent.click(screen.getByLabelText("Send now"));
|
fireEvent.click(screen.getByLabelText("Send now"));
|
||||||
|
|
||||||
const prep = h.state.transport!.prepareSendMessagesRequest!;
|
const prep = h.state.transport!.prepareSendMessagesRequest;
|
||||||
|
// The send right after "send now" carries interrupted: true...
|
||||||
expect(prep({ messages: [], body: {} }).body.interrupted).toBe(true);
|
expect(prep({ messages: [], body: {} }).body.interrupted).toBe(true);
|
||||||
|
// ...and only that one (the flag is read-and-cleared).
|
||||||
expect(prep({ messages: [], body: {} }).body.interrupted).toBe(false);
|
expect(prep({ messages: [], body: {} }).body.interrupted).toBe(false);
|
||||||
});
|
});
|
||||||
|
|
||||||
@@ -193,92 +136,42 @@ describe("ChatThread — send now (#198)", () => {
|
|||||||
fireEvent.click(screen.getByTestId("queue-btn"));
|
fireEvent.click(screen.getByTestId("queue-btn"));
|
||||||
fireEvent.click(screen.getByLabelText("Send now"));
|
fireEvent.click(screen.getByLabelText("Send now"));
|
||||||
|
|
||||||
|
// No turn to interrupt: sent straight away, no abort, not flagged.
|
||||||
expect(h.state.stop).not.toHaveBeenCalled();
|
expect(h.state.stop).not.toHaveBeenCalled();
|
||||||
expect(h.state.sendMessage).toHaveBeenCalledWith({ text: "queued text" });
|
expect(h.state.sendMessage).toHaveBeenCalledWith({ text: "queued text" });
|
||||||
const prep = h.state.transport!.prepareSendMessagesRequest!;
|
const prep = h.state.transport!.prepareSendMessagesRequest;
|
||||||
expect(prep({ messages: [], body: {} }).body.interrupted).toBe(false);
|
expect(prep({ messages: [], body: {} }).body.interrupted).toBe(false);
|
||||||
});
|
});
|
||||||
});
|
});
|
||||||
|
|
||||||
// #388: the editor selection is snapshotted at send time and nested inside
|
// The turn-end decision lives in the `onFinish` handler: given the terminal
|
||||||
// openPage on the wire. The getter is read live from a ref, so each send ships a
|
// outcome of a turn (`isAbort` / `isDisconnect` / `isError`, or none = clean),
|
||||||
// fresh snapshot.
|
// it decides whether to CONTINUE (flush the next queued message) or END (leave
|
||||||
describe("ChatThread — editor selection wiring (#388)", () => {
|
// the queue intact for the user), and which stop notice — if any — to show.
|
||||||
beforeEach(resetState);
|
// `sendNow` is exercised above; these tests pin down the plain outcomes.
|
||||||
afterEach(cleanup);
|
|
||||||
|
|
||||||
function renderWithSelection(props: {
|
|
||||||
openPage?: { id: string; title: string } | null;
|
|
||||||
getEditorSelection?: () => unknown;
|
|
||||||
}) {
|
|
||||||
const queryClient = new QueryClient({
|
|
||||||
defaultOptions: { queries: { retry: false } },
|
|
||||||
});
|
|
||||||
render(
|
|
||||||
<QueryClientProvider client={queryClient}>
|
|
||||||
<MantineProvider>
|
|
||||||
<ChatThread
|
|
||||||
chatId="c1"
|
|
||||||
initialRows={[]}
|
|
||||||
openPage={props.openPage as never}
|
|
||||||
getEditorSelection={props.getEditorSelection as never}
|
|
||||||
onTurnFinished={vi.fn()}
|
|
||||||
onResumeFallback={vi.fn()}
|
|
||||||
onServerStop={vi.fn()}
|
|
||||||
/>
|
|
||||||
</MantineProvider>
|
|
||||||
</QueryClientProvider>,
|
|
||||||
);
|
|
||||||
}
|
|
||||||
|
|
||||||
it("nests the snapshot from the getter into openPage.selection at send time", () => {
|
|
||||||
const selection = { text: "fix this", blockIds: ["b1"], before: "a " };
|
|
||||||
renderWithSelection({
|
|
||||||
openPage: { id: "p1", title: "Doc" },
|
|
||||||
getEditorSelection: () => selection,
|
|
||||||
});
|
|
||||||
const prep = h.state.transport!.prepareSendMessagesRequest!;
|
|
||||||
const openPage = prep({ messages: [], body: {} }).body.openPage as Record<
|
|
||||||
string,
|
|
||||||
unknown
|
|
||||||
>;
|
|
||||||
expect(openPage).toEqual({ id: "p1", title: "Doc", selection });
|
|
||||||
});
|
|
||||||
|
|
||||||
it("sends selection: null when the getter returns null", () => {
|
|
||||||
renderWithSelection({
|
|
||||||
openPage: { id: "p1", title: "Doc" },
|
|
||||||
getEditorSelection: () => null,
|
|
||||||
});
|
|
||||||
const prep = h.state.transport!.prepareSendMessagesRequest!;
|
|
||||||
const openPage = prep({ messages: [], body: {} }).body.openPage as Record<
|
|
||||||
string,
|
|
||||||
unknown
|
|
||||||
>;
|
|
||||||
expect(openPage).toEqual({ id: "p1", title: "Doc", selection: null });
|
|
||||||
});
|
|
||||||
|
|
||||||
it("does not send selection at all on a non-page route (openPage null)", () => {
|
|
||||||
const getter = vi.fn(() => ({ text: "sel" }));
|
|
||||||
renderWithSelection({ openPage: null, getEditorSelection: getter });
|
|
||||||
const prep = h.state.transport!.prepareSendMessagesRequest!;
|
|
||||||
expect(prep({ messages: [], body: {} }).body.openPage).toBeNull();
|
|
||||||
// The getter must not even be consulted when there is no page.
|
|
||||||
expect(getter).not.toHaveBeenCalled();
|
|
||||||
});
|
|
||||||
});
|
|
||||||
|
|
||||||
describe("ChatThread — turn-end decision (onFinish)", () => {
|
describe("ChatThread — turn-end decision (onFinish)", () => {
|
||||||
beforeEach(resetState);
|
beforeEach(() => {
|
||||||
|
h.state.status = "streaming";
|
||||||
|
h.state.onFinish = null;
|
||||||
|
h.state.sendMessage.mockClear();
|
||||||
|
h.state.stop.mockClear();
|
||||||
|
h.state.transport = null;
|
||||||
|
});
|
||||||
|
|
||||||
|
// Drive a fresh onFinish with the given terminal flags after queueing a
|
||||||
|
// message, and report both what the parent was told and whether the queue was
|
||||||
|
// flushed (a resend to the sendMessage spy).
|
||||||
function finishWith(flags: {
|
function finishWith(flags: {
|
||||||
isAbort?: boolean;
|
isAbort?: boolean;
|
||||||
isDisconnect?: boolean;
|
isDisconnect?: boolean;
|
||||||
isError?: boolean;
|
isError?: boolean;
|
||||||
}) {
|
}) {
|
||||||
|
// Tear down any prior render so the loop-driven "every outcome" case does
|
||||||
|
// not leave duplicate queue buttons in the DOM.
|
||||||
cleanup();
|
cleanup();
|
||||||
h.state.sendMessage.mockClear();
|
h.state.sendMessage.mockClear();
|
||||||
const { onTurnFinished } = renderThread();
|
const { onTurnFinished } = renderThread();
|
||||||
|
// Populate the queue while the turn is streaming.
|
||||||
fireEvent.click(screen.getByTestId("queue-btn"));
|
fireEvent.click(screen.getByTestId("queue-btn"));
|
||||||
act(() => {
|
act(() => {
|
||||||
h.state.onFinish?.({
|
h.state.onFinish?.({
|
||||||
@@ -294,12 +187,16 @@ describe("ChatThread — turn-end decision (onFinish)", () => {
|
|||||||
|
|
||||||
it("CONTINUES — flushes the next queued message on a clean finish", () => {
|
it("CONTINUES — flushes the next queued message on a clean finish", () => {
|
||||||
finishWith({});
|
finishWith({});
|
||||||
|
// Clean finish (no terminal flag): the queued message is auto-sent.
|
||||||
expect(h.state.sendMessage).toHaveBeenCalledWith({ text: "queued text" });
|
expect(h.state.sendMessage).toHaveBeenCalledWith({ text: "queued text" });
|
||||||
|
// A clean finish shows no stop notice.
|
||||||
expect(screen.queryByText("Response stopped.")).toBeNull();
|
expect(screen.queryByText("Response stopped.")).toBeNull();
|
||||||
});
|
});
|
||||||
|
|
||||||
it("ENDS — keeps the queue intact on a user abort and shows the stopped notice", () => {
|
it("ENDS — keeps the queue intact on a user abort and shows the stopped notice", () => {
|
||||||
finishWith({ isAbort: true });
|
finishWith({ isAbort: true });
|
||||||
|
// A plain Stop (not the sendNow interrupt path) must NOT auto-resend: the
|
||||||
|
// queue is preserved for the user to decide.
|
||||||
expect(h.state.sendMessage).not.toHaveBeenCalled();
|
expect(h.state.sendMessage).not.toHaveBeenCalled();
|
||||||
expect(screen.getByText("Response stopped.")).toBeTruthy();
|
expect(screen.getByText("Response stopped.")).toBeTruthy();
|
||||||
});
|
});
|
||||||
@@ -314,11 +211,15 @@ describe("ChatThread — turn-end decision (onFinish)", () => {
|
|||||||
|
|
||||||
it("ENDS — keeps the queue intact on a stream error (no auto-retry, no stopped notice)", () => {
|
it("ENDS — keeps the queue intact on a stream error (no auto-retry, no stopped notice)", () => {
|
||||||
finishWith({ isError: true });
|
finishWith({ isError: true });
|
||||||
|
// Blindly retrying after a failure would be wrong; the queue is left alone.
|
||||||
expect(h.state.sendMessage).not.toHaveBeenCalled();
|
expect(h.state.sendMessage).not.toHaveBeenCalled();
|
||||||
|
// isError clears the neutral notice (the error banner covers this case).
|
||||||
expect(screen.queryByText("Response stopped.")).toBeNull();
|
expect(screen.queryByText("Response stopped.")).toBeNull();
|
||||||
});
|
});
|
||||||
|
|
||||||
it("notifies the parent on EVERY terminal outcome", () => {
|
it("notifies the parent on EVERY terminal outcome", () => {
|
||||||
|
// The chat-list refresh / new-chat id adoption must run on success and on
|
||||||
|
// every failure path alike.
|
||||||
for (const flags of [
|
for (const flags of [
|
||||||
{},
|
{},
|
||||||
{ isAbort: true },
|
{ isAbort: true },
|
||||||
@@ -331,411 +232,55 @@ describe("ChatThread — turn-end decision (onFinish)", () => {
|
|||||||
});
|
});
|
||||||
});
|
});
|
||||||
|
|
||||||
// #184 phase 1.5: the resumable-SSE client. A reopened tab resumes the live run
|
// #184 passive-observer merge: when reconnecting to a still-running run, the
|
||||||
// via the SDK's reconnect transport (attach: replay + tail) instead of polling.
|
// parent feeds the polled run message via `observedRow`; ChatThread merges it via
|
||||||
describe("ChatThread — resume (attach) machinery (#184)", () => {
|
// setMessages — but ONLY when this tab is NOT itself streaming (the streamer's
|
||||||
const streamingTail = () => [
|
// SSE owns the view, so a stale observedRow must never overwrite it).
|
||||||
row("u1", "user", undefined, "hi"),
|
describe("ChatThread — observer run merge (#184)", () => {
|
||||||
row("a1", "assistant", "streaming", "partial"),
|
beforeEach(() => {
|
||||||
];
|
h.state.onFinish = null;
|
||||||
const settledTail = () => [
|
h.state.setMessages.mockReset();
|
||||||
row("u1", "user", undefined, "hi"),
|
});
|
||||||
row("a1", "assistant", "succeeded", "done"),
|
|
||||||
];
|
|
||||||
const userTail = () => [row("u1", "user", undefined, "hi")];
|
|
||||||
|
|
||||||
const visibleMsg = {
|
const observedRow = {
|
||||||
id: "a1",
|
id: "a-run",
|
||||||
role: "assistant",
|
role: "assistant",
|
||||||
parts: [{ type: "text", text: "streamed answer" }],
|
content: "step 1\nstep 2",
|
||||||
};
|
metadata: {
|
||||||
const emptyMsg = { id: "a1", role: "assistant", parts: [] };
|
parts: [{ type: "text", text: "step 1\nstep 2" }],
|
||||||
|
},
|
||||||
|
createdAt: "2026-01-01T00:00:00Z",
|
||||||
|
} as const;
|
||||||
|
|
||||||
beforeEach(resetState);
|
function renderObserver(status: string) {
|
||||||
// NOTE: do NOT vi.unstubAllGlobals() here — vitest.setup.ts installs
|
h.state.status = status;
|
||||||
// matchMedia/localStorage via vi.stubGlobal and unstubbing wipes them for the
|
render(
|
||||||
// rest of the file. Fetch is re-stubbed per test that needs it.
|
|
||||||
afterEach(cleanup);
|
|
||||||
|
|
||||||
it("resumes on mount only when the flag is on, chatId is set, and the tail is not a settled assistant", () => {
|
|
||||||
// streaming tail -> resume
|
|
||||||
renderThread({ autonomousRunsEnabled: true, initialRows: streamingTail() });
|
|
||||||
expect(h.state.resumeStream).toHaveBeenCalledTimes(1);
|
|
||||||
|
|
||||||
// user tail -> resume (the assistant row may not be seeded yet)
|
|
||||||
cleanup();
|
|
||||||
h.state.resumeStream.mockClear();
|
|
||||||
renderThread({ autonomousRunsEnabled: true, initialRows: userTail() });
|
|
||||||
expect(h.state.resumeStream).toHaveBeenCalledTimes(1);
|
|
||||||
|
|
||||||
// settled assistant tail -> NO resume
|
|
||||||
cleanup();
|
|
||||||
h.state.resumeStream.mockClear();
|
|
||||||
renderThread({ autonomousRunsEnabled: true, initialRows: settledTail() });
|
|
||||||
expect(h.state.resumeStream).not.toHaveBeenCalled();
|
|
||||||
|
|
||||||
// flag off -> NO resume
|
|
||||||
cleanup();
|
|
||||||
h.state.resumeStream.mockClear();
|
|
||||||
renderThread({ autonomousRunsEnabled: false, initialRows: streamingTail() });
|
|
||||||
expect(h.state.resumeStream).not.toHaveBeenCalled();
|
|
||||||
|
|
||||||
// no chatId -> NO resume
|
|
||||||
cleanup();
|
|
||||||
h.state.resumeStream.mockClear();
|
|
||||||
renderThread({
|
|
||||||
autonomousRunsEnabled: true,
|
|
||||||
chatId: null,
|
|
||||||
initialRows: streamingTail(),
|
|
||||||
});
|
|
||||||
expect(h.state.resumeStream).not.toHaveBeenCalled();
|
|
||||||
});
|
|
||||||
|
|
||||||
it("strips the streaming tail from the seed, but keeps a user tail whole", () => {
|
|
||||||
renderThread({ autonomousRunsEnabled: true, initialRows: streamingTail() });
|
|
||||||
// 2 rows in, streaming tail stripped -> 1 seeded message.
|
|
||||||
expect(h.state.seededMessages).toHaveLength(1);
|
|
||||||
|
|
||||||
cleanup();
|
|
||||||
renderThread({ autonomousRunsEnabled: true, initialRows: userTail() });
|
|
||||||
// user tail is not stripped.
|
|
||||||
expect(h.state.seededMessages).toHaveLength(1);
|
|
||||||
});
|
|
||||||
|
|
||||||
it("builds the attach URL with expect=live&anchor only when the streaming tail was stripped", () => {
|
|
||||||
renderThread({ autonomousRunsEnabled: true, initialRows: streamingTail() });
|
|
||||||
expect(h.state.transport!.prepareReconnectToStreamRequest!().api).toBe(
|
|
||||||
"/api/ai-chat/runs/c1/stream?expect=live&anchor=a1",
|
|
||||||
);
|
|
||||||
|
|
||||||
cleanup();
|
|
||||||
renderThread({ autonomousRunsEnabled: true, initialRows: userTail() });
|
|
||||||
expect(h.state.transport!.prepareReconnectToStreamRequest!().api).toBe(
|
|
||||||
"/api/ai-chat/runs/c1/stream",
|
|
||||||
);
|
|
||||||
});
|
|
||||||
|
|
||||||
async function fetch204() {
|
|
||||||
vi.stubGlobal(
|
|
||||||
"fetch",
|
|
||||||
vi.fn().mockResolvedValue({ status: 204, ok: false }),
|
|
||||||
);
|
|
||||||
await act(async () => {
|
|
||||||
await h.state.transport!.fetch!("http://x", { method: "GET" });
|
|
||||||
});
|
|
||||||
}
|
|
||||||
|
|
||||||
it("204 on a user tail: no crash, no restore, reconcile+invalidate, onResumeFallback(true)", async () => {
|
|
||||||
const { onResumeFallback, invalidateSpy } = renderThread({
|
|
||||||
autonomousRunsEnabled: true,
|
|
||||||
initialRows: userTail(),
|
|
||||||
});
|
|
||||||
await fetch204();
|
|
||||||
// No stripped row -> no restore merge.
|
|
||||||
expect(h.state.setMessages).not.toHaveBeenCalled();
|
|
||||||
expect(invalidateSpy).toHaveBeenCalledWith({
|
|
||||||
queryKey: ["ai-chat-messages", "c1"],
|
|
||||||
});
|
|
||||||
expect(onResumeFallback).toHaveBeenCalledWith(true);
|
|
||||||
});
|
|
||||||
|
|
||||||
it("204 on a streaming tail: restore + invalidate + onResumeFallback(true)", async () => {
|
|
||||||
const { onResumeFallback, invalidateSpy } = renderThread({
|
|
||||||
autonomousRunsEnabled: true,
|
|
||||||
initialRows: streamingTail(),
|
|
||||||
});
|
|
||||||
await fetch204();
|
|
||||||
// Stripped row is restored to the store.
|
|
||||||
expect(h.state.setMessages).toHaveBeenCalledTimes(1);
|
|
||||||
expect(invalidateSpy).toHaveBeenCalledWith({
|
|
||||||
queryKey: ["ai-chat-messages", "c1"],
|
|
||||||
});
|
|
||||||
expect(onResumeFallback).toHaveBeenCalledWith(true);
|
|
||||||
});
|
|
||||||
|
|
||||||
it("F7 restart-survival: a 500 attach failure restores the stripped row AND arms the poll (not lost)", async () => {
|
|
||||||
const { onResumeFallback, invalidateSpy } = renderThread({
|
|
||||||
autonomousRunsEnabled: true,
|
|
||||||
initialRows: streamingTail(),
|
|
||||||
});
|
|
||||||
vi.stubGlobal(
|
|
||||||
"fetch",
|
|
||||||
vi.fn().mockResolvedValue({ status: 500, ok: false }),
|
|
||||||
);
|
|
||||||
await act(async () => {
|
|
||||||
await h.state.transport!.fetch!("http://x", { method: "GET" });
|
|
||||||
});
|
|
||||||
expect(h.state.setMessages).toHaveBeenCalledTimes(1); // stripped row restored
|
|
||||||
expect(invalidateSpy).toHaveBeenCalledWith({
|
|
||||||
queryKey: ["ai-chat-messages", "c1"],
|
|
||||||
});
|
|
||||||
expect(onResumeFallback).toHaveBeenCalledWith(true); // degraded poll armed
|
|
||||||
});
|
|
||||||
|
|
||||||
it("F7 restart-survival: a network throw restores the stripped row AND arms the poll", async () => {
|
|
||||||
const { onResumeFallback, invalidateSpy } = renderThread({
|
|
||||||
autonomousRunsEnabled: true,
|
|
||||||
initialRows: streamingTail(),
|
|
||||||
});
|
|
||||||
vi.stubGlobal(
|
|
||||||
"fetch",
|
|
||||||
vi.fn().mockRejectedValue(new Error("network down")),
|
|
||||||
);
|
|
||||||
await act(async () => {
|
|
||||||
await h.state
|
|
||||||
.transport!.fetch!("http://x", { method: "GET" })
|
|
||||||
.catch(() => undefined); // the wrapper rethrows; swallow here
|
|
||||||
});
|
|
||||||
expect(h.state.setMessages).toHaveBeenCalledTimes(1);
|
|
||||||
expect(invalidateSpy).toHaveBeenCalledWith({
|
|
||||||
queryKey: ["ai-chat-messages", "c1"],
|
|
||||||
});
|
|
||||||
expect(onResumeFallback).toHaveBeenCalledWith(true);
|
|
||||||
});
|
|
||||||
|
|
||||||
it("unmount during a pending attach aborts the controller and gates late callbacks", async () => {
|
|
||||||
const { onResumeFallback, invalidateSpy, unmount } = renderThread({
|
|
||||||
autonomousRunsEnabled: true,
|
|
||||||
initialRows: streamingTail(),
|
|
||||||
});
|
|
||||||
let abortSeen = false;
|
|
||||||
let resolveFetch!: (v: unknown) => void;
|
|
||||||
vi.stubGlobal(
|
|
||||||
"fetch",
|
|
||||||
vi.fn().mockImplementation((_input: unknown, init: RequestInit) => {
|
|
||||||
init.signal?.addEventListener("abort", () => {
|
|
||||||
abortSeen = true;
|
|
||||||
});
|
|
||||||
return new Promise((res) => {
|
|
||||||
resolveFetch = res;
|
|
||||||
});
|
|
||||||
}),
|
|
||||||
);
|
|
||||||
// Kick a reconnect GET (stays pending).
|
|
||||||
let pending!: Promise<unknown>;
|
|
||||||
act(() => {
|
|
||||||
pending = h.state.transport!.fetch!("http://x", { method: "GET" });
|
|
||||||
});
|
|
||||||
// Unmount: the cleanup aborts the in-flight attach.
|
|
||||||
unmount();
|
|
||||||
expect(abortSeen).toBe(true);
|
|
||||||
// A late 204 landing after unmount must NOT arm a poll / invalidate the (now
|
|
||||||
// different) chat.
|
|
||||||
onResumeFallback.mockClear();
|
|
||||||
invalidateSpy.mockClear();
|
|
||||||
await act(async () => {
|
|
||||||
resolveFetch({ status: 204, ok: false });
|
|
||||||
await pending;
|
|
||||||
});
|
|
||||||
expect(onResumeFallback).not.toHaveBeenCalledWith(true);
|
|
||||||
expect(invalidateSpy).not.toHaveBeenCalled();
|
|
||||||
});
|
|
||||||
|
|
||||||
it("a resume fetch error clears resumedTurn so the next local turn flushes the queue", async () => {
|
|
||||||
renderThread({ autonomousRunsEnabled: true, initialRows: streamingTail() });
|
|
||||||
h.state.status = "ready";
|
|
||||||
vi.stubGlobal(
|
|
||||||
"fetch",
|
|
||||||
vi.fn().mockResolvedValue({ status: 500, ok: false }),
|
|
||||||
);
|
|
||||||
await act(async () => {
|
|
||||||
await h.state.transport!.fetch!("http://x", { method: "GET" });
|
|
||||||
});
|
|
||||||
// Queue then clean-finish: suppression was cleared, so the queue flushes.
|
|
||||||
fireEvent.click(screen.getByTestId("queue-btn"));
|
|
||||||
act(() => {
|
|
||||||
h.state.onFinish?.({
|
|
||||||
message: visibleMsg,
|
|
||||||
isAbort: false,
|
|
||||||
isDisconnect: false,
|
|
||||||
isError: false,
|
|
||||||
});
|
|
||||||
});
|
|
||||||
expect(h.state.sendMessage).toHaveBeenCalledWith({ text: "queued text" });
|
|
||||||
});
|
|
||||||
|
|
||||||
it("a resumed turn's onFinish does NOT flush the queue", () => {
|
|
||||||
renderThread({ autonomousRunsEnabled: true, initialRows: streamingTail() });
|
|
||||||
fireEvent.click(screen.getByTestId("queue-btn"));
|
|
||||||
act(() => {
|
|
||||||
h.state.onFinish?.({
|
|
||||||
message: visibleMsg,
|
|
||||||
isAbort: false,
|
|
||||||
isDisconnect: false,
|
|
||||||
isError: false,
|
|
||||||
});
|
|
||||||
});
|
|
||||||
expect(h.state.sendMessage).not.toHaveBeenCalled();
|
|
||||||
});
|
|
||||||
|
|
||||||
it("a healthy resumed finish (visible content) arms nothing and keeps the store", () => {
|
|
||||||
h.state.status = "ready";
|
|
||||||
const { onResumeFallback } = renderThread({
|
|
||||||
autonomousRunsEnabled: true,
|
|
||||||
initialRows: streamingTail(),
|
|
||||||
});
|
|
||||||
h.state.setMessages.mockClear();
|
|
||||||
onResumeFallback.mockClear();
|
|
||||||
act(() => {
|
|
||||||
h.state.onFinish?.({
|
|
||||||
message: visibleMsg,
|
|
||||||
isAbort: false,
|
|
||||||
isDisconnect: false,
|
|
||||||
isError: false,
|
|
||||||
});
|
|
||||||
});
|
|
||||||
// No restore (would clobber the fuller streamed message), no poll arm.
|
|
||||||
expect(h.state.setMessages).not.toHaveBeenCalled();
|
|
||||||
expect(onResumeFallback).not.toHaveBeenCalledWith(true);
|
|
||||||
});
|
|
||||||
|
|
||||||
it("isDisconnect WITH visible content arms the poll but does NOT restore", () => {
|
|
||||||
h.state.status = "ready";
|
|
||||||
const { onResumeFallback, invalidateSpy } = renderThread({
|
|
||||||
autonomousRunsEnabled: true,
|
|
||||||
initialRows: streamingTail(),
|
|
||||||
});
|
|
||||||
h.state.setMessages.mockClear();
|
|
||||||
onResumeFallback.mockClear();
|
|
||||||
invalidateSpy.mockClear();
|
|
||||||
act(() => {
|
|
||||||
h.state.onFinish?.({
|
|
||||||
message: visibleMsg,
|
|
||||||
isAbort: false,
|
|
||||||
isDisconnect: true,
|
|
||||||
isError: false,
|
|
||||||
});
|
|
||||||
});
|
|
||||||
expect(onResumeFallback).toHaveBeenCalledWith(true);
|
|
||||||
expect(invalidateSpy).toHaveBeenCalledWith({
|
|
||||||
queryKey: ["ai-chat-messages", "c1"],
|
|
||||||
});
|
|
||||||
// Restore forbidden: the on-screen partial must not roll back.
|
|
||||||
expect(h.state.setMessages).not.toHaveBeenCalled();
|
|
||||||
});
|
|
||||||
|
|
||||||
it("an empty resumed message (starved replay) restores the stripped row AND arms the poll", () => {
|
|
||||||
h.state.status = "ready";
|
|
||||||
const { onResumeFallback } = renderThread({
|
|
||||||
autonomousRunsEnabled: true,
|
|
||||||
initialRows: streamingTail(),
|
|
||||||
});
|
|
||||||
h.state.setMessages.mockClear();
|
|
||||||
onResumeFallback.mockClear();
|
|
||||||
act(() => {
|
|
||||||
h.state.onFinish?.({
|
|
||||||
message: emptyMsg,
|
|
||||||
isAbort: false,
|
|
||||||
isDisconnect: false,
|
|
||||||
isError: false,
|
|
||||||
});
|
|
||||||
});
|
|
||||||
expect(h.state.setMessages).toHaveBeenCalledTimes(1); // restore
|
|
||||||
expect(onResumeFallback).toHaveBeenCalledWith(true); // arm
|
|
||||||
});
|
|
||||||
|
|
||||||
it("degraded-merge: merges the tail per initialRows update, and settles disarm the poll", async () => {
|
|
||||||
h.state.status = "ready";
|
|
||||||
const { rerender, onResumeFallback } = renderResumable(streamingTail());
|
|
||||||
// Arm reconcile via a 204.
|
|
||||||
vi.stubGlobal(
|
|
||||||
"fetch",
|
|
||||||
vi.fn().mockResolvedValue({ status: 204, ok: false }),
|
|
||||||
);
|
|
||||||
await act(async () => {
|
|
||||||
await h.state.transport!.fetch!("http://x", { method: "GET" });
|
|
||||||
});
|
|
||||||
h.state.setMessages.mockClear();
|
|
||||||
onResumeFallback.mockClear();
|
|
||||||
|
|
||||||
// A streaming-tail update: merge, poll stays armed.
|
|
||||||
rerender([
|
|
||||||
row("u1", "user", undefined, "hi"),
|
|
||||||
row("a1", "assistant", "streaming", "step 1\nstep 2"),
|
|
||||||
]);
|
|
||||||
expect(h.state.setMessages).toHaveBeenCalledTimes(1);
|
|
||||||
expect(onResumeFallback).not.toHaveBeenCalledWith(false);
|
|
||||||
|
|
||||||
// A settled-tail update: merge + disarm.
|
|
||||||
h.state.setMessages.mockClear();
|
|
||||||
rerender([
|
|
||||||
row("u1", "user", undefined, "hi"),
|
|
||||||
row("a1", "assistant", "succeeded", "final"),
|
|
||||||
]);
|
|
||||||
expect(h.state.setMessages).toHaveBeenCalledTimes(1);
|
|
||||||
expect(onResumeFallback).toHaveBeenCalledWith(false);
|
|
||||||
});
|
|
||||||
|
|
||||||
it("a local stream disarms both the merge and the poll", () => {
|
|
||||||
h.state.status = "streaming";
|
|
||||||
const { rerender, onResumeFallback } = renderResumable(streamingTail());
|
|
||||||
onResumeFallback.mockClear();
|
|
||||||
// A re-render while streaming: the reconciliation effect disarms.
|
|
||||||
rerender(streamingTail());
|
|
||||||
expect(onResumeFallback).toHaveBeenCalledWith(false);
|
|
||||||
});
|
|
||||||
|
|
||||||
it("Send now is hidden on a resumed turn but visible on a local stream", () => {
|
|
||||||
// Resumed turn: hidden.
|
|
||||||
renderThread({ autonomousRunsEnabled: true, initialRows: streamingTail() });
|
|
||||||
fireEvent.click(screen.getByTestId("queue-btn"));
|
|
||||||
expect(screen.queryByLabelText("Send now")).toBeNull();
|
|
||||||
|
|
||||||
// Local streaming turn (no resume): visible.
|
|
||||||
cleanup();
|
|
||||||
resetState();
|
|
||||||
renderThread({ initialRows: [] });
|
|
||||||
fireEvent.click(screen.getByTestId("queue-btn"));
|
|
||||||
expect(screen.getByLabelText("Send now")).toBeTruthy();
|
|
||||||
});
|
|
||||||
|
|
||||||
it("handleStop aborts the attach controller and calls onServerStop", async () => {
|
|
||||||
const { onServerStop } = renderThread({
|
|
||||||
autonomousRunsEnabled: true,
|
|
||||||
initialRows: streamingTail(),
|
|
||||||
});
|
|
||||||
// Establish an attach controller via a (pending) reconnect GET.
|
|
||||||
let abortSeen = false;
|
|
||||||
vi.stubGlobal(
|
|
||||||
"fetch",
|
|
||||||
vi.fn().mockImplementation((_input: unknown, init: RequestInit) => {
|
|
||||||
init.signal?.addEventListener("abort", () => {
|
|
||||||
abortSeen = true;
|
|
||||||
});
|
|
||||||
return new Promise(() => undefined); // never resolves
|
|
||||||
}),
|
|
||||||
);
|
|
||||||
act(() => {
|
|
||||||
void h.state.transport!.fetch!("http://x", { method: "GET" });
|
|
||||||
});
|
|
||||||
fireEvent.click(screen.getByLabelText("Stop"));
|
|
||||||
expect(abortSeen).toBe(true);
|
|
||||||
expect(onServerStop).toHaveBeenCalledWith("c1");
|
|
||||||
});
|
|
||||||
});
|
|
||||||
|
|
||||||
// Helper: render a resumable thread and expose a rerender that only swaps
|
|
||||||
// initialRows (the degraded-merge effect depends on it).
|
|
||||||
function renderResumable(initialRows: IAiChatMessageRow[]) {
|
|
||||||
const onResumeFallback = vi.fn();
|
|
||||||
const queryClient = new QueryClient({
|
|
||||||
defaultOptions: { queries: { retry: false } },
|
|
||||||
});
|
|
||||||
const Wrapper = ({ rows }: { rows: IAiChatMessageRow[] }) => (
|
|
||||||
<QueryClientProvider client={queryClient}>
|
|
||||||
<MantineProvider>
|
<MantineProvider>
|
||||||
<ChatThread
|
<ChatThread
|
||||||
chatId="c1"
|
chatId="c1"
|
||||||
initialRows={rows}
|
initialRows={[]}
|
||||||
autonomousRunsEnabled
|
|
||||||
onTurnFinished={vi.fn()}
|
onTurnFinished={vi.fn()}
|
||||||
onResumeFallback={onResumeFallback}
|
observedRow={observedRow as never}
|
||||||
/>
|
/>
|
||||||
</MantineProvider>
|
</MantineProvider>,
|
||||||
</QueryClientProvider>
|
);
|
||||||
);
|
}
|
||||||
const view = render(<Wrapper rows={initialRows} />);
|
|
||||||
const rerender = (rows: IAiChatMessageRow[]) =>
|
it("merges the polled run message when this tab is a passive observer", () => {
|
||||||
act(() => view.rerender(<Wrapper rows={rows} />));
|
renderObserver("ready");
|
||||||
return { rerender, onResumeFallback };
|
expect(h.state.setMessages).toHaveBeenCalledTimes(1);
|
||||||
}
|
// The updater replaces/append the observed assistant row by id.
|
||||||
|
const updater = h.state.setMessages.mock.calls[0][0] as (
|
||||||
|
prev: { id: string; parts: { text: string }[] }[],
|
||||||
|
) => { id: string; parts: { text: string }[] }[];
|
||||||
|
const merged = updater([{ id: "u1", parts: [{ text: "hi" }] }]);
|
||||||
|
expect(merged).toHaveLength(2);
|
||||||
|
expect(merged[1].id).toBe("a-run");
|
||||||
|
expect(merged[1].parts[0].text).toBe("step 1\nstep 2");
|
||||||
|
});
|
||||||
|
|
||||||
|
it("does NOT merge while THIS tab is the streamer (no double-render)", () => {
|
||||||
|
renderObserver("streaming");
|
||||||
|
expect(h.state.setMessages).not.toHaveBeenCalled();
|
||||||
|
});
|
||||||
|
});
|
||||||
|
|||||||
@@ -1,5 +1,4 @@
|
|||||||
import { useCallback, useEffect, useMemo, useRef, useState } from "react";
|
import { useCallback, useEffect, useMemo, useRef, useState } from "react";
|
||||||
import { useQueryClient } from "@tanstack/react-query";
|
|
||||||
import { generateId } from "ai";
|
import { generateId } from "ai";
|
||||||
import { ActionIcon, Box, Group, Stack, Text, Tooltip } from "@mantine/core";
|
import { ActionIcon, Box, Group, Stack, Text, Tooltip } from "@mantine/core";
|
||||||
import {
|
import {
|
||||||
@@ -25,15 +24,7 @@ import {
|
|||||||
} from "@/features/ai-chat/utils/role-launch.ts";
|
} from "@/features/ai-chat/utils/role-launch.ts";
|
||||||
import { describeChatError } from "@/features/ai-chat/utils/error-message.ts";
|
import { describeChatError } from "@/features/ai-chat/utils/error-message.ts";
|
||||||
import { extractServerChatId } from "@/features/ai-chat/utils/adopt-chat-id.ts";
|
import { extractServerChatId } from "@/features/ai-chat/utils/adopt-chat-id.ts";
|
||||||
import { assistantMessageHasVisibleContent } from "@/features/ai-chat/utils/message-content.ts";
|
import { mergeObservedMessage } from "@/features/ai-chat/utils/run-polling.ts";
|
||||||
import {
|
|
||||||
isStreamingTail,
|
|
||||||
isSettledAssistantTail,
|
|
||||||
seedRows,
|
|
||||||
mergeById,
|
|
||||||
} from "@/features/ai-chat/utils/resume-helpers.ts";
|
|
||||||
import { AI_CHAT_MESSAGES_RQ_KEY } from "@/features/ai-chat/queries/ai-chat-query.ts";
|
|
||||||
import type { EditorSelectionContext } from "@/features/editor/utils/get-editor-selection.ts";
|
|
||||||
import {
|
import {
|
||||||
dequeue,
|
dequeue,
|
||||||
enqueueMessage,
|
enqueueMessage,
|
||||||
@@ -70,10 +61,6 @@ interface ChatThreadProps {
|
|||||||
/** The page currently open in the workspace, or null on a non-page route.
|
/** The page currently open in the workspace, or null on a non-page route.
|
||||||
* Sent with each turn so the agent knows what "this page" refers to. */
|
* Sent with each turn so the agent knows what "this page" refers to. */
|
||||||
openPage?: OpenPageContext | null;
|
openPage?: OpenPageContext | null;
|
||||||
/** #388: snapshot the user's current editor selection at SEND time. Invoked
|
|
||||||
* inside prepareSendMessagesRequest and nested into openPage on the wire, so a
|
|
||||||
* fresh snapshot ships each turn. Null/absent => nothing selected. */
|
|
||||||
getEditorSelection?: () => EditorSelectionContext | null;
|
|
||||||
/** The agent role selected for a NEW chat (null = universal assistant). Sent
|
/** The agent role selected for a NEW chat (null = universal assistant). Sent
|
||||||
* in the request body so the server persists it on chat creation; ignored by
|
* in the request body so the server persists it on chat creation; ignored by
|
||||||
* the server for existing chats (the role is read from the chat row). */
|
* the server for existing chats (the role is read from the chat row). */
|
||||||
@@ -100,13 +87,19 @@ interface ChatThreadProps {
|
|||||||
* Copy/export button available mid-stream). Distinct from onTurnFinished,
|
* Copy/export button available mid-stream). Distinct from onTurnFinished,
|
||||||
* which fires only at the terminal outcome. */
|
* which fires only at the terminal outcome. */
|
||||||
onServerChatId?: (serverChatId?: string) => void;
|
onServerChatId?: (serverChatId?: string) => void;
|
||||||
/** #184 phase 1.5: arm/disarm the parent's degraded-poll fallback for THIS
|
/** #184 reconnect-and-live-follow. When THIS tab reopened a chat whose agent
|
||||||
* chat's window. Called `true` when a resume attempt could not attach to the
|
* run is still going (it is a PASSIVE OBSERVER — it did not start the run here),
|
||||||
* live run (attach 204 / starved-or-torn resumed finish), so the window starts
|
* the parent polls the reconnect endpoint and feeds the run's incrementally-
|
||||||
* a dumb timed poll of the message history to follow the detached run to settle;
|
* persisted assistant message here; we merge it into the live list so new
|
||||||
* called `false` the moment a local stream starts or the terminal settled row is
|
* steps/tool-calls appear as they are persisted. Null when there is nothing to
|
||||||
* merged (invariant 8). The window owns the timer + its 10-min cap. */
|
* observe (no run, feature off, or this tab IS the streamer). The merge is
|
||||||
onResumeFallback?: (active: boolean) => void;
|
* ADDITIONALLY guarded by our own `isStreaming`, so a stale value can never
|
||||||
|
* fight the local stream when we are the streamer. */
|
||||||
|
observedRow?: IAiChatMessageRow | null;
|
||||||
|
/** Report this tab's live streaming status up to the parent, so it can stop
|
||||||
|
* polling the run while WE are the active streamer (the SSE owns the view) and
|
||||||
|
* resume once we go idle. Called from an effect on every transition. */
|
||||||
|
onStreamingChange?: (streaming: boolean) => void;
|
||||||
/** #184: whether detached/autonomous agent runs are enabled for this workspace.
|
/** #184: whether detached/autonomous agent runs are enabled for this workspace.
|
||||||
* When true the Stop button must additionally hit the AUTHORITATIVE server stop
|
* When true the Stop button must additionally hit the AUTHORITATIVE server stop
|
||||||
* (via onServerStop) — aborting only the local SSE is just a client disconnect,
|
* (via onServerStop) — aborting only the local SSE is just a client disconnect,
|
||||||
@@ -156,65 +149,21 @@ export default function ChatThread({
|
|||||||
threadKey,
|
threadKey,
|
||||||
initialRows,
|
initialRows,
|
||||||
openPage,
|
openPage,
|
||||||
getEditorSelection,
|
|
||||||
roleId,
|
roleId,
|
||||||
roles,
|
roles,
|
||||||
onRolePicked,
|
onRolePicked,
|
||||||
assistantName,
|
assistantName,
|
||||||
onTurnFinished,
|
onTurnFinished,
|
||||||
onServerChatId,
|
onServerChatId,
|
||||||
onResumeFallback,
|
observedRow,
|
||||||
|
onStreamingChange,
|
||||||
autonomousRunsEnabled,
|
autonomousRunsEnabled,
|
||||||
onServerStop,
|
onServerStop,
|
||||||
}: ChatThreadProps) {
|
}: ChatThreadProps) {
|
||||||
const { t } = useTranslation();
|
const { t } = useTranslation();
|
||||||
const queryClient = useQueryClient();
|
|
||||||
|
|
||||||
// resume machinery refs (#184 phase 1.5)
|
|
||||||
const attachAbortRef = useRef<AbortController | null>(null);
|
|
||||||
const reconcileTailRef = useRef(false);
|
|
||||||
const noStreamHandledRef = useRef(false);
|
|
||||||
const onNoActiveStreamRef = useRef<(() => void) | null>(null);
|
|
||||||
// Live mount flag. The attach GET and the resumed `onFinish` are async and can
|
|
||||||
// land AFTER this thread unmounts (the parent remounts per chat via `key`); with
|
|
||||||
// chatIdRef then pointing at the NEW chat, an ungated late callback would arm a
|
|
||||||
// spurious poll + foreign invalidation on the newly-opened chat. Every parent-
|
|
||||||
// facing resume side-effect is gated on this.
|
|
||||||
const mountedRef = useRef(true);
|
|
||||||
const [resumedTurn, setResumedTurn] = useState(false);
|
|
||||||
const resumedTurnRef = useRef(false);
|
|
||||||
// Identity-stable pair setter (bare useState setter + ref write): it is closed
|
|
||||||
// over by the transport useMemo([]), so it MUST NOT capture state.
|
|
||||||
const setResumedTurnPair = useCallback((v: boolean) => {
|
|
||||||
resumedTurnRef.current = v;
|
|
||||||
setResumedTurn(v);
|
|
||||||
}, []);
|
|
||||||
|
|
||||||
// Mount-time resume gating (in refs — computed once for this mount; the parent
|
|
||||||
// remounts per chat via `key`).
|
|
||||||
//
|
|
||||||
// Attempt resume for any non-settled tail: a streaming tail (strip + expect
|
|
||||||
// live replay) or a user tail (the run may exist but its assistant row is not
|
|
||||||
// seeded yet — attach to the pre-opened registry entry and wait for frames).
|
|
||||||
// A settled assistant tail must NEVER resume: replaying a finished run into a
|
|
||||||
// store that already contains its message duplicates parts (SDK text-start
|
|
||||||
// always pushes a new part).
|
|
||||||
const stripRef = useRef(chatId !== null && isStreamingTail(initialRows ?? []));
|
|
||||||
const attemptResumeRef = useRef(
|
|
||||||
autonomousRunsEnabled === true &&
|
|
||||||
chatId !== null &&
|
|
||||||
!isSettledAssistantTail(initialRows ?? []),
|
|
||||||
);
|
|
||||||
const strippedRowRef = useRef<IAiChatMessageRow | null>(
|
|
||||||
stripRef.current ? (initialRows ?? [])[initialRows!.length - 1] : null,
|
|
||||||
);
|
|
||||||
|
|
||||||
const initialMessages = useMemo<UIMessage[]>(
|
const initialMessages = useMemo<UIMessage[]>(
|
||||||
() =>
|
() => (initialRows ?? []).map(rowToUiMessage),
|
||||||
seedRows(
|
|
||||||
initialRows ?? [],
|
|
||||||
attemptResumeRef.current && stripRef.current,
|
|
||||||
).map(rowToUiMessage),
|
|
||||||
[initialRows],
|
[initialRows],
|
||||||
);
|
);
|
||||||
|
|
||||||
@@ -232,14 +181,6 @@ export default function ChatThread({
|
|||||||
const openPageRef = useRef<OpenPageContext | null>(openPage ?? null);
|
const openPageRef = useRef<OpenPageContext | null>(openPage ?? null);
|
||||||
openPageRef.current = openPage ?? null;
|
openPageRef.current = openPage ?? null;
|
||||||
|
|
||||||
// Keep the selection snapshotter in a ref, same rationale as openPageRef: the
|
|
||||||
// transport useMemo([]) closes it over, so prop-identity churn must not matter.
|
|
||||||
// Called at send time inside prepareSendMessagesRequest (#388).
|
|
||||||
const getEditorSelectionRef = useRef<
|
|
||||||
(() => EditorSelectionContext | null) | undefined
|
|
||||||
>(getEditorSelection);
|
|
||||||
getEditorSelectionRef.current = getEditorSelection;
|
|
||||||
|
|
||||||
// Keep the selected role id in a ref, same rationale as openPageRef. Only the
|
// Keep the selected role id in a ref, same rationale as openPageRef. Only the
|
||||||
// FIRST request of a brand-new chat uses it (the server persists it then and
|
// FIRST request of a brand-new chat uses it (the server persists it then and
|
||||||
// ignores it for existing chats), but sending it on every send is harmless.
|
// ignores it for existing chats), but sending it on every send is harmless.
|
||||||
@@ -320,12 +261,9 @@ export default function ChatThread({
|
|||||||
const { head, rest } = dequeue(queuedRef.current);
|
const { head, rest } = dequeue(queuedRef.current);
|
||||||
if (!head) return false;
|
if (!head) return false;
|
||||||
setQueue(rest);
|
setQueue(rest);
|
||||||
// Local send: clear any resume-suppression flag so this genuine local turn's
|
|
||||||
// onFinish flushes normally (invariant 8).
|
|
||||||
setResumedTurnPair(false);
|
|
||||||
sendMessageRef.current?.({ text: head.text });
|
sendMessageRef.current?.({ text: head.text });
|
||||||
return true;
|
return true;
|
||||||
}, [setQueue, setResumedTurnPair]);
|
}, [setQueue]);
|
||||||
|
|
||||||
const enqueue = useCallback(
|
const enqueue = useCallback(
|
||||||
(text: string) => {
|
(text: string) => {
|
||||||
@@ -345,47 +283,6 @@ export default function ChatThread({
|
|||||||
new DefaultChatTransport<UIMessage>({
|
new DefaultChatTransport<UIMessage>({
|
||||||
api: "/api/ai-chat/stream",
|
api: "/api/ai-chat/stream",
|
||||||
credentials: "include",
|
credentials: "include",
|
||||||
prepareReconnectToStreamRequest: () => ({
|
|
||||||
// SDK default URL uses the useChat STORE id — always build from the real chat id.
|
|
||||||
// ?expect=live&anchor=<row id> ONLY when we stripped a streaming tail: expect=live
|
|
||||||
// is the only case where a finished-retained replay is safe (the row is stripped,
|
|
||||||
// replay rebuilds it), and the anchor pins the replay to OUR run — a mismatching
|
|
||||||
// (newer) run must 204 into the restore+poll path instead of replaying a foreign
|
|
||||||
// transcript into this store.
|
|
||||||
api: `/api/ai-chat/runs/${chatIdRef.current}/stream${
|
|
||||||
stripRef.current
|
|
||||||
? `?expect=live&anchor=${strippedRowRef.current!.id}`
|
|
||||||
: ""
|
|
||||||
}`,
|
|
||||||
}),
|
|
||||||
fetch: async (input: RequestInfo | URL, init: RequestInit = {}) => {
|
|
||||||
if ((init.method ?? "GET") !== "GET") return fetch(input, init); // send path untouched
|
|
||||||
// Reconnect GET: the SDK passes no AbortSignal, so wire our own controller
|
|
||||||
// for observer Stop / unmount abort.
|
|
||||||
const controller = new AbortController();
|
|
||||||
attachAbortRef.current = controller;
|
|
||||||
try {
|
|
||||||
const response = await fetch(input, {
|
|
||||||
...init,
|
|
||||||
signal: controller.signal,
|
|
||||||
});
|
|
||||||
// No onFinish will come for a 204 (silent no-op) OR any non-2xx
|
|
||||||
// (5xx/502 — a server restart mid-attach). Both run the same
|
|
||||||
// no-active-stream recovery: restore the stripped row, invalidate, and
|
|
||||||
// arm the degraded poll (idempotent via noStreamHandledRef; its part-d
|
|
||||||
// also clears the resumedTurn flag). This is the restart-survival path
|
|
||||||
// the removed F7 latch used to guard — a transient attach failure must
|
|
||||||
// NOT drop the in-progress row or stop tracking the durable run.
|
|
||||||
if (response.status === 204 || !response.ok)
|
|
||||||
onNoActiveStreamRef.current?.();
|
|
||||||
return response;
|
|
||||||
} catch (err) {
|
|
||||||
// Network throw: same no-onFinish recovery, then rethrow so the SDK
|
|
||||||
// still surfaces the error to its own machinery.
|
|
||||||
onNoActiveStreamRef.current?.();
|
|
||||||
throw err;
|
|
||||||
}
|
|
||||||
},
|
|
||||||
// Inject the chat id and the currently-open page alongside the useChat
|
// Inject the chat id and the currently-open page alongside the useChat
|
||||||
// messages so the server can resolve an existing chat (or create one
|
// messages so the server can resolve an existing chat (or create one
|
||||||
// when null) and tell the agent which page "this page" refers to. Both
|
// when null) and tell the agent which page "this page" refers to. Both
|
||||||
@@ -402,16 +299,7 @@ export default function ChatThread({
|
|||||||
body: {
|
body: {
|
||||||
...body,
|
...body,
|
||||||
chatId: chatIdRef.current,
|
chatId: chatIdRef.current,
|
||||||
// Attach the live editor selection to the open-page context at send
|
openPage: openPageRef.current,
|
||||||
// time — "this"/"here" in the user's message means THIS selection.
|
|
||||||
// Nested inside openPage so it dies with the page when the server
|
|
||||||
// rejects the page id (#388). Null when nothing is selected.
|
|
||||||
openPage: openPageRef.current
|
|
||||||
? {
|
|
||||||
...openPageRef.current,
|
|
||||||
selection: getEditorSelectionRef.current?.() ?? null,
|
|
||||||
}
|
|
||||||
: null,
|
|
||||||
// Honoured by the server only when creating a new chat; null =>
|
// Honoured by the server only when creating a new chat; null =>
|
||||||
// universal assistant.
|
// universal assistant.
|
||||||
roleId: roleIdRef.current,
|
roleId: roleIdRef.current,
|
||||||
@@ -424,15 +312,7 @@ export default function ChatThread({
|
|||||||
[],
|
[],
|
||||||
);
|
);
|
||||||
|
|
||||||
const {
|
const { messages, sendMessage, status, stop, error, setMessages } = useChat({
|
||||||
messages,
|
|
||||||
sendMessage,
|
|
||||||
status,
|
|
||||||
stop,
|
|
||||||
error,
|
|
||||||
setMessages,
|
|
||||||
resumeStream,
|
|
||||||
} = useChat({
|
|
||||||
// Stable per-mount key. Existing chats use their real id; new chats use a
|
// Stable per-mount key. Existing chats use their real id; new chats use a
|
||||||
// generated client id (never `undefined`) so the store is NOT re-created on
|
// generated client id (never `undefined`) so the store is NOT re-created on
|
||||||
// every render mid-stream (see `chatStoreId` above).
|
// every render mid-stream (see `chatStoreId` above).
|
||||||
@@ -450,38 +330,6 @@ export default function ChatThread({
|
|||||||
// would be wrong, so on Stop/disconnect/error the queue is left intact for
|
// would be wrong, so on Stop/disconnect/error the queue is left intact for
|
||||||
// the user to decide.
|
// the user to decide.
|
||||||
onFinish: ({ message, isAbort, isDisconnect, isError }) => {
|
onFinish: ({ message, isAbort, isDisconnect, isError }) => {
|
||||||
// (1) Capture whether THIS finish belongs to a resumed (attach) turn and
|
|
||||||
// immediately clear the flag so it can never suppress a LATER local turn.
|
|
||||||
const wasResumed = resumedTurnRef.current;
|
|
||||||
setResumedTurnPair(false);
|
|
||||||
// (2) Recovery after a starved/torn resumed finish (invariant 9). The arm
|
|
||||||
// and the stripped-row restore are gated DIFFERENTLY. Skip entirely once
|
|
||||||
// unmounted (an abort-triggered onFinish landing after a chat switch must
|
|
||||||
// not arm a poll / invalidate on the new chat).
|
|
||||||
if (wasResumed && mountedRef.current) {
|
|
||||||
const hasVisibleContent = assistantMessageHasVisibleContent(message);
|
|
||||||
// ARM the reconcile + degraded poll when the resumed message carries no
|
|
||||||
// visible content (starved replay) OR the connection dropped mid-run — in
|
|
||||||
// both cases the poll must drive the row to its real terminal state.
|
|
||||||
if (isDisconnect || !hasVisibleContent) {
|
|
||||||
reconcileTailRef.current = true;
|
|
||||||
queryClient.invalidateQueries({
|
|
||||||
queryKey: AI_CHAT_MESSAGES_RQ_KEY(chatIdRef.current),
|
|
||||||
});
|
|
||||||
onResumeFallback?.(true);
|
|
||||||
}
|
|
||||||
// RESTORE the stripped streaming row ONLY when the resumed message has no
|
|
||||||
// visible content. On isDisconnect WITH visible content restore is
|
|
||||||
// FORBIDDEN: the live stream may have advanced far past the mount-time
|
|
||||||
// snapshot, so restoring would clobber on-screen content (invariant 9) —
|
|
||||||
// the arm above suffices, the poll reaches the true terminal.
|
|
||||||
if (!hasVisibleContent && strippedRowRef.current) {
|
|
||||||
setMessages((prev) =>
|
|
||||||
mergeById(prev, rowToUiMessage(strippedRowRef.current!)),
|
|
||||||
);
|
|
||||||
}
|
|
||||||
}
|
|
||||||
// (3) Standard branches.
|
|
||||||
// Forward the authoritative server chatId (streamed on the assistant
|
// Forward the authoritative server chatId (streamed on the assistant
|
||||||
// message metadata) so the parent adopts the REAL created chat id for a new
|
// message metadata) so the parent adopts the REAL created chat id for a new
|
||||||
// chat — see adopt-chat-id.ts for the full #137 design. `threadKey` lets the
|
// chat — see adopt-chat-id.ts for the full #137 design. `threadKey` lets the
|
||||||
@@ -494,10 +342,6 @@ export default function ChatThread({
|
|||||||
else if (isAbort) setStopNotice("manual");
|
else if (isAbort) setStopNotice("manual");
|
||||||
else if (isDisconnect) setStopNotice("disconnect");
|
else if (isDisconnect) setStopNotice("disconnect");
|
||||||
else setStopNotice(null);
|
else setStopNotice(null);
|
||||||
// A resumed turn NEVER flushes the queue (invariant 7): skip BOTH the
|
|
||||||
// flush-on-abort branch and the plain flush. The local streamer is the only
|
|
||||||
// tab that owns the queue.
|
|
||||||
if (wasResumed) return;
|
|
||||||
// "Send now": WE triggered this abort to interrupt the current turn and
|
// "Send now": WE triggered this abort to interrupt the current turn and
|
||||||
// immediately send the promoted head. Flush it even though the turn was
|
// immediately send the promoted head. Flush it even though the turn was
|
||||||
// aborted (the normal abort path below keeps the queue intact). The
|
// aborted (the normal abort path below keeps the queue intact). The
|
||||||
@@ -579,98 +423,26 @@ export default function ChatThread({
|
|||||||
|
|
||||||
const isStreaming = status === "submitted" || status === "streaming";
|
const isStreaming = status === "submitted" || status === "streaming";
|
||||||
|
|
||||||
// 204-handler (`onNoActiveStream`): the attach returned 204 — nothing live to
|
// #184: report our live streaming status up so the parent stops polling the run
|
||||||
// resume (overflow / begin-failure / after retention / anchor-mismatch). One-
|
// while WE are the streamer (the SSE owns the view) and resumes once we go idle.
|
||||||
// shot via noStreamHandledRef (we do NOT null onNoActiveStreamRef). Exactly four
|
// Effect (not render) so it never updates parent state during our own render;
|
||||||
// parts. Kept in a ref (read by the transport's fetch closure) and refreshed
|
// fires on mount with `false`, which also re-syncs the parent after a chat
|
||||||
// each render below.
|
// switch remounts this thread (a fresh mount is idle until the user sends).
|
||||||
const onNoActiveStream = useCallback(() => {
|
|
||||||
// A late attach outcome after unmount must not arm a poll / invalidate on the
|
|
||||||
// now-different chat this thread's refs were reused for.
|
|
||||||
if (!mountedRef.current) return;
|
|
||||||
if (noStreamHandledRef.current) return;
|
|
||||||
noStreamHandledRef.current = true;
|
|
||||||
// (a) Restore the stripped streaming row to the store — ONLY when we actually
|
|
||||||
// stripped one (a user-tail 204 does NOT reach here with a stripped row, so do
|
|
||||||
// not dereference null).
|
|
||||||
if (strippedRowRef.current) {
|
|
||||||
setMessages((prev) =>
|
|
||||||
mergeById(prev, rowToUiMessage(strippedRowRef.current!)),
|
|
||||||
);
|
|
||||||
}
|
|
||||||
// (b) Reconcile the tail from the message history + invalidate it so the
|
|
||||||
// degraded poll starts from a fresh fetch.
|
|
||||||
reconcileTailRef.current = true;
|
|
||||||
queryClient.invalidateQueries({
|
|
||||||
queryKey: AI_CHAT_MESSAGES_RQ_KEY(chatIdRef.current),
|
|
||||||
});
|
|
||||||
// (c) Arm the degraded poll (a dumb timer with a 10-min cap in the window);
|
|
||||||
// the thread disarms it via onResumeFallback(false) on settle / local stream.
|
|
||||||
onResumeFallback?.(true);
|
|
||||||
// (d) 204 means onFinish will NOT fire — clear the suppression flag so it
|
|
||||||
// cannot swallow the NEXT local turn's queue flush.
|
|
||||||
setResumedTurnPair(false);
|
|
||||||
}, [setMessages, queryClient, onResumeFallback, setResumedTurnPair]);
|
|
||||||
onNoActiveStreamRef.current = onNoActiveStream;
|
|
||||||
|
|
||||||
// Mount effect: kick off the resume attempt for a non-settled tail. Marking the
|
|
||||||
// turn as resumed BEFORE resumeStream so onFinish (invariant 7/8) sees it.
|
|
||||||
useEffect(() => {
|
useEffect(() => {
|
||||||
// Re-arm on (re)mount — StrictMode dev-mounts twice, and the cleanup below
|
onStreamingChange?.(isStreaming);
|
||||||
// flips this false between the two.
|
}, [isStreaming, onStreamingChange]);
|
||||||
mountedRef.current = true;
|
|
||||||
if (attemptResumeRef.current) {
|
|
||||||
setResumedTurnPair(true);
|
|
||||||
void resumeStream();
|
|
||||||
}
|
|
||||||
// Unmount: mark unmounted (gates late attach/onFinish side-effects) and abort
|
|
||||||
// the in-flight attach GET so its callbacks don't fire against the next chat.
|
|
||||||
return () => {
|
|
||||||
mountedRef.current = false;
|
|
||||||
attachAbortRef.current?.abort();
|
|
||||||
};
|
|
||||||
// Mount-only by design; the parent remounts per chat via `key`.
|
|
||||||
// eslint-disable-next-line react-hooks/exhaustive-deps
|
|
||||||
}, []);
|
|
||||||
|
|
||||||
// Reconciliation + degraded-merge (invariant 8). Deps are EXACTLY
|
// #184 passive-observer merge: when the parent feeds a polled run message (we
|
||||||
// [initialRows, isStreaming, setMessages].
|
// reopened a chat whose run is still going and did NOT start it here), merge it
|
||||||
|
// into the live list so new steps/tool-calls appear as they are persisted. Hard-
|
||||||
|
// gated by `!isStreaming`: if THIS tab is actually the streamer, the local SSE
|
||||||
|
// owns the view and a stale observedRow must never overwrite it. `observedRow`
|
||||||
|
// is a stable per-poll object, so this runs once per poll, not per render.
|
||||||
useEffect(() => {
|
useEffect(() => {
|
||||||
// A local stream owns the view: disarm BOTH the merge and the window poll.
|
if (isStreaming || !observedRow) return;
|
||||||
if (isStreaming) {
|
const observed = rowToUiMessage(observedRow);
|
||||||
reconcileTailRef.current = false;
|
setMessages((prev) => mergeObservedMessage(prev, observed));
|
||||||
onResumeFallback?.(false);
|
}, [observedRow, isStreaming, setMessages]);
|
||||||
return;
|
|
||||||
}
|
|
||||||
if (!reconcileTailRef.current) return;
|
|
||||||
const rows = initialRows ?? [];
|
|
||||||
const tail = rows[rows.length - 1];
|
|
||||||
if (!tail || tail.role !== "assistant") return;
|
|
||||||
// Merge the polled assistant tail on EVERY initialRows update — while the
|
|
||||||
// degraded poll is active this IS the live per-step progress.
|
|
||||||
setMessages((prev) => mergeById(prev, rowToUiMessage(tail)));
|
|
||||||
// Anchor-mismatch coherence: when we restored a stripped streaming row A but a
|
|
||||||
// DIFFERENT run's row B is now the tail (A finished, B replaced the registry
|
|
||||||
// entry, so the attach 204'd), A would otherwise linger forever as an orphan
|
|
||||||
// jumping-dots row over the real run. Settle it from fresh history (where A is
|
|
||||||
// now persisted) so no phantom row survives. No-op in the common case where A
|
|
||||||
// IS the tail (id match).
|
|
||||||
const stripped = strippedRowRef.current;
|
|
||||||
if (stripped && stripped.id !== tail.id) {
|
|
||||||
const historical = rows.find((r) => r.id === stripped.id);
|
|
||||||
if (historical)
|
|
||||||
setMessages((prev) => mergeById(prev, rowToUiMessage(historical)));
|
|
||||||
}
|
|
||||||
// Settled: the terminal merge is done — disarm the flag AND the window poll
|
|
||||||
// explicitly (the window only has a time cap, it will not disarm itself).
|
|
||||||
if (tail.status !== "streaming") {
|
|
||||||
reconcileTailRef.current = false;
|
|
||||||
onResumeFallback?.(false);
|
|
||||||
}
|
|
||||||
// onResumeFallback intentionally omitted (parent-stable callback); deps are
|
|
||||||
// fixed by the resume design.
|
|
||||||
// eslint-disable-next-line react-hooks/exhaustive-deps
|
|
||||||
}, [initialRows, isStreaming, setMessages]);
|
|
||||||
|
|
||||||
// "Send now" on a queued message: interrupt the current turn and immediately
|
// "Send now" on a queued message: interrupt the current turn and immediately
|
||||||
// send THIS message, keeping the agent's partial output. Other queued messages
|
// send THIS message, keeping the agent's partial output. Other queued messages
|
||||||
@@ -697,12 +469,10 @@ export default function ChatThread({
|
|||||||
const msg = queuedRef.current.find((m) => m.id === id);
|
const msg = queuedRef.current.find((m) => m.id === id);
|
||||||
if (!msg) return;
|
if (!msg) return;
|
||||||
setQueue(removeQueuedById(queuedRef.current, id));
|
setQueue(removeQueuedById(queuedRef.current, id));
|
||||||
// Local send: clear any resume-suppression flag (invariant 8).
|
|
||||||
setResumedTurnPair(false);
|
|
||||||
sendMessageRef.current?.({ text: msg.text });
|
sendMessageRef.current?.({ text: msg.text });
|
||||||
}
|
}
|
||||||
},
|
},
|
||||||
[setQueue, stop, setResumedTurnPair],
|
[setQueue, stop],
|
||||||
);
|
);
|
||||||
|
|
||||||
// Stop the current turn. ALWAYS abort the local SSE (`stop()`) so the composer
|
// Stop the current turn. ALWAYS abort the local SSE (`stop()`) so the composer
|
||||||
@@ -715,9 +485,6 @@ export default function ChatThread({
|
|||||||
// is not known yet — a brand-new chat in the first moment of its first turn —
|
// is not known yet — a brand-new chat in the first moment of its first turn —
|
||||||
// only the local abort happens (there is no server-side run handle to stop yet).
|
// only the local abort happens (there is no server-side run handle to stop yet).
|
||||||
const handleStop = useCallback(() => {
|
const handleStop = useCallback(() => {
|
||||||
// Abort the resume/attach GET first: the SDK does not pass it a signal, so an
|
|
||||||
// observer's Stop would otherwise leave the attach fetch running.
|
|
||||||
attachAbortRef.current?.abort();
|
|
||||||
stop();
|
stop();
|
||||||
if (!autonomousRunsEnabled) return;
|
if (!autonomousRunsEnabled) return;
|
||||||
if (chatIdRef.current) {
|
if (chatIdRef.current) {
|
||||||
@@ -850,23 +617,17 @@ export default function ChatThread({
|
|||||||
<Text size="xs" lineClamp={2} className={classes.queuedText}>
|
<Text size="xs" lineClamp={2} className={classes.queuedText}>
|
||||||
{m.text}
|
{m.text}
|
||||||
</Text>
|
</Text>
|
||||||
{/* "Send now" (interrupt) is hidden on a RESUMED turn: a local
|
<Tooltip label={t("Interrupt and send now")} withArrow>
|
||||||
stop() does not abort the resumed attach fetch, so the click
|
<ActionIcon
|
||||||
would be swallowed while flushOnAbortRef would fire minutes
|
size="xs"
|
||||||
later on the natural finish. Only the remove affordance stays. */}
|
variant="subtle"
|
||||||
{!resumedTurn && (
|
color="blue"
|
||||||
<Tooltip label={t("Interrupt and send now")} withArrow>
|
onClick={() => sendNow(m.id)}
|
||||||
<ActionIcon
|
aria-label={t("Send now")}
|
||||||
size="xs"
|
>
|
||||||
variant="subtle"
|
<IconPlayerPlayFilled size={12} />
|
||||||
color="blue"
|
</ActionIcon>
|
||||||
onClick={() => sendNow(m.id)}
|
</Tooltip>
|
||||||
aria-label={t("Send now")}
|
|
||||||
>
|
|
||||||
<IconPlayerPlayFilled size={12} />
|
|
||||||
</ActionIcon>
|
|
||||||
</Tooltip>
|
|
||||||
)}
|
|
||||||
<ActionIcon
|
<ActionIcon
|
||||||
size="xs"
|
size="xs"
|
||||||
variant="subtle"
|
variant="subtle"
|
||||||
@@ -881,11 +642,7 @@ export default function ChatThread({
|
|||||||
</Stack>
|
</Stack>
|
||||||
)}
|
)}
|
||||||
<ChatInput
|
<ChatInput
|
||||||
onSend={(text) => {
|
onSend={(text) => sendMessage({ text })}
|
||||||
// Local send: clear any resume-suppression flag (invariant 8).
|
|
||||||
setResumedTurnPair(false);
|
|
||||||
sendMessage({ text });
|
|
||||||
}}
|
|
||||||
onQueue={enqueue}
|
onQueue={enqueue}
|
||||||
onStop={handleStop}
|
onStop={handleStop}
|
||||||
isStreaming={isStreaming}
|
isStreaming={isStreaming}
|
||||||
|
|||||||
@@ -40,13 +40,6 @@ interface MessageItemProps {
|
|||||||
* Defaults to true (internal chat). The public share passes false.
|
* Defaults to true (internal chat). The public share passes false.
|
||||||
*/
|
*/
|
||||||
showCitations?: boolean;
|
showCitations?: boolean;
|
||||||
/**
|
|
||||||
* Forwarded to ToolCallCard: whether tool cards render the one-line summary of
|
|
||||||
* a call's arguments (e.g. the search query). Defaults to true (internal
|
|
||||||
* chat). The public share passes false so an anonymous reader doesn't see the
|
|
||||||
* agent's raw query/argument text.
|
|
||||||
*/
|
|
||||||
showInput?: boolean;
|
|
||||||
/**
|
/**
|
||||||
* Neutralize internal/relative markdown links in the rendered answer (drop
|
* Neutralize internal/relative markdown links in the rendered answer (drop
|
||||||
* their href so they become inert text). Defaults to false (internal chat,
|
* their href so they become inert text). Defaults to false (internal chat,
|
||||||
@@ -124,7 +117,6 @@ const MarkdownPart = memo(function MarkdownPart({
|
|||||||
function MessageItem({
|
function MessageItem({
|
||||||
message,
|
message,
|
||||||
showCitations = true,
|
showCitations = true,
|
||||||
showInput = true,
|
|
||||||
neutralizeInternalLinks = false,
|
neutralizeInternalLinks = false,
|
||||||
assistantName,
|
assistantName,
|
||||||
turnStreaming = false,
|
turnStreaming = false,
|
||||||
@@ -218,7 +210,6 @@ function MessageItem({
|
|||||||
key={index}
|
key={index}
|
||||||
part={part as unknown as ToolUiPart}
|
part={part as unknown as ToolUiPart}
|
||||||
showCitations={showCitations}
|
showCitations={showCitations}
|
||||||
showInput={showInput}
|
|
||||||
/>
|
/>
|
||||||
);
|
);
|
||||||
}
|
}
|
||||||
@@ -283,7 +274,6 @@ export function arePropsEqual(
|
|||||||
return (
|
return (
|
||||||
prev.signature === next.signature &&
|
prev.signature === next.signature &&
|
||||||
prev.showCitations === next.showCitations &&
|
prev.showCitations === next.showCitations &&
|
||||||
prev.showInput === next.showInput &&
|
|
||||||
prev.neutralizeInternalLinks === next.neutralizeInternalLinks &&
|
prev.neutralizeInternalLinks === next.neutralizeInternalLinks &&
|
||||||
prev.assistantName === next.assistantName &&
|
prev.assistantName === next.assistantName &&
|
||||||
// The turn-end flip re-renders every row once (cheap, terminal event) —
|
// The turn-end flip re-renders every row once (cheap, terminal event) —
|
||||||
|
|||||||
@@ -25,13 +25,6 @@ interface MessageListProps {
|
|||||||
* false because an anonymous reader cannot open the linked internal pages.
|
* false because an anonymous reader cannot open the linked internal pages.
|
||||||
*/
|
*/
|
||||||
showCitations?: boolean;
|
showCitations?: boolean;
|
||||||
/**
|
|
||||||
* Forwarded to MessageItem -> ToolCallCard: whether tool cards render the
|
|
||||||
* one-line summary of a call's arguments (e.g. the search query). Defaults to
|
|
||||||
* true (internal chat). The public share passes false so an anonymous reader
|
|
||||||
* doesn't see the agent's raw query/argument text.
|
|
||||||
*/
|
|
||||||
showInput?: boolean;
|
|
||||||
/**
|
/**
|
||||||
* Forwarded to MessageItem: neutralize internal/relative markdown links in
|
* Forwarded to MessageItem: neutralize internal/relative markdown links in
|
||||||
* the rendered answers (drop their href so they render as inert text).
|
* the rendered answers (drop their href so they render as inert text).
|
||||||
@@ -126,7 +119,6 @@ export default function MessageList({
|
|||||||
isStreaming,
|
isStreaming,
|
||||||
emptyState,
|
emptyState,
|
||||||
showCitations = true,
|
showCitations = true,
|
||||||
showInput = true,
|
|
||||||
neutralizeInternalLinks = false,
|
neutralizeInternalLinks = false,
|
||||||
assistantName,
|
assistantName,
|
||||||
}: MessageListProps) {
|
}: MessageListProps) {
|
||||||
@@ -216,7 +208,6 @@ export default function MessageList({
|
|||||||
message={message}
|
message={message}
|
||||||
signature={messageSignature(message)}
|
signature={messageSignature(message)}
|
||||||
showCitations={showCitations}
|
showCitations={showCitations}
|
||||||
showInput={showInput}
|
|
||||||
neutralizeInternalLinks={neutralizeInternalLinks}
|
neutralizeInternalLinks={neutralizeInternalLinks}
|
||||||
assistantName={assistantName}
|
assistantName={assistantName}
|
||||||
// Turn-level liveness, gated to the TAIL row: only the tail message
|
// Turn-level liveness, gated to the TAIL row: only the tail message
|
||||||
|
|||||||
@@ -5,7 +5,6 @@ import { useTranslation } from "react-i18next";
|
|||||||
import {
|
import {
|
||||||
getToolName,
|
getToolName,
|
||||||
toolCitations,
|
toolCitations,
|
||||||
toolInputSummary,
|
|
||||||
toolLabelKey,
|
toolLabelKey,
|
||||||
toolRunState,
|
toolRunState,
|
||||||
ToolUiPart,
|
ToolUiPart,
|
||||||
@@ -22,14 +21,6 @@ interface ToolCallCardProps {
|
|||||||
* (the action log itself) while dropping the unusable links.
|
* (the action log itself) while dropping the unusable links.
|
||||||
*/
|
*/
|
||||||
showCitations?: boolean;
|
showCitations?: boolean;
|
||||||
/**
|
|
||||||
* Whether to render the one-line summary of the call's arguments (e.g. the
|
|
||||||
* search query) under the label. Defaults to true (the internal chat). The
|
|
||||||
* public share passes false: an anonymous reader should not see the agent's
|
|
||||||
* raw query/argument text. Conservative and reversible — it only suppresses
|
|
||||||
* the extra summary line, leaving the card (the action log) intact.
|
|
||||||
*/
|
|
||||||
showInput?: boolean;
|
|
||||||
}
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
@@ -40,14 +31,12 @@ interface ToolCallCardProps {
|
|||||||
export default function ToolCallCard({
|
export default function ToolCallCard({
|
||||||
part,
|
part,
|
||||||
showCitations = true,
|
showCitations = true,
|
||||||
showInput = true,
|
|
||||||
}: ToolCallCardProps) {
|
}: ToolCallCardProps) {
|
||||||
const { t } = useTranslation();
|
const { t } = useTranslation();
|
||||||
const toolName = getToolName(part);
|
const toolName = getToolName(part);
|
||||||
const state = toolRunState(part.state);
|
const state = toolRunState(part.state);
|
||||||
const { key, values } = toolLabelKey(toolName);
|
const { key, values } = toolLabelKey(toolName);
|
||||||
const citations = showCitations ? toolCitations(part) : [];
|
const citations = showCitations ? toolCitations(part) : [];
|
||||||
const inputSummary = showInput ? toolInputSummary(part) : undefined;
|
|
||||||
|
|
||||||
return (
|
return (
|
||||||
<div className={classes.toolCard}>
|
<div className={classes.toolCard}>
|
||||||
@@ -68,12 +57,6 @@ export default function ToolCallCard({
|
|||||||
</Text>
|
</Text>
|
||||||
</Group>
|
</Group>
|
||||||
|
|
||||||
{inputSummary && (
|
|
||||||
<Text size="xs" c="dimmed" mt={2} lineClamp={2}>
|
|
||||||
{inputSummary}
|
|
||||||
</Text>
|
|
||||||
)}
|
|
||||||
|
|
||||||
{state === "error" && part.errorText && (
|
{state === "error" && part.errorText && (
|
||||||
<Text size="xs" c="red" mt={2}>
|
<Text size="xs" c="red" mt={2}>
|
||||||
{part.errorText}
|
{part.errorText}
|
||||||
|
|||||||
@@ -1,90 +0,0 @@
|
|||||||
import { describe, it, expect, vi, beforeEach } from "vitest";
|
|
||||||
import React from "react";
|
|
||||||
import { renderHook, waitFor } from "@testing-library/react";
|
|
||||||
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
|
|
||||||
|
|
||||||
// react-i18next / notifications are pulled in transitively by ai-chat-query.ts
|
|
||||||
// (the mutation hooks use them); stub so the module imports cleanly.
|
|
||||||
vi.mock("react-i18next", () => ({
|
|
||||||
useTranslation: () => ({ t: (key: string) => key }),
|
|
||||||
}));
|
|
||||||
vi.mock("@mantine/notifications", () => ({
|
|
||||||
notifications: { show: vi.fn() },
|
|
||||||
}));
|
|
||||||
|
|
||||||
// Mock the service module; only getAiChatMessages is exercised, but the other
|
|
||||||
// named exports must exist so ai-chat-query.ts imports resolve.
|
|
||||||
vi.mock("@/features/ai-chat/services/ai-chat-service.ts", () => ({
|
|
||||||
getAiChatMessages: vi.fn(),
|
|
||||||
getAiChats: vi.fn(),
|
|
||||||
getAiRoleCatalog: vi.fn(),
|
|
||||||
getAiRoleCatalogBundle: vi.fn(),
|
|
||||||
getAiRoles: vi.fn(),
|
|
||||||
importAiRolesFromCatalog: vi.fn(),
|
|
||||||
createAiRole: vi.fn(),
|
|
||||||
deleteAiChat: vi.fn(),
|
|
||||||
deleteAiRole: vi.fn(),
|
|
||||||
renameAiChat: vi.fn(),
|
|
||||||
updateAiRole: vi.fn(),
|
|
||||||
updateAiRoleFromCatalog: vi.fn(),
|
|
||||||
}));
|
|
||||||
|
|
||||||
import { getAiChatMessages } from "@/features/ai-chat/services/ai-chat-service.ts";
|
|
||||||
import { useAiChatMessagesQuery } from "@/features/ai-chat/queries/ai-chat-query.ts";
|
|
||||||
|
|
||||||
const emptyPage = { items: [], meta: { hasNextPage: false, nextCursor: null } };
|
|
||||||
|
|
||||||
function createWrapper() {
|
|
||||||
const queryClient = new QueryClient({
|
|
||||||
defaultOptions: { queries: { retry: false } },
|
|
||||||
});
|
|
||||||
return function Wrapper({ children }: { children: React.ReactNode }) {
|
|
||||||
return (
|
|
||||||
<QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
|
|
||||||
);
|
|
||||||
};
|
|
||||||
}
|
|
||||||
|
|
||||||
// The degraded-poll fallback (#184 phase 1.5) is threaded into this query as a
|
|
||||||
// `refetchInterval`; AiChatWindow supplies the deliberately-dumb callback. These
|
|
||||||
// pin the plumbing the window depends on: the interval polls the message history,
|
|
||||||
// and — critically — fetch ERRORS do NOT stop the tick (TanStack v5 resets the
|
|
||||||
// failure count each fetch, so the poll must survive a server restart).
|
|
||||||
describe("useAiChatMessagesQuery — degraded refetchInterval", () => {
|
|
||||||
beforeEach(() => {
|
|
||||||
vi.clearAllMocks();
|
|
||||||
});
|
|
||||||
|
|
||||||
it("re-polls at the interval while the callback returns a duration", async () => {
|
|
||||||
vi.mocked(getAiChatMessages).mockResolvedValue(emptyPage as never);
|
|
||||||
renderHook(() => useAiChatMessagesQuery("c1", () => 30), {
|
|
||||||
wrapper: createWrapper(),
|
|
||||||
});
|
|
||||||
await waitFor(() =>
|
|
||||||
expect(vi.mocked(getAiChatMessages).mock.calls.length).toBeGreaterThan(2),
|
|
||||||
);
|
|
||||||
});
|
|
||||||
|
|
||||||
it("does NOT re-poll when the callback returns false", async () => {
|
|
||||||
vi.mocked(getAiChatMessages).mockResolvedValue(emptyPage as never);
|
|
||||||
renderHook(() => useAiChatMessagesQuery("c1", () => false), {
|
|
||||||
wrapper: createWrapper(),
|
|
||||||
});
|
|
||||||
await waitFor(() =>
|
|
||||||
expect(vi.mocked(getAiChatMessages)).toHaveBeenCalledTimes(1),
|
|
||||||
);
|
|
||||||
// Give any errant interval a chance to fire, then assert it did not.
|
|
||||||
await new Promise((r) => setTimeout(r, 60));
|
|
||||||
expect(vi.mocked(getAiChatMessages)).toHaveBeenCalledTimes(1);
|
|
||||||
});
|
|
||||||
|
|
||||||
it("keeps ticking through fetch errors (errors do not gate the poll)", async () => {
|
|
||||||
vi.mocked(getAiChatMessages).mockRejectedValue(new Error("server down"));
|
|
||||||
renderHook(() => useAiChatMessagesQuery("c1", () => 30), {
|
|
||||||
wrapper: createWrapper(),
|
|
||||||
});
|
|
||||||
await waitFor(() =>
|
|
||||||
expect(vi.mocked(getAiChatMessages).mock.calls.length).toBeGreaterThan(2),
|
|
||||||
);
|
|
||||||
});
|
|
||||||
});
|
|
||||||
@@ -13,6 +13,7 @@ import {
|
|||||||
deleteAiChat,
|
deleteAiChat,
|
||||||
deleteAiRole,
|
deleteAiRole,
|
||||||
getAiChatMessages,
|
getAiChatMessages,
|
||||||
|
getAiChatRun,
|
||||||
getAiChats,
|
getAiChats,
|
||||||
getAiRoleCatalog,
|
getAiRoleCatalog,
|
||||||
getAiRoleCatalogBundle,
|
getAiRoleCatalogBundle,
|
||||||
@@ -25,6 +26,7 @@ import {
|
|||||||
import {
|
import {
|
||||||
IAiChat,
|
IAiChat,
|
||||||
IAiChatMessageRow,
|
IAiChatMessageRow,
|
||||||
|
IAiChatRunResponse,
|
||||||
IAiRole,
|
IAiRole,
|
||||||
IAiRoleCatalog,
|
IAiRoleCatalog,
|
||||||
IAiRoleCatalogBundle,
|
IAiRoleCatalogBundle,
|
||||||
@@ -35,6 +37,7 @@ import {
|
|||||||
IAiRoleUpdateFromCatalogResult,
|
IAiRoleUpdateFromCatalogResult,
|
||||||
} from "@/features/ai-chat/types/ai-chat.types.ts";
|
} from "@/features/ai-chat/types/ai-chat.types.ts";
|
||||||
import { IPagination } from "@/lib/types.ts";
|
import { IPagination } from "@/lib/types.ts";
|
||||||
|
import { runPollInterval } from "@/features/ai-chat/utils/run-polling.ts";
|
||||||
|
|
||||||
export const AI_CHATS_RQ_KEY = ["ai-chats"];
|
export const AI_CHATS_RQ_KEY = ["ai-chats"];
|
||||||
export const AI_ROLES_RQ_KEY = ["ai-roles"];
|
export const AI_ROLES_RQ_KEY = ["ai-roles"];
|
||||||
@@ -52,6 +55,7 @@ export const AI_CHAT_MESSAGES_RQ_KEY = (chatId: string) => [
|
|||||||
"ai-chat-messages",
|
"ai-chat-messages",
|
||||||
chatId,
|
chatId,
|
||||||
];
|
];
|
||||||
|
export const AI_CHAT_RUN_RQ_KEY = (chatId: string) => ["ai-chat-run", chatId];
|
||||||
|
|
||||||
/** Paginated list of the current user's chats (auto-loads further pages). */
|
/** Paginated list of the current user's chats (auto-loads further pages). */
|
||||||
export function useAiChatsQuery() {
|
export function useAiChatsQuery() {
|
||||||
@@ -85,15 +89,7 @@ export function useAiChatsQuery() {
|
|||||||
* Load all persisted messages of a chat (oldest first), flattening the
|
* Load all persisted messages of a chat (oldest first), flattening the
|
||||||
* paginated server response. Used to seed `useChat` initial messages.
|
* paginated server response. Used to seed `useChat` initial messages.
|
||||||
*/
|
*/
|
||||||
export function useAiChatMessagesQuery(
|
export function useAiChatMessagesQuery(chatId: string | undefined) {
|
||||||
chatId: string | undefined,
|
|
||||||
// #184 phase 1.5: the degraded-poll fallback. When a tab could not attach to a
|
|
||||||
// still-running run (the attach returned 204 / the resumed stream ended with no
|
|
||||||
// terminal row), the window arms a dumb timed poll of the message history to
|
|
||||||
// follow the detached run to settle. The callback form lives in AiChatWindow;
|
|
||||||
// threaded here verbatim so this query owns the polling. Undefined => no poll.
|
|
||||||
refetchInterval?: number | false | (() => number | false),
|
|
||||||
) {
|
|
||||||
const query = useInfiniteQuery({
|
const query = useInfiniteQuery({
|
||||||
queryKey: AI_CHAT_MESSAGES_RQ_KEY(chatId ?? ""),
|
queryKey: AI_CHAT_MESSAGES_RQ_KEY(chatId ?? ""),
|
||||||
queryFn: ({ pageParam }) =>
|
queryFn: ({ pageParam }) =>
|
||||||
@@ -104,7 +100,6 @@ export function useAiChatMessagesQuery(
|
|||||||
? (lastPage.meta.nextCursor ?? undefined)
|
? (lastPage.meta.nextCursor ?? undefined)
|
||||||
: undefined,
|
: undefined,
|
||||||
enabled: !!chatId,
|
enabled: !!chatId,
|
||||||
refetchInterval,
|
|
||||||
});
|
});
|
||||||
|
|
||||||
// useInfiniteQuery only fetches the first page on its own. The hook's contract
|
// useInfiniteQuery only fetches the first page on its own. The hook's contract
|
||||||
@@ -144,6 +139,34 @@ export function useAiChatMessagesQuery(
|
|||||||
};
|
};
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Reconnect to a chat's latest agent run and LIVE-FOLLOW it (#184). While the run
|
||||||
|
* is active the query re-polls every {@link runPollInterval} ms (driven off the
|
||||||
|
* fetched `run.status`, the same status-keyed refetchInterval pattern as the
|
||||||
|
* embeddings reindex polling); once the run reaches a terminal status — or there
|
||||||
|
* is no run — the interval returns `false` and polling stops on its own. Polling
|
||||||
|
* is thus naturally bounded by the run terminating; no separate timeout cap.
|
||||||
|
*
|
||||||
|
* `enabled` gates the whole thing: callers pass `false` when the autonomous-runs
|
||||||
|
* feature is off (the endpoint is NOT flag-gated server-side, but with the feature
|
||||||
|
* off the chat has no runs, so polling would only ever return `{ run: null }`) OR
|
||||||
|
* when THIS tab is the one actively streaming the run (the live SSE owns the view,
|
||||||
|
* so we must not also poll/merge). The global `retry: false` means a failed fetch
|
||||||
|
* leaves `data` undefined, so refetchInterval(undefined run) returns false — a
|
||||||
|
* failed fetch can never spin a tight loop.
|
||||||
|
*/
|
||||||
|
export function useAiChatRunQuery(
|
||||||
|
chatId: string | undefined,
|
||||||
|
enabled: boolean,
|
||||||
|
) {
|
||||||
|
return useQuery<IAiChatRunResponse, Error>({
|
||||||
|
queryKey: AI_CHAT_RUN_RQ_KEY(chatId ?? ""),
|
||||||
|
queryFn: () => getAiChatRun(chatId as string),
|
||||||
|
enabled: !!chatId && enabled,
|
||||||
|
refetchInterval: (query) => runPollInterval(query.state.data?.run),
|
||||||
|
});
|
||||||
|
}
|
||||||
|
|
||||||
export function useRenameAiChatMutation() {
|
export function useRenameAiChatMutation() {
|
||||||
const queryClient = useQueryClient();
|
const queryClient = useQueryClient();
|
||||||
const { t } = useTranslation();
|
const { t } = useTranslation();
|
||||||
|
|||||||
@@ -0,0 +1,92 @@
|
|||||||
|
import { describe, it, expect, vi, beforeEach } from "vitest";
|
||||||
|
import React from "react";
|
||||||
|
import { renderHook, waitFor } from "@testing-library/react";
|
||||||
|
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
|
||||||
|
import type { IAiChatRunResponse } from "@/features/ai-chat/types/ai-chat.types.ts";
|
||||||
|
|
||||||
|
// react-i18next is pulled in transitively by ai-chat-query.ts (the mutation hooks
|
||||||
|
// use it); stub it so the module imports cleanly in this hook test.
|
||||||
|
vi.mock("react-i18next", () => ({
|
||||||
|
useTranslation: () => ({ t: (key: string) => key }),
|
||||||
|
}));
|
||||||
|
|
||||||
|
vi.mock("@mantine/notifications", () => ({
|
||||||
|
notifications: { show: vi.fn() },
|
||||||
|
}));
|
||||||
|
|
||||||
|
// Mock the whole service module; only getAiChatRun is exercised here, but the
|
||||||
|
// other named exports must exist so ai-chat-query.ts imports resolve.
|
||||||
|
vi.mock("@/features/ai-chat/services/ai-chat-service.ts", () => ({
|
||||||
|
getAiChatRun: vi.fn(),
|
||||||
|
getAiChatMessages: vi.fn(),
|
||||||
|
getAiChats: vi.fn(),
|
||||||
|
getAiRoleCatalog: vi.fn(),
|
||||||
|
getAiRoleCatalogBundle: vi.fn(),
|
||||||
|
getAiRoles: vi.fn(),
|
||||||
|
importAiRolesFromCatalog: vi.fn(),
|
||||||
|
createAiRole: vi.fn(),
|
||||||
|
deleteAiChat: vi.fn(),
|
||||||
|
deleteAiRole: vi.fn(),
|
||||||
|
renameAiChat: vi.fn(),
|
||||||
|
updateAiRole: vi.fn(),
|
||||||
|
updateAiRoleFromCatalog: vi.fn(),
|
||||||
|
}));
|
||||||
|
|
||||||
|
import { getAiChatRun } from "@/features/ai-chat/services/ai-chat-service.ts";
|
||||||
|
import { useAiChatRunQuery } from "@/features/ai-chat/queries/ai-chat-query.ts";
|
||||||
|
|
||||||
|
function createWrapper() {
|
||||||
|
const queryClient = new QueryClient({
|
||||||
|
defaultOptions: { queries: { retry: false } },
|
||||||
|
});
|
||||||
|
return function Wrapper({ children }: { children: React.ReactNode }) {
|
||||||
|
return (
|
||||||
|
<QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
|
||||||
|
);
|
||||||
|
};
|
||||||
|
}
|
||||||
|
|
||||||
|
const runningResponse: IAiChatRunResponse = {
|
||||||
|
run: { id: "run-1", chatId: "c1", status: "running" },
|
||||||
|
message: {
|
||||||
|
id: "a1",
|
||||||
|
role: "assistant",
|
||||||
|
content: "working...",
|
||||||
|
createdAt: "2026-01-01T00:00:00Z",
|
||||||
|
},
|
||||||
|
};
|
||||||
|
|
||||||
|
describe("useAiChatRunQuery — enable gating", () => {
|
||||||
|
beforeEach(() => {
|
||||||
|
vi.clearAllMocks();
|
||||||
|
});
|
||||||
|
|
||||||
|
it("fetches the run when enabled (passive observer, feature on)", async () => {
|
||||||
|
vi.mocked(getAiChatRun).mockResolvedValue(runningResponse);
|
||||||
|
const { result } = renderHook(() => useAiChatRunQuery("c1", true), {
|
||||||
|
wrapper: createWrapper(),
|
||||||
|
});
|
||||||
|
await waitFor(() => expect(result.current.isSuccess).toBe(true));
|
||||||
|
expect(getAiChatRun).toHaveBeenCalledWith("c1");
|
||||||
|
expect(result.current.data?.run?.status).toBe("running");
|
||||||
|
});
|
||||||
|
|
||||||
|
it("does NOT fetch when disabled (this tab is the streamer / feature off)", async () => {
|
||||||
|
vi.mocked(getAiChatRun).mockResolvedValue(runningResponse);
|
||||||
|
renderHook(() => useAiChatRunQuery("c1", false), {
|
||||||
|
wrapper: createWrapper(),
|
||||||
|
});
|
||||||
|
// Give any errant fetch a chance to fire, then assert none did.
|
||||||
|
await new Promise((r) => setTimeout(r, 20));
|
||||||
|
expect(getAiChatRun).not.toHaveBeenCalled();
|
||||||
|
});
|
||||||
|
|
||||||
|
it("does NOT fetch when there is no chat id", async () => {
|
||||||
|
vi.mocked(getAiChatRun).mockResolvedValue(runningResponse);
|
||||||
|
renderHook(() => useAiChatRunQuery(undefined, true), {
|
||||||
|
wrapper: createWrapper(),
|
||||||
|
});
|
||||||
|
await new Promise((r) => setTimeout(r, 20));
|
||||||
|
expect(getAiChatRun).not.toHaveBeenCalled();
|
||||||
|
});
|
||||||
|
});
|
||||||
@@ -5,6 +5,7 @@ import {
|
|||||||
IAiChatListParams,
|
IAiChatListParams,
|
||||||
IAiChatMessageRow,
|
IAiChatMessageRow,
|
||||||
IAiChatMessagesParams,
|
IAiChatMessagesParams,
|
||||||
|
IAiChatRunResponse,
|
||||||
IAiRole,
|
IAiRole,
|
||||||
IAiRoleCatalog,
|
IAiRoleCatalog,
|
||||||
IAiRoleCatalogBundle,
|
IAiRoleCatalogBundle,
|
||||||
@@ -42,6 +43,23 @@ export async function getAiChatMessages(
|
|||||||
return req.data;
|
return req.data;
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Reconnect to the latest agent run of a chat (#184). Returns the run's
|
||||||
|
* persisted lifecycle state and the assistant message it materializes (the
|
||||||
|
* partial output while the run is in-flight, the final output once it finished).
|
||||||
|
* The DB is the source of truth, so this works for an in-flight run (the browser
|
||||||
|
* dropped, the run kept going) and a finished one alike; `{ run: null }` when the
|
||||||
|
* chat has never had a run. Owner-gated server-side (the requesting user must own
|
||||||
|
* the chat); it is NOT flag-gated — when the feature is off the chat simply has no
|
||||||
|
* runs, so the endpoint returns `{ run: null }`.
|
||||||
|
*/
|
||||||
|
export async function getAiChatRun(
|
||||||
|
chatId: string,
|
||||||
|
): Promise<IAiChatRunResponse> {
|
||||||
|
const req = await api.post<IAiChatRunResponse>("/ai-chat/run", { chatId });
|
||||||
|
return req.data;
|
||||||
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Explicitly STOP the active agent run of a chat (#184). This is the ONLY thing
|
* Explicitly STOP the active agent run of a chat (#184). This is the ONLY thing
|
||||||
* that ends a DETACHED run — a mere browser disconnect (aborting the local SSE)
|
* that ends a DETACHED run — a mere browser disconnect (aborting the local SSE)
|
||||||
|
|||||||
@@ -210,14 +210,41 @@ export interface IAiChatMessageRow {
|
|||||||
// renders a "stopped" marker on interrupted turns.
|
// renders a "stopped" marker on interrupted turns.
|
||||||
finishReason?: string;
|
finishReason?: string;
|
||||||
} | null;
|
} | null;
|
||||||
// Persisted lifecycle status of the row's turn, carried on the wire by
|
|
||||||
// `baseFields`. 'streaming' marks a still-in-progress assistant row (used by
|
|
||||||
// the resume machinery to decide whether a tail is a live stream to attach to
|
|
||||||
// or a settled row that must not be replayed).
|
|
||||||
status?: string;
|
|
||||||
createdAt: string;
|
createdAt: string;
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* A persisted agent-run row (#184), mirroring the `ai_chat_runs` fields the
|
||||||
|
* client reads from `POST /ai-chat/run`. Only `status` is load-bearing for the
|
||||||
|
* reconnect-and-live-update UX (it drives the poll cadence); the rest are carried
|
||||||
|
* for display/diagnostics. The DB is the source of truth, so this resolves for an
|
||||||
|
* in-flight run (the browser dropped, the run kept going) and a finished one.
|
||||||
|
*/
|
||||||
|
export interface IAiChatRun {
|
||||||
|
id: string;
|
||||||
|
chatId: string;
|
||||||
|
// 'pending' | 'running' | 'succeeded' | 'failed' | 'aborted'. The first two are
|
||||||
|
// ACTIVE (keep polling); the rest are TERMINAL (stop polling).
|
||||||
|
status: "pending" | "running" | "succeeded" | "failed" | "aborted" | string;
|
||||||
|
error?: string | null;
|
||||||
|
stepCount?: number;
|
||||||
|
assistantMessageId?: string | null;
|
||||||
|
startedAt?: string | null;
|
||||||
|
finishedAt?: string | null;
|
||||||
|
createdAt?: string;
|
||||||
|
updatedAt?: string;
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Response of `POST /ai-chat/run` (#184): the latest run of a chat and the
|
||||||
|
* assistant message it materializes (the partial/final output, projected from the
|
||||||
|
* persisted rows). Both are `null` when the chat has never had a run.
|
||||||
|
*/
|
||||||
|
export interface IAiChatRunResponse {
|
||||||
|
run: IAiChatRun | null;
|
||||||
|
message: IAiChatMessageRow | null;
|
||||||
|
}
|
||||||
|
|
||||||
export interface IAiChatListParams extends QueryParams {}
|
export interface IAiChatListParams extends QueryParams {}
|
||||||
|
|
||||||
export interface IAiChatMessagesParams {
|
export interface IAiChatMessagesParams {
|
||||||
|
|||||||
@@ -1,112 +0,0 @@
|
|||||||
import { describe, it, expect } from "vitest";
|
|
||||||
import type { UIMessage } from "@ai-sdk/react";
|
|
||||||
import type { IAiChatMessageRow } from "@/features/ai-chat/types/ai-chat.types.ts";
|
|
||||||
import {
|
|
||||||
isStreamingTail,
|
|
||||||
isSettledAssistantTail,
|
|
||||||
seedRows,
|
|
||||||
mergeById,
|
|
||||||
} from "./resume-helpers.ts";
|
|
||||||
|
|
||||||
function row(
|
|
||||||
id: string,
|
|
||||||
role: string,
|
|
||||||
status?: string,
|
|
||||||
): IAiChatMessageRow {
|
|
||||||
return { id, role, content: "", status, createdAt: "2026-01-01T00:00:00Z" };
|
|
||||||
}
|
|
||||||
|
|
||||||
function makeMsg(id: string, text: string): UIMessage {
|
|
||||||
return {
|
|
||||||
id,
|
|
||||||
role: "assistant",
|
|
||||||
parts: [{ type: "text", text }],
|
|
||||||
} as UIMessage;
|
|
||||||
}
|
|
||||||
|
|
||||||
describe("isStreamingTail", () => {
|
|
||||||
it("is true when the last row is a streaming assistant row", () => {
|
|
||||||
expect(
|
|
||||||
isStreamingTail([row("u1", "user"), row("a1", "assistant", "streaming")]),
|
|
||||||
).toBe(true);
|
|
||||||
});
|
|
||||||
|
|
||||||
it("is false for a settled assistant tail", () => {
|
|
||||||
expect(isStreamingTail([row("a1", "assistant", "succeeded")])).toBe(false);
|
|
||||||
expect(isStreamingTail([row("a1", "assistant")])).toBe(false);
|
|
||||||
});
|
|
||||||
|
|
||||||
it("is false when the tail is a user row or the list is empty", () => {
|
|
||||||
expect(isStreamingTail([row("u1", "user")])).toBe(false);
|
|
||||||
expect(isStreamingTail([])).toBe(false);
|
|
||||||
});
|
|
||||||
});
|
|
||||||
|
|
||||||
describe("isSettledAssistantTail", () => {
|
|
||||||
it("is true for an assistant tail whose status is not streaming", () => {
|
|
||||||
expect(isSettledAssistantTail([row("a1", "assistant", "succeeded")])).toBe(
|
|
||||||
true,
|
|
||||||
);
|
|
||||||
expect(isSettledAssistantTail([row("a1", "assistant")])).toBe(true);
|
|
||||||
expect(isSettledAssistantTail([row("a1", "assistant", "aborted")])).toBe(
|
|
||||||
true,
|
|
||||||
);
|
|
||||||
});
|
|
||||||
|
|
||||||
it("is false for a streaming assistant tail", () => {
|
|
||||||
expect(isSettledAssistantTail([row("a1", "assistant", "streaming")])).toBe(
|
|
||||||
false,
|
|
||||||
);
|
|
||||||
});
|
|
||||||
|
|
||||||
it("is false when the tail is a user row or the list is empty", () => {
|
|
||||||
expect(isSettledAssistantTail([row("u1", "user")])).toBe(false);
|
|
||||||
expect(isSettledAssistantTail([])).toBe(false);
|
|
||||||
});
|
|
||||||
});
|
|
||||||
|
|
||||||
describe("seedRows", () => {
|
|
||||||
const rows = [row("u1", "user"), row("a1", "assistant", "streaming")];
|
|
||||||
|
|
||||||
it("returns the rows unchanged when not stripping", () => {
|
|
||||||
expect(seedRows(rows, false)).toBe(rows);
|
|
||||||
});
|
|
||||||
|
|
||||||
it("drops the last row when stripping", () => {
|
|
||||||
const seeded = seedRows(rows, true);
|
|
||||||
expect(seeded).toHaveLength(1);
|
|
||||||
expect(seeded[0].id).toBe("u1");
|
|
||||||
});
|
|
||||||
|
|
||||||
it("returns an empty list when stripping a single-row list", () => {
|
|
||||||
expect(seedRows([row("a1", "assistant", "streaming")], true)).toHaveLength(
|
|
||||||
0,
|
|
||||||
);
|
|
||||||
});
|
|
||||||
});
|
|
||||||
|
|
||||||
describe("mergeById", () => {
|
|
||||||
it("replaces the message with the same id in place (per-step growth)", () => {
|
|
||||||
const prev = [makeMsg("u1", "hi"), makeMsg("a1", "step 1")];
|
|
||||||
const incoming = makeMsg("a1", "step 1\nstep 2");
|
|
||||||
const next = mergeById(prev, incoming);
|
|
||||||
expect(next).toHaveLength(2);
|
|
||||||
expect(next[1]).toBe(incoming);
|
|
||||||
expect(next[0]).toBe(prev[0]); // untouched
|
|
||||||
expect(next).not.toBe(prev); // new array (never mutates input)
|
|
||||||
});
|
|
||||||
|
|
||||||
it("appends when the incoming message is not yet present", () => {
|
|
||||||
const prev = [makeMsg("u1", "hi")];
|
|
||||||
const incoming = makeMsg("a1", "first token");
|
|
||||||
const next = mergeById(prev, incoming);
|
|
||||||
expect(next).toHaveLength(2);
|
|
||||||
expect(next[1]).toBe(incoming);
|
|
||||||
});
|
|
||||||
|
|
||||||
it("returns the original list unchanged when there is nothing to merge", () => {
|
|
||||||
const prev = [makeMsg("u1", "hi")];
|
|
||||||
expect(mergeById(prev, null)).toBe(prev);
|
|
||||||
expect(mergeById(prev, undefined)).toBe(prev);
|
|
||||||
});
|
|
||||||
});
|
|
||||||
@@ -1,62 +0,0 @@
|
|||||||
import type { UIMessage } from "@ai-sdk/react";
|
|
||||||
import type { IAiChatMessageRow } from "@/features/ai-chat/types/ai-chat.types.ts";
|
|
||||||
|
|
||||||
/**
|
|
||||||
* Pure decisions for the resumable-SSE resume machinery (#184 phase 1.5). A tab
|
|
||||||
* that reopens a chat whose agent run is still going attaches to the server's
|
|
||||||
* run-stream registry (replay + live tail) instead of polling snapshots; these
|
|
||||||
* small predicates decide WHICH tail is safe to resume and how to seed the store,
|
|
||||||
* extracted so they can be unit-tested in isolation.
|
|
||||||
*/
|
|
||||||
|
|
||||||
/**
|
|
||||||
* A STREAMING tail: the last persisted row is an assistant row still marked
|
|
||||||
* `status === 'streaming'`. Such a tail is stripped from the seed and rebuilt by
|
|
||||||
* the replay (`expect=live`), since the SDK's `text-start` always pushes a new
|
|
||||||
* part and replaying over a seeded in-progress row would duplicate its text.
|
|
||||||
*/
|
|
||||||
export function isStreamingTail(rows: IAiChatMessageRow[]): boolean {
|
|
||||||
const tail = rows[rows.length - 1];
|
|
||||||
return !!tail && tail.role === "assistant" && tail.status === "streaming";
|
|
||||||
}
|
|
||||||
|
|
||||||
/**
|
|
||||||
* A SETTLED assistant tail: the last row is an assistant row whose status is
|
|
||||||
* anything OTHER than 'streaming'. A settled assistant tail must NEVER resume —
|
|
||||||
* replaying a finished run into a store that already holds its message duplicates
|
|
||||||
* parts (`text-start` always pushes a new part).
|
|
||||||
*/
|
|
||||||
export function isSettledAssistantTail(rows: IAiChatMessageRow[]): boolean {
|
|
||||||
const tail = rows[rows.length - 1];
|
|
||||||
return !!tail && tail.role === "assistant" && tail.status !== "streaming";
|
|
||||||
}
|
|
||||||
|
|
||||||
/**
|
|
||||||
* Seed rows for `useChat`: return the rows unchanged, or without the last row when
|
|
||||||
* `strip` is set (the streaming tail is stripped so the live replay rebuilds it
|
|
||||||
* without duplicating parts).
|
|
||||||
*/
|
|
||||||
export function seedRows(
|
|
||||||
rows: IAiChatMessageRow[],
|
|
||||||
strip: boolean,
|
|
||||||
): IAiChatMessageRow[] {
|
|
||||||
return strip ? rows.slice(0, -1) : rows;
|
|
||||||
}
|
|
||||||
|
|
||||||
/**
|
|
||||||
* Merge an assistant message into the rendered list by id: replace the message
|
|
||||||
* with the same id in place (the in-progress assistant row is already seeded from
|
|
||||||
* history, so per-step growth replaces it), or append it when absent. Returns a
|
|
||||||
* new array; the input is never mutated.
|
|
||||||
*/
|
|
||||||
export function mergeById(
|
|
||||||
messages: UIMessage[],
|
|
||||||
incoming: UIMessage | null | undefined,
|
|
||||||
): UIMessage[] {
|
|
||||||
if (!incoming) return messages;
|
|
||||||
const idx = messages.findIndex((m) => m.id === incoming.id);
|
|
||||||
if (idx === -1) return [...messages, incoming];
|
|
||||||
const next = messages.slice();
|
|
||||||
next[idx] = incoming;
|
|
||||||
return next;
|
|
||||||
}
|
|
||||||
@@ -0,0 +1,303 @@
|
|||||||
|
import { describe, it, expect } from "vitest";
|
||||||
|
import type { UIMessage } from "@ai-sdk/react";
|
||||||
|
import type { IAiChatRun } from "@/features/ai-chat/types/ai-chat.types.ts";
|
||||||
|
import {
|
||||||
|
RUN_POLL_INTERVAL_MS,
|
||||||
|
isRunActive,
|
||||||
|
runPollInterval,
|
||||||
|
shouldObserveRun,
|
||||||
|
shouldClearStoppingLatch,
|
||||||
|
shouldClearLatchOnQueryError,
|
||||||
|
mergeObservedMessage,
|
||||||
|
} from "./run-polling.ts";
|
||||||
|
|
||||||
|
function makeRun(status: string): IAiChatRun {
|
||||||
|
return { id: "run-1", chatId: "c1", status };
|
||||||
|
}
|
||||||
|
|
||||||
|
function makeMsg(id: string, text: string): UIMessage {
|
||||||
|
return {
|
||||||
|
id,
|
||||||
|
role: "assistant",
|
||||||
|
parts: [{ type: "text", text }],
|
||||||
|
} as UIMessage;
|
||||||
|
}
|
||||||
|
|
||||||
|
describe("isRunActive", () => {
|
||||||
|
it("treats pending and running as active", () => {
|
||||||
|
expect(isRunActive(makeRun("pending"))).toBe(true);
|
||||||
|
expect(isRunActive(makeRun("running"))).toBe(true);
|
||||||
|
});
|
||||||
|
|
||||||
|
it("treats terminal / unknown / nullish as not active", () => {
|
||||||
|
expect(isRunActive(makeRun("succeeded"))).toBe(false);
|
||||||
|
expect(isRunActive(makeRun("failed"))).toBe(false);
|
||||||
|
expect(isRunActive(makeRun("aborted"))).toBe(false);
|
||||||
|
expect(isRunActive(makeRun("weird-future-status"))).toBe(false);
|
||||||
|
expect(isRunActive(null)).toBe(false);
|
||||||
|
expect(isRunActive(undefined)).toBe(false);
|
||||||
|
});
|
||||||
|
});
|
||||||
|
|
||||||
|
describe("runPollInterval (the refetchInterval helper)", () => {
|
||||||
|
it("returns 2000ms while the run is pending/running", () => {
|
||||||
|
expect(runPollInterval(makeRun("pending"))).toBe(RUN_POLL_INTERVAL_MS);
|
||||||
|
expect(runPollInterval(makeRun("running"))).toBe(RUN_POLL_INTERVAL_MS);
|
||||||
|
expect(RUN_POLL_INTERVAL_MS).toBe(2000);
|
||||||
|
});
|
||||||
|
|
||||||
|
it("returns false (stop polling) once the run is terminal", () => {
|
||||||
|
expect(runPollInterval(makeRun("succeeded"))).toBe(false);
|
||||||
|
expect(runPollInterval(makeRun("failed"))).toBe(false);
|
||||||
|
expect(runPollInterval(makeRun("aborted"))).toBe(false);
|
||||||
|
});
|
||||||
|
|
||||||
|
it("returns false (no polling) when there is no run", () => {
|
||||||
|
expect(runPollInterval(null)).toBe(false);
|
||||||
|
expect(runPollInterval(undefined)).toBe(false);
|
||||||
|
});
|
||||||
|
});
|
||||||
|
|
||||||
|
describe("shouldObserveRun (observer-vs-streamer decision)", () => {
|
||||||
|
it("observes an active run when this tab is NOT the local streamer", () => {
|
||||||
|
expect(shouldObserveRun(makeRun("running"), false)).toBe(true);
|
||||||
|
expect(shouldObserveRun(makeRun("pending"), false)).toBe(true);
|
||||||
|
});
|
||||||
|
|
||||||
|
it("observes a terminal run too (so the final output shows on reopen)", () => {
|
||||||
|
expect(shouldObserveRun(makeRun("succeeded"), false)).toBe(true);
|
||||||
|
});
|
||||||
|
|
||||||
|
it("does NOT observe when this tab IS the streamer (no double-render)", () => {
|
||||||
|
expect(shouldObserveRun(makeRun("running"), true)).toBe(false);
|
||||||
|
expect(shouldObserveRun(makeRun("succeeded"), true)).toBe(false);
|
||||||
|
});
|
||||||
|
|
||||||
|
it("does NOT observe when there is no run", () => {
|
||||||
|
expect(shouldObserveRun(null, false)).toBe(false);
|
||||||
|
expect(shouldObserveRun(undefined, false)).toBe(false);
|
||||||
|
});
|
||||||
|
});
|
||||||
|
|
||||||
|
describe("shouldClearStoppingLatch (#234 latch-release decision)", () => {
|
||||||
|
// The one case the latch SHOULD clear: we requested a stop, we are the passive
|
||||||
|
// observer (not streaming), and the CURRENT run is terminal.
|
||||||
|
it("clears only when stopping, observing, and the run is terminal", () => {
|
||||||
|
expect(
|
||||||
|
shouldClearStoppingLatch({
|
||||||
|
stoppingRun: true,
|
||||||
|
run: makeRun("aborted"),
|
||||||
|
isLocalStreaming: false,
|
||||||
|
}),
|
||||||
|
).toBe(true);
|
||||||
|
expect(
|
||||||
|
shouldClearStoppingLatch({
|
||||||
|
stoppingRun: true,
|
||||||
|
run: makeRun("succeeded"),
|
||||||
|
isLocalStreaming: false,
|
||||||
|
}),
|
||||||
|
).toBe(true);
|
||||||
|
expect(
|
||||||
|
shouldClearStoppingLatch({
|
||||||
|
stoppingRun: true,
|
||||||
|
run: makeRun("failed"),
|
||||||
|
isLocalStreaming: false,
|
||||||
|
}),
|
||||||
|
).toBe(true);
|
||||||
|
});
|
||||||
|
|
||||||
|
// Round-3 regression: clearing while THIS tab is still the local streamer would
|
||||||
|
// re-open the flash for the current turn the moment we switch to observer role.
|
||||||
|
// A predicate lacking the streaming gate would (wrongly) return true here.
|
||||||
|
it("does NOT clear while this tab is the local streamer", () => {
|
||||||
|
expect(
|
||||||
|
shouldClearStoppingLatch({
|
||||||
|
stoppingRun: true,
|
||||||
|
run: makeRun("aborted"),
|
||||||
|
isLocalStreaming: true,
|
||||||
|
}),
|
||||||
|
).toBe(false);
|
||||||
|
expect(
|
||||||
|
shouldClearStoppingLatch({
|
||||||
|
stoppingRun: true,
|
||||||
|
run: makeRun("succeeded"),
|
||||||
|
isLocalStreaming: true,
|
||||||
|
}),
|
||||||
|
).toBe(false);
|
||||||
|
});
|
||||||
|
|
||||||
|
// The detached run keeps growing after a local abort — while it is still
|
||||||
|
// active the latch MUST hold so the observer merge stays suppressed.
|
||||||
|
it("does NOT clear while the run is still active", () => {
|
||||||
|
expect(
|
||||||
|
shouldClearStoppingLatch({
|
||||||
|
stoppingRun: true,
|
||||||
|
run: makeRun("running"),
|
||||||
|
isLocalStreaming: false,
|
||||||
|
}),
|
||||||
|
).toBe(false);
|
||||||
|
expect(
|
||||||
|
shouldClearStoppingLatch({
|
||||||
|
stoppingRun: true,
|
||||||
|
run: makeRun("pending"),
|
||||||
|
isLocalStreaming: false,
|
||||||
|
}),
|
||||||
|
).toBe(false);
|
||||||
|
});
|
||||||
|
|
||||||
|
// #234 F4: on Stop the stale PREVIOUS-turn run is removed from the cache, so the
|
||||||
|
// observed `run` is null until the current turn's run is fetched fresh. A null
|
||||||
|
// run HOLDS the latch — it can never clear against the just-removed stale run,
|
||||||
|
// only against the current turn's own terminal run once observed.
|
||||||
|
it("does NOT clear against a removed/absent run (F4 stale-run guard)", () => {
|
||||||
|
expect(
|
||||||
|
shouldClearStoppingLatch({
|
||||||
|
stoppingRun: true,
|
||||||
|
run: null,
|
||||||
|
isLocalStreaming: false,
|
||||||
|
}),
|
||||||
|
).toBe(false);
|
||||||
|
expect(
|
||||||
|
shouldClearStoppingLatch({
|
||||||
|
stoppingRun: true,
|
||||||
|
run: undefined,
|
||||||
|
isLocalStreaming: false,
|
||||||
|
}),
|
||||||
|
).toBe(false);
|
||||||
|
});
|
||||||
|
|
||||||
|
it("does NOT clear when no stop was requested", () => {
|
||||||
|
expect(
|
||||||
|
shouldClearStoppingLatch({
|
||||||
|
stoppingRun: false,
|
||||||
|
run: makeRun("aborted"),
|
||||||
|
isLocalStreaming: false,
|
||||||
|
}),
|
||||||
|
).toBe(false);
|
||||||
|
});
|
||||||
|
});
|
||||||
|
|
||||||
|
describe("shouldClearLatchOnQueryError (#234 F7 error-safety-net decision)", () => {
|
||||||
|
// This guards the REAL anti-flash decision the component's run-query-error
|
||||||
|
// safety-net effect uses (ai-chat-window.tsx wires the effect to THIS helper,
|
||||||
|
// not a copy — so the test is non-vacuous vs the live code).
|
||||||
|
|
||||||
|
// (b) The F7 hole: a TRANSIENT run-query error while `run` is STILL ACTIVE must
|
||||||
|
// NOT clear the latch. TanStack Query v5 retains `data` on error, so
|
||||||
|
// runQueryFailed can be true while the held run is still pending/running.
|
||||||
|
// Against the PRE-F7 condition (without `!isRunActive(run)`) this would return
|
||||||
|
// true — so this assertion fails on the buggy code (non-vacuous).
|
||||||
|
it("does NOT clear on a transient error while the run is still ACTIVE (F7)", () => {
|
||||||
|
expect(
|
||||||
|
shouldClearLatchOnQueryError({
|
||||||
|
stoppingRun: true,
|
||||||
|
isLocalStreaming: false,
|
||||||
|
runQueryFailed: true,
|
||||||
|
run: makeRun("running"),
|
||||||
|
}),
|
||||||
|
).toBe(false);
|
||||||
|
expect(
|
||||||
|
shouldClearLatchOnQueryError({
|
||||||
|
stoppingRun: true,
|
||||||
|
isLocalStreaming: false,
|
||||||
|
runQueryFailed: true,
|
||||||
|
run: makeRun("pending"),
|
||||||
|
}),
|
||||||
|
).toBe(false);
|
||||||
|
});
|
||||||
|
|
||||||
|
// (a) The genuine permanent-null-freeze: run cache cleared by removeQueries +
|
||||||
|
// the refetch keeps ERRORING, so `run === null`. This is the ONLY case the
|
||||||
|
// safety-net exists to cure — it MUST clear so the frozen view resumes.
|
||||||
|
it("clears on a permanent error when the run is null (permanent-null-freeze)", () => {
|
||||||
|
expect(
|
||||||
|
shouldClearLatchOnQueryError({
|
||||||
|
stoppingRun: true,
|
||||||
|
isLocalStreaming: false,
|
||||||
|
runQueryFailed: true,
|
||||||
|
run: null,
|
||||||
|
}),
|
||||||
|
).toBe(true);
|
||||||
|
expect(
|
||||||
|
shouldClearLatchOnQueryError({
|
||||||
|
stoppingRun: true,
|
||||||
|
isLocalStreaming: false,
|
||||||
|
runQueryFailed: true,
|
||||||
|
run: undefined,
|
||||||
|
}),
|
||||||
|
).toBe(true);
|
||||||
|
});
|
||||||
|
|
||||||
|
// A TERMINAL run also satisfies `!isRunActive`; clearing then is harmless — the
|
||||||
|
// terminal effect (shouldClearStoppingLatch) already clears for a terminal run,
|
||||||
|
// so this only ever agrees with it. Asserted so the (c) reasoning is pinned.
|
||||||
|
it("clears on an error when the run is terminal (harmless, agrees with terminal effect)", () => {
|
||||||
|
expect(
|
||||||
|
shouldClearLatchOnQueryError({
|
||||||
|
stoppingRun: true,
|
||||||
|
isLocalStreaming: false,
|
||||||
|
runQueryFailed: true,
|
||||||
|
run: makeRun("aborted"),
|
||||||
|
}),
|
||||||
|
).toBe(true);
|
||||||
|
});
|
||||||
|
|
||||||
|
it("does NOT clear without an actual query error", () => {
|
||||||
|
expect(
|
||||||
|
shouldClearLatchOnQueryError({
|
||||||
|
stoppingRun: true,
|
||||||
|
isLocalStreaming: false,
|
||||||
|
runQueryFailed: false,
|
||||||
|
run: null,
|
||||||
|
}),
|
||||||
|
).toBe(false);
|
||||||
|
});
|
||||||
|
|
||||||
|
it("does NOT clear while this tab is the local streamer", () => {
|
||||||
|
expect(
|
||||||
|
shouldClearLatchOnQueryError({
|
||||||
|
stoppingRun: true,
|
||||||
|
isLocalStreaming: true,
|
||||||
|
runQueryFailed: true,
|
||||||
|
run: null,
|
||||||
|
}),
|
||||||
|
).toBe(false);
|
||||||
|
});
|
||||||
|
|
||||||
|
it("does NOT clear when no stop was requested", () => {
|
||||||
|
expect(
|
||||||
|
shouldClearLatchOnQueryError({
|
||||||
|
stoppingRun: false,
|
||||||
|
isLocalStreaming: false,
|
||||||
|
runQueryFailed: true,
|
||||||
|
run: null,
|
||||||
|
}),
|
||||||
|
).toBe(false);
|
||||||
|
});
|
||||||
|
});
|
||||||
|
|
||||||
|
describe("mergeObservedMessage", () => {
|
||||||
|
it("replaces the message with the same id in place (per-step growth)", () => {
|
||||||
|
const prev = [makeMsg("u1", "hi"), makeMsg("a1", "step 1")];
|
||||||
|
const observed = makeMsg("a1", "step 1\nstep 2");
|
||||||
|
const next = mergeObservedMessage(prev, observed);
|
||||||
|
expect(next).toHaveLength(2);
|
||||||
|
expect(next[1]).toBe(observed);
|
||||||
|
expect(next[0]).toBe(prev[0]); // untouched
|
||||||
|
expect(next).not.toBe(prev); // new array (never mutates input)
|
||||||
|
});
|
||||||
|
|
||||||
|
it("appends when the observed message is not yet present", () => {
|
||||||
|
const prev = [makeMsg("u1", "hi")];
|
||||||
|
const observed = makeMsg("a1", "first token");
|
||||||
|
const next = mergeObservedMessage(prev, observed);
|
||||||
|
expect(next).toHaveLength(2);
|
||||||
|
expect(next[1]).toBe(observed);
|
||||||
|
});
|
||||||
|
|
||||||
|
it("returns the original list unchanged when there is nothing to merge", () => {
|
||||||
|
const prev = [makeMsg("u1", "hi")];
|
||||||
|
expect(mergeObservedMessage(prev, null)).toBe(prev);
|
||||||
|
expect(mergeObservedMessage(prev, undefined)).toBe(prev);
|
||||||
|
});
|
||||||
|
});
|
||||||
@@ -0,0 +1,151 @@
|
|||||||
|
import type { UIMessage } from "@ai-sdk/react";
|
||||||
|
import type { IAiChatRun } from "@/features/ai-chat/types/ai-chat.types.ts";
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Reconnect-and-live-follow helpers (#184). When a chat is reopened while its
|
||||||
|
* agent run is STILL going, this tab is a PASSIVE OBSERVER: it did not start the
|
||||||
|
* run here (no local SSE stream), so it catches up by POLLING the reconnect
|
||||||
|
* endpoint (`POST /ai-chat/run`) and merging the run's incrementally-persisted
|
||||||
|
* assistant message into the rendered thread. These are the small pure decisions
|
||||||
|
* that machinery hangs off, extracted so they can be unit-tested in isolation
|
||||||
|
* (mirrors how reindex polling / editor-sync-state are tested).
|
||||||
|
*/
|
||||||
|
|
||||||
|
/** How often to re-poll the reconnect endpoint while a run is ACTIVE. */
|
||||||
|
export const RUN_POLL_INTERVAL_MS = 2000;
|
||||||
|
|
||||||
|
// 'pending' and 'running' are the two ACTIVE statuses; 'succeeded' | 'failed' |
|
||||||
|
// 'aborted' are TERMINAL (and any unknown future status is treated as terminal,
|
||||||
|
// so a stale/odd value never polls forever).
|
||||||
|
const ACTIVE_STATUSES = new Set(["pending", "running"]);
|
||||||
|
|
||||||
|
/** Whether a run is still going (worth polling / merging live updates from). */
|
||||||
|
export function isRunActive(run: IAiChatRun | null | undefined): boolean {
|
||||||
|
return !!run && ACTIVE_STATUSES.has(run.status);
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* The TanStack Query `refetchInterval` value for the run query: poll every
|
||||||
|
* {@link RUN_POLL_INTERVAL_MS} while the run is active, and `false` (stop) once
|
||||||
|
* it is terminal or there is no run. Polling is thus naturally bounded by the run
|
||||||
|
* reaching a terminal status — no separate timeout cap is needed.
|
||||||
|
*/
|
||||||
|
export function runPollInterval(
|
||||||
|
run: IAiChatRun | null | undefined,
|
||||||
|
): number | false {
|
||||||
|
return isRunActive(run) ? RUN_POLL_INTERVAL_MS : false;
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Observer-vs-streamer decision. We render the polled run message (catch up +
|
||||||
|
* keep advancing) ONLY when this tab is a passive observer: there IS a run AND
|
||||||
|
* this tab is NOT the one locally streaming it (we reconnected, we didn't start
|
||||||
|
* it here). When this tab is the streamer, the live SSE stream owns the view, so
|
||||||
|
* we neither poll nor merge — avoiding a double-render fight. Terminal runs still
|
||||||
|
* merge (so the final persisted output is shown on reopen); the poll itself is
|
||||||
|
* stopped separately by {@link runPollInterval}.
|
||||||
|
*/
|
||||||
|
export function shouldObserveRun(
|
||||||
|
run: IAiChatRun | null | undefined,
|
||||||
|
localStreaming: boolean,
|
||||||
|
): boolean {
|
||||||
|
return !!run && !localStreaming;
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Should the "stopping" latch — which suppresses the observer re-stream flash
|
||||||
|
* after the user pressed Stop — be RELEASED now? All three must hold:
|
||||||
|
* - `stoppingRun`: we actually requested a stop (otherwise nothing to release);
|
||||||
|
* - `!isLocalStreaming`: this tab is NOT the local streamer. While we are the
|
||||||
|
* streamer the run query is disabled, so the observed `run` is not the run we
|
||||||
|
* are following — releasing the latch then would re-open the flash for the
|
||||||
|
* current turn the instant we switch to observer role;
|
||||||
|
* - the observed `run` EXISTS and has reached a TERMINAL status.
|
||||||
|
*
|
||||||
|
* The null / still-active `run` case is the #234 F4 invariant. On Stop the stale
|
||||||
|
* PREVIOUS-turn run is removed from the query cache (`removeQueries`), so `run`
|
||||||
|
* is null until the CURRENT turn's run is re-fetched fresh; a null or active run
|
||||||
|
* therefore HOLDS the latch, so it can only ever clear against the current turn's
|
||||||
|
* OWN terminal run — never a stale cached one. (The cache removal itself is
|
||||||
|
* integration-level in AiChatWindow; this predicate encodes the decision given
|
||||||
|
* whatever run is currently observed, and a stale terminal run is
|
||||||
|
* indistinguishable from a current terminal run at the predicate level — hence
|
||||||
|
* the cache removal is what guarantees only the current run is ever passed here.)
|
||||||
|
*/
|
||||||
|
export function shouldClearStoppingLatch(args: {
|
||||||
|
stoppingRun: boolean;
|
||||||
|
run: IAiChatRun | null | undefined;
|
||||||
|
isLocalStreaming: boolean;
|
||||||
|
}): boolean {
|
||||||
|
const { stoppingRun, run, isLocalStreaming } = args;
|
||||||
|
if (!stoppingRun || isLocalStreaming) return false;
|
||||||
|
return !!run && !isRunActive(run);
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Should the "stopping" latch be RELEASED by the run-query ERROR safety-net?
|
||||||
|
* (#234 F7 — a NEW path of the same re-stream flash the F4 latch exists to
|
||||||
|
* prevent.) After Stop, `handleServerStop` clears the run cache; the terminal
|
||||||
|
* effect then holds the latch via `if (!run) return` until the CURRENT turn's run
|
||||||
|
* is fetched fresh. If that refetch instead ERRORS permanently, `run` stays null,
|
||||||
|
* its status-keyed refetchInterval is off, and nothing would ever observe a
|
||||||
|
* terminal run — freezing the view with the observer merge suppressed. This
|
||||||
|
* safety-net cures ONLY that genuine permanent-null-freeze.
|
||||||
|
*
|
||||||
|
* All four must hold:
|
||||||
|
* - `stoppingRun`: we actually requested a stop (otherwise nothing to release);
|
||||||
|
* - `!isLocalStreaming`: this tab is NOT the local streamer (same reason as
|
||||||
|
* {@link shouldClearStoppingLatch});
|
||||||
|
* - `runQueryFailed`: the run query is in its error state (TanStack Query v5 with
|
||||||
|
* retry:false — isError);
|
||||||
|
* - `!isRunActive(run)`: the observed `run` is NOT an active (pending/running)
|
||||||
|
* held run. This is the F7 gate. In TanStack Query v5 the query's `data` is
|
||||||
|
* RETAINED on error, so `runQueryFailed` can be true while `run` is STILL an
|
||||||
|
* ACTIVE run (a single transient GET-run failure in the window between Stop and
|
||||||
|
* settle). Without this gate a transient error would release the latch early —
|
||||||
|
* re-opening the observer merge and flashing the growing detached run over the
|
||||||
|
* frozen row (exactly the F4 flash). Gating on the run NOT being active means we
|
||||||
|
* only ever cure the permanent-null-freeze (`run === null`, so
|
||||||
|
* `isRunActive(null)` is false), never release against an active run.
|
||||||
|
*
|
||||||
|
* (A terminal `run` also satisfies `!isRunActive(run)`; clearing then is harmless
|
||||||
|
* — the terminal effect's {@link shouldClearStoppingLatch} already clears the
|
||||||
|
* latch for a terminal run, so this only ever agrees with it, never conflicts.)
|
||||||
|
*
|
||||||
|
* INVARIANT (do not break): clearing the latch on the `run === null` branch is safe
|
||||||
|
* ONLY because the run query's `refetchInterval` (see {@link runPollInterval}) stops
|
||||||
|
* polling when the data is empty — so after we clear on null+error there is no
|
||||||
|
* subsequent auto-poll that could return a still-active detached run and re-open the
|
||||||
|
* merge. If `refetchInterval` is ever changed to keep polling on `run === null`/on
|
||||||
|
* error, this null-branch clear would re-open the F7 flash through the null path.
|
||||||
|
* Do not change the run query's refetchInterval without re-checking this path.
|
||||||
|
*/
|
||||||
|
export function shouldClearLatchOnQueryError(args: {
|
||||||
|
stoppingRun: boolean;
|
||||||
|
isLocalStreaming: boolean;
|
||||||
|
runQueryFailed: boolean;
|
||||||
|
run: IAiChatRun | null | undefined;
|
||||||
|
}): boolean {
|
||||||
|
const { stoppingRun, isLocalStreaming, runQueryFailed, run } = args;
|
||||||
|
return (
|
||||||
|
stoppingRun && !isLocalStreaming && runQueryFailed && !isRunActive(run)
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Merge an observed assistant message into the rendered list: replace the message
|
||||||
|
* with the same id in place (the in-progress assistant row is already seeded from
|
||||||
|
* history, so per-step growth replaces it), or append it when absent. Returns a
|
||||||
|
* new array; the input is never mutated.
|
||||||
|
*/
|
||||||
|
export function mergeObservedMessage(
|
||||||
|
messages: UIMessage[],
|
||||||
|
observed: UIMessage | null | undefined,
|
||||||
|
): UIMessage[] {
|
||||||
|
if (!observed) return messages;
|
||||||
|
const idx = messages.findIndex((m) => m.id === observed.id);
|
||||||
|
if (idx === -1) return [...messages, observed];
|
||||||
|
const next = messages.slice();
|
||||||
|
next[idx] = observed;
|
||||||
|
return next;
|
||||||
|
}
|
||||||
@@ -1,7 +1,6 @@
|
|||||||
import { describe, it, expect } from "vitest";
|
import { describe, it, expect } from "vitest";
|
||||||
import {
|
import {
|
||||||
toolCitations,
|
toolCitations,
|
||||||
toolInputSummary,
|
|
||||||
toolRunState,
|
toolRunState,
|
||||||
type ToolUiPart,
|
type ToolUiPart,
|
||||||
} from "./tool-parts";
|
} from "./tool-parts";
|
||||||
@@ -78,138 +77,6 @@ describe("toolCitations", () => {
|
|||||||
});
|
});
|
||||||
});
|
});
|
||||||
|
|
||||||
describe("toolInputSummary", () => {
|
|
||||||
it("returns the primary `query` string", () => {
|
|
||||||
const part: ToolUiPart = {
|
|
||||||
type: "tool-Search_web_search",
|
|
||||||
state: "input-available",
|
|
||||||
input: { query: "hello world" },
|
|
||||||
};
|
|
||||||
expect(toolInputSummary(part)).toBe("hello world");
|
|
||||||
});
|
|
||||||
|
|
||||||
it("summarizes a primary array field with a (+N) suffix", () => {
|
|
||||||
// `urls` is an external MCP read_pages-style list; the first element plus a
|
|
||||||
// count of the rest.
|
|
||||||
const part: ToolUiPart = {
|
|
||||||
type: "tool-read_pages",
|
|
||||||
state: "input-available",
|
|
||||||
input: { urls: ["a", "b", "c"] },
|
|
||||||
};
|
|
||||||
expect(toolInputSummary(part)).toBe("a (+2)");
|
|
||||||
});
|
|
||||||
|
|
||||||
it("omits the (+N) suffix for a single-element array", () => {
|
|
||||||
const part: ToolUiPart = {
|
|
||||||
type: "tool-read_pages",
|
|
||||||
state: "input-available",
|
|
||||||
input: { urls: ["only"] },
|
|
||||||
};
|
|
||||||
expect(toolInputSummary(part)).toBe("only");
|
|
||||||
});
|
|
||||||
|
|
||||||
it("falls back to `title` for a page op with no query", () => {
|
|
||||||
const part: ToolUiPart = {
|
|
||||||
type: "tool-createPage",
|
|
||||||
state: "input-available",
|
|
||||||
input: { pageId: "x", title: "My Page" },
|
|
||||||
};
|
|
||||||
expect(toolInputSummary(part)).toBe("My Page");
|
|
||||||
});
|
|
||||||
|
|
||||||
it("prefers the earlier primary field when several are present", () => {
|
|
||||||
const part: ToolUiPart = {
|
|
||||||
type: "tool-x",
|
|
||||||
state: "input-available",
|
|
||||||
// `query` outranks `title` in PRIMARY_INPUT_FIELDS — the ordered list is
|
|
||||||
// the contract, so a reordering must break this test.
|
|
||||||
input: { query: "Q", title: "T" },
|
|
||||||
};
|
|
||||||
expect(toolInputSummary(part)).toBe("Q");
|
|
||||||
});
|
|
||||||
|
|
||||||
it("does not clamp a value exactly at the 140-char limit", () => {
|
|
||||||
const exact = "a".repeat(140);
|
|
||||||
const part: ToolUiPart = {
|
|
||||||
type: "tool-Search_web_search",
|
|
||||||
state: "input-available",
|
|
||||||
input: { query: exact },
|
|
||||||
};
|
|
||||||
const out = toolInputSummary(part)!;
|
|
||||||
expect(out).toBe(exact);
|
|
||||||
expect(out.endsWith("…")).toBe(false);
|
|
||||||
expect(out.length).toBe(140);
|
|
||||||
});
|
|
||||||
|
|
||||||
it("clamps one char over the limit (141 -> 140 + ellipsis)", () => {
|
|
||||||
const part: ToolUiPart = {
|
|
||||||
type: "tool-Search_web_search",
|
|
||||||
state: "input-available",
|
|
||||||
input: { query: "a".repeat(141) },
|
|
||||||
};
|
|
||||||
const out = toolInputSummary(part)!;
|
|
||||||
expect(out.endsWith("…")).toBe(true);
|
|
||||||
expect(out.length).toBe(141);
|
|
||||||
expect(out).toBe("a".repeat(140) + "…");
|
|
||||||
});
|
|
||||||
|
|
||||||
it("clamps a long value to ~140 chars with an ellipsis", () => {
|
|
||||||
const long = "a".repeat(300);
|
|
||||||
const part: ToolUiPart = {
|
|
||||||
type: "tool-Search_web_search",
|
|
||||||
state: "input-available",
|
|
||||||
input: { query: long },
|
|
||||||
};
|
|
||||||
const out = toolInputSummary(part)!;
|
|
||||||
expect(out.endsWith("…")).toBe(true);
|
|
||||||
expect(out.length).toBeLessThanOrEqual(141);
|
|
||||||
});
|
|
||||||
|
|
||||||
it("collapses newlines and repeated spaces to single spaces", () => {
|
|
||||||
const part: ToolUiPart = {
|
|
||||||
type: "tool-Search_web_search",
|
|
||||||
state: "input-available",
|
|
||||||
input: { query: " foo\n\n bar baz " },
|
|
||||||
};
|
|
||||||
expect(toolInputSummary(part)).toBe("foo bar baz");
|
|
||||||
});
|
|
||||||
|
|
||||||
it("returns undefined with no input", () => {
|
|
||||||
expect(
|
|
||||||
toolInputSummary({ type: "tool-x", state: "input-available" }),
|
|
||||||
).toBeUndefined();
|
|
||||||
});
|
|
||||||
|
|
||||||
it("returns undefined for an empty object input", () => {
|
|
||||||
expect(
|
|
||||||
toolInputSummary({
|
|
||||||
type: "tool-x",
|
|
||||||
state: "input-available",
|
|
||||||
input: {},
|
|
||||||
}),
|
|
||||||
).toBeUndefined();
|
|
||||||
});
|
|
||||||
|
|
||||||
it("returns undefined for a non-object input", () => {
|
|
||||||
expect(
|
|
||||||
toolInputSummary({
|
|
||||||
type: "tool-x",
|
|
||||||
state: "input-available",
|
|
||||||
input: "just a string",
|
|
||||||
}),
|
|
||||||
).toBeUndefined();
|
|
||||||
});
|
|
||||||
|
|
||||||
it("returns undefined while the input is still streaming (even with a full input)", () => {
|
|
||||||
const part: ToolUiPart = {
|
|
||||||
type: "tool-Search_web_search",
|
|
||||||
state: "input-streaming",
|
|
||||||
input: { query: "hello world" },
|
|
||||||
};
|
|
||||||
expect(toolInputSummary(part)).toBeUndefined();
|
|
||||||
});
|
|
||||||
});
|
|
||||||
|
|
||||||
describe("toolRunState", () => {
|
describe("toolRunState", () => {
|
||||||
it('maps "output-error" to error', () => {
|
it('maps "output-error" to error', () => {
|
||||||
expect(toolRunState("output-error")).toBe("error");
|
expect(toolRunState("output-error")).toBe("error");
|
||||||
|
|||||||
@@ -97,69 +97,6 @@ function asString(value: unknown): string | undefined {
|
|||||||
return typeof value === "string" && value.length > 0 ? value : undefined;
|
return typeof value === "string" && value.length > 0 ? value : undefined;
|
||||||
}
|
}
|
||||||
|
|
||||||
/** Collapse runs of whitespace/newlines to a single space and trim. */
|
|
||||||
function collapse(s: string): string {
|
|
||||||
return s.replace(/\s+/g, " ").trim();
|
|
||||||
}
|
|
||||||
|
|
||||||
/** Truncate to ~140 chars, appending an ellipsis when it overflows. */
|
|
||||||
function clamp(s: string): string {
|
|
||||||
const MAX = 140;
|
|
||||||
return s.length > MAX ? s.slice(0, MAX).trimEnd() + "…" : s;
|
|
||||||
}
|
|
||||||
|
|
||||||
/**
|
|
||||||
* Priority "primary" argument fields, in order. The first present one supplies
|
|
||||||
* the summary. `urls` is included (external MCP `read_pages`-style tools take a
|
|
||||||
* list of URLs) and is handled as an array; `url` covers the single-URL form.
|
|
||||||
*/
|
|
||||||
const PRIMARY_INPUT_FIELDS = [
|
|
||||||
"query",
|
|
||||||
"q",
|
|
||||||
"searchQuery",
|
|
||||||
"url",
|
|
||||||
"urls",
|
|
||||||
"title",
|
|
||||||
"name",
|
|
||||||
"text",
|
|
||||||
"prompt",
|
|
||||||
] as const;
|
|
||||||
|
|
||||||
/**
|
|
||||||
* A short, PLAIN-TEXT one-line summary of a tool call's arguments (e.g. the
|
|
||||||
* search query), or undefined when no recognizable primary field is present.
|
|
||||||
* Rendered under the tool label so tools without a friendly name (external MCP
|
|
||||||
* tools like `Search_web_search`) still show WHAT was requested, not just a
|
|
||||||
* generic "Ran tool {{name}}". The returned string is plain text and MUST be
|
|
||||||
* rendered React-escaped (Mantine `<Text>`), never as markdown/HTML.
|
|
||||||
*
|
|
||||||
* Streaming gate: while `state === "input-streaming"` the `input` object grows
|
|
||||||
* chunk by chunk but `messageSignature` deliberately does NOT track `input`, so
|
|
||||||
* a live summary computed here would freeze at its first captured value and go
|
|
||||||
* stale. We therefore return undefined until the state flips to
|
|
||||||
* `input-available` (input finalized) — that state change IS tracked by the
|
|
||||||
* signature, so the row re-renders and shows the complete summary. Do NOT add
|
|
||||||
* `input` to `message-signature.ts` to work around this.
|
|
||||||
*/
|
|
||||||
export function toolInputSummary(part: ToolUiPart): string | undefined {
|
|
||||||
if (part.state === "input-streaming") return undefined;
|
|
||||||
if (!part.input || typeof part.input !== "object") return undefined;
|
|
||||||
const input = part.input as Record<string, unknown>;
|
|
||||||
|
|
||||||
for (const field of PRIMARY_INPUT_FIELDS) {
|
|
||||||
const value = input[field];
|
|
||||||
if (typeof value === "string" && value.length > 0) {
|
|
||||||
return clamp(collapse(value));
|
|
||||||
}
|
|
||||||
if (Array.isArray(value) && value.length > 0) {
|
|
||||||
const first = collapse(String(value[0]));
|
|
||||||
if (first.length === 0) continue;
|
|
||||||
return clamp(first + (value.length > 1 ? ` (+${value.length - 1})` : ""));
|
|
||||||
}
|
|
||||||
}
|
|
||||||
return undefined;
|
|
||||||
}
|
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Resolve the page citation(s) a tool part references, from its input/output.
|
* Resolve the page citation(s) a tool part references, from its input/output.
|
||||||
* Only output-available parts (the tool returned) yield citations. Search
|
* Only output-available parts (the tool returned) yield citations. Search
|
||||||
|
|||||||
@@ -1,113 +0,0 @@
|
|||||||
import { describe, it, expect } from "vitest";
|
|
||||||
import { Editor } from "@tiptap/core";
|
|
||||||
import { Document } from "@tiptap/extension-document";
|
|
||||||
import { Paragraph } from "@tiptap/extension-paragraph";
|
|
||||||
import { Text } from "@tiptap/extension-text";
|
|
||||||
import { EditorState, TextSelection } from "@tiptap/pm/state";
|
|
||||||
import type { Node as PMNode } from "@tiptap/pm/model";
|
|
||||||
import { UniqueID } from "@docmost/editor-ext";
|
|
||||||
import { getEditorSelectionContext } from "./get-editor-selection";
|
|
||||||
|
|
||||||
/**
|
|
||||||
* Unit tests for getEditorSelectionContext (#388). Built on a headless
|
|
||||||
* ProseMirror schema (Document + Paragraph + Text + the block-id UniqueID
|
|
||||||
* extension), mirroring the editor-ext test style. We assemble docs with
|
|
||||||
* explicit block ids so the covered-blockIds assertions are deterministic.
|
|
||||||
*/
|
|
||||||
|
|
||||||
// A schema that carries the `id` block attribute (UniqueID) on paragraphs, just
|
|
||||||
// like the real editor.
|
|
||||||
const { schema } = new Editor({
|
|
||||||
extensions: [
|
|
||||||
Document,
|
|
||||||
Paragraph,
|
|
||||||
Text,
|
|
||||||
UniqueID.configure({ types: ["paragraph"] }),
|
|
||||||
],
|
|
||||||
content: "",
|
|
||||||
});
|
|
||||||
|
|
||||||
function docOf(blocks: { id: string; text: string }[]): PMNode {
|
|
||||||
return schema.node(
|
|
||||||
"doc",
|
|
||||||
null,
|
|
||||||
blocks.map((b) =>
|
|
||||||
schema.node("paragraph", { id: b.id }, b.text ? schema.text(b.text) : []),
|
|
||||||
),
|
|
||||||
);
|
|
||||||
}
|
|
||||||
|
|
||||||
function stateWith(doc: PMNode, from: number, to: number): EditorState {
|
|
||||||
const base = EditorState.create({ schema, doc });
|
|
||||||
return base.apply(base.tr.setSelection(TextSelection.create(doc, from, to)));
|
|
||||||
}
|
|
||||||
|
|
||||||
// Select every text position of the doc (pos 1 .. content.size - 1).
|
|
||||||
function selectAll(doc: PMNode): EditorState {
|
|
||||||
return stateWith(doc, 1, doc.content.size - 1);
|
|
||||||
}
|
|
||||||
|
|
||||||
describe("getEditorSelectionContext", () => {
|
|
||||||
it("returns null for an empty (collapsed) selection", () => {
|
|
||||||
const doc = docOf([{ id: "b1", text: "Hello world" }]);
|
|
||||||
const state = stateWith(doc, 3, 3); // caret, from === to
|
|
||||||
expect(getEditorSelectionContext(state)).toBeNull();
|
|
||||||
});
|
|
||||||
|
|
||||||
it("returns null for the default caret-at-start of a fresh editor", () => {
|
|
||||||
const editor = new Editor({
|
|
||||||
extensions: [
|
|
||||||
Document,
|
|
||||||
Paragraph,
|
|
||||||
Text,
|
|
||||||
UniqueID.configure({ types: ["paragraph"] }),
|
|
||||||
],
|
|
||||||
content: "<p>fresh</p>",
|
|
||||||
});
|
|
||||||
expect(getEditorSelectionContext(editor.state)).toBeNull();
|
|
||||||
editor.destroy();
|
|
||||||
});
|
|
||||||
|
|
||||||
it("reads a single-paragraph selection with no block-separator artifacts", () => {
|
|
||||||
const doc = docOf([{ id: "b1", text: "Hello world" }]);
|
|
||||||
const sel = getEditorSelectionContext(selectAll(doc))!;
|
|
||||||
expect(sel.text).toBe("Hello world");
|
|
||||||
expect(sel.blockIds).toEqual(["b1"]);
|
|
||||||
expect(sel.truncated).toBeUndefined();
|
|
||||||
});
|
|
||||||
|
|
||||||
it("joins multiple blocks with a newline and collects all covered blockIds", () => {
|
|
||||||
const doc = docOf([
|
|
||||||
{ id: "b1", text: "First" },
|
|
||||||
{ id: "b2", text: "Second" },
|
|
||||||
]);
|
|
||||||
const sel = getEditorSelectionContext(selectAll(doc))!;
|
|
||||||
expect(sel.text).toBe("First\nSecond");
|
|
||||||
expect(sel.blockIds).toEqual(["b1", "b2"]);
|
|
||||||
});
|
|
||||||
|
|
||||||
it("caps the text at 2000 chars and flags truncated", () => {
|
|
||||||
const doc = docOf([{ id: "b1", text: "x".repeat(2500) }]);
|
|
||||||
const sel = getEditorSelectionContext(selectAll(doc))!;
|
|
||||||
expect(sel.text).toHaveLength(2000);
|
|
||||||
expect(sel.truncated).toBe(true);
|
|
||||||
});
|
|
||||||
|
|
||||||
it("computes before/after context and clamps it to the doc bounds", () => {
|
|
||||||
// One paragraph "0123456789abcdefghij"; select the middle "56789".
|
|
||||||
const doc = docOf([{ id: "b1", text: "0123456789abcdefghij" }]);
|
|
||||||
// text char i lives at pos (1 + i); select chars index 5..9 -> pos 6..11.
|
|
||||||
const sel = getEditorSelectionContext(stateWith(doc, 6, 11))!;
|
|
||||||
expect(sel.text).toBe("56789");
|
|
||||||
expect(sel.before).toBe("01234");
|
|
||||||
expect(sel.after).toBe("abcdefghij");
|
|
||||||
});
|
|
||||||
|
|
||||||
it("omits before/after at the document boundaries (never reads past 0/size)", () => {
|
|
||||||
const doc = docOf([{ id: "b1", text: "Edge" }]);
|
|
||||||
const sel = getEditorSelectionContext(selectAll(doc))!;
|
|
||||||
// Selection spans the whole single block: nothing before or after it.
|
|
||||||
expect(sel.before).toBeUndefined();
|
|
||||||
expect(sel.after).toBeUndefined();
|
|
||||||
});
|
|
||||||
});
|
|
||||||
@@ -1,71 +0,0 @@
|
|||||||
import type { EditorState } from "@tiptap/pm/state";
|
|
||||||
|
|
||||||
export interface EditorSelectionContext {
|
|
||||||
text: string;
|
|
||||||
truncated?: boolean;
|
|
||||||
blockIds?: string[];
|
|
||||||
before?: string;
|
|
||||||
after?: string;
|
|
||||||
}
|
|
||||||
|
|
||||||
// Client-side caps. The server re-caps every field independently (defence in
|
|
||||||
// depth — the payload is attacker-controllable), so these only keep the wire
|
|
||||||
// small for the common case.
|
|
||||||
const TEXT_CAP = 2000;
|
|
||||||
const CONTEXT_CHARS = 160;
|
|
||||||
const MAX_BLOCK_IDS = 20;
|
|
||||||
|
|
||||||
// Pure: takes an EditorState so it is unit-testable with a headless editor.
|
|
||||||
// Snapshots the user's current selection into the wire shape carried inside
|
|
||||||
// openPage — plain text + the ids of the blocks it covers + a little surrounding
|
|
||||||
// context. Returns null when nothing meaningful is selected.
|
|
||||||
//
|
|
||||||
// Deliberately does NOT emit the ProseMirror positions (from/to): they rot the
|
|
||||||
// instant the document changes and the server tools address content by block id
|
|
||||||
// + text (getNode / editPageText find-replace), never by position.
|
|
||||||
export function getEditorSelectionContext(
|
|
||||||
state: EditorState,
|
|
||||||
): EditorSelectionContext | null {
|
|
||||||
const { selection, doc } = state;
|
|
||||||
// An empty selection (incl. the default caret-at-start of a fresh editor) is
|
|
||||||
// never a "this"/"here" — bail before reading any text.
|
|
||||||
if (selection.empty) return null;
|
|
||||||
|
|
||||||
const { from, to } = selection;
|
|
||||||
|
|
||||||
let text = doc.textBetween(from, to, "\n");
|
|
||||||
let truncated = false;
|
|
||||||
if (text.length > TEXT_CAP) {
|
|
||||||
text = text.slice(0, TEXT_CAP);
|
|
||||||
truncated = true;
|
|
||||||
}
|
|
||||||
// A selection spanning only non-text nodes (e.g. an image) trims to empty ->
|
|
||||||
// treat as no selection.
|
|
||||||
if (text.trim().length === 0) return null;
|
|
||||||
|
|
||||||
// Ids of every block the selection covers, deduped and capped. These bridge
|
|
||||||
// the plain-text selection to the server tools (getNode / editPageText).
|
|
||||||
const blockIds: string[] = [];
|
|
||||||
doc.nodesBetween(from, to, (node) => {
|
|
||||||
const id = node.isBlock ? node.attrs?.id : undefined;
|
|
||||||
if (typeof id === "string" && id.length > 0 && !blockIds.includes(id)) {
|
|
||||||
blockIds.push(id);
|
|
||||||
}
|
|
||||||
});
|
|
||||||
|
|
||||||
// ~160 chars of plain text on each side, clamped to the document bounds, so
|
|
||||||
// editPageText can disambiguate a duplicate of the selected text.
|
|
||||||
const before = doc.textBetween(Math.max(0, from - CONTEXT_CHARS), from, "\n");
|
|
||||||
const after = doc.textBetween(
|
|
||||||
to,
|
|
||||||
Math.min(doc.content.size, to + CONTEXT_CHARS),
|
|
||||||
"\n",
|
|
||||||
);
|
|
||||||
|
|
||||||
const result: EditorSelectionContext = { text };
|
|
||||||
if (truncated) result.truncated = true;
|
|
||||||
if (blockIds.length > 0) result.blockIds = blockIds.slice(0, MAX_BLOCK_IDS);
|
|
||||||
if (before.length > 0) result.before = before;
|
|
||||||
if (after.length > 0) result.after = after;
|
|
||||||
return result;
|
|
||||||
}
|
|
||||||
@@ -0,0 +1,234 @@
|
|||||||
|
import { describe, it, expect, vi, afterEach, beforeAll } from "vitest";
|
||||||
|
import { render, screen, cleanup, within } from "@testing-library/react";
|
||||||
|
import { MantineProvider } from "@mantine/core";
|
||||||
|
|
||||||
|
// Mantine Tooltip mounts its label lazily on hover via Floating UI, which is
|
||||||
|
// flaky under jsdom. Replace ONLY the Tooltip with a thin wrapper that renders
|
||||||
|
// the label inline (keeping Badge/Switch/etc. real), so the provenance label —
|
||||||
|
// the contract we care about — is deterministically queryable.
|
||||||
|
vi.mock("@mantine/core", async () => {
|
||||||
|
const actual =
|
||||||
|
await vi.importActual<typeof import("@mantine/core")>("@mantine/core");
|
||||||
|
const Tooltip = ({
|
||||||
|
label,
|
||||||
|
children,
|
||||||
|
}: {
|
||||||
|
label?: React.ReactNode;
|
||||||
|
children?: React.ReactNode;
|
||||||
|
}) => (
|
||||||
|
<>
|
||||||
|
{children}
|
||||||
|
<span data-testid="tooltip-label">{label}</span>
|
||||||
|
</>
|
||||||
|
);
|
||||||
|
Tooltip.Group = ({ children }: { children?: React.ReactNode }) => (
|
||||||
|
<>{children}</>
|
||||||
|
);
|
||||||
|
return { ...actual, Tooltip };
|
||||||
|
});
|
||||||
|
|
||||||
|
// jsdom lacks matchMedia, which MantineProvider's color-scheme hook needs.
|
||||||
|
beforeAll(() => {
|
||||||
|
if (!window.matchMedia) {
|
||||||
|
window.matchMedia = (query: string) =>
|
||||||
|
({
|
||||||
|
matches: false,
|
||||||
|
media: query,
|
||||||
|
onchange: null,
|
||||||
|
addListener: () => {},
|
||||||
|
removeListener: () => {},
|
||||||
|
addEventListener: () => {},
|
||||||
|
removeEventListener: () => {},
|
||||||
|
dispatchEvent: () => false,
|
||||||
|
}) as unknown as MediaQueryList;
|
||||||
|
}
|
||||||
|
});
|
||||||
|
|
||||||
|
// --- Mocks for the heavy / networked module graph ---------------------------
|
||||||
|
// HistoryItem pulls in i18n, jotai atoms (ai-chat / history), a config-backed
|
||||||
|
// avatar and a time formatter. The provenance-badge contract is the unit under
|
||||||
|
// test, so we stub everything else down to inert, deterministic renders and
|
||||||
|
// keep the real Mantine Badge/Tooltip so role/label queries are meaningful.
|
||||||
|
|
||||||
|
// i18n: interpolate {{name}} so the git-sync tooltip carries the author name,
|
||||||
|
// letting us assert provenance attribution without a real i18n backend.
|
||||||
|
vi.mock("react-i18next", () => ({
|
||||||
|
useTranslation: () => ({
|
||||||
|
t: (key: string, vars?: Record<string, unknown>) =>
|
||||||
|
vars && typeof vars.name !== "undefined"
|
||||||
|
? key.replace("{{name}}", String(vars.name))
|
||||||
|
: key,
|
||||||
|
}),
|
||||||
|
}));
|
||||||
|
|
||||||
|
// jotai setters: the badges call useSetAtom; return inert setters so a click on
|
||||||
|
// the (deep-linkable) AiAgentBadge would fire these — proving the git-sync badge
|
||||||
|
// does NOT wire any of them.
|
||||||
|
const setAiChatWindowOpen = vi.fn();
|
||||||
|
const setActiveChatId = vi.fn();
|
||||||
|
const setDraft = vi.fn();
|
||||||
|
const setHistoryModalOpen = vi.fn();
|
||||||
|
vi.mock("jotai", async () => {
|
||||||
|
const actual = await vi.importActual<typeof import("jotai")>("jotai");
|
||||||
|
return {
|
||||||
|
...actual,
|
||||||
|
useSetAtom: (atom: unknown) => {
|
||||||
|
switch (atom) {
|
||||||
|
case aiChatWindowOpenAtom:
|
||||||
|
return setAiChatWindowOpen;
|
||||||
|
case activeAiChatIdAtom:
|
||||||
|
return setActiveChatId;
|
||||||
|
case aiChatDraftAtom:
|
||||||
|
return setDraft;
|
||||||
|
case historyAtoms:
|
||||||
|
return setHistoryModalOpen;
|
||||||
|
default:
|
||||||
|
return vi.fn();
|
||||||
|
}
|
||||||
|
},
|
||||||
|
};
|
||||||
|
});
|
||||||
|
|
||||||
|
// Atoms are imported only as identity tokens for the useSetAtom switch above.
|
||||||
|
vi.mock("@/features/ai-chat/atoms/ai-chat-atom.ts", () => ({
|
||||||
|
activeAiChatIdAtom: { __tag: "activeAiChatIdAtom" },
|
||||||
|
aiChatWindowOpenAtom: { __tag: "aiChatWindowOpenAtom" },
|
||||||
|
aiChatDraftAtom: { __tag: "aiChatDraftAtom" },
|
||||||
|
}));
|
||||||
|
vi.mock("@/features/page-history/atoms/history-atoms.ts", () => ({
|
||||||
|
historyAtoms: { __tag: "historyAtoms" },
|
||||||
|
}));
|
||||||
|
|
||||||
|
// Avatar reaches into config (getAvatarUrl) — stub to a plain element.
|
||||||
|
vi.mock("@/components/ui/custom-avatar.tsx", () => ({
|
||||||
|
CustomAvatar: ({ name }: { name?: string }) => (
|
||||||
|
<span data-testid="avatar">{name}</span>
|
||||||
|
),
|
||||||
|
}));
|
||||||
|
|
||||||
|
// Deterministic, locale-free date string.
|
||||||
|
vi.mock("@/lib/time", () => ({
|
||||||
|
formattedDate: () => "2026-06-21",
|
||||||
|
}));
|
||||||
|
|
||||||
|
import HistoryItem from "./history-item";
|
||||||
|
import {
|
||||||
|
activeAiChatIdAtom,
|
||||||
|
aiChatWindowOpenAtom,
|
||||||
|
aiChatDraftAtom,
|
||||||
|
} from "@/features/ai-chat/atoms/ai-chat-atom.ts";
|
||||||
|
import { historyAtoms } from "@/features/page-history/atoms/history-atoms.ts";
|
||||||
|
import type { IPageHistory } from "@/features/page-history/types/page.types";
|
||||||
|
|
||||||
|
function makeItem(overrides: Partial<IPageHistory> = {}): IPageHistory {
|
||||||
|
return {
|
||||||
|
id: "h1",
|
||||||
|
pageId: "p1",
|
||||||
|
title: "Title",
|
||||||
|
slug: "slug",
|
||||||
|
icon: "",
|
||||||
|
coverPhoto: "",
|
||||||
|
version: 1,
|
||||||
|
lastUpdatedById: "u1",
|
||||||
|
workspaceId: "w1",
|
||||||
|
createdAt: "2026-06-21T00:00:00.000Z",
|
||||||
|
updatedAt: "2026-06-21T00:00:00.000Z",
|
||||||
|
lastUpdatedBy: { id: "u1", name: "Alice", avatarUrl: "" },
|
||||||
|
...overrides,
|
||||||
|
};
|
||||||
|
}
|
||||||
|
|
||||||
|
function renderItem(item: IPageHistory) {
|
||||||
|
return render(
|
||||||
|
<MantineProvider>
|
||||||
|
<HistoryItem
|
||||||
|
historyItem={item}
|
||||||
|
index={0}
|
||||||
|
onSelect={vi.fn()}
|
||||||
|
isActive={false}
|
||||||
|
/>
|
||||||
|
</MantineProvider>,
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
afterEach(() => {
|
||||||
|
cleanup();
|
||||||
|
vi.clearAllMocks();
|
||||||
|
});
|
||||||
|
|
||||||
|
describe("HistoryItem git-sync provenance badge", () => {
|
||||||
|
// Test 1: the git-sync badge renders ONLY for lastUpdatedSource === 'git-sync'.
|
||||||
|
it("renders the Git sync badge only when lastUpdatedSource is 'git-sync'", () => {
|
||||||
|
renderItem(makeItem({ lastUpdatedSource: "git-sync" }));
|
||||||
|
expect(screen.getByText("Git sync")).toBeTruthy();
|
||||||
|
});
|
||||||
|
|
||||||
|
it.each([
|
||||||
|
["agent", "agent"],
|
||||||
|
["user", "user"],
|
||||||
|
["undefined", undefined],
|
||||||
|
])(
|
||||||
|
"does NOT render the Git sync badge when lastUpdatedSource is %s",
|
||||||
|
(_label, source) => {
|
||||||
|
renderItem(makeItem({ lastUpdatedSource: source }));
|
||||||
|
expect(screen.queryByText("Git sync")).toBeNull();
|
||||||
|
},
|
||||||
|
);
|
||||||
|
|
||||||
|
// Test 2: provenance attribution + the git-sync badge is NOT interactive.
|
||||||
|
it("attributes the git-sync provenance to the correct author and is not clickable", () => {
|
||||||
|
renderItem(
|
||||||
|
makeItem({
|
||||||
|
lastUpdatedSource: "git-sync",
|
||||||
|
lastUpdatedBy: { id: "u2", name: "Bob", avatarUrl: "" },
|
||||||
|
}),
|
||||||
|
);
|
||||||
|
|
||||||
|
const badge = screen.getByText("Git sync");
|
||||||
|
|
||||||
|
// Provenance attribution: the tooltip label carries the author name (the
|
||||||
|
// git-sync badge passes authorName -> "Synced from Git on behalf of {{name}}").
|
||||||
|
expect(screen.getByText("Synced from Git on behalf of Bob")).toBeTruthy();
|
||||||
|
|
||||||
|
// The git-sync badge must NOT behave like AiAgentBadge: the badge element
|
||||||
|
// itself is not a button, carries no role=button and no tabIndex, and
|
||||||
|
// clicking it must not trigger any ai-chat deep-link. (The surrounding
|
||||||
|
// history-row IS an UnstyledButton — that is the row's own select affordance,
|
||||||
|
// not the badge — so we scope these checks to the badge element.)
|
||||||
|
const badgeRoot = (badge.closest("[class*='mantine-Badge-root']") ??
|
||||||
|
badge) as HTMLElement;
|
||||||
|
expect(badgeRoot.getAttribute("role")).not.toBe("button");
|
||||||
|
expect(badgeRoot.getAttribute("tabindex")).toBeNull();
|
||||||
|
expect(badgeRoot.tagName.toLowerCase()).not.toBe("button");
|
||||||
|
// No interactive descendant button lives inside the badge itself.
|
||||||
|
expect(within(badgeRoot).queryByRole("button")).toBeNull();
|
||||||
|
|
||||||
|
badgeRoot.dispatchEvent(new MouseEvent("click", { bubbles: true }));
|
||||||
|
expect(setActiveChatId).not.toHaveBeenCalled();
|
||||||
|
expect(setAiChatWindowOpen).not.toHaveBeenCalled();
|
||||||
|
expect(setDraft).not.toHaveBeenCalled();
|
||||||
|
expect(setHistoryModalOpen).not.toHaveBeenCalled();
|
||||||
|
});
|
||||||
|
|
||||||
|
// Sanity contrast: the agent provenance IS interactive when it carries an
|
||||||
|
// aiChatId — proving the not-clickable assertion above is real. The old text
|
||||||
|
// `AiAgentBadge` was superseded by `AgentAvatarStack` (#300), which becomes a
|
||||||
|
// role=button deep-link (and fires the ai-chat atoms) when an aiChatId is present.
|
||||||
|
it("contrast: the agent stack is a deep-link button when it has an aiChatId", () => {
|
||||||
|
renderItem(
|
||||||
|
makeItem({
|
||||||
|
lastUpdatedSource: "agent",
|
||||||
|
agent: { name: "Zeta" },
|
||||||
|
lastUpdatedAiChatId: "chat-1",
|
||||||
|
}),
|
||||||
|
);
|
||||||
|
// The agent glyph lives inside the clickable stack; walk up to its role=button.
|
||||||
|
const root = screen.getByTestId("agent-glyph").closest("[role='button']");
|
||||||
|
expect(root).not.toBeNull();
|
||||||
|
(root as HTMLElement).dispatchEvent(
|
||||||
|
new MouseEvent("click", { bubbles: true }),
|
||||||
|
);
|
||||||
|
expect(setActiveChatId).toHaveBeenCalledWith("chat-1");
|
||||||
|
expect(setAiChatWindowOpen).toHaveBeenCalled();
|
||||||
|
});
|
||||||
|
});
|
||||||
@@ -1,5 +1,6 @@
|
|||||||
import { Text, Group, UnstyledButton, Avatar, Tooltip } from "@mantine/core";
|
import { Text, Group, UnstyledButton, Avatar, Tooltip } from "@mantine/core";
|
||||||
import { CustomAvatar } from "@/components/ui/custom-avatar.tsx";
|
import { CustomAvatar } from "@/components/ui/custom-avatar.tsx";
|
||||||
|
import { GitSyncBadge } from "@/components/ui/git-sync-badge.tsx";
|
||||||
import { AgentAvatarStack } from "@/components/ui/agent-avatar-stack.tsx";
|
import { AgentAvatarStack } from "@/components/ui/agent-avatar-stack.tsx";
|
||||||
import { formattedDate } from "@/lib/time";
|
import { formattedDate } from "@/lib/time";
|
||||||
import classes from "./css/history.module.css";
|
import classes from "./css/history.module.css";
|
||||||
@@ -41,6 +42,7 @@ const HistoryItem = memo(function HistoryItem({
|
|||||||
const contributors = historyItem.contributors;
|
const contributors = historyItem.contributors;
|
||||||
const hasContributors = contributors && contributors.length > 0;
|
const hasContributors = contributors && contributors.length > 0;
|
||||||
const isAgentEdit = historyItem.lastUpdatedSource === "agent";
|
const isAgentEdit = historyItem.lastUpdatedSource === "agent";
|
||||||
|
const isGitSyncEdit = historyItem.lastUpdatedSource === "git-sync";
|
||||||
|
|
||||||
return (
|
return (
|
||||||
<UnstyledButton
|
<UnstyledButton
|
||||||
@@ -109,6 +111,10 @@ const HistoryItem = memo(function HistoryItem({
|
|||||||
onActivate={() => setHistoryModalOpen(false)}
|
onActivate={() => setHistoryModalOpen(false)}
|
||||||
/>
|
/>
|
||||||
)}
|
)}
|
||||||
|
|
||||||
|
{isGitSyncEdit && (
|
||||||
|
<GitSyncBadge authorName={historyItem.lastUpdatedBy?.name} />
|
||||||
|
)}
|
||||||
</Group>
|
</Group>
|
||||||
</UnstyledButton>
|
</UnstyledButton>
|
||||||
);
|
);
|
||||||
|
|||||||
@@ -165,9 +165,6 @@ export default function ShareAiWidget({
|
|||||||
isStreaming={isStreaming}
|
isStreaming={isStreaming}
|
||||||
assistantName={assistantName}
|
assistantName={assistantName}
|
||||||
showCitations={false}
|
showCitations={false}
|
||||||
// Anonymous reader: suppress the tool-argument summary line so the
|
|
||||||
// agent's raw query/argument text isn't shown on the public share.
|
|
||||||
showInput={false}
|
|
||||||
// Anonymous reader: neutralize internal/relative links in the
|
// Anonymous reader: neutralize internal/relative links in the
|
||||||
// assistant's markdown so internal UUIDs/auth-gated routes don't
|
// assistant's markdown so internal UUIDs/auth-gated routes don't
|
||||||
// leak as clickable links (external http(s) links are kept).
|
// leak as clickable links (external http(s) links are kept).
|
||||||
|
|||||||
@@ -0,0 +1,240 @@
|
|||||||
|
import {
|
||||||
|
describe,
|
||||||
|
it,
|
||||||
|
expect,
|
||||||
|
vi,
|
||||||
|
beforeAll,
|
||||||
|
afterEach,
|
||||||
|
} from "vitest";
|
||||||
|
import {
|
||||||
|
render,
|
||||||
|
screen,
|
||||||
|
cleanup,
|
||||||
|
fireEvent,
|
||||||
|
waitFor,
|
||||||
|
} from "@testing-library/react";
|
||||||
|
import { MantineProvider } from "@mantine/core";
|
||||||
|
|
||||||
|
// --- Mocks for the heavy / networked module graph ---------------------------
|
||||||
|
// EditSpaceForm wires the "Enable Git sync" Switch to a TanStack-Query mutation
|
||||||
|
// (useUpdateSpaceMutation). We mock ONLY that hook so the test fully controls
|
||||||
|
// mutateAsync (resolve / reject) and isPending, and stub i18n. The real Mantine
|
||||||
|
// Switch is rendered so the checkbox role / disabled state is meaningful.
|
||||||
|
|
||||||
|
// i18n: identity translator — labels stay as their English keys for queries.
|
||||||
|
vi.mock("react-i18next", () => ({
|
||||||
|
useTranslation: () => ({ t: (key: string) => key }),
|
||||||
|
}));
|
||||||
|
|
||||||
|
// Mutation hook: a controllable mutateAsync plus a togglable isPending.
|
||||||
|
const mutateAsync = vi.fn();
|
||||||
|
let isPending = false;
|
||||||
|
vi.mock("@/features/space/queries/space-query.ts", () => ({
|
||||||
|
useUpdateSpaceMutation: () => ({
|
||||||
|
mutateAsync,
|
||||||
|
get isPending() {
|
||||||
|
return isPending;
|
||||||
|
},
|
||||||
|
}),
|
||||||
|
}));
|
||||||
|
|
||||||
|
// jsdom lacks matchMedia, which MantineProvider's color-scheme hook needs.
|
||||||
|
beforeAll(() => {
|
||||||
|
if (!window.matchMedia) {
|
||||||
|
window.matchMedia = (query: string) =>
|
||||||
|
({
|
||||||
|
matches: false,
|
||||||
|
media: query,
|
||||||
|
onchange: null,
|
||||||
|
addListener: () => {},
|
||||||
|
removeListener: () => {},
|
||||||
|
addEventListener: () => {},
|
||||||
|
removeEventListener: () => {},
|
||||||
|
dispatchEvent: () => false,
|
||||||
|
}) as unknown as MediaQueryList;
|
||||||
|
}
|
||||||
|
});
|
||||||
|
|
||||||
|
import { EditSpaceForm } from "./edit-space-form";
|
||||||
|
import type { ISpace } from "@/features/space/types/space.types.ts";
|
||||||
|
|
||||||
|
function makeSpace(overrides: Partial<ISpace> = {}): ISpace {
|
||||||
|
return {
|
||||||
|
id: "space-1",
|
||||||
|
name: "Engineering",
|
||||||
|
description: "",
|
||||||
|
slug: "eng",
|
||||||
|
hostname: "host",
|
||||||
|
creatorId: "u1",
|
||||||
|
createdAt: new Date("2026-01-01"),
|
||||||
|
updatedAt: new Date("2026-01-01"),
|
||||||
|
...overrides,
|
||||||
|
} as ISpace;
|
||||||
|
}
|
||||||
|
|
||||||
|
function renderForm(props: { space: ISpace; readOnly?: boolean }) {
|
||||||
|
return render(
|
||||||
|
<MantineProvider>
|
||||||
|
<EditSpaceForm space={props.space} readOnly={props.readOnly} />
|
||||||
|
</MantineProvider>,
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
// The form now renders TWO switches (git-sync enable + auto-merge-conflicts) in
|
||||||
|
// that DOM order. Mantine renders each as an <input type="checkbox"
|
||||||
|
// role="switch"> but does NOT expose its label as the accessible name, so we
|
||||||
|
// disambiguate by DOM order (index 0 = enable, 1 = auto-merge) and assert the
|
||||||
|
// human-readable label text is present alongside.
|
||||||
|
function getToggle(): HTMLInputElement {
|
||||||
|
screen.getByText("Enable Git sync");
|
||||||
|
return screen.getAllByRole("switch")[0] as HTMLInputElement;
|
||||||
|
}
|
||||||
|
|
||||||
|
function getAutoMergeToggle(): HTMLInputElement {
|
||||||
|
screen.getByText("Auto-merge conflicts on push");
|
||||||
|
return screen.getAllByRole("switch")[1] as HTMLInputElement;
|
||||||
|
}
|
||||||
|
|
||||||
|
afterEach(() => {
|
||||||
|
cleanup();
|
||||||
|
mutateAsync.mockReset();
|
||||||
|
isPending = false;
|
||||||
|
});
|
||||||
|
|
||||||
|
describe("EditSpaceForm git-sync toggle", () => {
|
||||||
|
// Test 3: initial checked state derives from settings.gitSync.enabled ?? false.
|
||||||
|
it("derives initial checked state from space.settings.gitSync.enabled (true -> checked)", () => {
|
||||||
|
renderForm({
|
||||||
|
space: makeSpace({ settings: { gitSync: { enabled: true } } }),
|
||||||
|
});
|
||||||
|
expect(getToggle().checked).toBe(true);
|
||||||
|
});
|
||||||
|
|
||||||
|
it("defaults to unchecked when gitSync settings are missing", () => {
|
||||||
|
renderForm({ space: makeSpace() });
|
||||||
|
expect(getToggle().checked).toBe(false);
|
||||||
|
});
|
||||||
|
|
||||||
|
// Test 4: toggling fires the mutation with { spaceId, gitSyncEnabled } and
|
||||||
|
// optimistically flips the switch.
|
||||||
|
it("fires the mutation with the correct payload and optimistically flips on", async () => {
|
||||||
|
mutateAsync.mockResolvedValue(undefined);
|
||||||
|
renderForm({ space: makeSpace() });
|
||||||
|
|
||||||
|
const toggle = getToggle();
|
||||||
|
expect(toggle.checked).toBe(false);
|
||||||
|
|
||||||
|
fireEvent.click(toggle);
|
||||||
|
|
||||||
|
// Optimistic update: the switch reflects the new state immediately.
|
||||||
|
expect(toggle.checked).toBe(true);
|
||||||
|
|
||||||
|
expect(mutateAsync).toHaveBeenCalledTimes(1);
|
||||||
|
expect(mutateAsync).toHaveBeenCalledWith({
|
||||||
|
spaceId: "space-1",
|
||||||
|
gitSyncEnabled: true,
|
||||||
|
});
|
||||||
|
|
||||||
|
// Resolution leaves the toggle on.
|
||||||
|
await waitFor(() => expect(toggle.checked).toBe(true));
|
||||||
|
});
|
||||||
|
|
||||||
|
// Test 5: rollback on mutation error — the most valuable test.
|
||||||
|
it("rolls back the toggle to its prior state when the mutation rejects", async () => {
|
||||||
|
mutateAsync.mockRejectedValue(new Error("network"));
|
||||||
|
renderForm({
|
||||||
|
space: makeSpace({ settings: { gitSync: { enabled: false } } }),
|
||||||
|
});
|
||||||
|
|
||||||
|
const toggle = getToggle();
|
||||||
|
expect(toggle.checked).toBe(false);
|
||||||
|
|
||||||
|
fireEvent.click(toggle);
|
||||||
|
|
||||||
|
// Optimistically flips on before the rejection lands.
|
||||||
|
expect(toggle.checked).toBe(true);
|
||||||
|
expect(mutateAsync).toHaveBeenCalledWith({
|
||||||
|
spaceId: "space-1",
|
||||||
|
gitSyncEnabled: true,
|
||||||
|
});
|
||||||
|
|
||||||
|
// After the rejected promise settles, the component reverts to OFF so the
|
||||||
|
// user is not misled into believing sync is enabled.
|
||||||
|
await waitFor(() => expect(toggle.checked).toBe(false));
|
||||||
|
});
|
||||||
|
|
||||||
|
// Test 6: disabled when readOnly and when the mutation is pending.
|
||||||
|
it("disables the toggle when readOnly", () => {
|
||||||
|
renderForm({ space: makeSpace(), readOnly: true });
|
||||||
|
expect(getToggle().disabled).toBe(true);
|
||||||
|
});
|
||||||
|
|
||||||
|
it("disables the toggle while the mutation is pending", () => {
|
||||||
|
isPending = true;
|
||||||
|
renderForm({ space: makeSpace() });
|
||||||
|
expect(getToggle().disabled).toBe(true);
|
||||||
|
});
|
||||||
|
});
|
||||||
|
|
||||||
|
describe("EditSpaceForm auto-merge-conflicts toggle", () => {
|
||||||
|
it("derives initial checked state from space.settings.gitSync.autoMergeConflicts (true -> checked)", () => {
|
||||||
|
renderForm({
|
||||||
|
space: makeSpace({
|
||||||
|
settings: { gitSync: { autoMergeConflicts: true } },
|
||||||
|
}),
|
||||||
|
});
|
||||||
|
expect(getAutoMergeToggle().checked).toBe(true);
|
||||||
|
});
|
||||||
|
|
||||||
|
it("defaults to unchecked when autoMergeConflicts is missing (SAFE default)", () => {
|
||||||
|
renderForm({ space: makeSpace() });
|
||||||
|
expect(getAutoMergeToggle().checked).toBe(false);
|
||||||
|
});
|
||||||
|
|
||||||
|
it("fires the mutation with { spaceId, autoMergeConflicts } and optimistically flips on", async () => {
|
||||||
|
mutateAsync.mockResolvedValue(undefined);
|
||||||
|
renderForm({ space: makeSpace() });
|
||||||
|
|
||||||
|
const toggle = getAutoMergeToggle();
|
||||||
|
expect(toggle.checked).toBe(false);
|
||||||
|
|
||||||
|
fireEvent.click(toggle);
|
||||||
|
|
||||||
|
// Optimistic update.
|
||||||
|
expect(toggle.checked).toBe(true);
|
||||||
|
expect(mutateAsync).toHaveBeenCalledTimes(1);
|
||||||
|
expect(mutateAsync).toHaveBeenCalledWith({
|
||||||
|
spaceId: "space-1",
|
||||||
|
autoMergeConflicts: true,
|
||||||
|
});
|
||||||
|
|
||||||
|
await waitFor(() => expect(toggle.checked).toBe(true));
|
||||||
|
});
|
||||||
|
|
||||||
|
it("rolls back to its prior state when the mutation rejects", async () => {
|
||||||
|
mutateAsync.mockRejectedValue(new Error("network"));
|
||||||
|
renderForm({
|
||||||
|
space: makeSpace({
|
||||||
|
settings: { gitSync: { autoMergeConflicts: false } },
|
||||||
|
}),
|
||||||
|
});
|
||||||
|
|
||||||
|
const toggle = getAutoMergeToggle();
|
||||||
|
expect(toggle.checked).toBe(false);
|
||||||
|
|
||||||
|
fireEvent.click(toggle);
|
||||||
|
|
||||||
|
expect(toggle.checked).toBe(true);
|
||||||
|
expect(mutateAsync).toHaveBeenCalledWith({
|
||||||
|
spaceId: "space-1",
|
||||||
|
autoMergeConflicts: true,
|
||||||
|
});
|
||||||
|
|
||||||
|
await waitFor(() => expect(toggle.checked).toBe(false));
|
||||||
|
});
|
||||||
|
|
||||||
|
it("disables the toggle when readOnly", () => {
|
||||||
|
renderForm({ space: makeSpace(), readOnly: true });
|
||||||
|
expect(getAutoMergeToggle().disabled).toBe(true);
|
||||||
|
});
|
||||||
|
});
|
||||||
@@ -1,5 +1,14 @@
|
|||||||
import { Group, Box, Button, TextInput, Stack, Textarea } from "@mantine/core";
|
import {
|
||||||
import React from "react";
|
Group,
|
||||||
|
Box,
|
||||||
|
Button,
|
||||||
|
TextInput,
|
||||||
|
Stack,
|
||||||
|
Textarea,
|
||||||
|
Divider,
|
||||||
|
Switch,
|
||||||
|
} from "@mantine/core";
|
||||||
|
import React, { useState } from "react";
|
||||||
import { useForm } from "@mantine/form";
|
import { useForm } from "@mantine/form";
|
||||||
import { zod4Resolver } from "mantine-form-zod-resolver";
|
import { zod4Resolver } from "mantine-form-zod-resolver";
|
||||||
import { z } from "zod/v4";
|
import { z } from "zod/v4";
|
||||||
@@ -29,6 +38,37 @@ export function EditSpaceForm({ space, readOnly }: EditSpaceFormProps) {
|
|||||||
const { t } = useTranslation();
|
const { t } = useTranslation();
|
||||||
const updateSpaceMutation = useUpdateSpaceMutation();
|
const updateSpaceMutation = useUpdateSpaceMutation();
|
||||||
|
|
||||||
|
const [gitSyncEnabled, setGitSyncEnabled] = useState<boolean>(
|
||||||
|
space?.settings?.gitSync?.enabled ?? false,
|
||||||
|
);
|
||||||
|
|
||||||
|
const [autoMergeConflicts, setAutoMergeConflicts] = useState<boolean>(
|
||||||
|
space?.settings?.gitSync?.autoMergeConflicts ?? false,
|
||||||
|
);
|
||||||
|
|
||||||
|
// One parameterized handler for both git-sync space toggles: they differ only by
|
||||||
|
// the local state setter, the mutation payload field, and the error label. The
|
||||||
|
// update is optimistic and reverts the local state on failure (the mutation
|
||||||
|
// surfaces a toast via onError; the raw error is still logged per AGENTS.md).
|
||||||
|
const handleToggle = async (
|
||||||
|
field: "gitSyncEnabled" | "autoMergeConflicts",
|
||||||
|
value: boolean,
|
||||||
|
previous: boolean,
|
||||||
|
setLocal: (next: boolean) => void,
|
||||||
|
errorLabel: string,
|
||||||
|
) => {
|
||||||
|
setLocal(value); // optimistic update
|
||||||
|
try {
|
||||||
|
await updateSpaceMutation.mutateAsync({
|
||||||
|
spaceId: space.id,
|
||||||
|
[field]: value,
|
||||||
|
});
|
||||||
|
} catch (err) {
|
||||||
|
setLocal(previous); // revert on failure
|
||||||
|
console.error(errorLabel, err);
|
||||||
|
}
|
||||||
|
};
|
||||||
|
|
||||||
const form = useForm<FormValues>({
|
const form = useForm<FormValues>({
|
||||||
validate: zod4Resolver(formSchema),
|
validate: zod4Resolver(formSchema),
|
||||||
initialValues: {
|
initialValues: {
|
||||||
@@ -104,6 +144,43 @@ export function EditSpaceForm({ space, readOnly }: EditSpaceFormProps) {
|
|||||||
</Group>
|
</Group>
|
||||||
)}
|
)}
|
||||||
</form>
|
</form>
|
||||||
|
|
||||||
|
<Divider my="lg" />
|
||||||
|
|
||||||
|
<Switch
|
||||||
|
label={t("Enable Git sync")}
|
||||||
|
description={t("Sync this space's pages to a Git repository.")}
|
||||||
|
checked={gitSyncEnabled}
|
||||||
|
disabled={readOnly || updateSpaceMutation.isPending}
|
||||||
|
onChange={(event) =>
|
||||||
|
handleToggle(
|
||||||
|
"gitSyncEnabled",
|
||||||
|
event.currentTarget.checked,
|
||||||
|
gitSyncEnabled,
|
||||||
|
setGitSyncEnabled,
|
||||||
|
"Failed to toggle git-sync for space",
|
||||||
|
)
|
||||||
|
}
|
||||||
|
/>
|
||||||
|
|
||||||
|
<Switch
|
||||||
|
mt="md"
|
||||||
|
label={t("Auto-merge conflicts on push")}
|
||||||
|
description={t(
|
||||||
|
"When off (recommended), a page whose content still has unresolved Git conflict markers is skipped on push until you resolve the conflict in Git. When on, the markers are stripped and both sides' content is pushed.",
|
||||||
|
)}
|
||||||
|
checked={autoMergeConflicts}
|
||||||
|
disabled={readOnly || updateSpaceMutation.isPending}
|
||||||
|
onChange={(event) =>
|
||||||
|
handleToggle(
|
||||||
|
"autoMergeConflicts",
|
||||||
|
event.currentTarget.checked,
|
||||||
|
autoMergeConflicts,
|
||||||
|
setAutoMergeConflicts,
|
||||||
|
"Failed to toggle git-sync auto-merge-conflicts",
|
||||||
|
)
|
||||||
|
}
|
||||||
|
/>
|
||||||
</Box>
|
</Box>
|
||||||
</>
|
</>
|
||||||
);
|
);
|
||||||
|
|||||||
@@ -13,9 +13,15 @@ export interface ISpaceCommentsSettings {
|
|||||||
allowViewerComments?: boolean;
|
allowViewerComments?: boolean;
|
||||||
}
|
}
|
||||||
|
|
||||||
|
export interface ISpaceGitSyncSettings {
|
||||||
|
enabled?: boolean;
|
||||||
|
autoMergeConflicts?: boolean;
|
||||||
|
}
|
||||||
|
|
||||||
export interface ISpaceSettings {
|
export interface ISpaceSettings {
|
||||||
sharing?: ISpaceSharingSettings;
|
sharing?: ISpaceSharingSettings;
|
||||||
comments?: ISpaceCommentsSettings;
|
comments?: ISpaceCommentsSettings;
|
||||||
|
gitSync?: ISpaceGitSyncSettings;
|
||||||
}
|
}
|
||||||
|
|
||||||
export interface ISpace {
|
export interface ISpace {
|
||||||
@@ -35,6 +41,8 @@ export interface ISpace {
|
|||||||
// for updates
|
// for updates
|
||||||
disablePublicSharing?: boolean;
|
disablePublicSharing?: boolean;
|
||||||
allowViewerComments?: boolean;
|
allowViewerComments?: boolean;
|
||||||
|
gitSyncEnabled?: boolean;
|
||||||
|
autoMergeConflicts?: boolean;
|
||||||
}
|
}
|
||||||
|
|
||||||
interface IMembership {
|
interface IMembership {
|
||||||
|
|||||||
@@ -23,7 +23,7 @@
|
|||||||
"migration:reset": "tsx src/database/migrate.ts down-to NO_MIGRATIONS",
|
"migration:reset": "tsx src/database/migrate.ts down-to NO_MIGRATIONS",
|
||||||
"migration:codegen": "kysely-codegen --dialect=postgres --camel-case --env-file=../../.env --out-file=./src/database/types/db.d.ts",
|
"migration:codegen": "kysely-codegen --dialect=postgres --camel-case --env-file=../../.env --out-file=./src/database/types/db.d.ts",
|
||||||
"lint": "eslint \"{src,apps,libs,test}/**/*.ts\" --fix",
|
"lint": "eslint \"{src,apps,libs,test}/**/*.ts\" --fix",
|
||||||
"pretest": "pnpm --filter @docmost/editor-ext build && pnpm --filter @docmost/prosemirror-markdown build",
|
"pretest": "pnpm --filter @docmost/editor-ext build && pnpm --filter @docmost/prosemirror-markdown build && pnpm --filter @docmost/git-sync build && pnpm --filter @docmost/mcp build",
|
||||||
"test": "jest",
|
"test": "jest",
|
||||||
"test:int": "jest --config test/jest-integration.json",
|
"test:int": "jest --config test/jest-integration.json",
|
||||||
"test:watch": "jest --watch",
|
"test:watch": "jest --watch",
|
||||||
@@ -41,6 +41,7 @@
|
|||||||
"@aws-sdk/s3-request-presigner": "3.1050.0",
|
"@aws-sdk/s3-request-presigner": "3.1050.0",
|
||||||
"@azure/storage-blob": "12.31.0",
|
"@azure/storage-blob": "12.31.0",
|
||||||
"@clickhouse/client": "^1.18.2",
|
"@clickhouse/client": "^1.18.2",
|
||||||
|
"@docmost/git-sync": "workspace:*",
|
||||||
"@docmost/mcp": "workspace:*",
|
"@docmost/mcp": "workspace:*",
|
||||||
"@docmost/pdf-inspector": "1.9.6",
|
"@docmost/pdf-inspector": "1.9.6",
|
||||||
"@docmost/prosemirror-markdown": "workspace:*",
|
"@docmost/prosemirror-markdown": "workspace:*",
|
||||||
@@ -191,7 +192,12 @@
|
|||||||
]
|
]
|
||||||
}
|
}
|
||||||
],
|
],
|
||||||
"^.+\\.(t|j)sx?$": "ts-jest"
|
"^.+\\.(t|j)sx?$": [
|
||||||
|
"ts-jest",
|
||||||
|
{
|
||||||
|
"isolatedModules": true
|
||||||
|
}
|
||||||
|
]
|
||||||
},
|
},
|
||||||
"transformIgnorePatterns": [
|
"transformIgnorePatterns": [
|
||||||
"/node_modules/(?!(\\.pnpm/)?(nanoid|uuid|image-dimensions|marked|happy-dom|lib0|@docmost/prosemirror-markdown)(@|/))"
|
"/node_modules/(?!(\\.pnpm/)?(nanoid|uuid|image-dimensions|marked|happy-dom|lib0|@docmost/prosemirror-markdown)(@|/))"
|
||||||
@@ -201,12 +207,18 @@
|
|||||||
],
|
],
|
||||||
"coverageDirectory": "../coverage",
|
"coverageDirectory": "../coverage",
|
||||||
"testEnvironment": "node",
|
"testEnvironment": "node",
|
||||||
|
"setupFiles": [
|
||||||
|
"<rootDir>/../test/jest.setup.ts"
|
||||||
|
],
|
||||||
"moduleNameMapper": {
|
"moduleNameMapper": {
|
||||||
"^@docmost/db/(.*)$": "<rootDir>/database/$1",
|
"^@docmost/db/(.*)$": "<rootDir>/database/$1",
|
||||||
"^@docmost/transactional/(.*)$": "<rootDir>/integrations/transactional/$1",
|
"^@docmost/transactional/(.*)$": "<rootDir>/integrations/transactional/$1",
|
||||||
"^@docmost/ee/(.*)$": "<rootDir>/ee/$1",
|
"^@docmost/ee/(.*)$": "<rootDir>/ee/$1",
|
||||||
"^src/(.*)$": "<rootDir>/$1",
|
"^src/(.*)$": "<rootDir>/$1",
|
||||||
"^@tiptap/react$": "<rootDir>/../test/stubs/tiptap-react.js"
|
"^@tiptap/react$": "<rootDir>/../test/stubs/tiptap-react.js",
|
||||||
|
"^@docmost/git-sync$": "<rootDir>/../../../packages/git-sync/src/index.ts",
|
||||||
|
"^@docmost/git-sync/(.*)$": "<rootDir>/../../../packages/git-sync/src/$1",
|
||||||
|
"^(\\.{1,2}/.*)\\.js$": "$1"
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|||||||
@@ -28,6 +28,7 @@ import { ClsModule } from 'nestjs-cls';
|
|||||||
import { NoopAuditModule } from './integrations/audit/audit.module';
|
import { NoopAuditModule } from './integrations/audit/audit.module';
|
||||||
import { ThrottleModule } from './integrations/throttle/throttle.module';
|
import { ThrottleModule } from './integrations/throttle/throttle.module';
|
||||||
import { McpModule } from './integrations/mcp/mcp.module';
|
import { McpModule } from './integrations/mcp/mcp.module';
|
||||||
|
import { GitSyncModule } from './integrations/git-sync/git-sync.module';
|
||||||
import { SandboxModule } from './integrations/sandbox/sandbox.module';
|
import { SandboxModule } from './integrations/sandbox/sandbox.module';
|
||||||
import { AiModule } from './integrations/ai/ai.module';
|
import { AiModule } from './integrations/ai/ai.module';
|
||||||
import { AiChatModule } from './core/ai-chat/ai-chat.module';
|
import { AiChatModule } from './core/ai-chat/ai-chat.module';
|
||||||
@@ -92,6 +93,7 @@ try {
|
|||||||
TelemetryModule,
|
TelemetryModule,
|
||||||
ThrottleModule,
|
ThrottleModule,
|
||||||
McpModule,
|
McpModule,
|
||||||
|
GitSyncModule,
|
||||||
SandboxModule,
|
SandboxModule,
|
||||||
AiModule,
|
AiModule,
|
||||||
AiChatModule,
|
AiChatModule,
|
||||||
|
|||||||
@@ -1,9 +1,4 @@
|
|||||||
import {
|
import { Hocuspocus } from '@hocuspocus/server';
|
||||||
connectedPayload,
|
|
||||||
Extension,
|
|
||||||
Hocuspocus,
|
|
||||||
onConnectPayload,
|
|
||||||
} from '@hocuspocus/server';
|
|
||||||
import { IncomingMessage } from 'http';
|
import { IncomingMessage } from 'http';
|
||||||
import WebSocket from 'ws';
|
import WebSocket from 'ws';
|
||||||
import { AuthenticationExtension } from './extensions/authentication.extension';
|
import { AuthenticationExtension } from './extensions/authentication.extension';
|
||||||
@@ -30,56 +25,6 @@ import {
|
|||||||
CollaborationHandler,
|
CollaborationHandler,
|
||||||
CollabEventHandlers,
|
CollabEventHandlers,
|
||||||
} from './collaboration.handler';
|
} from './collaboration.handler';
|
||||||
import {
|
|
||||||
incDocLoad,
|
|
||||||
incDocUnload,
|
|
||||||
isMetricsEnabled,
|
|
||||||
observeCollabConnect,
|
|
||||||
registerDocsOpenSource,
|
|
||||||
} from '../integrations/metrics/metrics.registry';
|
|
||||||
|
|
||||||
/**
|
|
||||||
* #402 — collab lifecycle metrics as a lightweight hocuspocus extension.
|
|
||||||
*
|
|
||||||
* - afterLoadDocument / afterUnloadDocument (fire once PER DOCUMENT) drive the
|
|
||||||
* doc load/unload counters.
|
|
||||||
* - collab_connect_duration_seconds: I time the onConnect→connected hook pair,
|
|
||||||
* i.e. connection ACCEPTANCE (which includes the auth handshake). This is the
|
|
||||||
* cleanest per-connection correlation hocuspocus exposes: both payloads carry
|
|
||||||
* the SAME `request` IncomingMessage object, so a WeakMap keyed on it gives a
|
|
||||||
* per-connection start with NO leak (the entry is GC'd with the request if a
|
|
||||||
* connection is rejected in onAuthenticate and `connected` never fires).
|
|
||||||
* I deliberately do NOT observe at afterLoadDocument: that hook fires per
|
|
||||||
* DOCUMENT, not per connection, so a second client joining an already-open
|
|
||||||
* doc would be missed. auth/load latencies are their own separate metrics.
|
|
||||||
*
|
|
||||||
* All helpers are no-ops when METRICS_PORT is unset; these hooks are per
|
|
||||||
* connect/load/unload (never per message), so there is no hot-path cost.
|
|
||||||
*/
|
|
||||||
class CollabMetricsExtension implements Extension {
|
|
||||||
// Keyed by the per-connection request object → connect start time (ms).
|
|
||||||
private readonly connectStarts = new WeakMap<object, number>();
|
|
||||||
|
|
||||||
async onConnect(data: onConnectPayload) {
|
|
||||||
this.connectStarts.set(data.request, performance.now());
|
|
||||||
}
|
|
||||||
|
|
||||||
async connected(data: connectedPayload) {
|
|
||||||
const start = this.connectStarts.get(data.request);
|
|
||||||
if (start !== undefined) {
|
|
||||||
observeCollabConnect((performance.now() - start) / 1000);
|
|
||||||
this.connectStarts.delete(data.request);
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
async afterLoadDocument() {
|
|
||||||
incDocLoad();
|
|
||||||
}
|
|
||||||
|
|
||||||
async afterUnloadDocument() {
|
|
||||||
incDocUnload();
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
@Injectable()
|
@Injectable()
|
||||||
export class CollaborationGateway {
|
export class CollaborationGateway {
|
||||||
@@ -113,18 +58,9 @@ export class CollaborationGateway {
|
|||||||
this.authenticationExtension,
|
this.authenticationExtension,
|
||||||
this.persistenceExtension,
|
this.persistenceExtension,
|
||||||
this.loggerExtension,
|
this.loggerExtension,
|
||||||
// #402 collab lifecycle + connect-duration metrics (no-op when off).
|
|
||||||
new CollabMetricsExtension(),
|
|
||||||
],
|
],
|
||||||
});
|
});
|
||||||
|
|
||||||
// #402 — read-on-scrape source for collab_docs_open. Wire ONCE, gated, so
|
|
||||||
// nothing runs when metrics are disabled. The gauge's collect() pulls the
|
|
||||||
// live count from the hocuspocus instance on each scrape (no inc/dec drift).
|
|
||||||
if (isMetricsEnabled()) {
|
|
||||||
registerDocsOpenSource(() => this.hocuspocus.getDocumentsCount());
|
|
||||||
}
|
|
||||||
|
|
||||||
if (this.withRedis) {
|
if (this.withRedis) {
|
||||||
this.redisClient = new RedisClient({
|
this.redisClient = new RedisClient({
|
||||||
host: this.redisConfig.host,
|
host: this.redisConfig.host,
|
||||||
@@ -252,6 +188,45 @@ export class CollaborationGateway {
|
|||||||
return this.hocuspocus.openDirectConnection(documentName, context);
|
return this.hocuspocus.openDirectConnection(documentName, context);
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Write a git-originated body into a page, applying the merge on the instance
|
||||||
|
* that OWNS the live Y.Doc so a connected editor CONVERGES on the change.
|
||||||
|
*
|
||||||
|
* git-sync must NOT use openDirectConnection directly for this: that opens the
|
||||||
|
* document on whichever instance/process runs git-sync (the API/worker). When
|
||||||
|
* an editor is connected to a DIFFERENT collab instance/process, that is a
|
||||||
|
* SEPARATE, detached Y.Doc — the merge lands in the detached doc and the DB,
|
||||||
|
* but the live editor never receives the Yjs update; its next debounced
|
||||||
|
* autosave then overwrites the DB with its stale state and SILENTLY REVERTS
|
||||||
|
* the git change (the data-loss bug). Routing through the custom-event channel
|
||||||
|
* runs the merge on the owning instance's shared Document, whose update is
|
||||||
|
* broadcast to every connection (handleUpdate), so the editor's CRDT converges
|
||||||
|
* on the merged result.
|
||||||
|
*
|
||||||
|
* Without redis there is a single instance, so the write runs locally — which
|
||||||
|
* is already the owning (and only) instance the editor is connected to.
|
||||||
|
*/
|
||||||
|
async writePageBody(
|
||||||
|
documentName: string,
|
||||||
|
payload: {
|
||||||
|
prosemirrorJson: unknown;
|
||||||
|
baseProsemirrorJson?: unknown;
|
||||||
|
userId: string;
|
||||||
|
},
|
||||||
|
): Promise<void> {
|
||||||
|
if (this.redisSync) {
|
||||||
|
await this.handleYjsEvent(
|
||||||
|
'gitSyncWriteBody',
|
||||||
|
documentName,
|
||||||
|
payload as any,
|
||||||
|
);
|
||||||
|
return;
|
||||||
|
}
|
||||||
|
await this.collabEventsService
|
||||||
|
.getHandlers(this.hocuspocus)
|
||||||
|
.gitSyncWriteBody(documentName, payload as any);
|
||||||
|
}
|
||||||
|
|
||||||
/*
|
/*
|
||||||
*Can be used before calling openDirectConnection directly
|
*Can be used before calling openDirectConnection directly
|
||||||
*/
|
*/
|
||||||
|
|||||||
@@ -0,0 +1,262 @@
|
|||||||
|
// Exercises the REAL `gitSyncWriteBody` collab handler (the owner-routed body
|
||||||
|
// write the data-loss fix introduces). The handler imports the editor graph via
|
||||||
|
// collaboration.util / yjs.util (tiptapExtensions -> editor-ext -> react-dom,
|
||||||
|
// unloadable under jest's node env, same coupling noted in
|
||||||
|
// gitmost-datasource.service.spec.ts), so we stub those + the transformer. The
|
||||||
|
// stubbed toYdoc builds paragraph blocks straight from the ProseMirror JSON so
|
||||||
|
// we can assert convergence on real text.
|
||||||
|
jest.mock('./collaboration.util', () => ({
|
||||||
|
tiptapExtensions: [],
|
||||||
|
getPageId: (name: string) => name.replace(/^page\./, ''),
|
||||||
|
prosemirrorNodeToYElement: jest.fn(),
|
||||||
|
}));
|
||||||
|
jest.mock('./yjs.util', () => ({
|
||||||
|
setYjsMark: jest.fn(),
|
||||||
|
updateYjsMarkAttribute: jest.fn(),
|
||||||
|
}));
|
||||||
|
jest.mock('@hocuspocus/transformer', () => {
|
||||||
|
const Yjs = require('yjs');
|
||||||
|
return {
|
||||||
|
TiptapTransformer: {
|
||||||
|
toYdoc: (json: any) => {
|
||||||
|
if (json?.__throw) throw new Error('boom: malformed doc');
|
||||||
|
const d = new Yjs.Doc();
|
||||||
|
const frag = d.getXmlFragment('default');
|
||||||
|
const blocks = (json?.content ?? []).map((node: any) => {
|
||||||
|
const el = new Yjs.XmlElement(node.type || 'paragraph');
|
||||||
|
const text = (node.content ?? [])
|
||||||
|
.map((t: any) => t.text ?? '')
|
||||||
|
.join('');
|
||||||
|
const t = new Yjs.XmlText();
|
||||||
|
if (text) t.insert(0, text);
|
||||||
|
el.insert(0, [t]);
|
||||||
|
return el;
|
||||||
|
});
|
||||||
|
if (blocks.length) frag.insert(0, blocks);
|
||||||
|
return d;
|
||||||
|
},
|
||||||
|
},
|
||||||
|
};
|
||||||
|
});
|
||||||
|
|
||||||
|
import * as Y from 'yjs';
|
||||||
|
import { CollaborationHandler } from './collaboration.handler';
|
||||||
|
|
||||||
|
const pmDoc = (...paras: string[]) => ({
|
||||||
|
type: 'doc',
|
||||||
|
content: paras.map((text) => ({
|
||||||
|
type: 'paragraph',
|
||||||
|
content: text ? [{ type: 'text', text }] : [],
|
||||||
|
})),
|
||||||
|
});
|
||||||
|
|
||||||
|
const texts = (frag: Y.XmlFragment): string[] =>
|
||||||
|
frag.toArray().map((el) =>
|
||||||
|
(el as Y.XmlElement)
|
||||||
|
.toArray()
|
||||||
|
.map((c) => (c as Y.XmlText).toString())
|
||||||
|
.join(''),
|
||||||
|
);
|
||||||
|
|
||||||
|
// Build a fake Hocuspocus whose openDirectConnection yields a DirectConnection
|
||||||
|
// over a REAL shared Document, with a connected "editor" doc that receives the
|
||||||
|
// shared doc's updates (modelling Document.handleUpdate's broadcast on the
|
||||||
|
// OWNING instance). Initial content carries live block ids; the editor starts
|
||||||
|
// fully synced with the shared doc.
|
||||||
|
function fakeHocuspocus(initial: { text: string; id: string }[]) {
|
||||||
|
const shared = new Y.Doc();
|
||||||
|
const frag = shared.getXmlFragment('default');
|
||||||
|
shared.transact(() => {
|
||||||
|
frag.insert(
|
||||||
|
0,
|
||||||
|
initial.map((s) => {
|
||||||
|
const el = new Y.XmlElement('paragraph');
|
||||||
|
el.setAttribute('id', s.id);
|
||||||
|
const t = new Y.XmlText();
|
||||||
|
if (s.text) t.insert(0, s.text);
|
||||||
|
el.insert(0, [t]);
|
||||||
|
return el;
|
||||||
|
}),
|
||||||
|
);
|
||||||
|
});
|
||||||
|
const editor = new Y.Doc();
|
||||||
|
Y.applyUpdate(editor, Y.encodeStateAsUpdate(shared));
|
||||||
|
// Broadcast relay: server-originated updates flow to the connected editor.
|
||||||
|
shared.on('update', (u: Uint8Array, origin: any) => {
|
||||||
|
if (origin !== 'editor') Y.applyUpdate(editor, u, 'server');
|
||||||
|
});
|
||||||
|
|
||||||
|
const openDirectConnection = jest.fn(async () => ({
|
||||||
|
// DirectConnection.transact runs the fn directly against the Document (no
|
||||||
|
// wrapping Y transaction), exactly like @hocuspocus/server.
|
||||||
|
transact: async (fn: (doc: Y.Doc) => void) => fn(shared),
|
||||||
|
disconnect: jest.fn(async () => undefined),
|
||||||
|
}));
|
||||||
|
|
||||||
|
return { hocuspocus: { openDirectConnection } as any, shared, editor };
|
||||||
|
}
|
||||||
|
|
||||||
|
describe('CollaborationHandler.gitSyncWriteBody (owner-routed body write)', () => {
|
||||||
|
it('converges a connected editor on the git change (no silent revert)', async () => {
|
||||||
|
const { hocuspocus, shared, editor } = fakeHocuspocus([
|
||||||
|
{ text: 'alpha', id: 'p1' },
|
||||||
|
{ text: 'beta', id: 'p2' },
|
||||||
|
]);
|
||||||
|
const handler = new CollaborationHandler();
|
||||||
|
const handlers = handler.getHandlers(hocuspocus);
|
||||||
|
|
||||||
|
// git changed block 1 beta -> beta2; base is the pre-change content.
|
||||||
|
await handlers.gitSyncWriteBody('page.x', {
|
||||||
|
prosemirrorJson: pmDoc('alpha', 'beta2'),
|
||||||
|
baseProsemirrorJson: pmDoc('alpha', 'beta'),
|
||||||
|
userId: 'svc-user',
|
||||||
|
});
|
||||||
|
|
||||||
|
// The shared (owning-instance) doc holds the merge...
|
||||||
|
expect(texts(shared.getXmlFragment('default'))).toEqual(['alpha', 'beta2']);
|
||||||
|
// ...and the connected editor CONVERGED via the broadcast (the bug would
|
||||||
|
// leave it on 'beta' and revert the page on its next autosave).
|
||||||
|
expect(texts(editor.getXmlFragment('default'))).toEqual(['alpha', 'beta2']);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('preserves a concurrent edit to a DIFFERENT block (3-way, finding #2)', async () => {
|
||||||
|
const { hocuspocus, shared, editor } = fakeHocuspocus([
|
||||||
|
{ text: 'alpha', id: 'p1' },
|
||||||
|
{ text: 'beta', id: 'p2' },
|
||||||
|
]);
|
||||||
|
// The editor is actively editing block 0 while the push arrives.
|
||||||
|
const eFrag = editor.getXmlFragment('default');
|
||||||
|
editor.transact(
|
||||||
|
() => (eFrag.get(0) as Y.XmlElement).get(0) instanceof Y.XmlText &&
|
||||||
|
((eFrag.get(0) as Y.XmlElement).get(0) as Y.XmlText).insert(5, ' EDIT'),
|
||||||
|
'editor',
|
||||||
|
);
|
||||||
|
Y.applyUpdate(shared, Y.encodeStateAsUpdate(editor), 'editor');
|
||||||
|
|
||||||
|
const handler = new CollaborationHandler();
|
||||||
|
await handler.getHandlers(hocuspocus).gitSyncWriteBody('page.x', {
|
||||||
|
prosemirrorJson: pmDoc('alpha', 'beta2'),
|
||||||
|
baseProsemirrorJson: pmDoc('alpha', 'beta'),
|
||||||
|
userId: 'svc-user',
|
||||||
|
});
|
||||||
|
|
||||||
|
// Human's block-0 edit AND git's block-1 change both survive on the editor.
|
||||||
|
expect(texts(editor.getXmlFragment('default'))).toEqual([
|
||||||
|
'alpha EDIT',
|
||||||
|
'beta2',
|
||||||
|
]);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('FLUSHES the pending debounced store BEFORE merging so an in-flight edit survives (finding #2)', async () => {
|
||||||
|
// QA #119 finding #2: the 3-way merge must run against the latest live-doc
|
||||||
|
// state. A concurrent UI edit that is still in-flight (the store is debounced)
|
||||||
|
// must be drained into the live doc BEFORE git merges, or git clean-applies and
|
||||||
|
// the edit is silently dropped — even on a DIFFERENT block. Model the drain via
|
||||||
|
// the pending-store flush: when it runs, the in-flight block-0 edit lands.
|
||||||
|
const shared = new Y.Doc();
|
||||||
|
const frag = shared.getXmlFragment('default');
|
||||||
|
shared.transact(() => {
|
||||||
|
frag.insert(
|
||||||
|
0,
|
||||||
|
[
|
||||||
|
{ text: 'alpha', id: 'p1' },
|
||||||
|
{ text: 'beta', id: 'p2' },
|
||||||
|
].map((s) => {
|
||||||
|
const el = new Y.XmlElement('paragraph');
|
||||||
|
el.setAttribute('id', s.id);
|
||||||
|
const t = new Y.XmlText();
|
||||||
|
t.insert(0, s.text);
|
||||||
|
el.insert(0, [t]);
|
||||||
|
return el;
|
||||||
|
}),
|
||||||
|
);
|
||||||
|
});
|
||||||
|
|
||||||
|
const order: string[] = [];
|
||||||
|
const debouncer = {
|
||||||
|
isDebounced: jest.fn(() => true),
|
||||||
|
executeNow: jest.fn(async () => {
|
||||||
|
order.push('flush');
|
||||||
|
// The in-flight client edit to block 0 only lands once the pending store
|
||||||
|
// is flushed (i.e. the event loop is drained) — BEFORE the merge.
|
||||||
|
shared.transact(() =>
|
||||||
|
((frag.get(0) as Y.XmlElement).get(0) as Y.XmlText).insert(5, ' EDIT'),
|
||||||
|
);
|
||||||
|
}),
|
||||||
|
};
|
||||||
|
const openDirectConnection = jest.fn(async () => ({
|
||||||
|
transact: async (fn: (doc: Y.Doc) => void) => {
|
||||||
|
order.push('merge');
|
||||||
|
fn(shared);
|
||||||
|
},
|
||||||
|
disconnect: jest.fn(async () => undefined),
|
||||||
|
}));
|
||||||
|
const hocuspocus = { openDirectConnection, debouncer } as any;
|
||||||
|
|
||||||
|
const handler = new CollaborationHandler();
|
||||||
|
await handler.getHandlers(hocuspocus).gitSyncWriteBody('page.x', {
|
||||||
|
prosemirrorJson: pmDoc('alpha', 'beta2'), // git changes block 1
|
||||||
|
baseProsemirrorJson: pmDoc('alpha', 'beta'),
|
||||||
|
userId: 'svc-user',
|
||||||
|
});
|
||||||
|
|
||||||
|
// The flush ran, and it ran BEFORE the merge transaction.
|
||||||
|
expect(debouncer.executeNow).toHaveBeenCalledTimes(1);
|
||||||
|
expect(order).toEqual(['flush', 'merge']);
|
||||||
|
// Both the in-flight block-0 edit and git's block-1 change survive — the
|
||||||
|
// pre-flush bug would have produced ['alpha', 'beta2'] (UI edit dropped).
|
||||||
|
expect(texts(shared.getXmlFragment('default'))).toEqual([
|
||||||
|
'alpha EDIT',
|
||||||
|
'beta2',
|
||||||
|
]);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('does not flush when no store is pending (isDebounced false)', async () => {
|
||||||
|
const { hocuspocus, shared } = fakeHocuspocus([{ text: 'a', id: 'p1' }]);
|
||||||
|
const executeNow = jest.fn();
|
||||||
|
(hocuspocus as any).debouncer = {
|
||||||
|
isDebounced: jest.fn(() => false),
|
||||||
|
executeNow,
|
||||||
|
};
|
||||||
|
const handler = new CollaborationHandler();
|
||||||
|
await handler.getHandlers(hocuspocus).gitSyncWriteBody('page.x', {
|
||||||
|
prosemirrorJson: pmDoc('a', 'b'),
|
||||||
|
userId: 'svc-user',
|
||||||
|
});
|
||||||
|
expect(executeNow).not.toHaveBeenCalled();
|
||||||
|
expect(texts(shared.getXmlFragment('default'))).toEqual(['a', 'b']);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('crash-safe: a transform failure never opens the connection or mutates the live doc', async () => {
|
||||||
|
const { hocuspocus, shared } = fakeHocuspocus([{ text: 'alpha', id: 'p1' }]);
|
||||||
|
const before = texts(shared.getXmlFragment('default'));
|
||||||
|
const handler = new CollaborationHandler();
|
||||||
|
|
||||||
|
await expect(
|
||||||
|
handler.getHandlers(hocuspocus).gitSyncWriteBody('page.x', {
|
||||||
|
prosemirrorJson: { __throw: true } as any,
|
||||||
|
userId: 'svc-user',
|
||||||
|
}),
|
||||||
|
).rejects.toThrow('boom');
|
||||||
|
|
||||||
|
// The incoming doc is built BEFORE opening the connection, so the throw
|
||||||
|
// happens first: the live doc is untouched and no connection was opened.
|
||||||
|
expect(hocuspocus.openDirectConnection).not.toHaveBeenCalled();
|
||||||
|
expect(texts(shared.getXmlFragment('default'))).toEqual(before);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('falls back to a 2-way merge when no base is supplied', async () => {
|
||||||
|
const { hocuspocus, shared, editor } = fakeHocuspocus([
|
||||||
|
{ text: 'alpha', id: 'p1' },
|
||||||
|
]);
|
||||||
|
const handler = new CollaborationHandler();
|
||||||
|
|
||||||
|
await handler.getHandlers(hocuspocus).gitSyncWriteBody('page.x', {
|
||||||
|
prosemirrorJson: pmDoc('alpha', 'gamma'),
|
||||||
|
userId: 'svc-user',
|
||||||
|
});
|
||||||
|
|
||||||
|
expect(texts(shared.getXmlFragment('default'))).toEqual(['alpha', 'gamma']);
|
||||||
|
expect(texts(editor.getXmlFragment('default'))).toEqual(['alpha', 'gamma']);
|
||||||
|
});
|
||||||
|
});
|
||||||
@@ -14,6 +14,10 @@ import {
|
|||||||
} from './yjs.util';
|
} from './yjs.util';
|
||||||
import * as Y from 'yjs';
|
import * as Y from 'yjs';
|
||||||
import { User } from '@docmost/db/types/entity.types';
|
import { User } from '@docmost/db/types/entity.types';
|
||||||
|
import {
|
||||||
|
mergeXmlFragments,
|
||||||
|
mergeXmlFragments3WayWithStats,
|
||||||
|
} from './merge/yjs-body-merge';
|
||||||
|
|
||||||
export type CollabEventHandlers = ReturnType<
|
export type CollabEventHandlers = ReturnType<
|
||||||
CollaborationHandler['getHandlers']
|
CollaborationHandler['getHandlers']
|
||||||
@@ -181,9 +185,130 @@ export class CollaborationHandler {
|
|||||||
},
|
},
|
||||||
);
|
);
|
||||||
},
|
},
|
||||||
|
/**
|
||||||
|
* Git-sync body write, applied as a block-level MERGE into the LIVE doc on
|
||||||
|
* the instance that OWNS it (routed here via the custom-event channel —
|
||||||
|
* see CollaborationGateway.writePageBody). Running on the owning instance
|
||||||
|
* is what makes a connected editor CONVERGE: the merge mutates the shared
|
||||||
|
* Document, whose update is broadcast to every connection, so the editor's
|
||||||
|
* CRDT applies the git change instead of silently reverting it on its next
|
||||||
|
* autosave (the data-loss bug this fixes).
|
||||||
|
*
|
||||||
|
* With a `baseProsemirrorJson` (the last-synced common ancestor) it does a
|
||||||
|
* THREE-WAY merge — a block only the human changed is kept, a block only
|
||||||
|
* git changed is taken (conflicts -> git). Without a base it falls back to
|
||||||
|
* the 2-way merge.
|
||||||
|
*/
|
||||||
|
gitSyncWriteBody: async (
|
||||||
|
documentName: string,
|
||||||
|
payload: {
|
||||||
|
prosemirrorJson: any;
|
||||||
|
baseProsemirrorJson?: any;
|
||||||
|
userId: string;
|
||||||
|
},
|
||||||
|
) => {
|
||||||
|
const { prosemirrorJson, baseProsemirrorJson, userId } = payload;
|
||||||
|
|
||||||
|
// Build the incoming (and base) Yjs docs BEFORE opening the connection /
|
||||||
|
// touching the live doc. If a transform throws (a malformed/unsupported
|
||||||
|
// doc) we must NOT have mutated the live body — otherwise a conversion
|
||||||
|
// failure could leave the page empty (crash-safe conversion).
|
||||||
|
const targetDoc = TiptapTransformer.toYdoc(
|
||||||
|
prosemirrorJson,
|
||||||
|
'default',
|
||||||
|
tiptapExtensions,
|
||||||
|
);
|
||||||
|
const baseDoc =
|
||||||
|
baseProsemirrorJson != null
|
||||||
|
? TiptapTransformer.toYdoc(
|
||||||
|
baseProsemirrorJson,
|
||||||
|
'default',
|
||||||
|
tiptapExtensions,
|
||||||
|
)
|
||||||
|
: null;
|
||||||
|
|
||||||
|
// CONCURRENT-EDIT FLUSH (QA #119, finding #2). The 3-way merge below runs
|
||||||
|
// against the LIVE Y.Doc, so a concurrent UI edit is only preserved if it
|
||||||
|
// is already part of that doc. A user's edit is debounced before it lands
|
||||||
|
// (the editor batches; the collab store is debounced up to 10s), so the
|
||||||
|
// merge could otherwise run against a PRE-EDIT doc: git would then
|
||||||
|
// clean-apply (no same-block conflict detected) and the in-flight UI edit
|
||||||
|
// — even on a DIFFERENT block — would be silently dropped.
|
||||||
|
//
|
||||||
|
// Flushing the pending debounced store here (a) drains the event loop so a
|
||||||
|
// just-arrived client Yjs update is applied to the live doc BEFORE we
|
||||||
|
// merge, and (b) persists the live doc so the merge baseline is current
|
||||||
|
// even on the doc-reload-from-DB path. After the flush the merge sees the
|
||||||
|
// latest state, so an edit on a different block is MERGED (not overwritten)
|
||||||
|
// and a genuine same-block edit is detected as a conflict -> the
|
||||||
|
// boundary-snapshot in PersistenceExtension pins it to page history
|
||||||
|
// (recoverable) instead of vanishing silently.
|
||||||
|
await this.flushPendingStore(hocuspocus, documentName);
|
||||||
|
|
||||||
|
// actor:'git-sync' + the service user flow into PersistenceExtension
|
||||||
|
// (lastUpdatedSource='git-sync', lastUpdatedById=userId).
|
||||||
|
await this.withYdocConnection(
|
||||||
|
hocuspocus,
|
||||||
|
documentName,
|
||||||
|
{ actor: 'git-sync', user: { id: userId } },
|
||||||
|
(doc) => {
|
||||||
|
const liveFrag = doc.getXmlFragment('default');
|
||||||
|
const targetFrag = targetDoc.getXmlFragment('default');
|
||||||
|
if (baseDoc) {
|
||||||
|
const { conflicts } = mergeXmlFragments3WayWithStats(
|
||||||
|
liveFrag,
|
||||||
|
targetFrag,
|
||||||
|
baseDoc.getXmlFragment('default'),
|
||||||
|
);
|
||||||
|
// SAME-BLOCK conflict contract (SPEC §9): a block both the human
|
||||||
|
// and git changed resolves to GIT (deterministic). Make that
|
||||||
|
// OBSERVABLE rather than silent — log it. The losing human content
|
||||||
|
// is NOT destroyed: the persistence extension's boundary snapshot
|
||||||
|
// pins the pre-merge page state to history on this user->git-sync
|
||||||
|
// transition, so it stays recoverable.
|
||||||
|
if (conflicts > 0) {
|
||||||
|
this.logger.warn(
|
||||||
|
`git-sync merge for ${documentName}: ${conflicts} same-block ` +
|
||||||
|
`conflict(s) resolved to the git version; the prior page ` +
|
||||||
|
`state is preserved in page history (recoverable).`,
|
||||||
|
);
|
||||||
|
}
|
||||||
|
} else {
|
||||||
|
mergeXmlFragments(liveFrag, targetFrag);
|
||||||
|
}
|
||||||
|
},
|
||||||
|
);
|
||||||
|
},
|
||||||
};
|
};
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Flush any pending DEBOUNCED store for `documentName` so the live Y.Doc and the
|
||||||
|
* DB are current BEFORE a git-sync merge reads them (QA #119, finding #2 —
|
||||||
|
* concurrent UI edit silently lost). Mirrors the PersistenceExtension.onDisconnect
|
||||||
|
* flush: only acts when a store is actually pending (`isDebounced`), runs the
|
||||||
|
* SAME scheduled payload (`executeNow`, preserving the edit's context/actor), and
|
||||||
|
* never throws — a flush failure must not abort the git-sync write. Awaiting it
|
||||||
|
* also drains the event loop, so a client Yjs update sitting in the socket buffer
|
||||||
|
* is applied to the live doc before the merge transaction runs.
|
||||||
|
*/
|
||||||
|
private async flushPendingStore(
|
||||||
|
hocuspocus: Hocuspocus,
|
||||||
|
documentName: string,
|
||||||
|
): Promise<void> {
|
||||||
|
const debounceId = `onStoreDocument-${documentName}`;
|
||||||
|
try {
|
||||||
|
const debouncer = (hocuspocus as any)?.debouncer;
|
||||||
|
if (!debouncer?.isDebounced?.(debounceId)) return;
|
||||||
|
await debouncer.executeNow(debounceId);
|
||||||
|
} catch (err) {
|
||||||
|
this.logger.warn(
|
||||||
|
`git-sync pre-merge flush failed for ${documentName}: ` +
|
||||||
|
(err instanceof Error ? err.message : String(err)),
|
||||||
|
);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
async withYdocConnection<T>(
|
async withYdocConnection<T>(
|
||||||
hocuspocus: Hocuspocus,
|
hocuspocus: Hocuspocus,
|
||||||
documentName: string,
|
documentName: string,
|
||||||
|
|||||||
@@ -16,7 +16,6 @@ import { isUserDisabled } from '../../common/helpers';
|
|||||||
import { getPageId } from '../collaboration.util';
|
import { getPageId } from '../collaboration.util';
|
||||||
import { JwtCollabPayload, JwtType } from '../../core/auth/dto/jwt-payload';
|
import { JwtCollabPayload, JwtType } from '../../core/auth/dto/jwt-payload';
|
||||||
import { resolveProvenance } from '../../common/decorators/auth-provenance.decorator';
|
import { resolveProvenance } from '../../common/decorators/auth-provenance.decorator';
|
||||||
import { observeCollabAuth } from '../../integrations/metrics/metrics.registry';
|
|
||||||
|
|
||||||
@Injectable()
|
@Injectable()
|
||||||
export class AuthenticationExtension implements Extension {
|
export class AuthenticationExtension implements Extension {
|
||||||
@@ -31,18 +30,6 @@ export class AuthenticationExtension implements Extension {
|
|||||||
) {}
|
) {}
|
||||||
|
|
||||||
async onAuthenticate(data: onAuthenticatePayload) {
|
async onAuthenticate(data: onAuthenticatePayload) {
|
||||||
// #402 — time the whole auth (verify + user/page/permission lookups) into
|
|
||||||
// collab_auth_duration_seconds. finally so failed auths are timed too.
|
|
||||||
// No-op when METRICS_PORT is unset. Behavior unchanged.
|
|
||||||
const start = performance.now();
|
|
||||||
try {
|
|
||||||
return await this.doAuthenticate(data);
|
|
||||||
} finally {
|
|
||||||
observeCollabAuth((performance.now() - start) / 1000);
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
private async doAuthenticate(data: onAuthenticatePayload) {
|
|
||||||
const { documentName, token } = data;
|
const { documentName, token } = data;
|
||||||
const pageId = getPageId(documentName);
|
const pageId = getPageId(documentName);
|
||||||
|
|
||||||
|
|||||||
@@ -0,0 +1,89 @@
|
|||||||
|
import { PersistenceExtension } from './persistence.extension';
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Regression for the QA #119 "loss-on-fast-close" data loss: editing a page then
|
||||||
|
* closing the tab within the collab debounce window (~3-18s) lost the edit
|
||||||
|
* because, with `unloadImmediately: false`, Hocuspocus does NOT flush the
|
||||||
|
* debounced onStoreDocument on a last-client disconnect. PersistenceExtension
|
||||||
|
* now flushes the pending store on the LAST disconnect (and only then).
|
||||||
|
*/
|
||||||
|
describe('PersistenceExtension.onDisconnect flush (loss-on-fast-close)', () => {
|
||||||
|
function makeExt(): PersistenceExtension {
|
||||||
|
// onDisconnect touches none of the injected deps; pass casts.
|
||||||
|
return new PersistenceExtension(
|
||||||
|
null as any,
|
||||||
|
null as any,
|
||||||
|
null as any,
|
||||||
|
null as any,
|
||||||
|
null as any,
|
||||||
|
null as any,
|
||||||
|
null as any,
|
||||||
|
null as any,
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
function makeData(opts: {
|
||||||
|
clientsCount: number;
|
||||||
|
isDebounced: boolean;
|
||||||
|
isLoading?: boolean;
|
||||||
|
}) {
|
||||||
|
const executeNow = jest.fn(async () => undefined);
|
||||||
|
const isDebounced = jest.fn(() => opts.isDebounced);
|
||||||
|
return {
|
||||||
|
executeNow,
|
||||||
|
isDebounced,
|
||||||
|
payload: {
|
||||||
|
clientsCount: opts.clientsCount,
|
||||||
|
context: {},
|
||||||
|
document: { isLoading: opts.isLoading ?? false } as any,
|
||||||
|
documentName: 'page.abc',
|
||||||
|
instance: { debouncer: { isDebounced, executeNow } } as any,
|
||||||
|
requestHeaders: {},
|
||||||
|
requestParameters: new URLSearchParams(),
|
||||||
|
socketId: 's',
|
||||||
|
} as any,
|
||||||
|
};
|
||||||
|
}
|
||||||
|
|
||||||
|
it('flushes the pending store when the LAST client disconnects', async () => {
|
||||||
|
const ext = makeExt();
|
||||||
|
const { executeNow, payload } = makeData({
|
||||||
|
clientsCount: 0,
|
||||||
|
isDebounced: true,
|
||||||
|
});
|
||||||
|
await ext.onDisconnect(payload);
|
||||||
|
expect(executeNow).toHaveBeenCalledTimes(1);
|
||||||
|
expect(executeNow).toHaveBeenCalledWith('onStoreDocument-page.abc');
|
||||||
|
});
|
||||||
|
|
||||||
|
it('does NOT flush while other editors remain connected', async () => {
|
||||||
|
const ext = makeExt();
|
||||||
|
const { executeNow, payload } = makeData({
|
||||||
|
clientsCount: 2,
|
||||||
|
isDebounced: true,
|
||||||
|
});
|
||||||
|
await ext.onDisconnect(payload);
|
||||||
|
expect(executeNow).not.toHaveBeenCalled();
|
||||||
|
});
|
||||||
|
|
||||||
|
it('does NOT write when nothing is pending (already persisted)', async () => {
|
||||||
|
const ext = makeExt();
|
||||||
|
const { executeNow, payload } = makeData({
|
||||||
|
clientsCount: 0,
|
||||||
|
isDebounced: false,
|
||||||
|
});
|
||||||
|
await ext.onDisconnect(payload);
|
||||||
|
expect(executeNow).not.toHaveBeenCalled();
|
||||||
|
});
|
||||||
|
|
||||||
|
it('does NOT flush a doc that is still loading (load error guard)', async () => {
|
||||||
|
const ext = makeExt();
|
||||||
|
const { executeNow, payload } = makeData({
|
||||||
|
clientsCount: 0,
|
||||||
|
isDebounced: true,
|
||||||
|
isLoading: true,
|
||||||
|
});
|
||||||
|
await ext.onDisconnect(payload);
|
||||||
|
expect(executeNow).not.toHaveBeenCalled();
|
||||||
|
});
|
||||||
|
});
|
||||||
@@ -0,0 +1,223 @@
|
|||||||
|
// Stub collaboration.util so importing the extension does not drag in the
|
||||||
|
// editor-ext -> @tiptap/react -> react-dom graph (unloadable under jest's node
|
||||||
|
// env, same coupling the gitmost-datasource / mcp specs document). The
|
||||||
|
// extension only calls getPageId, jsonToText and isEmptyParagraphDoc from it on
|
||||||
|
// the store path; tiptapExtensions is unused by onStoreDocument.
|
||||||
|
jest.mock('../collaboration.util', () => ({
|
||||||
|
tiptapExtensions: [],
|
||||||
|
getPageId: (name: string) => name.replace(/^page\./, ''),
|
||||||
|
jsonToText: () => 'text',
|
||||||
|
isEmptyParagraphDoc: () => false,
|
||||||
|
// The post-write mention extraction walks the doc via jsonToNode().descendants;
|
||||||
|
// return a node-like stub with no descendants so no mentions are produced
|
||||||
|
// (mention handling is out of scope here — we only assert provenance).
|
||||||
|
jsonToNode: () => ({ descendants: () => undefined }),
|
||||||
|
}));
|
||||||
|
|
||||||
|
// Control the Yjs<->JSON bridge: fromYdoc returns the "incoming" doc the writer
|
||||||
|
// is storing. We keep it distinct from the page's persisted content so the
|
||||||
|
// no-op guard (isDeepStrictEqual) never short-circuits the write.
|
||||||
|
const INCOMING_JSON = { type: 'doc', content: [{ type: 'paragraph' }, { t: 1 }] };
|
||||||
|
jest.mock('@hocuspocus/transformer', () => ({
|
||||||
|
TiptapTransformer: {
|
||||||
|
fromYdoc: jest.fn(() => INCOMING_JSON),
|
||||||
|
toYdoc: jest.fn(),
|
||||||
|
},
|
||||||
|
}));
|
||||||
|
|
||||||
|
// Run the executeTx callback inline with a passthrough trx.
|
||||||
|
jest.mock('@docmost/db/utils', () => ({
|
||||||
|
executeTx: jest.fn(async (_db: any, cb: any) => cb({} as any)),
|
||||||
|
}));
|
||||||
|
|
||||||
|
import * as Y from 'yjs';
|
||||||
|
import { PersistenceExtension } from './persistence.extension';
|
||||||
|
import {
|
||||||
|
onChangePayload,
|
||||||
|
onStoreDocumentPayload,
|
||||||
|
} from '@hocuspocus/server';
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Provenance-precedence coverage for PersistenceExtension.onStoreDocument
|
||||||
|
* (test-strategy Module 4 / item #2): the contract `agent > git-sync > user`,
|
||||||
|
* plus the negative that a git-sync store does NOT pin a boundary history
|
||||||
|
* snapshot. We drive the precedence through the real public method (onChange to
|
||||||
|
* arm the sticky agent marker, then onStoreDocument), mocking the repos / db /
|
||||||
|
* Yjs bridge so no real database or collab server is needed. The store's
|
||||||
|
* persisted `lastUpdatedSource` and the saveHistory call are the observable
|
||||||
|
* outputs.
|
||||||
|
*/
|
||||||
|
describe('PersistenceExtension.onStoreDocument — provenance precedence (#2)', () => {
|
||||||
|
const DOCUMENT_NAME = 'page.page-1';
|
||||||
|
const PAGE_ID = 'page-1';
|
||||||
|
|
||||||
|
// `page.content` differs from INCOMING_JSON so the write is never skipped.
|
||||||
|
const persistedPage = (overrides?: { lastUpdatedSource?: string }) => ({
|
||||||
|
id: PAGE_ID,
|
||||||
|
slugId: 'slug-1',
|
||||||
|
spaceId: 'space-1',
|
||||||
|
workspaceId: 'ws-1',
|
||||||
|
creatorId: 'creator-1',
|
||||||
|
contributorIds: ['creator-1'],
|
||||||
|
content: { type: 'doc', content: [{ type: 'paragraph', content: [] }] },
|
||||||
|
lastUpdatedSource: overrides?.lastUpdatedSource ?? 'user',
|
||||||
|
createdAt: new Date(),
|
||||||
|
});
|
||||||
|
|
||||||
|
const build = (pageOverrides?: { lastUpdatedSource?: string }) => {
|
||||||
|
const pageRepo = {
|
||||||
|
findById: jest.fn().mockResolvedValue(persistedPage(pageOverrides)),
|
||||||
|
updatePage: jest.fn().mockResolvedValue({ numUpdatedRows: 1n }),
|
||||||
|
};
|
||||||
|
const pageHistoryRepo = {
|
||||||
|
// No prior snapshot -> humanBaselineMissing is true, so the ONLY thing
|
||||||
|
// gating the boundary snapshot in these tests is the source precedence.
|
||||||
|
findPageLastHistory: jest.fn().mockResolvedValue(null),
|
||||||
|
saveHistory: jest.fn().mockResolvedValue(undefined),
|
||||||
|
};
|
||||||
|
const aiQueue = { add: jest.fn().mockResolvedValue(undefined) };
|
||||||
|
const historyQueue = { add: jest.fn().mockResolvedValue(undefined) };
|
||||||
|
const notificationQueue = { add: jest.fn().mockResolvedValue(undefined) };
|
||||||
|
const collabHistory = {
|
||||||
|
addContributors: jest.fn().mockResolvedValue(undefined),
|
||||||
|
};
|
||||||
|
const transclusionService = {
|
||||||
|
syncPageTransclusions: jest.fn().mockResolvedValue(undefined),
|
||||||
|
syncPageReferences: jest.fn().mockResolvedValue(undefined),
|
||||||
|
syncPageTemplateReferences: jest.fn().mockResolvedValue(undefined),
|
||||||
|
};
|
||||||
|
|
||||||
|
const ext = new PersistenceExtension(
|
||||||
|
pageRepo as any,
|
||||||
|
pageHistoryRepo as any,
|
||||||
|
{} as any, // db
|
||||||
|
aiQueue as any,
|
||||||
|
historyQueue as any,
|
||||||
|
notificationQueue as any,
|
||||||
|
collabHistory as any,
|
||||||
|
transclusionService as any,
|
||||||
|
);
|
||||||
|
|
||||||
|
return { ext, pageRepo, pageHistoryRepo, historyQueue };
|
||||||
|
};
|
||||||
|
|
||||||
|
// A real Y.Doc is required for Y.encodeStateAsUpdate(document); broadcastStateless
|
||||||
|
// is a no-op spy. The fromYdoc bridge is mocked, so the doc's contents are
|
||||||
|
// irrelevant to the JSON path.
|
||||||
|
const makeStorePayload = (context: any): onStoreDocumentPayload =>
|
||||||
|
({
|
||||||
|
documentName: DOCUMENT_NAME,
|
||||||
|
document: Object.assign(new Y.Doc(), {
|
||||||
|
broadcastStateless: jest.fn(),
|
||||||
|
}),
|
||||||
|
context,
|
||||||
|
}) as any;
|
||||||
|
|
||||||
|
const makeChangePayload = (actor: string): onChangePayload =>
|
||||||
|
({
|
||||||
|
documentName: DOCUMENT_NAME,
|
||||||
|
context: { user: { id: 'user-1' }, actor },
|
||||||
|
}) as any;
|
||||||
|
|
||||||
|
const sourceOf = (pageRepo: { updatePage: jest.Mock }) =>
|
||||||
|
pageRepo.updatePage.mock.calls[0][0].lastUpdatedSource;
|
||||||
|
|
||||||
|
it("tags 'user' for a plain write (no agent touch, no git-sync actor)", async () => {
|
||||||
|
const { ext, pageRepo } = build();
|
||||||
|
|
||||||
|
await ext.onStoreDocument(
|
||||||
|
makeStorePayload({ user: { id: 'user-1' }, actor: 'user' }),
|
||||||
|
);
|
||||||
|
|
||||||
|
expect(sourceOf(pageRepo)).toBe('user');
|
||||||
|
});
|
||||||
|
|
||||||
|
it("tags 'git-sync' when the writer's actor is 'git-sync' and no agent touched the window", async () => {
|
||||||
|
const { ext, pageRepo } = build();
|
||||||
|
|
||||||
|
await ext.onStoreDocument(
|
||||||
|
makeStorePayload({ user: { id: 'svc-user' }, actor: 'git-sync' }),
|
||||||
|
);
|
||||||
|
|
||||||
|
expect(sourceOf(pageRepo)).toBe('git-sync');
|
||||||
|
});
|
||||||
|
|
||||||
|
it("keeps 'git-sync' for an explicit git-sync store even with a sticky agent marker (#14 loop-guard)", async () => {
|
||||||
|
const { ext, pageRepo } = build();
|
||||||
|
|
||||||
|
// An agent edit landed earlier in the coalescing window (sticky marker),
|
||||||
|
// then a git-sync writer performs the store. Red-team finding #14: an
|
||||||
|
// EXPLICIT current-write actor is authoritative for THIS write, so the
|
||||||
|
// store must stay 'git-sync' — otherwise the PageChangeListener loop-guard
|
||||||
|
// (keyed on lastUpdatedSource === 'git-sync') fails to recognize git-sync's
|
||||||
|
// own write and re-exports it. Explicit 'agent' still wins (see below); the
|
||||||
|
// sticky marker only promotes a plain human writer to 'agent'.
|
||||||
|
await ext.onChange(makeChangePayload('agent'));
|
||||||
|
await ext.onStoreDocument(
|
||||||
|
makeStorePayload({ user: { id: 'svc-user' }, actor: 'git-sync' }),
|
||||||
|
);
|
||||||
|
|
||||||
|
expect(sourceOf(pageRepo)).toBe('git-sync');
|
||||||
|
});
|
||||||
|
|
||||||
|
it("tags 'agent' when the storing writer itself is the agent (no prior onChange)", async () => {
|
||||||
|
const { ext, pageRepo } = build();
|
||||||
|
|
||||||
|
await ext.onStoreDocument(
|
||||||
|
makeStorePayload({ user: { id: 'agent-user' }, actor: 'agent' }),
|
||||||
|
);
|
||||||
|
|
||||||
|
expect(sourceOf(pageRepo)).toBe('agent');
|
||||||
|
});
|
||||||
|
|
||||||
|
// --- boundary snapshot for a git-sync store over a HUMAN baseline -----------
|
||||||
|
// SPEC §9 observable-loss guard (bug #2): a git-sync body write is a block-level
|
||||||
|
// 3-way merge whose same-block rule is "git wins". To keep a concurrent human
|
||||||
|
// edit RECOVERABLE rather than silently overwritten, a git-sync store over a
|
||||||
|
// prior NON-git-sync baseline pins that prior state to page history first —
|
||||||
|
// exactly like the agent path. So saveHistory MUST be called here.
|
||||||
|
it('DOES pin a boundary snapshot for a git-sync store over a prior human state', async () => {
|
||||||
|
const { ext, pageHistoryRepo } = build({ lastUpdatedSource: 'user' });
|
||||||
|
|
||||||
|
await ext.onStoreDocument(
|
||||||
|
makeStorePayload({ user: { id: 'svc-user' }, actor: 'git-sync' }),
|
||||||
|
);
|
||||||
|
|
||||||
|
expect(pageHistoryRepo.saveHistory).toHaveBeenCalledTimes(1);
|
||||||
|
});
|
||||||
|
|
||||||
|
// --- negative: a git-sync store over a git-sync baseline does NOT re-pin -----
|
||||||
|
// The boundary is pinned once on the transition INTO git-sync; a subsequent
|
||||||
|
// git-sync store over an already-git-sync baseline must not churn history.
|
||||||
|
it('does NOT re-pin a boundary snapshot for a git-sync store over a git-sync baseline', async () => {
|
||||||
|
const { ext, pageHistoryRepo } = build({ lastUpdatedSource: 'git-sync' });
|
||||||
|
|
||||||
|
await ext.onStoreDocument(
|
||||||
|
makeStorePayload({ user: { id: 'svc-user' }, actor: 'git-sync' }),
|
||||||
|
);
|
||||||
|
|
||||||
|
expect(pageHistoryRepo.saveHistory).not.toHaveBeenCalled();
|
||||||
|
});
|
||||||
|
|
||||||
|
it('DOES pin a boundary snapshot for an agent store over a prior human state (control)', async () => {
|
||||||
|
// Confirms the negative above is meaningful: under the SAME mocks, an agent
|
||||||
|
// store over a 'user' baseline DOES trigger the boundary snapshot.
|
||||||
|
const { ext, pageHistoryRepo } = build({ lastUpdatedSource: 'user' });
|
||||||
|
|
||||||
|
await ext.onStoreDocument(
|
||||||
|
makeStorePayload({ user: { id: 'agent-user' }, actor: 'agent' }),
|
||||||
|
);
|
||||||
|
|
||||||
|
expect(pageHistoryRepo.saveHistory).toHaveBeenCalledTimes(1);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('does NOT pin a boundary snapshot for a plain user store', async () => {
|
||||||
|
const { ext, pageHistoryRepo } = build({ lastUpdatedSource: 'user' });
|
||||||
|
|
||||||
|
await ext.onStoreDocument(
|
||||||
|
makeStorePayload({ user: { id: 'user-1' }, actor: 'user' }),
|
||||||
|
);
|
||||||
|
|
||||||
|
expect(pageHistoryRepo.saveHistory).not.toHaveBeenCalled();
|
||||||
|
});
|
||||||
|
});
|
||||||
@@ -2,6 +2,7 @@ import {
|
|||||||
afterUnloadDocumentPayload,
|
afterUnloadDocumentPayload,
|
||||||
Extension,
|
Extension,
|
||||||
onChangePayload,
|
onChangePayload,
|
||||||
|
onDisconnectPayload,
|
||||||
onLoadDocumentPayload,
|
onLoadDocumentPayload,
|
||||||
onStatelessPayload,
|
onStatelessPayload,
|
||||||
onStoreDocumentPayload,
|
onStoreDocumentPayload,
|
||||||
@@ -41,10 +42,7 @@ import {
|
|||||||
HISTORY_INTERVAL,
|
HISTORY_INTERVAL,
|
||||||
} from '../constants';
|
} from '../constants';
|
||||||
import { TransclusionService } from '../../core/page/transclusion/transclusion.service';
|
import { TransclusionService } from '../../core/page/transclusion/transclusion.service';
|
||||||
import {
|
import { observeCollabStore } from '../../integrations/metrics/metrics.registry';
|
||||||
observeCollabLoad,
|
|
||||||
observeCollabStore,
|
|
||||||
} from '../../integrations/metrics/metrics.registry';
|
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* #251 — wire format of the client→server stateless message that signals a
|
* #251 — wire format of the client→server stateless message that signals a
|
||||||
@@ -86,7 +84,17 @@ export function resolveSource(
|
|||||||
stickyTouched: boolean,
|
stickyTouched: boolean,
|
||||||
contextActor?: string,
|
contextActor?: string,
|
||||||
): ProvenanceSource {
|
): ProvenanceSource {
|
||||||
return stickyTouched || contextActor === 'agent' ? 'agent' : 'user';
|
// An EXPLICIT current-write actor is authoritative for THIS write and wins
|
||||||
|
// over the sticky-agent fallback. Order: explicit 'agent' > explicit
|
||||||
|
// 'git-sync' > sticky agent marker > plain human 'user'. The git-sync case
|
||||||
|
// must NOT be masked by the sticky marker, or the PageChangeListener
|
||||||
|
// loop-guard (which keys on lastUpdatedSource === 'git-sync') would re-export
|
||||||
|
// git-sync's own writes (#14). Explicit agent still wins so a window that
|
||||||
|
// mixed an agent edit stays tagged 'agent'.
|
||||||
|
if (contextActor === 'agent') return 'agent';
|
||||||
|
if (contextActor === 'git-sync') return 'git-sync';
|
||||||
|
if (stickyTouched) return 'agent';
|
||||||
|
return 'user';
|
||||||
}
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
@@ -153,14 +161,10 @@ export class PersistenceExtension implements Extension {
|
|||||||
const { documentName, document } = data;
|
const { documentName, document } = data;
|
||||||
const pageId = getPageId(documentName);
|
const pageId = getPageId(documentName);
|
||||||
|
|
||||||
// #402 — the early return below (live doc already non-empty) does NOT touch
|
|
||||||
// the DB, so it is deliberately NOT timed. We only observe the real DB-load
|
|
||||||
// work, and only on each real-load return, tagged by the loaded doc size.
|
|
||||||
if (!document.isEmpty('default')) {
|
if (!document.isEmpty('default')) {
|
||||||
return;
|
return;
|
||||||
}
|
}
|
||||||
|
|
||||||
const startedAt = performance.now();
|
|
||||||
const page = await this.pageRepo.findById(pageId, {
|
const page = await this.pageRepo.findById(pageId, {
|
||||||
includeContent: true,
|
includeContent: true,
|
||||||
includeYdoc: true,
|
includeYdoc: true,
|
||||||
@@ -178,7 +182,6 @@ export class PersistenceExtension implements Extension {
|
|||||||
const dbState = new Uint8Array(page.ydoc);
|
const dbState = new Uint8Array(page.ydoc);
|
||||||
|
|
||||||
Y.applyUpdate(doc, dbState);
|
Y.applyUpdate(doc, dbState);
|
||||||
observeCollabLoad(dbState.length, (performance.now() - startedAt) / 1000);
|
|
||||||
return doc;
|
return doc;
|
||||||
}
|
}
|
||||||
|
|
||||||
@@ -192,42 +195,60 @@ export class PersistenceExtension implements Extension {
|
|||||||
tiptapExtensions,
|
tiptapExtensions,
|
||||||
);
|
);
|
||||||
|
|
||||||
// Reuse this single encode for the size label (do NOT add a second one).
|
Y.encodeStateAsUpdate(ydoc);
|
||||||
const encoded = Y.encodeStateAsUpdate(ydoc);
|
|
||||||
observeCollabLoad(
|
|
||||||
encoded.byteLength,
|
|
||||||
(performance.now() - startedAt) / 1000,
|
|
||||||
);
|
|
||||||
return ydoc;
|
return ydoc;
|
||||||
}
|
}
|
||||||
|
|
||||||
this.logger.debug(`creating fresh ydoc: ${pageId}`);
|
this.logger.debug(`creating fresh ydoc: ${pageId}`);
|
||||||
observeCollabLoad(0, (performance.now() - startedAt) / 1000);
|
|
||||||
return new Y.Doc();
|
return new Y.Doc();
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* LOSS-ON-FAST-CLOSE FIX (QA #119). When the LAST editor disconnects, FLUSH any
|
||||||
|
* pending (debounced) store to the DB IMMEDIATELY instead of waiting out the
|
||||||
|
* up-to-10s `debounce` window.
|
||||||
|
*
|
||||||
|
* The collab server runs with `unloadImmediately: false` (collaboration.gateway),
|
||||||
|
* so on a last-client disconnect Hocuspocus does NOT flush the debounced
|
||||||
|
* onStoreDocument — it relies on the timer firing later. A quick edit-then-close
|
||||||
|
* (closing the tab within the debounce window, ~3-18s) therefore left the edit
|
||||||
|
* only in the soon-to-be-unloaded in-memory Y.Doc; meanwhile git-sync mirrored
|
||||||
|
* the STALE/empty DB body to the vault (the reported "59-byte frontmatter-only"
|
||||||
|
* data loss). Running the already-scheduled store now closes that window.
|
||||||
|
*
|
||||||
|
* Gated tightly so it never adds a redundant write: only on the LAST disconnect
|
||||||
|
* (`clientsCount === 0`), only for a fully-loaded doc, and only when a store is
|
||||||
|
* actually pending (`isDebounced`). `executeNow` runs the SAME payload Hocuspocus
|
||||||
|
* scheduled (preserving the edit's context/actor) and clears the timer.
|
||||||
|
*/
|
||||||
|
async onDisconnect(data: onDisconnectPayload) {
|
||||||
|
const { instance, document, documentName, clientsCount } = data;
|
||||||
|
if (clientsCount > 0) return;
|
||||||
|
if (!document || document.isLoading) return;
|
||||||
|
const debounceId = `onStoreDocument-${documentName}`;
|
||||||
|
if (!instance?.debouncer?.isDebounced(debounceId)) return;
|
||||||
|
try {
|
||||||
|
await instance.debouncer.executeNow(debounceId);
|
||||||
|
} catch (err) {
|
||||||
|
this.logger.error(
|
||||||
|
`onDisconnect flush failed for ${documentName}: ` +
|
||||||
|
(err instanceof Error ? err.message : String(err)),
|
||||||
|
);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
async onStoreDocument(data: onStoreDocumentPayload) {
|
async onStoreDocument(data: onStoreDocumentPayload) {
|
||||||
// #355 — time the full store (persist + post-store side effects) into
|
// #355 — time the full store (persist + post-store side effects) into
|
||||||
// collab_store_duration_seconds. #402 — also tag by document size bucket.
|
// collab_store_duration_seconds. No-op when METRICS_PORT is unset.
|
||||||
// No-op when METRICS_PORT is unset.
|
|
||||||
const startedAt = performance.now();
|
const startedAt = performance.now();
|
||||||
// Default 0 so a throw before storeDocument returns still records a
|
|
||||||
// (smallest-bucket) observation rather than dropping the timing entirely.
|
|
||||||
let bytes = 0;
|
|
||||||
try {
|
try {
|
||||||
bytes = await this.storeDocument(data);
|
await this.storeDocument(data);
|
||||||
} finally {
|
} finally {
|
||||||
observeCollabStore(bytes, (performance.now() - startedAt) / 1000);
|
observeCollabStore((performance.now() - startedAt) / 1000);
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
/**
|
private async storeDocument(data: onStoreDocumentPayload) {
|
||||||
* Persist the document. Returns the serialized ydoc byte size (used as the
|
|
||||||
* store histogram's size_bucket). The single Y.encodeStateAsUpdate below is
|
|
||||||
* the ONLY serialization — its byteLength is reused for the label (no second
|
|
||||||
* encode).
|
|
||||||
*/
|
|
||||||
private async storeDocument(data: onStoreDocumentPayload): Promise<number> {
|
|
||||||
const { documentName, document, context } = data;
|
const { documentName, document, context } = data;
|
||||||
|
|
||||||
const pageId = getPageId(documentName);
|
const pageId = getPageId(documentName);
|
||||||
@@ -249,6 +270,11 @@ export class PersistenceExtension implements Extension {
|
|||||||
// Sticky agent marker: 'agent' if any agent edit landed in this window, OR
|
// Sticky agent marker: 'agent' if any agent edit landed in this window, OR
|
||||||
// if the current writer is the agent (covers a store with no prior onChange
|
// if the current writer is the agent (covers a store with no prior onChange
|
||||||
// agent event in the same window). §15 H2.
|
// agent event in the same window). §15 H2.
|
||||||
|
// Provenance precedence: agent > git-sync > user (see resolveSource). A
|
||||||
|
// 'git-sync' store is NOT given an immediate history snapshot — it is
|
||||||
|
// debounced like a human edit (a git-sync write is a block-level merge into
|
||||||
|
// the live doc, so it reads like an incremental human edit, not a bulk
|
||||||
|
// import that would warrant its own immediate snapshot).
|
||||||
const lastUpdatedSource = resolveSource(
|
const lastUpdatedSource = resolveSource(
|
||||||
this.consumeAgentTouched(documentName),
|
this.consumeAgentTouched(documentName),
|
||||||
context?.actor,
|
context?.actor,
|
||||||
@@ -315,17 +341,25 @@ export class PersistenceExtension implements Extension {
|
|||||||
// flag via that same hoisted consume (a "cleared then retyped"
|
// flag via that same hoisted consume (a "cleared then retyped"
|
||||||
// sequence can't leave a usable one behind).
|
// sequence can't leave a usable one behind).
|
||||||
const incomingEmpty = isEmptyParagraphDoc(tiptapJson as any);
|
const incomingEmpty = isEmptyParagraphDoc(tiptapJson as any);
|
||||||
|
// A git-sync write is authoritative and its content IS the vault file:
|
||||||
|
// an empty incoming doc there means the user DELIBERATELY cleared the
|
||||||
|
// page's markdown in git (there is no "transient glitch empty" for a
|
||||||
|
// file-sourced write). Honor it, otherwise the empty-guard rejects the
|
||||||
|
// clear, the vault ref has already advanced past the empty commit, and
|
||||||
|
// vault<->Docmost diverge permanently (review warning). This mirrors the
|
||||||
|
// #251 intentional-clear allowance for a different authoritative source.
|
||||||
|
const gitSyncClear = lastUpdatedSource === 'git-sync';
|
||||||
if (
|
if (
|
||||||
incomingEmpty &&
|
incomingEmpty &&
|
||||||
page.content &&
|
page.content &&
|
||||||
!isEmptyParagraphDoc(page.content as any)
|
!isEmptyParagraphDoc(page.content as any)
|
||||||
) {
|
) {
|
||||||
if (allowIntentionalClear) {
|
if (allowIntentionalClear || gitSyncClear) {
|
||||||
this.logger.debug(
|
this.logger.debug(
|
||||||
`Intentional clear for ${pageId}: persisting empty doc over ` +
|
`Intentional clear for ${pageId}: persisting empty doc over ` +
|
||||||
`non-empty content (user-signalled)`,
|
`non-empty content (${gitSyncClear ? 'git-sync' : 'user-signalled'})`,
|
||||||
);
|
);
|
||||||
// fall through — the empty write is allowed exactly once.
|
// fall through — the empty write is allowed.
|
||||||
} else {
|
} else {
|
||||||
this.logger.warn(
|
this.logger.warn(
|
||||||
`Skipping store for ${pageId}: empty live doc would overwrite ` +
|
`Skipping store for ${pageId}: empty live doc would overwrite ` +
|
||||||
@@ -350,21 +384,30 @@ export class PersistenceExtension implements Extension {
|
|||||||
//this.logger.debug('Contributors error:' + err?.['message']);
|
//this.logger.debug('Contributors error:' + err?.['message']);
|
||||||
}
|
}
|
||||||
|
|
||||||
// Approach A — boundary snapshot before the agent's first edit.
|
// Approach A — boundary snapshot before a MACHINE write overwrites a
|
||||||
// When this store is the agent's and the page's currently persisted
|
// human (or other-source) baseline. When this store is from a machine
|
||||||
// state was authored by a human, pin that human state as its own
|
// source — the AGENT or GIT-SYNC — and the page's currently persisted
|
||||||
// history version BEFORE the agent overwrites it. `page` still holds
|
// state was authored by a DIFFERENT source, pin that prior state as its
|
||||||
// the OLD content/provenance here, so saveHistory(page) captures the
|
// own history version BEFORE the machine write overwrites it. `page`
|
||||||
// pre-agent state tagged 'user'. The agent's new content is
|
// still holds the OLD content/provenance here, so saveHistory(page)
|
||||||
// snapshotted later by the debounced PAGE_HISTORY job ('agent'). Skip
|
// captures the pre-write state. The machine's new content is snapshotted
|
||||||
// if the prior state is already agent-authored (boundary already
|
// later by the debounced PAGE_HISTORY job.
|
||||||
// pinned on the user->agent transition), if the page is effectively
|
//
|
||||||
// empty, or if the latest existing snapshot already equals this human
|
// For GIT-SYNC this is the OBSERVABLE-LOSS guard (SPEC §9 conflict
|
||||||
// state (avoid duplicates).
|
// contract): a git-sync body write is a block-level 3-way merge whose
|
||||||
if (
|
// same-block rule is "git wins". Without this pin, a concurrent human
|
||||||
lastUpdatedSource === 'agent' &&
|
// edit to a block git also changed would be overwritten with NO trace.
|
||||||
page.lastUpdatedSource !== 'agent'
|
// Pinning the pre-merge state here means the human's content is always
|
||||||
) {
|
// RECOVERABLE via page history rather than silently lost — git still
|
||||||
|
// wins the live doc deterministically, but nothing is destroyed.
|
||||||
|
//
|
||||||
|
// Skip if the prior state was already authored by THIS machine source
|
||||||
|
// (boundary already pinned on the transition into it), if the page is
|
||||||
|
// effectively empty, or if the latest existing snapshot already equals
|
||||||
|
// the prior state (avoid duplicates).
|
||||||
|
const isMachineWrite =
|
||||||
|
lastUpdatedSource === 'agent' || lastUpdatedSource === 'git-sync';
|
||||||
|
if (isMachineWrite && page.lastUpdatedSource !== lastUpdatedSource) {
|
||||||
// pageHistory.pageId is uuid-typed; use page.id (never the doc-name
|
// pageHistory.pageId is uuid-typed; use page.id (never the doc-name
|
||||||
// slugId) so a `page.<slugId>` doc cannot throw 22P02 here (#260).
|
// slugId) so a `page.<slugId>` doc cannot throw 22P02 here (#260).
|
||||||
const lastHistory = await this.pageHistoryRepo.findPageLastHistory(
|
const lastHistory = await this.pageHistoryRepo.findPageLastHistory(
|
||||||
@@ -479,11 +522,6 @@ export class PersistenceExtension implements Extension {
|
|||||||
|
|
||||||
await this.enqueuePageHistory(page, lastUpdatedSource);
|
await this.enqueuePageHistory(page, lastUpdatedSource);
|
||||||
}
|
}
|
||||||
|
|
||||||
// #402 — report the serialized size for the store histogram's size_bucket.
|
|
||||||
// ydocState is always computed above (there is no earlier no-write return in
|
|
||||||
// this method), so this reflects the doc that was serialized this store.
|
|
||||||
return ydocState.byteLength;
|
|
||||||
}
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
|
|||||||
@@ -0,0 +1,208 @@
|
|||||||
|
// Regression coverage for the custom-event request/reply protocol in the
|
||||||
|
// RedisSyncExtension. git-sync routes its body write through a custom event
|
||||||
|
// (`gitSyncWriteBody`) which, when the target doc is owned by a DIFFERENT collab
|
||||||
|
// instance, runs REMOTELY inside `handleRedisMessage` on the owning instance. The
|
||||||
|
// remote handler can THROW (markdown->ProseMirror transform on a malformed body).
|
||||||
|
//
|
||||||
|
// Before the fix the throw was uncaught: (1) no `customEventComplete` reply was
|
||||||
|
// published, so the origin's awaiting promise only rejected after `customEventTTL`
|
||||||
|
// (~30s) as a generic 'TIMEOUT', and (2) an unhandledRejection escaped the async
|
||||||
|
// `messageBuffer` listener on the owning instance. These tests assert the throw is
|
||||||
|
// turned into an error-carrying reply that rejects the origin PROMPTLY with the
|
||||||
|
// real message, with the no-throw and local paths unchanged.
|
||||||
|
|
||||||
|
import { RedisSyncExtension } from './redis-sync.extension';
|
||||||
|
|
||||||
|
type Listener = (channel: Buffer, message: Buffer) => unknown;
|
||||||
|
|
||||||
|
// Minimal in-memory pub/sub + lock store shared across FakeRedis duplicates,
|
||||||
|
// modelling the two-instance topology (origin + owner) over one Redis.
|
||||||
|
class FakeRedisBus {
|
||||||
|
instances: FakeRedis[] = [];
|
||||||
|
locks = new Map<string, string>();
|
||||||
|
published: { channel: string; message: Buffer }[] = [];
|
||||||
|
|
||||||
|
register(inst: FakeRedis) {
|
||||||
|
this.instances.push(inst);
|
||||||
|
}
|
||||||
|
|
||||||
|
publish(channel: string, message: Buffer) {
|
||||||
|
this.published.push({ channel, message });
|
||||||
|
for (const inst of this.instances) {
|
||||||
|
if (!inst.subscribed.has(channel)) continue;
|
||||||
|
for (const listener of inst.messageListeners) {
|
||||||
|
// ioredis delivers async; `void` mirrors the production listener
|
||||||
|
// registration (`sub.on('messageBuffer', ...)`), whose rejection would
|
||||||
|
// surface as an unhandledRejection if the handler did not catch.
|
||||||
|
void listener(Buffer.from(channel), message);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
class FakeRedis {
|
||||||
|
subscribed = new Set<string>();
|
||||||
|
messageListeners: Listener[] = [];
|
||||||
|
|
||||||
|
constructor(private bus: FakeRedisBus) {
|
||||||
|
bus.register(this);
|
||||||
|
}
|
||||||
|
|
||||||
|
duplicate() {
|
||||||
|
return new FakeRedis(this.bus);
|
||||||
|
}
|
||||||
|
|
||||||
|
subscribe(...channels: string[]) {
|
||||||
|
for (const c of channels) this.subscribed.add(c);
|
||||||
|
return Promise.resolve();
|
||||||
|
}
|
||||||
|
|
||||||
|
on(event: string, cb: any) {
|
||||||
|
if (event === 'messageBuffer') this.messageListeners.push(cb as Listener);
|
||||||
|
return this;
|
||||||
|
}
|
||||||
|
|
||||||
|
publish(channel: string, message: Buffer) {
|
||||||
|
this.bus.publish(channel, message);
|
||||||
|
return Promise.resolve(1);
|
||||||
|
}
|
||||||
|
|
||||||
|
// Models `SET key val PX ttl NX GET`: only writes when absent (NX); returns the
|
||||||
|
// previous value (GET) so the origin observes the owner already holding the lock.
|
||||||
|
set(key: string, val: string, ...args: any[]) {
|
||||||
|
const hasNX = args.includes('NX');
|
||||||
|
const hasGET = args.includes('GET');
|
||||||
|
const old = this.bus.locks.get(key) ?? null;
|
||||||
|
if (!hasNX || old === null) this.bus.locks.set(key, val);
|
||||||
|
return Promise.resolve(hasGET ? old : 'OK');
|
||||||
|
}
|
||||||
|
|
||||||
|
del(key: string) {
|
||||||
|
this.bus.locks.delete(key);
|
||||||
|
return Promise.resolve(1);
|
||||||
|
}
|
||||||
|
|
||||||
|
disconnect() {}
|
||||||
|
}
|
||||||
|
|
||||||
|
const pack = (m: any) => Buffer.from(JSON.stringify(m));
|
||||||
|
const unpack = (b: Buffer) => JSON.parse(b.toString());
|
||||||
|
|
||||||
|
function makeExtension(
|
||||||
|
bus: FakeRedisBus,
|
||||||
|
serverId: string,
|
||||||
|
customEvents: Record<string, (doc: string, payload: any) => Promise<any>>,
|
||||||
|
) {
|
||||||
|
const ext = new RedisSyncExtension({
|
||||||
|
redis: new FakeRedis(bus) as any,
|
||||||
|
pack: pack as any,
|
||||||
|
unpack: unpack as any,
|
||||||
|
serverId,
|
||||||
|
customEvents: customEvents as any,
|
||||||
|
customEventTTL: 30_000,
|
||||||
|
});
|
||||||
|
// Doc is NOT loaded on this instance -> handleEvent takes the remote/proxy path.
|
||||||
|
(ext as any).instance = { documents: new Map() };
|
||||||
|
return ext;
|
||||||
|
}
|
||||||
|
|
||||||
|
describe('RedisSyncExtension custom-event error propagation', () => {
|
||||||
|
let unhandled: unknown[];
|
||||||
|
let onUnhandled: (e: unknown) => void;
|
||||||
|
|
||||||
|
beforeEach(() => {
|
||||||
|
// Fake timers so the 30s TTL fallback timer never fires (and never dangles).
|
||||||
|
jest.useFakeTimers();
|
||||||
|
unhandled = [];
|
||||||
|
onUnhandled = (e) => unhandled.push(e);
|
||||||
|
process.on('unhandledRejection', onUnhandled);
|
||||||
|
});
|
||||||
|
|
||||||
|
afterEach(() => {
|
||||||
|
process.off('unhandledRejection', onUnhandled);
|
||||||
|
jest.useRealTimers();
|
||||||
|
});
|
||||||
|
|
||||||
|
const flush = async () => {
|
||||||
|
for (let i = 0; i < 10; i++) await Promise.resolve();
|
||||||
|
};
|
||||||
|
|
||||||
|
it('owner publishes an error-carrying reply (no unhandledRejection) when the remote handler throws', async () => {
|
||||||
|
const bus = new FakeRedisBus();
|
||||||
|
const owner = makeExtension(bus, 'owner', {
|
||||||
|
boom: async () => {
|
||||||
|
throw new Error('kaboom');
|
||||||
|
},
|
||||||
|
});
|
||||||
|
|
||||||
|
// Drive the remote branch directly, as if the origin's customEventStart arrived.
|
||||||
|
await (owner as any).handleRedisMessage(
|
||||||
|
Buffer.from('collabMsg:owner'),
|
||||||
|
pack({
|
||||||
|
type: 'customEventStart',
|
||||||
|
documentName: 'page.x',
|
||||||
|
eventName: 'boom',
|
||||||
|
payload: {},
|
||||||
|
replyTo: 'collabMsg:origin',
|
||||||
|
replyId: 7,
|
||||||
|
}),
|
||||||
|
);
|
||||||
|
await flush();
|
||||||
|
|
||||||
|
const replies = bus.published
|
||||||
|
.filter((p) => p.channel === 'collabMsg:origin')
|
||||||
|
.map((p) => unpack(p.message));
|
||||||
|
expect(replies).toHaveLength(1);
|
||||||
|
expect(replies[0]).toMatchObject({
|
||||||
|
type: 'customEventComplete',
|
||||||
|
replyId: 7,
|
||||||
|
error: 'kaboom',
|
||||||
|
});
|
||||||
|
expect(unhandled).toHaveLength(0);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('origin rejects PROMPTLY with the real error (not a TTL TIMEOUT) when the remote handler throws', async () => {
|
||||||
|
const bus = new FakeRedisBus();
|
||||||
|
// Owner already holds the document lock.
|
||||||
|
bus.locks.set('collabLock:page.x', 'owner');
|
||||||
|
makeExtension(bus, 'owner', {
|
||||||
|
boom: async () => {
|
||||||
|
throw new Error('kaboom');
|
||||||
|
},
|
||||||
|
});
|
||||||
|
const origin = makeExtension(bus, 'origin', {
|
||||||
|
boom: async () => undefined,
|
||||||
|
});
|
||||||
|
|
||||||
|
const promise = (origin as any).handleEvent('boom', 'page.x', { foo: 1 });
|
||||||
|
// Attach a catch immediately so a rejection is never momentarily unhandled.
|
||||||
|
const settled = promise.then(
|
||||||
|
() => ({ ok: true as const }),
|
||||||
|
(e: unknown) => ({ ok: false as const, error: e }),
|
||||||
|
);
|
||||||
|
|
||||||
|
await flush();
|
||||||
|
// Resolves WITHOUT advancing any timer -> the 30s TIMEOUT fallback did not fire.
|
||||||
|
const result = await settled;
|
||||||
|
expect(result.ok).toBe(false);
|
||||||
|
expect((result as any).error).toBeInstanceOf(Error);
|
||||||
|
expect(((result as any).error as Error).message).toBe('kaboom');
|
||||||
|
expect(unhandled).toHaveLength(0);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('origin resolves with the payload when the remote handler succeeds (unchanged behavior)', async () => {
|
||||||
|
const bus = new FakeRedisBus();
|
||||||
|
bus.locks.set('collabLock:page.x', 'owner');
|
||||||
|
makeExtension(bus, 'owner', {
|
||||||
|
ok: async (_doc: string, payload: any) => ({ echoed: payload }),
|
||||||
|
});
|
||||||
|
const origin = makeExtension(bus, 'origin', {
|
||||||
|
ok: async () => undefined,
|
||||||
|
});
|
||||||
|
|
||||||
|
const promise = (origin as any).handleEvent('ok', 'page.x', { foo: 1 });
|
||||||
|
await flush();
|
||||||
|
await expect(promise).resolves.toEqual({ echoed: { foo: 1 } });
|
||||||
|
expect(unhandled).toHaveLength(0);
|
||||||
|
});
|
||||||
|
});
|
||||||
@@ -51,9 +51,15 @@ export class RedisSyncExtension<TCE extends CustomEvents> implements Extension {
|
|||||||
private instance!: Hocuspocus;
|
private instance!: Hocuspocus;
|
||||||
private readonly customEvents: TCE;
|
private readonly customEvents: TCE;
|
||||||
private replyIdCounter: number = 0;
|
private replyIdCounter: number = 0;
|
||||||
// @ts-ignore
|
private pendingReplies: Record<
|
||||||
private pendingReplies: Record<number, PromiseWithResolvers<any>['resolve']> =
|
number,
|
||||||
{};
|
{
|
||||||
|
// @ts-ignore
|
||||||
|
resolve: PromiseWithResolvers<any>['resolve'];
|
||||||
|
// @ts-ignore
|
||||||
|
reject: PromiseWithResolvers<any>['reject'];
|
||||||
|
}
|
||||||
|
> = {};
|
||||||
|
|
||||||
constructor(configuration: Configuration<TCE>) {
|
constructor(configuration: Configuration<TCE>) {
|
||||||
const {
|
const {
|
||||||
@@ -176,25 +182,45 @@ export class RedisSyncExtension<TCE extends CustomEvents> implements Extension {
|
|||||||
}
|
}
|
||||||
if (type === 'customEventStart') {
|
if (type === 'customEventStart') {
|
||||||
const { documentName, eventName, payload, replyTo, replyId } = msg;
|
const { documentName, eventName, payload, replyTo, replyId } = msg;
|
||||||
const res = await this.handleEventLocally(
|
let reply: RSAMessageCustomEventComplete;
|
||||||
eventName as Extract<keyof TCE, string>,
|
try {
|
||||||
documentName,
|
const res = await this.handleEventLocally(
|
||||||
payload,
|
eventName as Extract<keyof TCE, string>,
|
||||||
);
|
documentName,
|
||||||
const reply: RSAMessageCustomEventComplete = {
|
payload,
|
||||||
type: 'customEventComplete',
|
);
|
||||||
replyId,
|
reply = {
|
||||||
payload: res,
|
type: 'customEventComplete',
|
||||||
};
|
replyId,
|
||||||
|
payload: res,
|
||||||
|
};
|
||||||
|
} catch (err) {
|
||||||
|
// The remote handler threw (e.g. the markdown->ProseMirror transform in
|
||||||
|
// gitSyncWriteBody can throw on a malformed body). Reply with the error on
|
||||||
|
// the SAME correlation channel so the origin rejects promptly with the real
|
||||||
|
// message instead of waiting out customEventTTL as a generic 'TIMEOUT'.
|
||||||
|
// Catching here also keeps the throw from escaping this async messageBuffer
|
||||||
|
// listener as an unhandledRejection on the owning instance.
|
||||||
|
reply = {
|
||||||
|
type: 'customEventComplete',
|
||||||
|
replyId,
|
||||||
|
payload: undefined,
|
||||||
|
error: err instanceof Error ? err.message : String(err),
|
||||||
|
};
|
||||||
|
}
|
||||||
this.pub.publish(`${replyTo}`, this.pack(reply));
|
this.pub.publish(`${replyTo}`, this.pack(reply));
|
||||||
return;
|
return;
|
||||||
}
|
}
|
||||||
if (type === 'customEventComplete') {
|
if (type === 'customEventComplete') {
|
||||||
const { replyId, payload } = msg;
|
const { replyId, payload, error } = msg;
|
||||||
const resolveFn = this.pendingReplies[replyId];
|
const pending = this.pendingReplies[replyId];
|
||||||
if (!resolveFn) return;
|
if (!pending) return;
|
||||||
delete this.pendingReplies[replyId];
|
delete this.pendingReplies[replyId];
|
||||||
resolveFn(payload);
|
if (error !== undefined) {
|
||||||
|
pending.reject(new Error(error));
|
||||||
|
} else {
|
||||||
|
pending.resolve(payload);
|
||||||
|
}
|
||||||
return;
|
return;
|
||||||
}
|
}
|
||||||
const { socketId } = msg;
|
const { socketId } = msg;
|
||||||
@@ -273,11 +299,22 @@ export class RedisSyncExtension<TCE extends CustomEvents> implements Extension {
|
|||||||
};
|
};
|
||||||
const msg = this.pack(proxyMessage);
|
const msg = this.pack(proxyMessage);
|
||||||
this.pub.publish(`${this.msgChannel}:${proxyTo}`, msg);
|
this.pub.publish(`${this.msgChannel}:${proxyTo}`, msg);
|
||||||
// @ts-ignore
|
// Manual deferred (no Promise.withResolvers) so this runs on Node < 22 too.
|
||||||
const { promise, resolve, reject } = Promise.withResolvers();
|
let resolve!: (v: unknown) => void;
|
||||||
this.pendingReplies[replyId] = resolve;
|
let reject!: (e: unknown) => void;
|
||||||
|
const promise = new Promise((res, rej) => {
|
||||||
|
resolve = res;
|
||||||
|
reject = rej;
|
||||||
|
});
|
||||||
|
this.pendingReplies[replyId] = { resolve, reject };
|
||||||
setTimeout(() => {
|
setTimeout(() => {
|
||||||
reject('TIMEOUT');
|
// Fallback for a genuinely lost reply. A handler that threw now rejects
|
||||||
|
// promptly via the error-carrying customEventComplete above; this TIMEOUT
|
||||||
|
// only fires when no reply ever comes back.
|
||||||
|
if (this.pendingReplies[replyId]) {
|
||||||
|
delete this.pendingReplies[replyId];
|
||||||
|
reject('TIMEOUT');
|
||||||
|
}
|
||||||
}, this.customEventTTL);
|
}, this.customEventTTL);
|
||||||
return promise as Promise<ReturnType<TCE[TName]>>;
|
return promise as Promise<ReturnType<TCE[TName]>>;
|
||||||
}
|
}
|
||||||
|
|||||||
@@ -72,6 +72,10 @@ export type RSAMessageCustomEventComplete = {
|
|||||||
type: 'customEventComplete';
|
type: 'customEventComplete';
|
||||||
replyId: number;
|
replyId: number;
|
||||||
payload: unknown;
|
payload: unknown;
|
||||||
|
// When the remote handler THREW, the owner sends back the error message here
|
||||||
|
// instead of a payload, so the origin can reject its awaiting promise promptly
|
||||||
|
// (with the real error) rather than waiting out the customEventTTL timeout.
|
||||||
|
error?: string;
|
||||||
};
|
};
|
||||||
|
|
||||||
export type RSAMessage =
|
export type RSAMessage =
|
||||||
|
|||||||
@@ -0,0 +1,587 @@
|
|||||||
|
/**
|
||||||
|
* JEST CONFIG NOTE (#119 ESM refactor): this is the one spec that needs the REAL
|
||||||
|
* `@docmost/git-sync` converter (not a mock). The package is now ESM, which jest
|
||||||
|
* cannot `require()` nor `import()` without --experimental-vm-modules, so the
|
||||||
|
* server jest config `moduleNameMapper`s `@docmost/git-sync` to its TS SOURCE and
|
||||||
|
* strips the ESM `.js` import suffixes. ts-jest then type-checks that source under
|
||||||
|
* the server's (looser) tsconfig and trips a benign narrowing; the global
|
||||||
|
* `isolatedModules: true` on the ts-jest transform (apps/server/package.json)
|
||||||
|
* makes it transpile-only so this spec loads. Full type-checking of the package
|
||||||
|
* is still enforced by its own `tsc`/vitest gates and the server `tsc --noEmit`.
|
||||||
|
*
|
||||||
|
* §13.1 IDEMPOTENCY GATE — the blocking gate for git-sync Phase B.
|
||||||
|
*
|
||||||
|
* Proves the `@docmost/git-sync` pure converter is schema-compatible
|
||||||
|
* with the server's REAL editor-ext document schema: a representative corpus of
|
||||||
|
* editor-ext ProseMirror documents must survive a full round trip through the
|
||||||
|
* actual server write path without losing any node / mark / attribute.
|
||||||
|
*
|
||||||
|
* Pipeline per document (issue #194 §13.1):
|
||||||
|
* 1. md = convertProseMirrorToMarkdown(content) // git-sync export
|
||||||
|
* 2. doc = await markdownToProseMirror(md) // git-sync import
|
||||||
|
* 3. push `doc` through the REAL editor-ext Yjs write path the server uses:
|
||||||
|
* ydoc = TiptapTransformer.toYdoc(doc, 'default', tiptapExtensions)
|
||||||
|
* normalized = TiptapTransformer.fromYdoc(ydoc, 'default')
|
||||||
|
* This is exactly what PersistenceExtension does on store
|
||||||
|
* (apps/server/src/collaboration/extensions/persistence.extension.ts:96/115)
|
||||||
|
* with the same `tiptapExtensions` (collaboration.util.ts) and the same
|
||||||
|
* `@hocuspocus/transformer`, so the gate exercises the real schema
|
||||||
|
* validation that runs on a git-sync write (issue #194 §3.3).
|
||||||
|
* 4. assert docsCanonicallyEqual(canon(original), canon(normalized)) === true
|
||||||
|
*
|
||||||
|
* Any node / mark / attr that editor-ext drops (because the git-sync
|
||||||
|
* docmost-schema named it differently, or declares a different default) makes
|
||||||
|
* the gate FAIL for that document — exactly the schema-divergence issue #194 §3.3 /
|
||||||
|
* §13.1 warn about. Genuine, irreducible divergences are isolated into the
|
||||||
|
* clearly-named `KNOWN DIVERGENCE` block at the bottom (never silently hidden).
|
||||||
|
*
|
||||||
|
* Requires the workspace packages built first:
|
||||||
|
* pnpm --filter @docmost/editor-ext build
|
||||||
|
* pnpm --filter @docmost/git-sync build
|
||||||
|
*/
|
||||||
|
import { TiptapTransformer } from '@hocuspocus/transformer';
|
||||||
|
// Import the server's real schema FIRST so `@docmost/editor-ext` resolves to its
|
||||||
|
// built CJS `dist` (its `main`). The ESM-only `@docmost/git-sync` package is
|
||||||
|
// mapped to its TS SOURCE by the jest `moduleNameMapper` (the built ESM cannot
|
||||||
|
// be `require()`d nor dynamically `import()`ed under jest's node VM), so ts-jest
|
||||||
|
// transpiles the real converter to CJS here — exercising the actual converter
|
||||||
|
// the server ships, not a stub.
|
||||||
|
import { tiptapExtensions } from './collaboration.util';
|
||||||
|
import {
|
||||||
|
convertProseMirrorToMarkdown,
|
||||||
|
markdownToProseMirror,
|
||||||
|
canonicalizeContent,
|
||||||
|
docsCanonicallyEqual,
|
||||||
|
} from '@docmost/git-sync';
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Run a single editor-ext document through the full gate pipeline and return
|
||||||
|
* the canonical original vs the canonical doc as it lands after the real Yjs
|
||||||
|
* write path, plus the intermediate markdown for diagnostics.
|
||||||
|
*/
|
||||||
|
async function runGate(original: any): Promise<{
|
||||||
|
md: string;
|
||||||
|
imported: any;
|
||||||
|
normalized: any;
|
||||||
|
canonOriginal: any;
|
||||||
|
canonNormalized: any;
|
||||||
|
}> {
|
||||||
|
// 1) editor-ext JSON -> markdown (git-sync export).
|
||||||
|
const md = convertProseMirrorToMarkdown(original);
|
||||||
|
|
||||||
|
// 2) markdown -> ProseMirror JSON (git-sync import, docmost-schema).
|
||||||
|
const imported = await markdownToProseMirror(md);
|
||||||
|
|
||||||
|
// 3) push through the REAL editor-ext schema via the server's Yjs write path.
|
||||||
|
// toYdoc validates `imported` against tiptapExtensions (throws on an
|
||||||
|
// unknown node, drops unknown attrs); fromYdoc reads it back as the
|
||||||
|
// normalized editor-ext JSON the server would persist.
|
||||||
|
const ydoc = TiptapTransformer.toYdoc(imported, 'default', tiptapExtensions);
|
||||||
|
const normalized = TiptapTransformer.fromYdoc(ydoc, 'default');
|
||||||
|
|
||||||
|
return {
|
||||||
|
md,
|
||||||
|
imported,
|
||||||
|
normalized,
|
||||||
|
canonOriginal: canonicalizeContent(original),
|
||||||
|
canonNormalized: canonicalizeContent(normalized),
|
||||||
|
};
|
||||||
|
}
|
||||||
|
|
||||||
|
const doc = (...content: any[]) => ({ type: 'doc', content });
|
||||||
|
const text = (t: string, marks?: any[]) =>
|
||||||
|
marks ? { type: 'text', text: t, marks } : { type: 'text', text: t };
|
||||||
|
const para = (...content: any[]) => ({ type: 'paragraph', content });
|
||||||
|
|
||||||
|
// ---------------------------------------------------------------------------
|
||||||
|
// Corpus: editor-ext ProseMirror documents covering the common node/mark types.
|
||||||
|
// Node / mark / attr names and DEFAULTS are taken from the real schema —
|
||||||
|
// editor-ext (packages/editor-ext/src) + the server's tiptapExtensions
|
||||||
|
// (collaboration.util.ts) — NOT guessed. Where editor-ext materializes a
|
||||||
|
// non-null default on import (e.g. image.align="center", callout.type, list
|
||||||
|
// start) the fixture pre-authors that materialized value so the round trip is
|
||||||
|
// already at its fixpoint (matches how the engine normalizes-on-write, SPEC §11).
|
||||||
|
// ---------------------------------------------------------------------------
|
||||||
|
const CORPUS: Record<string, any> = {
|
||||||
|
'paragraphs + headings (h1-h3)': doc(
|
||||||
|
{ type: 'heading', attrs: { level: 1 }, content: [text('Heading one')] },
|
||||||
|
{ type: 'heading', attrs: { level: 2 }, content: [text('Heading two')] },
|
||||||
|
{ type: 'heading', attrs: { level: 3 }, content: [text('Heading three')] },
|
||||||
|
para(text('A plain paragraph of text.')),
|
||||||
|
para(text('Second paragraph.')),
|
||||||
|
),
|
||||||
|
|
||||||
|
// A non-default paragraph alignment now round-trips (item #7 fix): it exports
|
||||||
|
// as `<p style="text-align:center">` and the schema's paragraph parseHTML
|
||||||
|
// reads `style="text-align"` back onto `textAlign` on import, so the alignment
|
||||||
|
// survives the full editor-ext write path. Promoted from the old KNOWN
|
||||||
|
// DIVERGENCE block (which only heading alignment still occupies).
|
||||||
|
'aligned paragraph (textAlign center)': doc({
|
||||||
|
type: 'paragraph',
|
||||||
|
attrs: { textAlign: 'center' },
|
||||||
|
content: [text('centered')],
|
||||||
|
}),
|
||||||
|
|
||||||
|
'inline marks (bold/italic/strike/code)': doc(
|
||||||
|
para(
|
||||||
|
text('normal '),
|
||||||
|
text('bold', [{ type: 'bold' }]),
|
||||||
|
text(' '),
|
||||||
|
text('italic', [{ type: 'italic' }]),
|
||||||
|
text(' '),
|
||||||
|
text('struck', [{ type: 'strike' }]),
|
||||||
|
text(' '),
|
||||||
|
text('code', [{ type: 'code' }]),
|
||||||
|
),
|
||||||
|
),
|
||||||
|
|
||||||
|
'links': doc(
|
||||||
|
para(
|
||||||
|
text('see '),
|
||||||
|
text('the site', [
|
||||||
|
{ type: 'link', attrs: { href: 'https://example.com' } },
|
||||||
|
]),
|
||||||
|
text(' for more'),
|
||||||
|
),
|
||||||
|
),
|
||||||
|
|
||||||
|
'bullet list': doc({
|
||||||
|
type: 'bulletList',
|
||||||
|
content: [
|
||||||
|
{ type: 'listItem', content: [para(text('first'))] },
|
||||||
|
{ type: 'listItem', content: [para(text('second'))] },
|
||||||
|
{ type: 'listItem', content: [para(text('third'))] },
|
||||||
|
],
|
||||||
|
}),
|
||||||
|
|
||||||
|
'ordered list': doc({
|
||||||
|
type: 'orderedList',
|
||||||
|
attrs: { start: 1 },
|
||||||
|
content: [
|
||||||
|
{ type: 'listItem', content: [para(text('one'))] },
|
||||||
|
{ type: 'listItem', content: [para(text('two'))] },
|
||||||
|
],
|
||||||
|
}),
|
||||||
|
|
||||||
|
'task list (checkbox)': doc({
|
||||||
|
type: 'taskList',
|
||||||
|
content: [
|
||||||
|
{
|
||||||
|
type: 'taskItem',
|
||||||
|
attrs: { checked: true },
|
||||||
|
content: [para(text('done item'))],
|
||||||
|
},
|
||||||
|
{
|
||||||
|
type: 'taskItem',
|
||||||
|
attrs: { checked: false },
|
||||||
|
content: [para(text('todo item'))],
|
||||||
|
},
|
||||||
|
],
|
||||||
|
}),
|
||||||
|
|
||||||
|
'blockquote': doc({
|
||||||
|
type: 'blockquote',
|
||||||
|
content: [para(text('a quoted line')), para(text('second quoted line'))],
|
||||||
|
}),
|
||||||
|
|
||||||
|
'callout (info)': doc({
|
||||||
|
type: 'callout',
|
||||||
|
attrs: { type: 'info' },
|
||||||
|
content: [para(text('an informational callout'))],
|
||||||
|
}),
|
||||||
|
|
||||||
|
'callout (warning)': doc({
|
||||||
|
type: 'callout',
|
||||||
|
attrs: { type: 'warning' },
|
||||||
|
content: [para(text('a warning callout'))],
|
||||||
|
}),
|
||||||
|
|
||||||
|
'code block (with language)': doc({
|
||||||
|
type: 'codeBlock',
|
||||||
|
attrs: { language: 'typescript' },
|
||||||
|
// A fenced code block's body is stored with a trailing newline (the form a
|
||||||
|
// markdown ``` fence round-trips to: marked normalizes the code text to end
|
||||||
|
// in "\n"). Authoring the fixture at that fixpoint mirrors how the engine
|
||||||
|
// normalizes-on-write (SPEC §11): codeBlock + `language` round-trip exactly.
|
||||||
|
content: [text('const a: number = 1;\nconsole.log(a);\n')],
|
||||||
|
}),
|
||||||
|
|
||||||
|
'horizontal rule': doc(
|
||||||
|
para(text('before')),
|
||||||
|
{ type: 'horizontalRule' },
|
||||||
|
para(text('after')),
|
||||||
|
),
|
||||||
|
|
||||||
|
'table (header row + cells)': doc({
|
||||||
|
type: 'table',
|
||||||
|
content: [
|
||||||
|
{
|
||||||
|
type: 'tableRow',
|
||||||
|
content: [
|
||||||
|
{
|
||||||
|
type: 'tableHeader',
|
||||||
|
attrs: { colspan: 1, rowspan: 1, colwidth: null },
|
||||||
|
content: [para(text('Name'))],
|
||||||
|
},
|
||||||
|
{
|
||||||
|
type: 'tableHeader',
|
||||||
|
attrs: { colspan: 1, rowspan: 1, colwidth: null },
|
||||||
|
content: [para(text('Value'))],
|
||||||
|
},
|
||||||
|
],
|
||||||
|
},
|
||||||
|
{
|
||||||
|
type: 'tableRow',
|
||||||
|
content: [
|
||||||
|
{
|
||||||
|
type: 'tableCell',
|
||||||
|
attrs: { colspan: 1, rowspan: 1, colwidth: null },
|
||||||
|
content: [para(text('alpha'))],
|
||||||
|
},
|
||||||
|
{
|
||||||
|
type: 'tableCell',
|
||||||
|
attrs: { colspan: 1, rowspan: 1, colwidth: null },
|
||||||
|
content: [para(text('1'))],
|
||||||
|
},
|
||||||
|
],
|
||||||
|
},
|
||||||
|
],
|
||||||
|
}),
|
||||||
|
|
||||||
|
// #8 — a table with a MULTI-BLOCK cell (two paragraphs). A GFM pipe table
|
||||||
|
// cannot hold two blocks without flattening them; the converter emits a
|
||||||
|
// lossless HTML <table> instead, and the two blocks must survive the round trip.
|
||||||
|
'table (multi-block cell, #8)': doc({
|
||||||
|
type: 'table',
|
||||||
|
content: [
|
||||||
|
{
|
||||||
|
type: 'tableRow',
|
||||||
|
content: [
|
||||||
|
{
|
||||||
|
type: 'tableHeader',
|
||||||
|
attrs: { colspan: 1, rowspan: 1, colwidth: null },
|
||||||
|
content: [para(text('H'))],
|
||||||
|
},
|
||||||
|
],
|
||||||
|
},
|
||||||
|
{
|
||||||
|
type: 'tableRow',
|
||||||
|
content: [
|
||||||
|
{
|
||||||
|
type: 'tableCell',
|
||||||
|
attrs: { colspan: 1, rowspan: 1, colwidth: null },
|
||||||
|
content: [para(text('first')), para(text('second'))],
|
||||||
|
},
|
||||||
|
],
|
||||||
|
},
|
||||||
|
],
|
||||||
|
}),
|
||||||
|
|
||||||
|
// #7 — a table nested inside a column. Columns render as HTML containers, and a
|
||||||
|
// table inside one must stay an HTML <table> (a GFM pipe table cannot live
|
||||||
|
// inside an HTML block), round-tripping without being unwrapped or lost.
|
||||||
|
// `widthMode` is pre-authored at its materialized `normal` default (SPEC §11).
|
||||||
|
'table inside a column (#7)': doc({
|
||||||
|
type: 'columns',
|
||||||
|
attrs: { layout: 'two', widthMode: 'normal' },
|
||||||
|
content: [
|
||||||
|
{
|
||||||
|
type: 'column',
|
||||||
|
content: [
|
||||||
|
{
|
||||||
|
type: 'table',
|
||||||
|
content: [
|
||||||
|
{
|
||||||
|
type: 'tableRow',
|
||||||
|
content: [
|
||||||
|
{
|
||||||
|
type: 'tableHeader',
|
||||||
|
attrs: { colspan: 1, rowspan: 1, colwidth: null },
|
||||||
|
content: [para(text('C7'))],
|
||||||
|
},
|
||||||
|
],
|
||||||
|
},
|
||||||
|
],
|
||||||
|
},
|
||||||
|
],
|
||||||
|
},
|
||||||
|
{ type: 'column', content: [para(text('right'))] },
|
||||||
|
],
|
||||||
|
}),
|
||||||
|
|
||||||
|
// --- editor-ext nodes/marks beyond the original corpus (item #7) ----------
|
||||||
|
// Each of these was verified to round-trip CLEANLY through the real gate
|
||||||
|
// (export -> markdown -> import -> editor-ext Yjs write path). Fixtures are
|
||||||
|
// pre-authored at the engine's normalize-on-write fixpoint (SPEC §11), e.g.
|
||||||
|
// details carries the materialized `open:false`, and color marks use the
|
||||||
|
// `rgb(...)` form the HTML re-parser normalizes to.
|
||||||
|
|
||||||
|
'mention (user)': doc(
|
||||||
|
para(
|
||||||
|
text('hi '),
|
||||||
|
{
|
||||||
|
type: 'mention',
|
||||||
|
attrs: {
|
||||||
|
id: 'user-123',
|
||||||
|
label: 'Alice',
|
||||||
|
entityType: 'user',
|
||||||
|
entityId: 'user-123',
|
||||||
|
creatorId: 'creator-1',
|
||||||
|
},
|
||||||
|
},
|
||||||
|
text(' there'),
|
||||||
|
),
|
||||||
|
),
|
||||||
|
|
||||||
|
'inline math': doc(
|
||||||
|
para(
|
||||||
|
text('inline '),
|
||||||
|
{ type: 'mathInline', attrs: { text: 'x^2' } },
|
||||||
|
text(' math'),
|
||||||
|
),
|
||||||
|
),
|
||||||
|
|
||||||
|
'block math': doc({ type: 'mathBlock', attrs: { text: 'x^2 + y^2 = z^2' } }),
|
||||||
|
|
||||||
|
'details (collapsible)': doc({
|
||||||
|
type: 'details',
|
||||||
|
// `open:false` is the value editor-ext materializes on import; pre-authoring
|
||||||
|
// it puts the fixture at its round-trip fixpoint.
|
||||||
|
attrs: { open: false },
|
||||||
|
content: [
|
||||||
|
{ type: 'detailsSummary', content: [text('Summary line')] },
|
||||||
|
{ type: 'detailsContent', content: [para(text('hidden body'))] },
|
||||||
|
],
|
||||||
|
}),
|
||||||
|
|
||||||
|
'highlight (mark, no color)': doc(
|
||||||
|
para(
|
||||||
|
text('a '),
|
||||||
|
text('highlighted', [{ type: 'highlight' }]),
|
||||||
|
text(' word'),
|
||||||
|
),
|
||||||
|
),
|
||||||
|
|
||||||
|
'highlight (mark, with color)': doc(
|
||||||
|
para(
|
||||||
|
text('a '),
|
||||||
|
text('red', [{ type: 'highlight', attrs: { color: 'rgb(255, 0, 0)' } }]),
|
||||||
|
text(' word'),
|
||||||
|
),
|
||||||
|
),
|
||||||
|
|
||||||
|
'subscript': doc(
|
||||||
|
para(text('H'), text('2', [{ type: 'subscript' }]), text('O')),
|
||||||
|
),
|
||||||
|
|
||||||
|
'superscript': doc(
|
||||||
|
para(text('E=mc'), text('2', [{ type: 'superscript' }])),
|
||||||
|
),
|
||||||
|
|
||||||
|
'text color (textStyle)': doc(
|
||||||
|
// The HTML re-parser normalizes CSS colors to the `rgb(...)` form, so the
|
||||||
|
// fixture pre-authors that form; a `#hex` color would round-trip to the
|
||||||
|
// equivalent rgb() and is therefore a value-normalization divergence (see
|
||||||
|
// the KNOWN DIVERGENCE block below).
|
||||||
|
para(text('green', [{ type: 'textStyle', attrs: { color: 'rgb(0, 255, 0)' } }])),
|
||||||
|
),
|
||||||
|
|
||||||
|
'nested / mixed document': doc(
|
||||||
|
{ type: 'heading', attrs: { level: 1 }, content: [text('Mixed')] },
|
||||||
|
para(
|
||||||
|
text('intro with '),
|
||||||
|
text('bold', [{ type: 'bold' }]),
|
||||||
|
text(' and a '),
|
||||||
|
text('link', [{ type: 'link', attrs: { href: 'https://example.com' } }]),
|
||||||
|
text('.'),
|
||||||
|
),
|
||||||
|
{
|
||||||
|
type: 'bulletList',
|
||||||
|
content: [
|
||||||
|
{
|
||||||
|
type: 'listItem',
|
||||||
|
content: [
|
||||||
|
para(text('item with '), text('code', [{ type: 'code' }])),
|
||||||
|
],
|
||||||
|
},
|
||||||
|
{
|
||||||
|
type: 'listItem',
|
||||||
|
content: [
|
||||||
|
para(text('item with sublist')),
|
||||||
|
{
|
||||||
|
type: 'bulletList',
|
||||||
|
content: [
|
||||||
|
{ type: 'listItem', content: [para(text('nested a'))] },
|
||||||
|
{ type: 'listItem', content: [para(text('nested b'))] },
|
||||||
|
],
|
||||||
|
},
|
||||||
|
],
|
||||||
|
},
|
||||||
|
],
|
||||||
|
},
|
||||||
|
{
|
||||||
|
type: 'callout',
|
||||||
|
attrs: { type: 'success' },
|
||||||
|
content: [
|
||||||
|
para(text('callout body')),
|
||||||
|
{ type: 'codeBlock', attrs: { language: 'bash' }, content: [text('echo hi\n')] },
|
||||||
|
],
|
||||||
|
},
|
||||||
|
{
|
||||||
|
type: 'blockquote',
|
||||||
|
content: [para(text('quote at the end'))],
|
||||||
|
},
|
||||||
|
),
|
||||||
|
|
||||||
|
// Atom embeds that carry no inline text: they must round-trip via their
|
||||||
|
// schema-matching HTML (data-type div), NOT a literal that re-imports as plain
|
||||||
|
// text. `subpages` used to export as the literal "{{SUBPAGES}}" and came back
|
||||||
|
// as visible text on the page (red-team round-trip data loss) — this locks it.
|
||||||
|
// editor-ext materializes the `recursive: false` default on import, so the
|
||||||
|
// fixture pre-authors it to sit at the round-trip fixpoint (matches the other
|
||||||
|
// default-materializing fixtures above).
|
||||||
|
'subpages embed': doc({ type: 'subpages', attrs: { recursive: false } }),
|
||||||
|
};
|
||||||
|
|
||||||
|
describe('git-sync converter §13.1 idempotency gate (editor-ext schema)', () => {
|
||||||
|
for (const [name, original] of Object.entries(CORPUS)) {
|
||||||
|
it(`round-trips losslessly: ${name}`, async () => {
|
||||||
|
const { md, canonOriginal, canonNormalized } = await runGate(original);
|
||||||
|
|
||||||
|
const equal = docsCanonicallyEqual(original, canonNormalized);
|
||||||
|
if (!equal) {
|
||||||
|
// Surface a readable diff so a real divergence is actionable.
|
||||||
|
// eslint-disable-next-line no-console
|
||||||
|
console.error(
|
||||||
|
`\n[GATE FAIL] ${name}\n--- markdown ---\n${md}\n` +
|
||||||
|
`--- canonical original ---\n${JSON.stringify(canonOriginal, null, 2)}\n` +
|
||||||
|
`--- canonical round-tripped ---\n${JSON.stringify(canonNormalized, null, 2)}\n`,
|
||||||
|
);
|
||||||
|
}
|
||||||
|
expect(equal).toBe(true);
|
||||||
|
});
|
||||||
|
}
|
||||||
|
});
|
||||||
|
|
||||||
|
// ---------------------------------------------------------------------------
|
||||||
|
// Image layout attrs preserved by canon #4 (width/height/align all round-trip).
|
||||||
|
//
|
||||||
|
// The `image` NODE round-trips through editor-ext fine. Plain markdown ``
|
||||||
|
// has no way to express layout attrs, so the canonical converter (#293/#326
|
||||||
|
// canon decision #4) appends a machine comment `<!--img {...}-->` carrying the
|
||||||
|
// NON-DEFAULT attrs, and re-parses it on import — the same trailing-comment
|
||||||
|
// pattern used for media/textAlign.
|
||||||
|
//
|
||||||
|
// About `align` — DO NOT repeat an earlier false diagnosis: align is NOT lost.
|
||||||
|
// `center` is the schema default, so the emitter omits it (only left/right go
|
||||||
|
// into the comment) and the importer restores it via the image `align` default
|
||||||
|
// ("center"). `canonNormalized.align` reads `undefined` here ONLY because
|
||||||
|
// `canonicalizeContent` normalizes the "center" default away SYMMETRICALLY (from
|
||||||
|
// both the original and the round trip), so docsCanonicallyEqual is unaffected —
|
||||||
|
// this is canonical-form normalization, not a divergence. Verified empirically:
|
||||||
|
// left/right survive the raw round trip; center is restored on import then
|
||||||
|
// canon-stripped on both sides. The real round-trip instability in this family
|
||||||
|
// was the empty-string-vs-absent class (image.alt `absent -> ""`), fixed
|
||||||
|
// parse-side in the converter PACKAGE on develop (PR #350). This branch absorbs
|
||||||
|
// that fix via the next develop merge; nothing to flip here for align.
|
||||||
|
// ---------------------------------------------------------------------------
|
||||||
|
describe('git-sync converter §13.1 image layout attrs round-trip (align via schema default)', () => {
|
||||||
|
const imageDoc = doc({
|
||||||
|
type: 'image',
|
||||||
|
attrs: {
|
||||||
|
src: 'https://example.com/pic.png',
|
||||||
|
width: 640,
|
||||||
|
height: 480,
|
||||||
|
align: 'center',
|
||||||
|
},
|
||||||
|
});
|
||||||
|
|
||||||
|
it('preserves width/height via the canon `<!--img {...}-->` comment; center align is the default', async () => {
|
||||||
|
const { md, canonNormalized } = await runGate(imageDoc);
|
||||||
|
|
||||||
|
// Canon #4: bare `` plus a trailing `<!--img {...}-->` comment that
|
||||||
|
// carries the non-default layout attrs. `center` is the default, so it is
|
||||||
|
// correctly OMITTED from the comment (only width/height appear here).
|
||||||
|
expect(md.trim()).toBe(
|
||||||
|
' <!--img {"width":"640","height":"480"}-->',
|
||||||
|
);
|
||||||
|
|
||||||
|
// The round-tripped image keeps src + width/height. width/height are
|
||||||
|
// re-imported as strings (matching the video/audio/pdf string convention),
|
||||||
|
// so assert the values rather than the JS type.
|
||||||
|
const imgAttrs = (canonNormalized as any).content[0].attrs;
|
||||||
|
expect((canonNormalized as any).content[0].type).toBe('image');
|
||||||
|
expect(imgAttrs.src).toBe('https://example.com/pic.png');
|
||||||
|
expect(String(imgAttrs.width)).toBe('640');
|
||||||
|
expect(String(imgAttrs.height)).toBe('480');
|
||||||
|
// `align` is NOT lost — see the block comment above: `center` is the schema
|
||||||
|
// default, restored on import then normalized away symmetrically by
|
||||||
|
// canonicalize, so it reads `undefined` on the CANONICAL form (not a loss).
|
||||||
|
expect(imgAttrs.align).toBeUndefined();
|
||||||
|
});
|
||||||
|
});
|
||||||
|
|
||||||
|
// ---------------------------------------------------------------------------
|
||||||
|
// HEADING text alignment — now round-trips (item A1; formerly a KNOWN DIVERGENCE).
|
||||||
|
// Symmetric with the paragraph fix: a heading's non-default `textAlign` is
|
||||||
|
// exported as a styled `<hN style="text-align:…">` (was a bare ATX `## text`
|
||||||
|
// that dropped it) and re-parsed by the heading + textAlign parseHTML on import,
|
||||||
|
// so a non-default heading alignment SURVIVES a full round trip.
|
||||||
|
// ---------------------------------------------------------------------------
|
||||||
|
describe('git-sync converter §13.1 heading text alignment round-trips', () => {
|
||||||
|
it('preserves a heading textAlign across the markdown round trip', async () => {
|
||||||
|
const alignedHeading = doc({
|
||||||
|
type: 'heading',
|
||||||
|
attrs: { level: 2, textAlign: 'center' },
|
||||||
|
content: [text('centered heading')],
|
||||||
|
});
|
||||||
|
|
||||||
|
const { md, canonNormalized } = await runGate(alignedHeading);
|
||||||
|
|
||||||
|
// Canon #9: ATX heading plus a trailing `<!--attrs {...}-->` comment carrying
|
||||||
|
// the non-default textAlign (was a lossy bare `## centered heading`).
|
||||||
|
expect(md.trim()).toBe(
|
||||||
|
'## centered heading <!--attrs {"textAlign":"center"}-->',
|
||||||
|
);
|
||||||
|
expect(docsCanonicallyEqual(alignedHeading, canonNormalized)).toBe(true);
|
||||||
|
});
|
||||||
|
});
|
||||||
|
|
||||||
|
// ---------------------------------------------------------------------------
|
||||||
|
// KNOWN DIVERGENCE — textStyle color is VALUE-NORMALIZED, not lost (item #7).
|
||||||
|
//
|
||||||
|
// The textStyle/color mark itself round-trips (the green CORPUS has the rgb()
|
||||||
|
// form). But a `#hex` color is normalized to the equivalent `rgb(...)` string
|
||||||
|
// by the HTML re-parser on import, and canonicalize.ts does NOT normalize color
|
||||||
|
// formats — so a `#hex` original is not STRING-identical to its round trip even
|
||||||
|
// though the color is semantically preserved. Locked here so the boundary is
|
||||||
|
// explicit: author color fixtures in rgb() form to stay in the green corpus.
|
||||||
|
// ---------------------------------------------------------------------------
|
||||||
|
describe('git-sync converter §13.1 KNOWN DIVERGENCE (textStyle color #hex -> rgb)', () => {
|
||||||
|
it('normalizes a #hex text color to rgb() (semantically preserved, string-divergent)', async () => {
|
||||||
|
const hexDoc = doc(
|
||||||
|
para(text('green', [{ type: 'textStyle', attrs: { color: '#00ff00' } }])),
|
||||||
|
);
|
||||||
|
|
||||||
|
const { canonNormalized } = await runGate(hexDoc);
|
||||||
|
|
||||||
|
// Color survives, but as the normalized rgb() string.
|
||||||
|
expect(canonNormalized).toEqual({
|
||||||
|
type: 'doc',
|
||||||
|
content: [
|
||||||
|
{
|
||||||
|
type: 'paragraph',
|
||||||
|
content: [
|
||||||
|
{
|
||||||
|
type: 'text',
|
||||||
|
text: 'green',
|
||||||
|
marks: [{ type: 'textStyle', attrs: { color: 'rgb(0, 255, 0)' } }],
|
||||||
|
},
|
||||||
|
],
|
||||||
|
},
|
||||||
|
],
|
||||||
|
});
|
||||||
|
// Not string-identical to the #hex original.
|
||||||
|
expect(docsCanonicallyEqual(hexDoc, canonNormalized)).toBe(false);
|
||||||
|
});
|
||||||
|
});
|
||||||
@@ -0,0 +1,26 @@
|
|||||||
|
/**
|
||||||
|
* Backward-filled LCS length table for sequences `a` and `b`: `dp[i][j]` is the
|
||||||
|
* length of the longest common subsequence of the suffixes `a[i:]` and `b[j:]`.
|
||||||
|
* O(n*m) time/space — fine for page block counts.
|
||||||
|
*
|
||||||
|
* Shared by the two-way block diff (`yjs-body-merge.diffBlocks`) and the
|
||||||
|
* three-way merge planner (`three-way-merge.lcsPairs`) so the (identical) table
|
||||||
|
* construction lives in ONE place; each caller does its own traceback over the
|
||||||
|
* returned table.
|
||||||
|
*/
|
||||||
|
export function buildLcsTable(a: string[], b: string[]): number[][] {
|
||||||
|
const n = a.length;
|
||||||
|
const m = b.length;
|
||||||
|
const dp: number[][] = Array.from({ length: n + 1 }, () =>
|
||||||
|
new Array(m + 1).fill(0),
|
||||||
|
);
|
||||||
|
for (let i = n - 1; i >= 0; i--) {
|
||||||
|
for (let j = m - 1; j >= 0; j--) {
|
||||||
|
dp[i][j] =
|
||||||
|
a[i] === b[j]
|
||||||
|
? dp[i + 1][j + 1] + 1
|
||||||
|
: Math.max(dp[i + 1][j], dp[i][j + 1]);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
return dp;
|
||||||
|
}
|
||||||
@@ -0,0 +1,20 @@
|
|||||||
|
import { diff3Plan, type Pick } from './three-way-merge';
|
||||||
|
|
||||||
|
// Materialize a plan into the merged key sequence for assertion.
|
||||||
|
function apply(plan: Pick[], live: string[], target: string[]): string[] {
|
||||||
|
return plan.map((p) => (p.src === 'live' ? live[p.index] : target[p.index]));
|
||||||
|
}
|
||||||
|
|
||||||
|
const merge = (o: string[], a: string[], b: string[]): string[] =>
|
||||||
|
apply(diff3Plan(o, a, b), a, b);
|
||||||
|
|
||||||
|
describe('diff3Plan red-team #9 (human edit + adjacent git insert)', () => {
|
||||||
|
it('keeps human block-2 edit AND applies git insert of 2.5', () => {
|
||||||
|
// base: 1 2 3
|
||||||
|
// live: 1 H 3 (human rewrote block 2)
|
||||||
|
// target: 1 2 2.5 3 (git inserted 2.5 after block 2)
|
||||||
|
expect(
|
||||||
|
merge(['1', '2', '3'], ['1', 'H', '3'], ['1', '2', '2.5', '3']),
|
||||||
|
).toEqual(['1', 'H', '2.5', '3']);
|
||||||
|
});
|
||||||
|
});
|
||||||
@@ -0,0 +1,159 @@
|
|||||||
|
import {
|
||||||
|
diff3Plan,
|
||||||
|
diff3PlanWithConflicts,
|
||||||
|
type Pick,
|
||||||
|
} from './three-way-merge';
|
||||||
|
|
||||||
|
// Materialize a plan into the merged key sequence for assertion.
|
||||||
|
function apply(plan: Pick[], live: string[], target: string[]): string[] {
|
||||||
|
return plan.map((p) => (p.src === 'live' ? live[p.index] : target[p.index]));
|
||||||
|
}
|
||||||
|
|
||||||
|
const merge = (o: string[], a: string[], b: string[]): string[] =>
|
||||||
|
apply(diff3Plan(o, a, b), a, b);
|
||||||
|
|
||||||
|
describe('diff3Plan (block-level three-way merge)', () => {
|
||||||
|
it('identical on all three sides -> unchanged (all from live)', () => {
|
||||||
|
const plan = diff3Plan(['1', '2', '3'], ['1', '2', '3'], ['1', '2', '3']);
|
||||||
|
expect(plan.every((p) => p.src === 'live')).toBe(true);
|
||||||
|
expect(apply(plan, ['1', '2', '3'], ['1', '2', '3'])).toEqual(['1', '2', '3']);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('git changed a block the human did not -> takes git', () => {
|
||||||
|
expect(merge(['1', '2', '3'], ['1', '2', '3'], ['1', '9', '3'])).toEqual([
|
||||||
|
'1',
|
||||||
|
'9',
|
||||||
|
'3',
|
||||||
|
]);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('human changed a block git did not -> KEEPS the human edit (the core 3-way win)', () => {
|
||||||
|
expect(merge(['1', '2', '3'], ['1', 'H', '3'], ['1', '2', '3'])).toEqual([
|
||||||
|
'1',
|
||||||
|
'H',
|
||||||
|
'3',
|
||||||
|
]);
|
||||||
|
});
|
||||||
|
|
||||||
|
// Bug #2 observability: diff3PlanWithConflicts reports SAME-BLOCK conflicts so
|
||||||
|
// the caller can surface the "git wins" loss (log + history pin) instead of
|
||||||
|
// dropping the human side silently.
|
||||||
|
describe('diff3PlanWithConflicts (same-block conflict reporting)', () => {
|
||||||
|
it('reports 0 conflicts when sides changed DIFFERENT blocks (clean merge)', () => {
|
||||||
|
const r = diff3PlanWithConflicts(
|
||||||
|
['1', '2', '3'],
|
||||||
|
['H', '2', '3'],
|
||||||
|
['1', '2', 'G'],
|
||||||
|
);
|
||||||
|
expect(r.conflicts).toBe(0);
|
||||||
|
expect(apply(r.picks, ['H', '2', '3'], ['1', '2', 'G'])).toEqual([
|
||||||
|
'H',
|
||||||
|
'2',
|
||||||
|
'G',
|
||||||
|
]);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('reports 1 conflict and git wins when BOTH rewrote the SAME block', () => {
|
||||||
|
const r = diff3PlanWithConflicts(
|
||||||
|
['1', '2', '3'],
|
||||||
|
['1', 'H', '3'], // human rewrote block 2
|
||||||
|
['1', 'G', '3'], // git rewrote block 2
|
||||||
|
);
|
||||||
|
expect(r.conflicts).toBe(1);
|
||||||
|
// Git wins the contested block; the human 'H' is NOT in the picks.
|
||||||
|
expect(apply(r.picks, ['1', 'H', '3'], ['1', 'G', '3'])).toEqual([
|
||||||
|
'1',
|
||||||
|
'G',
|
||||||
|
'3',
|
||||||
|
]);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('does NOT count a git-only region (no human content to lose) as a conflict', () => {
|
||||||
|
const r = diff3PlanWithConflicts(
|
||||||
|
['1', '2', '3'],
|
||||||
|
['1', '2', '3'], // human unchanged
|
||||||
|
['1', '9', '3'], // git rewrote block 2
|
||||||
|
);
|
||||||
|
expect(r.conflicts).toBe(0);
|
||||||
|
});
|
||||||
|
});
|
||||||
|
|
||||||
|
it('human and git changed DIFFERENT blocks -> both preserved', () => {
|
||||||
|
// human rewrote block 1, git rewrote block 3.
|
||||||
|
expect(merge(['1', '2', '3'], ['H', '2', '3'], ['1', '2', 'G'])).toEqual([
|
||||||
|
'H',
|
||||||
|
'2',
|
||||||
|
'G',
|
||||||
|
]);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('human inserted a block AND git changed a different block -> both preserved', () => {
|
||||||
|
expect(
|
||||||
|
merge(['1', '2', '3'], ['1', '1.5', '2', '3'], ['1', '2', 'G']),
|
||||||
|
).toEqual(['1', '1.5', '2', 'G']);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('both changed the SAME block -> conflict resolves to git', () => {
|
||||||
|
expect(merge(['1', '2', '3'], ['1', 'H', '3'], ['1', 'G', '3'])).toEqual([
|
||||||
|
'1',
|
||||||
|
'G',
|
||||||
|
'3',
|
||||||
|
]);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('both made the SAME edit -> that edit (no duplication)', () => {
|
||||||
|
expect(merge(['1', '2', '3'], ['1', 'X', '3'], ['1', 'X', '3'])).toEqual([
|
||||||
|
'1',
|
||||||
|
'X',
|
||||||
|
'3',
|
||||||
|
]);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('human deleted a block git left alone -> deletion preserved', () => {
|
||||||
|
expect(merge(['1', '2', '3'], ['1', '3'], ['1', '2', '3'])).toEqual([
|
||||||
|
'1',
|
||||||
|
'3',
|
||||||
|
]);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('git deleted a block the human left alone -> deletion applied', () => {
|
||||||
|
expect(merge(['1', '2', '3'], ['1', '2', '3'], ['1', '3'])).toEqual([
|
||||||
|
'1',
|
||||||
|
'3',
|
||||||
|
]);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('both deleted the same block -> gone (no conflict)', () => {
|
||||||
|
expect(merge(['1', '2', '3'], ['1', '3'], ['1', '3'])).toEqual(['1', '3']);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('git appended a trailing block -> appended', () => {
|
||||||
|
expect(merge(['1', '2'], ['1', '2'], ['1', '2', '3'])).toEqual([
|
||||||
|
'1',
|
||||||
|
'2',
|
||||||
|
'3',
|
||||||
|
]);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('human appended a trailing block git did not -> kept', () => {
|
||||||
|
expect(merge(['1', '2'], ['1', '2', '3'], ['1', '2'])).toEqual([
|
||||||
|
'1',
|
||||||
|
'2',
|
||||||
|
'3',
|
||||||
|
]);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('empty base, git provides content (brand-new page body) -> git content', () => {
|
||||||
|
expect(merge([], [], ['1', '2'])).toEqual(['1', '2']);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('git changed block 1, human edited block 3, far apart -> both kept', () => {
|
||||||
|
expect(
|
||||||
|
merge(
|
||||||
|
['a', 'b', 'c', 'd', 'e'],
|
||||||
|
['a', 'b', 'c', 'd', 'E'],
|
||||||
|
['A', 'b', 'c', 'd', 'e'],
|
||||||
|
),
|
||||||
|
).toEqual(['A', 'b', 'c', 'd', 'E']);
|
||||||
|
});
|
||||||
|
});
|
||||||
@@ -0,0 +1,284 @@
|
|||||||
|
/**
|
||||||
|
* Pure block-level THREE-WAY merge planner (diff3) over arrays of opaque block
|
||||||
|
* keys. Used by the git-sync body write to merge an incoming git body into the
|
||||||
|
* live page using the last-synced version as the common ancestor (review #5):
|
||||||
|
*
|
||||||
|
* - a block only the human changed (live != base, git == base) -> keep LIVE
|
||||||
|
* - a block only git changed (git != base, live == base) -> take GIT
|
||||||
|
* - a block both sides changed (a real conflict) -> GIT wins
|
||||||
|
* - inserts/deletes from either side are preserved when unambiguous
|
||||||
|
*
|
||||||
|
* Content-agnostic: it works on string keys and returns the merged block order as
|
||||||
|
* picks ({ src: 'live'|'target', index }) — the caller (the Yjs applier)
|
||||||
|
* materializes them — so the whole algorithm is unit-testable on plain arrays.
|
||||||
|
*
|
||||||
|
* Algorithm: anchor on base blocks present (unchanged) in BOTH live and target
|
||||||
|
* (their LCS-with-base intersection). Between consecutive anchors lies one region
|
||||||
|
* the human and/or git rewrote; resolve each region three-way. Stable anchor
|
||||||
|
* blocks are emitted from LIVE so the applier keeps the existing Yjs block
|
||||||
|
* instances (and the human's in-flight edits) in place.
|
||||||
|
*
|
||||||
|
* LOCATION (deferred): this and its `lcs.ts` sibling are pure, framework-free and
|
||||||
|
* could conceptually live in `packages/git-sync` (the engine). They are kept in
|
||||||
|
* the server integration on purpose: `packages/git-sync` is a VENDORED engine
|
||||||
|
* (pinned upstream, manually re-synced), so adding first-party files there
|
||||||
|
* complicates the re-sync story, and the only consumer today is the server. Move
|
||||||
|
* them into the engine only once the vendoring re-sync story is settled.
|
||||||
|
*/
|
||||||
|
|
||||||
|
import { buildLcsTable } from './lcs';
|
||||||
|
|
||||||
|
/** Matched index pairs of the longest common subsequence of `a` and `b`. */
|
||||||
|
function lcsPairs(a: string[], b: string[]): Array<[number, number]> {
|
||||||
|
const n = a.length;
|
||||||
|
const m = b.length;
|
||||||
|
const dp = buildLcsTable(a, b);
|
||||||
|
const pairs: Array<[number, number]> = [];
|
||||||
|
let i = 0;
|
||||||
|
let j = 0;
|
||||||
|
while (i < n && j < m) {
|
||||||
|
if (a[i] === b[j]) {
|
||||||
|
pairs.push([i, j]);
|
||||||
|
i++;
|
||||||
|
j++;
|
||||||
|
} else if (dp[i + 1][j] >= dp[i][j + 1]) {
|
||||||
|
i++;
|
||||||
|
} else {
|
||||||
|
j++;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
return pairs;
|
||||||
|
}
|
||||||
|
|
||||||
|
/** o-index -> matched index in the other side (only for LCS-matched blocks). */
|
||||||
|
function matchMap(pairs: Array<[number, number]>): Map<number, number> {
|
||||||
|
const m = new Map<number, number>();
|
||||||
|
for (const [o, x] of pairs) m.set(o, x);
|
||||||
|
return m;
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* One change `side` made to `base` within a region: base blocks `[oStart,oEnd)`
|
||||||
|
* were replaced by the side's blocks listed in `content` (region-local indices).
|
||||||
|
* A pure insert has `oStart === oEnd`; a pure delete has empty `content`.
|
||||||
|
*/
|
||||||
|
interface Hunk {
|
||||||
|
oStart: number;
|
||||||
|
oEnd: number;
|
||||||
|
content: number[];
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Diff `o` against one side as a list of non-overlapping hunks (the base spans
|
||||||
|
* the side rewrote/inserted/deleted), derived from their LCS alignment.
|
||||||
|
*/
|
||||||
|
function buildHunks(o: string[], side: string[]): Hunk[] {
|
||||||
|
const pairs = lcsPairs(o, side); // [oIdx, sideIdx] kept (unchanged) blocks
|
||||||
|
const hunks: Hunk[] = [];
|
||||||
|
let prevO = -1;
|
||||||
|
let prevS = -1;
|
||||||
|
const flush = (curO: number, curS: number): void => {
|
||||||
|
const oStart = prevO + 1;
|
||||||
|
const oEnd = curO;
|
||||||
|
const content: number[] = [];
|
||||||
|
for (let s = prevS + 1; s < curS; s++) content.push(s);
|
||||||
|
if (oEnd > oStart || content.length > 0) hunks.push({ oStart, oEnd, content });
|
||||||
|
};
|
||||||
|
for (const [oIdx, sIdx] of pairs) {
|
||||||
|
flush(oIdx, sIdx);
|
||||||
|
prevO = oIdx;
|
||||||
|
prevS = sIdx;
|
||||||
|
}
|
||||||
|
flush(o.length, side.length);
|
||||||
|
return hunks;
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Do two hunks (one per side) touch the same base region? Pure inserts only
|
||||||
|
* collide when nested strictly inside the other hunk's base span (or, for two
|
||||||
|
* inserts, at the same gap); changes sitting at a shared boundary do not.
|
||||||
|
*/
|
||||||
|
function hunksOverlap(a: Hunk, b: Hunk): boolean {
|
||||||
|
const aIns = a.oStart === a.oEnd;
|
||||||
|
const bIns = b.oStart === b.oEnd;
|
||||||
|
if (aIns && bIns) return a.oStart === b.oStart;
|
||||||
|
if (aIns) return b.oStart < a.oStart && a.oStart < b.oEnd;
|
||||||
|
if (bIns) return a.oStart < b.oStart && b.oStart < a.oEnd;
|
||||||
|
return Math.max(a.oStart, b.oStart) < Math.min(a.oEnd, b.oEnd);
|
||||||
|
}
|
||||||
|
|
||||||
|
interface LocalPick {
|
||||||
|
src: 'live' | 'target';
|
||||||
|
local: number;
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Fine-grained three-way merge of ONE inter-anchor region. Combines the human's
|
||||||
|
* and git's NON-overlapping hunks (e.g. a human edit to one block plus a git
|
||||||
|
* insert/delete of OTHER blocks in the same region) so neither change is lost.
|
||||||
|
* Returns the merged region as region-local picks, or `null` when the two sides
|
||||||
|
* changed the SAME base block — a genuine conflict the caller resolves by the
|
||||||
|
* original all-or-nothing rule (git wins the whole region).
|
||||||
|
*/
|
||||||
|
function tryMergeRegion(
|
||||||
|
o: string[],
|
||||||
|
a: string[],
|
||||||
|
b: string[],
|
||||||
|
): LocalPick[] | null {
|
||||||
|
// Agreement short-circuit (review #11). When live (a) and target (b) are
|
||||||
|
// identical, both sides converged on the SAME result — diff3 "agreement", NOT
|
||||||
|
// a conflict. This is the dominant echo case (live == target != base) that
|
||||||
|
// otherwise trips the overlap check below and is logged as a false "N same-block
|
||||||
|
// conflict(s) resolved to the git version", masking REAL data-loss signals.
|
||||||
|
// Emit the region straight from live (which equals target); no conflict.
|
||||||
|
if (a.length === b.length && a.every((v, i) => v === b[i])) {
|
||||||
|
return a.map((_v, i) => ({ src: 'live', local: i }) as LocalPick);
|
||||||
|
}
|
||||||
|
|
||||||
|
const aHunks = buildHunks(o, a);
|
||||||
|
const bHunks = buildHunks(o, b);
|
||||||
|
|
||||||
|
// Any overlap between a human hunk and a git hunk is a real conflict; bail so
|
||||||
|
// the caller falls back to git-wins (preserving the original behavior).
|
||||||
|
for (const ah of aHunks) {
|
||||||
|
for (const bh of bHunks) {
|
||||||
|
if (hunksOverlap(ah, bh)) return null;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
// Disjoint: live index of each base block that BOTH sides kept (stable).
|
||||||
|
const aKept = matchMap(lcsPairs(o, a)); // base index -> live index
|
||||||
|
|
||||||
|
const out: LocalPick[] = [];
|
||||||
|
let pa = 0;
|
||||||
|
let pb = 0;
|
||||||
|
let oi = 0;
|
||||||
|
while (oi < o.length || pa < aHunks.length || pb < bHunks.length) {
|
||||||
|
const ah = pa < aHunks.length ? aHunks[pa] : null;
|
||||||
|
const bh = pb < bHunks.length ? bHunks[pb] : null;
|
||||||
|
const nextStart = Math.min(
|
||||||
|
ah ? ah.oStart : o.length,
|
||||||
|
bh ? bh.oStart : o.length,
|
||||||
|
);
|
||||||
|
|
||||||
|
// Emit stable base blocks (kept by both) until the next hunk, from LIVE.
|
||||||
|
while (oi < nextStart) {
|
||||||
|
out.push({ src: 'live', local: aKept.get(oi) as number });
|
||||||
|
oi++;
|
||||||
|
}
|
||||||
|
if (!ah && !bh) break;
|
||||||
|
|
||||||
|
// Apply the hunk at oi. When both sides act here they are disjoint, so the
|
||||||
|
// pure-insert (oEnd === oi) is emitted before the side that consumes base oi.
|
||||||
|
const aHere = ah !== null && ah.oStart === oi;
|
||||||
|
const bHere = bh !== null && bh.oStart === oi;
|
||||||
|
let useA: boolean;
|
||||||
|
if (aHere && bHere) {
|
||||||
|
useA = ah!.oEnd === oi; // insert side first; otherwise either order is fine
|
||||||
|
} else {
|
||||||
|
useA = aHere;
|
||||||
|
}
|
||||||
|
const h = (useA ? ah : bh) as Hunk;
|
||||||
|
const src: 'live' | 'target' = useA ? 'live' : 'target';
|
||||||
|
for (const idx of h.content) out.push({ src, local: idx });
|
||||||
|
oi = h.oEnd;
|
||||||
|
if (useA) pa++;
|
||||||
|
else pb++;
|
||||||
|
}
|
||||||
|
return out;
|
||||||
|
}
|
||||||
|
|
||||||
|
export interface Pick {
|
||||||
|
src: 'live' | 'target';
|
||||||
|
index: number;
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* The merged block order PLUS how many regions resolved as a genuine SAME-BLOCK
|
||||||
|
* conflict (both sides rewrote the same base block — `tryMergeRegion` returned
|
||||||
|
* null and git won the whole region, so the live/human version of those blocks
|
||||||
|
* is NOT in `picks`). `conflicts > 0` is the OBSERVABLE signal the caller uses to
|
||||||
|
* surface "git won a concurrent same-block edit" (log it + pin the human
|
||||||
|
* baseline to page history) instead of dropping the human side silently.
|
||||||
|
*/
|
||||||
|
export interface Diff3Result {
|
||||||
|
picks: Pick[];
|
||||||
|
conflicts: number;
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Three-way merge of base `o`, live `a`, target `b` (arrays of block keys).
|
||||||
|
* Returns the merged block order as picks from live/target. Thin wrapper over
|
||||||
|
* `diff3PlanWithConflicts` (kept for the existing pure-array callers/tests).
|
||||||
|
*/
|
||||||
|
export function diff3Plan(o: string[], a: string[], b: string[]): Pick[] {
|
||||||
|
return diff3PlanWithConflicts(o, a, b).picks;
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Like `diff3Plan` but also reports the SAME-BLOCK conflict count (see
|
||||||
|
* `Diff3Result`). A region where both the human and git rewrote the same base
|
||||||
|
* block cannot be merged automatically; the rule is deterministic — GIT WINS the
|
||||||
|
* whole region — but the human's version of those blocks is then absent from the
|
||||||
|
* picks, so we count it so the caller can make the loss observable/recoverable
|
||||||
|
* rather than silent (the documented conflict contract).
|
||||||
|
*/
|
||||||
|
export function diff3PlanWithConflicts(
|
||||||
|
o: string[],
|
||||||
|
a: string[],
|
||||||
|
b: string[],
|
||||||
|
): Diff3Result {
|
||||||
|
const oToA = matchMap(lcsPairs(o, a));
|
||||||
|
const oToB = matchMap(lcsPairs(o, b));
|
||||||
|
|
||||||
|
const res: Pick[] = [];
|
||||||
|
let conflicts = 0;
|
||||||
|
let oi = 0;
|
||||||
|
let ai = 0;
|
||||||
|
let bi = 0;
|
||||||
|
|
||||||
|
for (;;) {
|
||||||
|
// Next anchor: a base block present (unchanged) in BOTH live and target.
|
||||||
|
let anchor = oi;
|
||||||
|
while (anchor < o.length && !(oToA.has(anchor) && oToB.has(anchor))) {
|
||||||
|
anchor++;
|
||||||
|
}
|
||||||
|
const aEnd = anchor < o.length ? (oToA.get(anchor) as number) : a.length;
|
||||||
|
const bEnd = anchor < o.length ? (oToB.get(anchor) as number) : b.length;
|
||||||
|
|
||||||
|
// Resolve the region [oi,anchor) that one or both sides rewrote/inserted.
|
||||||
|
// Try a fine-grained three-way merge first so a human block-edit survives a
|
||||||
|
// git insert/delete of OTHER blocks in the same region; only a genuine
|
||||||
|
// same-block conflict (null) falls back to the original git-wins rule.
|
||||||
|
const merged = tryMergeRegion(
|
||||||
|
o.slice(oi, anchor),
|
||||||
|
a.slice(ai, aEnd),
|
||||||
|
b.slice(bi, bEnd),
|
||||||
|
);
|
||||||
|
if (merged) {
|
||||||
|
for (const p of merged) {
|
||||||
|
res.push(
|
||||||
|
p.src === 'live'
|
||||||
|
? { src: 'live', index: ai + p.local }
|
||||||
|
: { src: 'target', index: bi + p.local },
|
||||||
|
);
|
||||||
|
}
|
||||||
|
} else {
|
||||||
|
// SAME-BLOCK CONFLICT: count it ONLY when the human side actually had
|
||||||
|
// content in this region that git's win discards (live region non-empty).
|
||||||
|
// A region only git rewrote (live region empty) is not a human loss.
|
||||||
|
if (aEnd > ai) conflicts++;
|
||||||
|
for (let k = bi; k < bEnd; k++) res.push({ src: 'target', index: k });
|
||||||
|
}
|
||||||
|
|
||||||
|
if (anchor >= o.length) break;
|
||||||
|
|
||||||
|
// Emit the stable anchor block from LIVE, then advance past it on all sides.
|
||||||
|
res.push({ src: 'live', index: aEnd });
|
||||||
|
ai = aEnd + 1;
|
||||||
|
bi = bEnd + 1;
|
||||||
|
oi = anchor + 1;
|
||||||
|
}
|
||||||
|
|
||||||
|
return { picks: res, conflicts };
|
||||||
|
}
|
||||||
@@ -0,0 +1,171 @@
|
|||||||
|
import { TiptapTransformer } from '@hocuspocus/transformer';
|
||||||
|
import * as Y from 'yjs';
|
||||||
|
import {
|
||||||
|
markdownToProseMirror,
|
||||||
|
convertProseMirrorToMarkdown,
|
||||||
|
} from '@docmost/git-sync';
|
||||||
|
|
||||||
|
import { tiptapExtensions } from '../collaboration.util';
|
||||||
|
import { mergeXmlFragments, mergeXmlFragments3Way } from './yjs-body-merge';
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Regression for the QA #119 callout findings (body-duplication re-verify +
|
||||||
|
* "callout strips the whole body"). These reproduce the ACTUAL live merge path:
|
||||||
|
*
|
||||||
|
* live = TiptapTransformer.toYdoc(editor JSON, tiptapExtensions) (the
|
||||||
|
* collaboration server's materialization — schema defaults stamped)
|
||||||
|
* git = toYdoc(markdownToProseMirror(convertProseMirrorToMarkdown(editor)))
|
||||||
|
* (the engine round-trip the push side feeds into writePageBody)
|
||||||
|
*
|
||||||
|
* A page containing a callout (with a neighbouring heading + paragraphs) must:
|
||||||
|
* - merge with ZERO ops on an unchanged resync (no duplication — bug #1), and
|
||||||
|
* - NEVER lose blocks / collapse to empty (no strip — bug #2),
|
||||||
|
* across repeated cycles, for every editor-canonical callout type.
|
||||||
|
*/
|
||||||
|
|
||||||
|
const toYdoc = (content: unknown[]) =>
|
||||||
|
TiptapTransformer.toYdoc(
|
||||||
|
{ type: 'doc', content },
|
||||||
|
'default',
|
||||||
|
tiptapExtensions as any,
|
||||||
|
);
|
||||||
|
|
||||||
|
const blockTypes = (f: Y.XmlFragment) =>
|
||||||
|
f.toArray().map((n: any) => n.nodeName);
|
||||||
|
|
||||||
|
function editorPage(calloutType: string) {
|
||||||
|
return [
|
||||||
|
{
|
||||||
|
type: 'heading',
|
||||||
|
attrs: { id: 'h1', level: 1 },
|
||||||
|
content: [{ type: 'text', text: 'Title here' }],
|
||||||
|
},
|
||||||
|
{
|
||||||
|
type: 'paragraph',
|
||||||
|
attrs: { id: 'p1' },
|
||||||
|
content: [{ type: 'text', text: 'Para before callout' }],
|
||||||
|
},
|
||||||
|
{
|
||||||
|
type: 'callout',
|
||||||
|
attrs: { type: calloutType },
|
||||||
|
content: [
|
||||||
|
{
|
||||||
|
type: 'paragraph',
|
||||||
|
attrs: { id: 'pc' },
|
||||||
|
content: [{ type: 'text', text: 'Inside the callout' }],
|
||||||
|
},
|
||||||
|
],
|
||||||
|
},
|
||||||
|
{
|
||||||
|
type: 'paragraph',
|
||||||
|
attrs: { id: 'p2' },
|
||||||
|
content: [{ type: 'text', text: 'Para after callout' }],
|
||||||
|
},
|
||||||
|
];
|
||||||
|
}
|
||||||
|
|
||||||
|
async function gitRoundTrip(content: unknown[]): Promise<any[]> {
|
||||||
|
const md = await convertProseMirrorToMarkdown({ type: 'doc', content });
|
||||||
|
const json = await markdownToProseMirror(md);
|
||||||
|
return json.content;
|
||||||
|
}
|
||||||
|
|
||||||
|
describe('git-sync callout merge is idempotent + non-destructive (QA #119)', () => {
|
||||||
|
for (const type of ['info', 'note', 'warning', 'danger', 'success', 'default']) {
|
||||||
|
it(`callout(${type}) resyncs with 0 ops and never strips the body`, async () => {
|
||||||
|
const editor = editorPage(type);
|
||||||
|
const gitContent = await gitRoundTrip(editor);
|
||||||
|
|
||||||
|
const liveDoc = toYdoc(editor);
|
||||||
|
const live = liveDoc.getXmlFragment('default');
|
||||||
|
const before = live.toArray().length;
|
||||||
|
expect(before).toBe(4);
|
||||||
|
|
||||||
|
// 2-way: live vs the git round-trip -> no-op (no dup, no strip).
|
||||||
|
let applied = -1;
|
||||||
|
liveDoc.transact(() => {
|
||||||
|
applied = mergeXmlFragments(live, toYdoc(gitContent).getXmlFragment('default'));
|
||||||
|
});
|
||||||
|
expect(applied).toBe(0);
|
||||||
|
expect(live.toArray().length).toBe(before);
|
||||||
|
|
||||||
|
// 3-way across 4 cycles with base == git (the steady-state) -> stable.
|
||||||
|
for (let cycle = 0; cycle < 4; cycle++) {
|
||||||
|
let a = -1;
|
||||||
|
liveDoc.transact(() => {
|
||||||
|
a = mergeXmlFragments3Way(
|
||||||
|
live,
|
||||||
|
toYdoc(gitContent).getXmlFragment('default'),
|
||||||
|
toYdoc(gitContent).getXmlFragment('default'),
|
||||||
|
);
|
||||||
|
});
|
||||||
|
expect(a).toBe(0);
|
||||||
|
expect(live.toArray().length).toBe(before);
|
||||||
|
expect(blockTypes(live)).toEqual([
|
||||||
|
'heading',
|
||||||
|
'paragraph',
|
||||||
|
'callout',
|
||||||
|
'paragraph',
|
||||||
|
]);
|
||||||
|
}
|
||||||
|
});
|
||||||
|
}
|
||||||
|
|
||||||
|
it('3-way with a stale base (callout JUST added) keeps the callout + neighbours', async () => {
|
||||||
|
// base = the previously-synced version WITHOUT the callout (git round-trip);
|
||||||
|
// the human just inserted the callout -> the merge must KEEP everything.
|
||||||
|
const prev = [
|
||||||
|
{ type: 'heading', attrs: { id: 'h1', level: 1 }, content: [{ type: 'text', text: 'Title here' }] },
|
||||||
|
{ type: 'paragraph', attrs: { id: 'p1' }, content: [{ type: 'text', text: 'Para before callout' }] },
|
||||||
|
{ type: 'paragraph', attrs: { id: 'p2' }, content: [{ type: 'text', text: 'Para after callout' }] },
|
||||||
|
];
|
||||||
|
const editor = editorPage('info');
|
||||||
|
const baseContent = await gitRoundTrip(prev);
|
||||||
|
const gitContent = await gitRoundTrip(editor);
|
||||||
|
|
||||||
|
const liveDoc = toYdoc(editor);
|
||||||
|
const live = liveDoc.getXmlFragment('default');
|
||||||
|
liveDoc.transact(() => {
|
||||||
|
mergeXmlFragments3Way(
|
||||||
|
live,
|
||||||
|
toYdoc(gitContent).getXmlFragment('default'),
|
||||||
|
toYdoc(baseContent).getXmlFragment('default'),
|
||||||
|
);
|
||||||
|
});
|
||||||
|
// Body survives in full — NOT stripped to empty / a lone paragraph.
|
||||||
|
expect(blockTypes(live)).toEqual([
|
||||||
|
'heading',
|
||||||
|
'paragraph',
|
||||||
|
'callout',
|
||||||
|
'paragraph',
|
||||||
|
]);
|
||||||
|
});
|
||||||
|
});
|
||||||
|
|
||||||
|
describe('git-sync callout type fidelity (QA "callout type -> [!info]")', () => {
|
||||||
|
for (const type of ['info', 'note', 'warning', 'danger', 'success', 'default']) {
|
||||||
|
it(`preserves callout type "${type}" across the engine round-trip`, async () => {
|
||||||
|
const content = editorPage(type);
|
||||||
|
const gitContent = await gitRoundTrip(content);
|
||||||
|
const co = gitContent.find((b: any) => b.type === 'callout');
|
||||||
|
expect(co?.attrs?.type).toBe(type);
|
||||||
|
});
|
||||||
|
}
|
||||||
|
|
||||||
|
it('maps a known GitHub/Obsidian alias to the editor banner (tip -> success)', async () => {
|
||||||
|
// `tip` is not a schema callout type — it is an input alias the editor itself
|
||||||
|
// maps onto the supported set (GITHUB_ALERT_TYPE_MAP: tip -> success). git-sync
|
||||||
|
// mirrors that so the ingest lands on the closest banner instead of flatly info.
|
||||||
|
const content = editorPage('tip');
|
||||||
|
const gitContent = await gitRoundTrip(content);
|
||||||
|
const co = gitContent.find((b: any) => b.type === 'callout');
|
||||||
|
expect(co?.attrs?.type).toBe('success');
|
||||||
|
});
|
||||||
|
|
||||||
|
it('flattens a genuinely unknown callout type to info', async () => {
|
||||||
|
const content = editorPage('banana'); // not a type and not a known alias
|
||||||
|
const gitContent = await gitRoundTrip(content);
|
||||||
|
const co = gitContent.find((b: any) => b.type === 'callout');
|
||||||
|
expect(co?.attrs?.type).toBe('info');
|
||||||
|
});
|
||||||
|
});
|
||||||
@@ -0,0 +1,198 @@
|
|||||||
|
import * as Y from 'yjs';
|
||||||
|
|
||||||
|
import { mergeXmlFragments, mergeXmlFragments3Way } from './yjs-body-merge';
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Regression for the HIGH-severity runaway whole-body duplication: a page body
|
||||||
|
* was RE-APPENDED in full on every git-sync reconcile cycle, unbounded, with NO
|
||||||
|
* client connected.
|
||||||
|
*
|
||||||
|
* ROOT CAUSE (confirmed in-process against the real failing page): the LIVE Yjs
|
||||||
|
* document materializes the editor-schema default `indent: 0` on every
|
||||||
|
* paragraph/heading (and on the paragraph inside every list item, callout, and
|
||||||
|
* table cell), but a body re-imported from git — parsed from clean markdown —
|
||||||
|
* carries NO indent attribute. So every live block's comparison key differed from
|
||||||
|
* the same block coming back from git; the three-way merge could anchor on
|
||||||
|
* NOTHING, and the trailing unit that git's export already contained (but the
|
||||||
|
* merge could not match against the byte-identical live tail) was re-appended
|
||||||
|
* each cycle. Each grown export then diverged from the last-pushed base by one
|
||||||
|
* more unit — a self-sustaining loop.
|
||||||
|
*
|
||||||
|
* The fix normalizes the materialized default (`indent: 0`) out of the block key
|
||||||
|
* (the schema-derived `serializeXmlNode` normalization in yjs-body-merge.ts drops
|
||||||
|
* every attr equal to its ProseMirror-schema default; `indent: 0` is one such),
|
||||||
|
* so a live block compares equal to its git-round-tripped twin and the resync is
|
||||||
|
* a true no-op. The sibling `yjs-body-merge.schema-defaults.spec.ts` covers the
|
||||||
|
* rest of the bug class (image.align, link mark internal, …).
|
||||||
|
*
|
||||||
|
* These tests model that EXACTLY at the Yjs level: a LIVE fragment whose blocks
|
||||||
|
* carry `indent: 0` + block ids, versus a git-derived fragment of the SAME
|
||||||
|
* content with neither — for a body built from BYTE-IDENTICAL units that each
|
||||||
|
* contain a heading, a paragraph, a callout, and a table with empty cells (the
|
||||||
|
* trigger). RED before the fix (the merge applies > 0 ops and the body grows),
|
||||||
|
* GREEN after (0 ops, no growth).
|
||||||
|
*/
|
||||||
|
|
||||||
|
type Attrs = Record<string, string | number>;
|
||||||
|
|
||||||
|
function el(
|
||||||
|
name: string,
|
||||||
|
attrs: Attrs,
|
||||||
|
children: (Y.XmlElement | Y.XmlText)[],
|
||||||
|
) {
|
||||||
|
const e = new Y.XmlElement(name);
|
||||||
|
for (const [k, v] of Object.entries(attrs)) e.setAttribute(k, v as string);
|
||||||
|
if (children.length) e.insert(0, children);
|
||||||
|
return e;
|
||||||
|
}
|
||||||
|
|
||||||
|
function text(s: string): Y.XmlText {
|
||||||
|
const t = new Y.XmlText();
|
||||||
|
if (s) t.insert(0, s);
|
||||||
|
return t;
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* One byte-identical content unit (heading / paragraph / callout / table-with-
|
||||||
|
* empty-cells). `live` toggles the two things that exist ONLY in the live Yjs
|
||||||
|
* doc and NOT in a git round-trip: the materialized `indent: 0` default and the
|
||||||
|
* per-block `id`. `n` makes each unit's ids unique (as the editor would stamp)
|
||||||
|
* while keeping the visible CONTENT byte-identical across units.
|
||||||
|
*/
|
||||||
|
function unit(
|
||||||
|
live: boolean,
|
||||||
|
n: number,
|
||||||
|
headingText = 'Big Heading',
|
||||||
|
): Y.XmlElement[] {
|
||||||
|
const ind: Attrs = live ? { indent: 0 } : {};
|
||||||
|
const id = (base: string): Attrs => (live ? { id: `${base}${n}` } : {});
|
||||||
|
const para = (attrs: Attrs, s: string) =>
|
||||||
|
el('paragraph', { ...attrs, ...ind }, [text(s)]);
|
||||||
|
|
||||||
|
const cell = (name: string) =>
|
||||||
|
el(name, { colspan: 1, rowspan: 1 }, [para({}, '')]);
|
||||||
|
|
||||||
|
return [
|
||||||
|
el('heading', { ...id('h'), level: 1, ...ind }, [text(headingText)]),
|
||||||
|
para(id('p'), 'Para with the same words'),
|
||||||
|
el('callout', { type: 'info' }, [para(id('c'), 'CalloutText here')]),
|
||||||
|
el('table', {}, [
|
||||||
|
el('tableRow', {}, [cell('tableHeader'), cell('tableHeader')]),
|
||||||
|
el('tableRow', {}, [cell('tableCell'), cell('tableCell')]),
|
||||||
|
]),
|
||||||
|
];
|
||||||
|
}
|
||||||
|
|
||||||
|
function fragmentOf(units: Y.XmlElement[][]): {
|
||||||
|
doc: Y.Doc;
|
||||||
|
frag: Y.XmlFragment;
|
||||||
|
} {
|
||||||
|
const doc = new Y.Doc();
|
||||||
|
const frag = doc.getXmlFragment('default');
|
||||||
|
const blocks = units.flat();
|
||||||
|
if (blocks.length) frag.insert(0, blocks);
|
||||||
|
return { doc, frag };
|
||||||
|
}
|
||||||
|
|
||||||
|
const blockCount = (frag: Y.XmlFragment): number => frag.toArray().length;
|
||||||
|
|
||||||
|
describe('git-sync reconcile import is idempotent (no whole-body duplication)', () => {
|
||||||
|
const UNITS = 3;
|
||||||
|
|
||||||
|
it('3-way: identical content, live carries indent:0, base stale-by-one -> 0 ops, no growth', () => {
|
||||||
|
// LIVE: the editor-stamped Yjs doc (indent:0 + ids on every block).
|
||||||
|
const { doc: liveDoc, frag: live } = fragmentOf(
|
||||||
|
Array.from({ length: UNITS }, (_, i) => unit(true, i)),
|
||||||
|
);
|
||||||
|
// INCOMING (git export -> re-import): same content, NO indent / ids.
|
||||||
|
const { frag: incoming } = fragmentOf(
|
||||||
|
Array.from({ length: UNITS }, (_, i) => unit(false, i)),
|
||||||
|
);
|
||||||
|
// BASE = last-pushed file, lagging by ONE unit (the realistic divergence
|
||||||
|
// that drives the trailing insert-vs-insert).
|
||||||
|
const { frag: base } = fragmentOf(
|
||||||
|
Array.from({ length: UNITS - 1 }, (_, i) => unit(false, i)),
|
||||||
|
);
|
||||||
|
|
||||||
|
const before = blockCount(live);
|
||||||
|
let applied = -1;
|
||||||
|
liveDoc.transact(() => {
|
||||||
|
applied = mergeXmlFragments3Way(live, incoming, base);
|
||||||
|
});
|
||||||
|
|
||||||
|
expect(applied).toBe(0);
|
||||||
|
expect(blockCount(live)).toBe(before);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('3-way is a fixpoint across repeated cycles (does not grow)', () => {
|
||||||
|
const { doc: liveDoc, frag: live } = fragmentOf(
|
||||||
|
Array.from({ length: UNITS }, (_, i) => unit(true, i)),
|
||||||
|
);
|
||||||
|
const incomingUnits = () =>
|
||||||
|
fragmentOf(Array.from({ length: UNITS }, (_, i) => unit(false, i))).frag;
|
||||||
|
const baseUnits = () =>
|
||||||
|
fragmentOf(Array.from({ length: UNITS - 1 }, (_, i) => unit(false, i)))
|
||||||
|
.frag;
|
||||||
|
|
||||||
|
const before = blockCount(live);
|
||||||
|
for (let cycle = 0; cycle < 5; cycle++) {
|
||||||
|
let applied = -1;
|
||||||
|
liveDoc.transact(() => {
|
||||||
|
applied = mergeXmlFragments3Way(live, incomingUnits(), baseUnits());
|
||||||
|
});
|
||||||
|
expect(applied).toBe(0);
|
||||||
|
expect(blockCount(live)).toBe(before);
|
||||||
|
}
|
||||||
|
});
|
||||||
|
|
||||||
|
it('2-way: identical content, live carries indent:0 -> 0 ops, no growth', () => {
|
||||||
|
const { doc: liveDoc, frag: live } = fragmentOf(
|
||||||
|
Array.from({ length: UNITS }, (_, i) => unit(true, i)),
|
||||||
|
);
|
||||||
|
const { frag: incoming } = fragmentOf(
|
||||||
|
Array.from({ length: UNITS }, (_, i) => unit(false, i)),
|
||||||
|
);
|
||||||
|
|
||||||
|
const before = blockCount(live);
|
||||||
|
let applied = -1;
|
||||||
|
liveDoc.transact(() => {
|
||||||
|
applied = mergeXmlFragments(live, incoming);
|
||||||
|
});
|
||||||
|
|
||||||
|
expect(applied).toBe(0);
|
||||||
|
expect(blockCount(live)).toBe(before);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('does NOT regress real edits: a git change to one block still lands', () => {
|
||||||
|
const { doc: liveDoc, frag: live } = fragmentOf(
|
||||||
|
Array.from({ length: UNITS }, (_, i) => unit(true, i)),
|
||||||
|
);
|
||||||
|
const base = fragmentOf(
|
||||||
|
Array.from({ length: UNITS }, (_, i) => unit(false, i)),
|
||||||
|
).frag;
|
||||||
|
// git edits the heading text of the LAST unit.
|
||||||
|
const incoming = fragmentOf(
|
||||||
|
Array.from({ length: UNITS }, (_, i) =>
|
||||||
|
unit(false, i, i === UNITS - 1 ? 'EDITED Heading' : 'Big Heading'),
|
||||||
|
),
|
||||||
|
).frag;
|
||||||
|
|
||||||
|
const before = blockCount(live);
|
||||||
|
liveDoc.transact(() => {
|
||||||
|
mergeXmlFragments3Way(live, incoming, base);
|
||||||
|
});
|
||||||
|
|
||||||
|
// The edit landed, and the body did NOT grow (one block changed in place).
|
||||||
|
const headings = live
|
||||||
|
.toArray()
|
||||||
|
.filter((b) => (b as Y.XmlElement).nodeName === 'heading')
|
||||||
|
.map((b) =>
|
||||||
|
(b as Y.XmlElement)
|
||||||
|
.toArray()
|
||||||
|
.map((c) => (c as Y.XmlText).toString())
|
||||||
|
.join(''),
|
||||||
|
);
|
||||||
|
expect(headings).toContain('EDITED Heading');
|
||||||
|
expect(blockCount(live)).toBe(before);
|
||||||
|
});
|
||||||
|
});
|
||||||
@@ -0,0 +1,316 @@
|
|||||||
|
import { TiptapTransformer } from '@hocuspocus/transformer';
|
||||||
|
import * as Y from 'yjs';
|
||||||
|
|
||||||
|
import { tiptapExtensions } from '../collaboration.util';
|
||||||
|
import { mergeXmlFragments, mergeXmlFragments3Way } from './yjs-body-merge';
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Regression for the BUG CLASS behind the runaway whole-body duplication: the
|
||||||
|
* point-fix (7a7b840e) only normalized `indent: 0`, but the SAME divergence
|
||||||
|
* recurs for every attribute whose editor-ext (server) schema default the live
|
||||||
|
* Yjs doc MATERIALIZES while the git round-trip — which comes through the engine
|
||||||
|
* schema (different, usually null, defaults) plus `y-prosemirror`'s null-attr
|
||||||
|
* dropping — does NOT carry. Confirmed triggers beyond `indent`:
|
||||||
|
*
|
||||||
|
* - `image.align` : editor-ext default "center" (materialized) vs engine
|
||||||
|
* default null (dropped) -> element-attr divergence.
|
||||||
|
* - link mark `internal`: editor-ext default false (materialized) vs engine
|
||||||
|
* default null -> MARK-attr divergence (the prior denylist
|
||||||
|
* could not reach marks at all — they are serialized raw in
|
||||||
|
* the XmlText delta).
|
||||||
|
*
|
||||||
|
* `highlight.colorName` is normalized too (defense-in-depth); it is NOT a strong
|
||||||
|
* real-world trigger because BOTH schemas default it to null, but the schema-
|
||||||
|
* derived normalization handles it for free and stays idempotent.
|
||||||
|
*
|
||||||
|
* The fix derives the defaults from the ACTUAL ProseMirror schema (getSchema of
|
||||||
|
* the server tiptapExtensions) and drops any element- OR mark-attribute equal to
|
||||||
|
* its schema default (or null/undefined) from the block comparison key — so a
|
||||||
|
* live block compares equal to its git-round-tripped twin and an unchanged
|
||||||
|
* resync applies 0 ops. RED before the fix (keys diverge -> ops > 0 / growth),
|
||||||
|
* GREEN after.
|
||||||
|
*/
|
||||||
|
|
||||||
|
type Attrs = Record<string, unknown>;
|
||||||
|
|
||||||
|
function el(
|
||||||
|
name: string,
|
||||||
|
attrs: Attrs,
|
||||||
|
children: (Y.XmlElement | Y.XmlText)[],
|
||||||
|
): Y.XmlElement {
|
||||||
|
const e = new Y.XmlElement(name);
|
||||||
|
for (const [k, v] of Object.entries(attrs)) e.setAttribute(k, v as string);
|
||||||
|
if (children.length) e.insert(0, children);
|
||||||
|
return e;
|
||||||
|
}
|
||||||
|
|
||||||
|
/** Text carrying marks, as the live Yjs doc stores them (XmlText format ops). */
|
||||||
|
function markedText(s: string, marks: Record<string, unknown>): Y.XmlText {
|
||||||
|
const t = new Y.XmlText();
|
||||||
|
t.insert(0, s, marks);
|
||||||
|
return t;
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* One byte-identical RICH unit: a paragraph with a LINK, a top-level IMAGE, and
|
||||||
|
* a paragraph with a HIGHLIGHT. `live` toggles exactly what the editor
|
||||||
|
* materializes but a git round-trip does not: block `id`, `indent: 0`,
|
||||||
|
* `image.align: "center"`, the link mark's `internal: false`, and the
|
||||||
|
* highlight's `colorName: null`.
|
||||||
|
*/
|
||||||
|
function richUnit(live: boolean, n: number): Y.XmlElement[] {
|
||||||
|
const ind: Attrs = live ? { indent: 0 } : {};
|
||||||
|
const id = (base: string): Attrs => (live ? { id: `${base}${n}` } : {});
|
||||||
|
|
||||||
|
const linkMarks = live
|
||||||
|
? {
|
||||||
|
link: {
|
||||||
|
href: 'https://example.com',
|
||||||
|
target: '_blank',
|
||||||
|
rel: 'noopener noreferrer nofollow',
|
||||||
|
class: null,
|
||||||
|
title: null,
|
||||||
|
internal: false, // editor-ext default, materialized
|
||||||
|
},
|
||||||
|
}
|
||||||
|
: {
|
||||||
|
link: {
|
||||||
|
href: 'https://example.com',
|
||||||
|
target: '_blank',
|
||||||
|
rel: 'noopener noreferrer nofollow',
|
||||||
|
internal: null, // engine default
|
||||||
|
},
|
||||||
|
};
|
||||||
|
|
||||||
|
const hlMarks = live
|
||||||
|
? { highlight: { color: '#ffd43b', colorName: null } }
|
||||||
|
: { highlight: { color: '#ffd43b' } };
|
||||||
|
|
||||||
|
const imageAttrs: Attrs = live
|
||||||
|
? { src: 'https://img.example.com/a.png', align: 'center' } // materialized
|
||||||
|
: { src: 'https://img.example.com/a.png' }; // align:null dropped on git side
|
||||||
|
|
||||||
|
return [
|
||||||
|
el('paragraph', { ...id('lp'), ...ind }, [
|
||||||
|
markedText('click here', linkMarks),
|
||||||
|
]),
|
||||||
|
el('image', imageAttrs, []),
|
||||||
|
el('paragraph', { ...id('hp'), ...ind }, [markedText('hot', hlMarks)]),
|
||||||
|
];
|
||||||
|
}
|
||||||
|
|
||||||
|
function fragmentOf(units: Y.XmlElement[][]): {
|
||||||
|
doc: Y.Doc;
|
||||||
|
frag: Y.XmlFragment;
|
||||||
|
} {
|
||||||
|
const doc = new Y.Doc();
|
||||||
|
const frag = doc.getXmlFragment('default');
|
||||||
|
const blocks = units.flat();
|
||||||
|
if (blocks.length) frag.insert(0, blocks);
|
||||||
|
return { doc, frag };
|
||||||
|
}
|
||||||
|
|
||||||
|
const blockCount = (frag: Y.XmlFragment): number => frag.toArray().length;
|
||||||
|
|
||||||
|
describe('git-sync reconcile is idempotent for schema-default attrs (image/link/highlight)', () => {
|
||||||
|
const UNITS = 3;
|
||||||
|
|
||||||
|
it('3-way: live carries image.align/link.internal/indent defaults, base stale-by-one -> 0 ops', () => {
|
||||||
|
const { doc: liveDoc, frag: live } = fragmentOf(
|
||||||
|
Array.from({ length: UNITS }, (_, i) => richUnit(true, i)),
|
||||||
|
);
|
||||||
|
const { frag: incoming } = fragmentOf(
|
||||||
|
Array.from({ length: UNITS }, (_, i) => richUnit(false, i)),
|
||||||
|
);
|
||||||
|
const { frag: base } = fragmentOf(
|
||||||
|
Array.from({ length: UNITS - 1 }, (_, i) => richUnit(false, i)),
|
||||||
|
);
|
||||||
|
|
||||||
|
const before = blockCount(live);
|
||||||
|
let applied = -1;
|
||||||
|
liveDoc.transact(() => {
|
||||||
|
applied = mergeXmlFragments3Way(live, incoming, base);
|
||||||
|
});
|
||||||
|
|
||||||
|
expect(applied).toBe(0);
|
||||||
|
expect(blockCount(live)).toBe(before);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('2-way: live carries the materialized defaults -> 0 ops, no growth', () => {
|
||||||
|
const { doc: liveDoc, frag: live } = fragmentOf(
|
||||||
|
Array.from({ length: UNITS }, (_, i) => richUnit(true, i)),
|
||||||
|
);
|
||||||
|
const { frag: incoming } = fragmentOf(
|
||||||
|
Array.from({ length: UNITS }, (_, i) => richUnit(false, i)),
|
||||||
|
);
|
||||||
|
|
||||||
|
const before = blockCount(live);
|
||||||
|
let applied = -1;
|
||||||
|
liveDoc.transact(() => {
|
||||||
|
applied = mergeXmlFragments(live, incoming);
|
||||||
|
});
|
||||||
|
|
||||||
|
expect(applied).toBe(0);
|
||||||
|
expect(blockCount(live)).toBe(before);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('is a fixpoint across repeated cycles (does not grow)', () => {
|
||||||
|
const { doc: liveDoc, frag: live } = fragmentOf(
|
||||||
|
Array.from({ length: UNITS }, (_, i) => richUnit(true, i)),
|
||||||
|
);
|
||||||
|
const incoming = () =>
|
||||||
|
fragmentOf(Array.from({ length: UNITS }, (_, i) => richUnit(false, i)))
|
||||||
|
.frag;
|
||||||
|
const base = () =>
|
||||||
|
fragmentOf(
|
||||||
|
Array.from({ length: UNITS - 1 }, (_, i) => richUnit(false, i)),
|
||||||
|
).frag;
|
||||||
|
|
||||||
|
const before = blockCount(live);
|
||||||
|
for (let cycle = 0; cycle < 5; cycle++) {
|
||||||
|
let applied = -1;
|
||||||
|
liveDoc.transact(() => {
|
||||||
|
applied = mergeXmlFragments3Way(live, incoming(), base());
|
||||||
|
});
|
||||||
|
expect(applied).toBe(0);
|
||||||
|
expect(blockCount(live)).toBe(before);
|
||||||
|
}
|
||||||
|
});
|
||||||
|
|
||||||
|
it('does NOT regress a genuine non-default value (a real link.href / image.align:left still diffs)', () => {
|
||||||
|
const { doc: liveDoc, frag: live } = fragmentOf([richUnit(true, 0)]);
|
||||||
|
const base = fragmentOf([richUnit(false, 0)]).frag;
|
||||||
|
// git genuinely changes the image alignment to a NON-default value.
|
||||||
|
const incomingUnit = richUnit(false, 0);
|
||||||
|
(incomingUnit[1] as Y.XmlElement).setAttribute('align', 'left');
|
||||||
|
const incoming = fragmentOf([incomingUnit]).frag;
|
||||||
|
|
||||||
|
liveDoc.transact(() => {
|
||||||
|
mergeXmlFragments3Way(live, incoming, base);
|
||||||
|
});
|
||||||
|
|
||||||
|
const img = live
|
||||||
|
.toArray()
|
||||||
|
.find((b) => (b as Y.XmlElement).nodeName === 'image') as Y.XmlElement;
|
||||||
|
expect(img.getAttribute('align')).toBe('left');
|
||||||
|
});
|
||||||
|
});
|
||||||
|
|
||||||
|
/**
|
||||||
|
* FAITHFUL end-to-end proof through the REAL server transformer: build the live
|
||||||
|
* doc the way the collaboration server does (defaults omitted in the JSON ->
|
||||||
|
* TiptapTransformer.toYdoc MATERIALIZES image.align:"center", link.internal:false,
|
||||||
|
* indent:0) versus the git-derived doc (engine-style: defaults emitted as
|
||||||
|
* explicit null, no block ids). An unchanged resync must apply 0 ops.
|
||||||
|
*/
|
||||||
|
describe('git-sync reconcile is idempotent through the real toYdoc materialization', () => {
|
||||||
|
const liveContent = [
|
||||||
|
{
|
||||||
|
type: 'paragraph',
|
||||||
|
attrs: { id: 'p1' },
|
||||||
|
content: [
|
||||||
|
{
|
||||||
|
type: 'text',
|
||||||
|
text: 'click here',
|
||||||
|
marks: [{ type: 'link', attrs: { href: 'https://example.com' } }],
|
||||||
|
},
|
||||||
|
],
|
||||||
|
},
|
||||||
|
{ type: 'image', attrs: { src: 'https://img.example.com/a.png' } },
|
||||||
|
{
|
||||||
|
type: 'paragraph',
|
||||||
|
attrs: { id: 'p2' },
|
||||||
|
content: [
|
||||||
|
{
|
||||||
|
type: 'text',
|
||||||
|
text: 'hot',
|
||||||
|
marks: [{ type: 'highlight', attrs: { color: '#ffd43b' } }],
|
||||||
|
},
|
||||||
|
],
|
||||||
|
},
|
||||||
|
];
|
||||||
|
|
||||||
|
// git/engine-style: explicit nulls for the engine-default attrs, no ids.
|
||||||
|
const gitContent = [
|
||||||
|
{
|
||||||
|
type: 'paragraph',
|
||||||
|
content: [
|
||||||
|
{
|
||||||
|
type: 'text',
|
||||||
|
text: 'click here',
|
||||||
|
marks: [
|
||||||
|
{
|
||||||
|
type: 'link',
|
||||||
|
attrs: {
|
||||||
|
href: 'https://example.com',
|
||||||
|
target: '_blank',
|
||||||
|
rel: 'noopener noreferrer nofollow',
|
||||||
|
class: null,
|
||||||
|
title: null,
|
||||||
|
internal: null,
|
||||||
|
},
|
||||||
|
},
|
||||||
|
],
|
||||||
|
},
|
||||||
|
],
|
||||||
|
},
|
||||||
|
{
|
||||||
|
type: 'image',
|
||||||
|
attrs: { src: 'https://img.example.com/a.png', align: null },
|
||||||
|
},
|
||||||
|
{
|
||||||
|
type: 'paragraph',
|
||||||
|
content: [
|
||||||
|
{
|
||||||
|
type: 'text',
|
||||||
|
text: 'hot',
|
||||||
|
marks: [
|
||||||
|
{ type: 'highlight', attrs: { color: '#ffd43b', colorName: null } },
|
||||||
|
],
|
||||||
|
},
|
||||||
|
],
|
||||||
|
},
|
||||||
|
];
|
||||||
|
|
||||||
|
const toYdoc = (content: unknown[]) =>
|
||||||
|
TiptapTransformer.toYdoc(
|
||||||
|
{ type: 'doc', content },
|
||||||
|
'default',
|
||||||
|
tiptapExtensions as any,
|
||||||
|
);
|
||||||
|
|
||||||
|
it('3-way: materialized-default live vs engine-style git, base stale-by-one -> 0 ops', () => {
|
||||||
|
const liveDoc = toYdoc(liveContent);
|
||||||
|
const targetDoc = toYdoc(gitContent);
|
||||||
|
const baseDoc = toYdoc(gitContent.slice(0, gitContent.length - 1));
|
||||||
|
|
||||||
|
const live = liveDoc.getXmlFragment('default');
|
||||||
|
const before = live.toArray().length;
|
||||||
|
let applied = -1;
|
||||||
|
liveDoc.transact(() => {
|
||||||
|
applied = mergeXmlFragments3Way(
|
||||||
|
live,
|
||||||
|
targetDoc.getXmlFragment('default'),
|
||||||
|
baseDoc.getXmlFragment('default'),
|
||||||
|
);
|
||||||
|
});
|
||||||
|
|
||||||
|
expect(applied).toBe(0);
|
||||||
|
expect(live.toArray().length).toBe(before);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('2-way: materialized-default live vs engine-style git -> 0 ops', () => {
|
||||||
|
const liveDoc = toYdoc(liveContent);
|
||||||
|
const targetDoc = toYdoc(gitContent);
|
||||||
|
|
||||||
|
const live = liveDoc.getXmlFragment('default');
|
||||||
|
const before = live.toArray().length;
|
||||||
|
let applied = -1;
|
||||||
|
liveDoc.transact(() => {
|
||||||
|
applied = mergeXmlFragments(live, targetDoc.getXmlFragment('default'));
|
||||||
|
});
|
||||||
|
|
||||||
|
expect(applied).toBe(0);
|
||||||
|
expect(live.toArray().length).toBe(before);
|
||||||
|
});
|
||||||
|
});
|
||||||
@@ -0,0 +1,373 @@
|
|||||||
|
import * as Y from 'yjs';
|
||||||
|
|
||||||
|
import {
|
||||||
|
mergeXmlFragments,
|
||||||
|
mergeXmlFragments3Way,
|
||||||
|
mergeXmlFragments3WayWithStats,
|
||||||
|
cloneXmlNode,
|
||||||
|
diffBlocks,
|
||||||
|
} from './yjs-body-merge';
|
||||||
|
|
||||||
|
// Build a Y.XmlFragment('default') in `doc` from a list of paragraph specs.
|
||||||
|
// Each spec is the paragraph's plain text (a single XmlText child).
|
||||||
|
function buildFragment(doc: Y.Doc, paragraphs: string[]): Y.XmlFragment {
|
||||||
|
const frag = doc.getXmlFragment('default');
|
||||||
|
const blocks = paragraphs.map((text) => {
|
||||||
|
const el = new Y.XmlElement('paragraph');
|
||||||
|
const t = new Y.XmlText();
|
||||||
|
if (text) t.insert(0, text);
|
||||||
|
el.insert(0, [t]);
|
||||||
|
return el;
|
||||||
|
});
|
||||||
|
if (blocks.length) frag.insert(0, blocks);
|
||||||
|
return frag;
|
||||||
|
}
|
||||||
|
|
||||||
|
function texts(frag: Y.XmlFragment): string[] {
|
||||||
|
return frag.toArray().map((el) => (el as Y.XmlElement).toArray()
|
||||||
|
.map((c) => (c as Y.XmlText).toString())
|
||||||
|
.join(''));
|
||||||
|
}
|
||||||
|
|
||||||
|
describe('yjs-body-merge', () => {
|
||||||
|
describe('diffBlocks (LCS edit script)', () => {
|
||||||
|
it('identical sequences produce only keeps (no edits)', () => {
|
||||||
|
const ops = diffBlocks(['a', 'b', 'c'], ['a', 'b', 'c']);
|
||||||
|
expect(ops.every((o) => o.op === 'keep')).toBe(true);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('a single changed middle element is one del + one ins', () => {
|
||||||
|
const ops = diffBlocks(['a', 'b', 'c'], ['a', 'B', 'c']);
|
||||||
|
expect(ops.filter((o) => o.op === 'del')).toHaveLength(1);
|
||||||
|
expect(ops.filter((o) => o.op === 'ins')).toHaveLength(1);
|
||||||
|
expect(ops.filter((o) => o.op === 'keep')).toHaveLength(2);
|
||||||
|
});
|
||||||
|
});
|
||||||
|
|
||||||
|
describe('mergeXmlFragments', () => {
|
||||||
|
it('identical content is a complete no-op (0 ops) — never clobbers an unchanged resync', () => {
|
||||||
|
const live = new Y.Doc();
|
||||||
|
const target = new Y.Doc();
|
||||||
|
const liveFrag = buildFragment(live, ['one', 'two', 'three']);
|
||||||
|
const targetFrag = buildFragment(target, ['one', 'two', 'three']);
|
||||||
|
|
||||||
|
// Capture block identities to prove they are left untouched.
|
||||||
|
const before = liveFrag.toArray();
|
||||||
|
let applied = -1;
|
||||||
|
live.transact(() => {
|
||||||
|
applied = mergeXmlFragments(liveFrag, targetFrag);
|
||||||
|
});
|
||||||
|
|
||||||
|
expect(applied).toBe(0);
|
||||||
|
// Same Y.XmlElement instances — nothing was deleted/recreated.
|
||||||
|
expect(liveFrag.toArray()).toEqual(before);
|
||||||
|
expect(texts(liveFrag)).toEqual(['one', 'two', 'three']);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('a human edit to one block survives a git change to a DIFFERENT block', () => {
|
||||||
|
// Live: the human has the doc open; block 0 holds their edit. Git changed
|
||||||
|
// only block 2. The merge must touch ONLY block 2 and leave block 0 (and
|
||||||
|
// its in-flight edit) exactly as-is.
|
||||||
|
const live = new Y.Doc();
|
||||||
|
const target = new Y.Doc();
|
||||||
|
const liveFrag = buildFragment(live, ['HUMAN EDIT', 'shared', 'old tail']);
|
||||||
|
const targetFrag = buildFragment(target, [
|
||||||
|
'HUMAN EDIT',
|
||||||
|
'shared',
|
||||||
|
'new tail from git',
|
||||||
|
]);
|
||||||
|
|
||||||
|
const block0Before = liveFrag.get(0); // the human's block instance
|
||||||
|
const block1Before = liveFrag.get(1);
|
||||||
|
|
||||||
|
let applied = -1;
|
||||||
|
live.transact(() => {
|
||||||
|
applied = mergeXmlFragments(liveFrag, targetFrag);
|
||||||
|
});
|
||||||
|
|
||||||
|
// Only block 2 was replaced: one del + one ins.
|
||||||
|
expect(applied).toBe(2);
|
||||||
|
// The human's block and the shared block are the SAME instances (untouched).
|
||||||
|
expect(liveFrag.get(0)).toBe(block0Before);
|
||||||
|
expect(liveFrag.get(1)).toBe(block1Before);
|
||||||
|
// Block 2 now carries git's content.
|
||||||
|
expect(texts(liveFrag)).toEqual([
|
||||||
|
'HUMAN EDIT',
|
||||||
|
'shared',
|
||||||
|
'new tail from git',
|
||||||
|
]);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('appends a new trailing block without disturbing existing ones', () => {
|
||||||
|
const live = new Y.Doc();
|
||||||
|
const target = new Y.Doc();
|
||||||
|
const liveFrag = buildFragment(live, ['a', 'b']);
|
||||||
|
const targetFrag = buildFragment(target, ['a', 'b', 'c']);
|
||||||
|
const a = liveFrag.get(0);
|
||||||
|
const b = liveFrag.get(1);
|
||||||
|
|
||||||
|
let applied = -1;
|
||||||
|
live.transact(() => {
|
||||||
|
applied = mergeXmlFragments(liveFrag, targetFrag);
|
||||||
|
});
|
||||||
|
|
||||||
|
expect(applied).toBe(1); // single insert
|
||||||
|
expect(liveFrag.get(0)).toBe(a);
|
||||||
|
expect(liveFrag.get(1)).toBe(b);
|
||||||
|
expect(texts(liveFrag)).toEqual(['a', 'b', 'c']);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('deletes a removed block, keeping its neighbours', () => {
|
||||||
|
const live = new Y.Doc();
|
||||||
|
const target = new Y.Doc();
|
||||||
|
const liveFrag = buildFragment(live, ['a', 'b', 'c']);
|
||||||
|
const targetFrag = buildFragment(target, ['a', 'c']);
|
||||||
|
const a = liveFrag.get(0);
|
||||||
|
|
||||||
|
let applied = -1;
|
||||||
|
live.transact(() => {
|
||||||
|
applied = mergeXmlFragments(liveFrag, targetFrag);
|
||||||
|
});
|
||||||
|
|
||||||
|
expect(applied).toBe(1); // single delete
|
||||||
|
expect(liveFrag.get(0)).toBe(a);
|
||||||
|
expect(texts(liveFrag)).toEqual(['a', 'c']);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('a fully different body is replaced (and stays valid)', () => {
|
||||||
|
const live = new Y.Doc();
|
||||||
|
const target = new Y.Doc();
|
||||||
|
const liveFrag = buildFragment(live, ['x', 'y']);
|
||||||
|
const targetFrag = buildFragment(target, ['p', 'q', 'r']);
|
||||||
|
live.transact(() => mergeXmlFragments(liveFrag, targetFrag));
|
||||||
|
expect(texts(liveFrag)).toEqual(['p', 'q', 'r']);
|
||||||
|
});
|
||||||
|
});
|
||||||
|
|
||||||
|
describe('mergeXmlFragments3Way', () => {
|
||||||
|
it('keeps a human edit to one block while applying a git change to another (3-way)', () => {
|
||||||
|
// base (last synced): [a, b, c]. Human edited block 0 in the live doc; git
|
||||||
|
// changed block 2 in the incoming file. 3-way must keep BOTH — the 2-way
|
||||||
|
// merge would instead revert the human's block 0 to git's stale version.
|
||||||
|
const base = new Y.Doc();
|
||||||
|
const live = new Y.Doc();
|
||||||
|
const target = new Y.Doc();
|
||||||
|
const baseFrag = buildFragment(base, ['a', 'b', 'c']);
|
||||||
|
const liveFrag = buildFragment(live, ['HUMAN', 'b', 'c']);
|
||||||
|
const targetFrag = buildFragment(target, ['a', 'b', 'GIT']);
|
||||||
|
|
||||||
|
const humanBlock = liveFrag.get(0); // the human's live instance
|
||||||
|
live.transact(() =>
|
||||||
|
mergeXmlFragments3Way(liveFrag, targetFrag, baseFrag),
|
||||||
|
);
|
||||||
|
|
||||||
|
// Human's block preserved as the SAME instance; git's change applied.
|
||||||
|
expect(liveFrag.get(0)).toBe(humanBlock);
|
||||||
|
expect(texts(liveFrag)).toEqual(['HUMAN', 'b', 'GIT']);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('a block both sides changed resolves to git (conflict policy)', () => {
|
||||||
|
const base = new Y.Doc();
|
||||||
|
const live = new Y.Doc();
|
||||||
|
const target = new Y.Doc();
|
||||||
|
const baseFrag = buildFragment(base, ['a', 'b', 'c']);
|
||||||
|
const liveFrag = buildFragment(live, ['a', 'HUMAN', 'c']);
|
||||||
|
const targetFrag = buildFragment(target, ['a', 'GIT', 'c']);
|
||||||
|
|
||||||
|
live.transact(() =>
|
||||||
|
mergeXmlFragments3Way(liveFrag, targetFrag, baseFrag),
|
||||||
|
);
|
||||||
|
expect(texts(liveFrag)).toEqual(['a', 'GIT', 'c']);
|
||||||
|
});
|
||||||
|
|
||||||
|
// Bug #2 observability: the stats variant reports the same-block conflict so
|
||||||
|
// the handler can log it + the persistence layer can pin the human baseline.
|
||||||
|
it('reports the same-block conflict count via mergeXmlFragments3WayWithStats', () => {
|
||||||
|
const base = new Y.Doc();
|
||||||
|
const live = new Y.Doc();
|
||||||
|
const target = new Y.Doc();
|
||||||
|
const baseFrag = buildFragment(base, ['a', 'b', 'c']);
|
||||||
|
const liveFrag = buildFragment(live, ['a', 'HUMAN', 'c']);
|
||||||
|
const targetFrag = buildFragment(target, ['a', 'GIT', 'c']);
|
||||||
|
|
||||||
|
let result!: { applied: number; conflicts: number };
|
||||||
|
live.transact(() => {
|
||||||
|
result = mergeXmlFragments3WayWithStats(liveFrag, targetFrag, baseFrag);
|
||||||
|
});
|
||||||
|
expect(result.conflicts).toBe(1);
|
||||||
|
expect(texts(liveFrag)).toEqual(['a', 'GIT', 'c']);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('reports 0 conflicts for a clean different-block 3-way merge', () => {
|
||||||
|
const base = new Y.Doc();
|
||||||
|
const live = new Y.Doc();
|
||||||
|
const target = new Y.Doc();
|
||||||
|
const baseFrag = buildFragment(base, ['a', 'b', 'c']);
|
||||||
|
const liveFrag = buildFragment(live, ['HUMAN', 'b', 'c']);
|
||||||
|
const targetFrag = buildFragment(target, ['a', 'b', 'GIT']);
|
||||||
|
|
||||||
|
let result!: { applied: number; conflicts: number };
|
||||||
|
live.transact(() => {
|
||||||
|
result = mergeXmlFragments3WayWithStats(liveFrag, targetFrag, baseFrag);
|
||||||
|
});
|
||||||
|
expect(result.conflicts).toBe(0);
|
||||||
|
expect(texts(liveFrag)).toEqual(['HUMAN', 'b', 'GIT']);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('git change with no concurrent human edit (live == base) applies cleanly', () => {
|
||||||
|
const base = new Y.Doc();
|
||||||
|
const live = new Y.Doc();
|
||||||
|
const target = new Y.Doc();
|
||||||
|
const baseFrag = buildFragment(base, ['a', 'b']);
|
||||||
|
const liveFrag = buildFragment(live, ['a', 'b']);
|
||||||
|
const targetFrag = buildFragment(target, ['a', 'B2']);
|
||||||
|
|
||||||
|
live.transact(() =>
|
||||||
|
mergeXmlFragments3Way(liveFrag, targetFrag, baseFrag),
|
||||||
|
);
|
||||||
|
expect(texts(liveFrag)).toEqual(['a', 'B2']);
|
||||||
|
});
|
||||||
|
});
|
||||||
|
|
||||||
|
// Regression: start-of-document content duplicating on every two-way sync.
|
||||||
|
//
|
||||||
|
// The LIVE Docmost doc stamps a per-block UniqueID on every heading/paragraph;
|
||||||
|
// a body arriving FROM git is parsed from clean markdown and carries NO block
|
||||||
|
// ids. If the merge comparison key includes that `id`, an unchanged live block
|
||||||
|
// never matches the SAME block coming from git, so the three-way merge cannot
|
||||||
|
// anchor on it — and an incoming block with no anchor (content inserted at the
|
||||||
|
// TOP of the page) is RE-ADDED on every cycle, an unbounded duplication loop.
|
||||||
|
// These tests model that exact id-asymmetry and assert the reconciliation is
|
||||||
|
// IDEMPOTENT (no block growth). They are RED before excluding `id` from the
|
||||||
|
// key in `serializeXmlNode`.
|
||||||
|
describe('idempotent reconciliation with live block ids (start-of-doc dup)', () => {
|
||||||
|
// Build a fragment from block specs. `id` is set only when provided, mirroring
|
||||||
|
// the live doc (ids present) vs a git-parsed body (ids absent).
|
||||||
|
type Spec = { tag: 'heading' | 'paragraph'; text: string; id?: string };
|
||||||
|
function buildDoc(doc: Y.Doc, specs: Spec[]): Y.XmlFragment {
|
||||||
|
const frag = doc.getXmlFragment('default');
|
||||||
|
const blocks = specs.map((s) => {
|
||||||
|
const el = new Y.XmlElement(s.tag);
|
||||||
|
if (s.id) el.setAttribute('id', s.id);
|
||||||
|
if (s.tag === 'heading') el.setAttribute('level', '2');
|
||||||
|
const t = new Y.XmlText();
|
||||||
|
if (s.text) t.insert(0, s.text);
|
||||||
|
el.insert(0, [t]);
|
||||||
|
return el;
|
||||||
|
});
|
||||||
|
if (blocks.length) frag.insert(0, blocks);
|
||||||
|
return frag;
|
||||||
|
}
|
||||||
|
const textsOf = (frag: Y.XmlFragment): string[] =>
|
||||||
|
frag.toArray().map((el) =>
|
||||||
|
(el as Y.XmlElement)
|
||||||
|
.toArray()
|
||||||
|
.map((c) => (c as Y.XmlText).toString())
|
||||||
|
.join(''),
|
||||||
|
);
|
||||||
|
|
||||||
|
it('re-merging the SAME git body does NOT re-add the top block (idempotent)', () => {
|
||||||
|
// last-synced base (from git markdown): NO block ids.
|
||||||
|
const base = new Y.Doc();
|
||||||
|
const baseFrag = buildDoc(base, [
|
||||||
|
{ tag: 'heading', text: 'Title' },
|
||||||
|
{ tag: 'paragraph', text: 'Some paragraph.' },
|
||||||
|
{ tag: 'paragraph', text: 'End block.' },
|
||||||
|
]);
|
||||||
|
// live Docmost doc: SAME content, but every block carries a UniqueID.
|
||||||
|
const live = new Y.Doc();
|
||||||
|
const liveFrag = buildDoc(live, [
|
||||||
|
{ tag: 'heading', text: 'Title', id: 'ida' },
|
||||||
|
{ tag: 'paragraph', text: 'Some paragraph.', id: 'idb' },
|
||||||
|
{ tag: 'paragraph', text: 'End block.', id: 'idc' },
|
||||||
|
]);
|
||||||
|
// incoming git body: the user inserted a heading at the very TOP.
|
||||||
|
const buildTarget = (): Y.XmlFragment =>
|
||||||
|
buildDoc(new Y.Doc(), [
|
||||||
|
{ tag: 'heading', text: 'TOPDUP' },
|
||||||
|
{ tag: 'heading', text: 'Title' },
|
||||||
|
{ tag: 'paragraph', text: 'Some paragraph.' },
|
||||||
|
{ tag: 'paragraph', text: 'End block.' },
|
||||||
|
]);
|
||||||
|
|
||||||
|
// First sync: the top block is added once.
|
||||||
|
live.transact(() =>
|
||||||
|
mergeXmlFragments3Way(liveFrag, buildTarget(), baseFrag),
|
||||||
|
);
|
||||||
|
expect(textsOf(liveFrag)).toEqual([
|
||||||
|
'TOPDUP',
|
||||||
|
'Title',
|
||||||
|
'Some paragraph.',
|
||||||
|
'End block.',
|
||||||
|
]);
|
||||||
|
|
||||||
|
// Subsequent sync of the SAME git body against the SAME base must be a
|
||||||
|
// NO-OP — not a second copy of the top block. Before the fix this re-adds
|
||||||
|
// 'TOPDUP', growing the doc on every cycle.
|
||||||
|
live.transact(() =>
|
||||||
|
mergeXmlFragments3Way(liveFrag, buildTarget(), baseFrag),
|
||||||
|
);
|
||||||
|
expect(textsOf(liveFrag)).toEqual([
|
||||||
|
'TOPDUP',
|
||||||
|
'Title',
|
||||||
|
'Some paragraph.',
|
||||||
|
'End block.',
|
||||||
|
]);
|
||||||
|
expect(textsOf(liveFrag).filter((t) => t === 'TOPDUP')).toHaveLength(1);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('an unchanged git body (live ids, none in git) is a complete no-op', () => {
|
||||||
|
// base == git body (no pending git change); live is the same content with
|
||||||
|
// ids. With `id` in the key the whole body looks rewritten; the merge must
|
||||||
|
// still leave live byte-identical (block instances untouched).
|
||||||
|
const base = new Y.Doc();
|
||||||
|
const baseFrag = buildDoc(base, [
|
||||||
|
{ tag: 'heading', text: 'Title' },
|
||||||
|
{ tag: 'paragraph', text: 'Body.' },
|
||||||
|
]);
|
||||||
|
const live = new Y.Doc();
|
||||||
|
const liveFrag = buildDoc(live, [
|
||||||
|
{ tag: 'heading', text: 'Title', id: 'ida' },
|
||||||
|
{ tag: 'paragraph', text: 'Body.', id: 'idb' },
|
||||||
|
]);
|
||||||
|
const before = liveFrag.toArray();
|
||||||
|
let applied = -1;
|
||||||
|
live.transact(() => {
|
||||||
|
applied = mergeXmlFragments3Way(
|
||||||
|
liveFrag,
|
||||||
|
buildDoc(new Y.Doc(), [
|
||||||
|
{ tag: 'heading', text: 'Title' },
|
||||||
|
{ tag: 'paragraph', text: 'Body.' },
|
||||||
|
]),
|
||||||
|
baseFrag,
|
||||||
|
);
|
||||||
|
});
|
||||||
|
expect(applied).toBe(0);
|
||||||
|
// Same live block instances (ids preserved) — nothing recreated.
|
||||||
|
expect(liveFrag.toArray()).toEqual(before);
|
||||||
|
});
|
||||||
|
});
|
||||||
|
|
||||||
|
describe('cloneXmlNode', () => {
|
||||||
|
it('preserves text marks (XmlText delta) across docs', () => {
|
||||||
|
const src = new Y.Doc();
|
||||||
|
const srcFrag = src.getXmlFragment('default');
|
||||||
|
const el = new Y.XmlElement('paragraph');
|
||||||
|
const t = new Y.XmlText();
|
||||||
|
t.insert(0, 'plain ');
|
||||||
|
t.insert(6, 'bold', { bold: true });
|
||||||
|
el.insert(0, [t]);
|
||||||
|
srcFrag.insert(0, [el]);
|
||||||
|
|
||||||
|
const dst = new Y.Doc();
|
||||||
|
const dstFrag = dst.getXmlFragment('default');
|
||||||
|
dstFrag.insert(0, [cloneXmlNode(srcFrag.get(0) as Y.XmlElement)]);
|
||||||
|
|
||||||
|
const clonedText = (dstFrag.get(0) as Y.XmlElement).get(0) as Y.XmlText;
|
||||||
|
expect(clonedText.toDelta()).toEqual([
|
||||||
|
{ insert: 'plain ' },
|
||||||
|
{ insert: 'bold', attributes: { bold: true } },
|
||||||
|
]);
|
||||||
|
});
|
||||||
|
});
|
||||||
|
});
|
||||||
@@ -0,0 +1,371 @@
|
|||||||
|
import * as Y from 'yjs';
|
||||||
|
import { getSchema } from '@tiptap/core';
|
||||||
|
import type { Schema } from '@tiptap/pm/model';
|
||||||
|
|
||||||
|
import { tiptapExtensions } from '../collaboration.util';
|
||||||
|
import { diff3PlanWithConflicts } from './three-way-merge';
|
||||||
|
import { buildLcsTable } from './lcs';
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Block-level merge of an incoming (git) page body into a LIVE Yjs document,
|
||||||
|
* replacing the previous full-body "delete everything + re-insert" write that
|
||||||
|
* clobbered concurrent human edits on every sync (review #5 — "do the write as a
|
||||||
|
* merge").
|
||||||
|
*
|
||||||
|
* Strategy: diff the two documents at TOP-LEVEL BLOCK granularity (an LCS over a
|
||||||
|
* canonical structural serialization of each block) and apply only the minimal
|
||||||
|
* insert/delete operations. Blocks that are byte-identical on both sides are
|
||||||
|
* left UNTOUCHED in the live doc — so a human editing one paragraph is unaffected
|
||||||
|
* when git changes a different paragraph, and an unchanged re-sync is a complete
|
||||||
|
* no-op (zero Yjs operations). Yjs then CRDT-merges the minimal ops with any
|
||||||
|
* concurrent edits.
|
||||||
|
*
|
||||||
|
* Merge mode: a THREE-WAY merge (live vs incoming vs base) runs whenever the
|
||||||
|
* engine plumbs the last-synced base (`baseMarkdown` from refs/docmost/last-pushed)
|
||||||
|
* — which it now does end-to-end — so a block both sides changed is a genuine
|
||||||
|
* conflict resolved deterministically (git wins that block; the prior state is
|
||||||
|
* preserved in page history). Only when NO base is available (a brand-new file)
|
||||||
|
* does it fall back to a 2-way merge (live vs incoming). Common cases — unchanged
|
||||||
|
* resync and edits to DIFFERENT blocks — are lossless in both modes.
|
||||||
|
*/
|
||||||
|
|
||||||
|
type XmlNode = Y.XmlElement | Y.XmlText | Y.XmlHook;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Node attributes that are VOLATILE identity (not content) and so must be
|
||||||
|
* excluded from the block comparison key.
|
||||||
|
*
|
||||||
|
* `id` is the per-block UniqueID the editor stamps on every heading/paragraph
|
||||||
|
* (and transclusionSource). It exists ONLY in the live Yjs document — a body
|
||||||
|
* arriving from git is parsed from clean markdown, which carries no block ids
|
||||||
|
* (`markdownToProseMirror` materializes `id: null`, which the Yjs transform then
|
||||||
|
* drops). If `id` were part of the key, an UNCHANGED live block (id "abc123")
|
||||||
|
* would never match the SAME block coming from git (no id), so the three-way
|
||||||
|
* merge's LCS could not anchor on it. The merge would then treat every live
|
||||||
|
* block as deleted-and-reinserted and, when an incoming block has no matching
|
||||||
|
* anchor (e.g. content inserted at the very TOP of the page), RE-ADD a copy of
|
||||||
|
* it on every sync cycle — a non-convergent, unbounded duplication loop
|
||||||
|
* (start-of-document content duplicating each push/pull cycle).
|
||||||
|
*
|
||||||
|
* Excluding `id` makes blocks compare by CONTENT, so an unchanged block matches
|
||||||
|
* across the git round-trip and the reconciliation is idempotent. Block identity
|
||||||
|
* is still preserved in the merged output: `diff3Plan` keeps the LIVE block
|
||||||
|
* INSTANCE (with its id) for an anchor — picks are by index, not by key — so the
|
||||||
|
* stable Yjs block (and any in-flight human edit on it) stays put. This mirrors
|
||||||
|
* `canonicalize.ts`, which already strips the regenerated block `id` from the
|
||||||
|
* round-trip idempotency comparison for exactly the same reason.
|
||||||
|
*
|
||||||
|
* Known limitation (accepted trade-off of content-based matching): two GENUINELY
|
||||||
|
* DISTINCT blocks whose content is byte-identical now collapse to the same content
|
||||||
|
* key, so when git deletes one of the duplicates the LCS may drop the OTHER live
|
||||||
|
* instance instead. The visible result is identical (one copy removed, one kept),
|
||||||
|
* but a concurrent in-flight human edit on the dropped instance could be lost.
|
||||||
|
*/
|
||||||
|
const VOLATILE_KEY_ATTRS = new Set(['id']);
|
||||||
|
|
||||||
|
/**
|
||||||
|
* The editor (ProseMirror) schema, built ONCE from the same `tiptapExtensions`
|
||||||
|
* the collaboration server uses to materialize Yjs docs. Memoized: building the
|
||||||
|
* schema is non-trivial and the block key is computed per block per cycle.
|
||||||
|
*
|
||||||
|
* Why the schema (not a hardcoded denylist): the LIVE Yjs document is produced by
|
||||||
|
* `TiptapTransformer.toYdoc(pm, 'default', tiptapExtensions)`, which STAMPS every
|
||||||
|
* schema-default attribute onto every node and mark — `indent: 0` on every
|
||||||
|
* paragraph/heading, `image.align: "center"`, the link mark's `internal: false`,
|
||||||
|
* `highlight.colorName: null`, and so on for youtube/pdf/any future node. A body
|
||||||
|
* re-imported from git comes through the engine's `markdownToProseMirror`, whose
|
||||||
|
* schema declares those attrs with DIFFERENT (usually null) defaults; the
|
||||||
|
* resulting null/absent element attrs are then DROPPED by `y-prosemirror`'s
|
||||||
|
* toYdoc. So the SAME block carries materialized defaults on the live side and
|
||||||
|
* nothing on the git side, its key diverges, the three-way merge anchors on
|
||||||
|
* NOTHING, and the whole body is RE-APPENDED every reconcile cycle — an unbounded
|
||||||
|
* duplication loop with no client connected.
|
||||||
|
*
|
||||||
|
* Deriving the defaults from the actual schema normalizes ALL such attributes
|
||||||
|
* generally (it is not another per-attribute denylist): any attribute whose value
|
||||||
|
* equals the schema default — or is null/undefined — is dropped from the key, on
|
||||||
|
* BOTH element attributes and the mark attributes inside each XmlText delta, so a
|
||||||
|
* live block compares equal to its git-round-tripped twin and an unchanged resync
|
||||||
|
* applies zero ops. Genuinely non-default values (a real `indent: 2`, an
|
||||||
|
* `align: "left"`, a real `link.href`, a real highlight color) are content and
|
||||||
|
* stay in the key, so real edits still diff and land.
|
||||||
|
*/
|
||||||
|
let memoSchema: Schema | null = null;
|
||||||
|
let memoSchemaTried = false;
|
||||||
|
function getMergeSchema(): Schema | null {
|
||||||
|
if (!memoSchemaTried) {
|
||||||
|
memoSchemaTried = true;
|
||||||
|
try {
|
||||||
|
memoSchema = getSchema(tiptapExtensions as any);
|
||||||
|
} catch {
|
||||||
|
// Defensive: if the schema can't be built (e.g. a degenerate extension
|
||||||
|
// set in a unit test that stubs `tiptapExtensions`), fall back to dropping
|
||||||
|
// only null/undefined attrs. The real server always builds it fine.
|
||||||
|
memoSchema = null;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
return memoSchema;
|
||||||
|
}
|
||||||
|
|
||||||
|
/** True if `value` is the schema default for `attrName` of `attrSpecs`, or is
|
||||||
|
* null/undefined (which a git round-trip drops). Such attributes are excluded
|
||||||
|
* from the comparison key. `attrSpecs` is a ProseMirror node/mark spec attr map
|
||||||
|
* (`{ [name]: { default } }`); a missing map (unknown node/mark) only drops
|
||||||
|
* null/undefined. (A non-null value matching an attr declared without a default
|
||||||
|
* cannot occur — `spec.default === value` is then `undefined === value`, false.) */
|
||||||
|
function isDefaultAttr(
|
||||||
|
attrSpecs: Record<string, any> | undefined | null,
|
||||||
|
attrName: string,
|
||||||
|
value: unknown,
|
||||||
|
): boolean {
|
||||||
|
if (value === null || value === undefined) return true;
|
||||||
|
const spec = attrSpecs?.[attrName];
|
||||||
|
return !!spec && spec.default === value;
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Normalize one XmlText delta op's mark attributes: drop every mark-attr whose
|
||||||
|
* value equals the mark's schema default (or is null/undefined), so the link
|
||||||
|
* mark's materialized `internal: false`/`target: "_blank"` and a highlight's
|
||||||
|
* `colorName: null` no longer diverge from a git round-trip that carries neither.
|
||||||
|
* The text (op.insert) and genuinely-set mark attrs (a real `href`, a real
|
||||||
|
* highlight color) are preserved verbatim. `attributes` maps markName -> mark
|
||||||
|
* attrs object (or `true`/boolean for attr-less marks); each is handled safely.
|
||||||
|
*/
|
||||||
|
function normalizeDelta(delta: any[]): any[] {
|
||||||
|
const schema = getMergeSchema();
|
||||||
|
return delta.map((op) => {
|
||||||
|
if (!op || op.attributes == null || typeof op.attributes !== 'object') {
|
||||||
|
return op;
|
||||||
|
}
|
||||||
|
const marks: Record<string, unknown> = {};
|
||||||
|
for (const markName of Object.keys(op.attributes).sort()) {
|
||||||
|
const markVal = op.attributes[markName];
|
||||||
|
if (markVal === null || markVal === undefined) continue;
|
||||||
|
if (typeof markVal !== 'object') {
|
||||||
|
// attr-less mark stored as a primitive (e.g. `true`) — keep as-is.
|
||||||
|
marks[markName] = markVal;
|
||||||
|
continue;
|
||||||
|
}
|
||||||
|
const markSpec = schema?.marks[markName]?.spec.attrs as
|
||||||
|
| Record<string, any>
|
||||||
|
| undefined;
|
||||||
|
const cleaned: Record<string, unknown> = {};
|
||||||
|
for (const ak of Object.keys(markVal as object).sort()) {
|
||||||
|
const av = (markVal as Record<string, unknown>)[ak];
|
||||||
|
if (isDefaultAttr(markSpec, ak, av)) continue;
|
||||||
|
cleaned[ak] = av;
|
||||||
|
}
|
||||||
|
marks[markName] = cleaned;
|
||||||
|
}
|
||||||
|
return { ...op, attributes: marks };
|
||||||
|
});
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Canonical, comparable serialization of a Yjs XML node (structure + text +
|
||||||
|
* marks + attributes), with attribute keys sorted so equal blocks always produce
|
||||||
|
* an identical string regardless of attribute insertion order. The volatile
|
||||||
|
* block `id` (see `VOLATILE_KEY_ATTRS`) and every schema-default attribute (see
|
||||||
|
* `getMergeSchema`) are excluded at every level — on element attributes AND on
|
||||||
|
* the mark attributes inside each XmlText delta — so a block compares equal by
|
||||||
|
* CONTENT across the git round-trip (which materializes neither), keeping the
|
||||||
|
* merge anchor-able and idempotent.
|
||||||
|
*/
|
||||||
|
export function serializeXmlNode(node: unknown): unknown {
|
||||||
|
if (node instanceof Y.XmlText) {
|
||||||
|
return { t: normalizeDelta(node.toDelta()) };
|
||||||
|
}
|
||||||
|
if (node instanceof Y.XmlElement) {
|
||||||
|
const attrs = node.getAttributes() as Record<string, unknown>;
|
||||||
|
const attrSpecs = getMergeSchema()?.nodes[node.nodeName]?.spec.attrs as
|
||||||
|
| Record<string, any>
|
||||||
|
| undefined;
|
||||||
|
const sorted: Record<string, unknown> = {};
|
||||||
|
for (const k of Object.keys(attrs).sort()) {
|
||||||
|
if (VOLATILE_KEY_ATTRS.has(k)) continue;
|
||||||
|
if (isDefaultAttr(attrSpecs, k, attrs[k])) continue;
|
||||||
|
sorted[k] = attrs[k];
|
||||||
|
}
|
||||||
|
return {
|
||||||
|
n: node.nodeName,
|
||||||
|
a: sorted,
|
||||||
|
c: node.toArray().map(serializeXmlNode),
|
||||||
|
};
|
||||||
|
}
|
||||||
|
// XmlHook / unknown: fall back to a stable string so it compares by identity
|
||||||
|
// of its serialized form (these do not occur in the Docmost block schema).
|
||||||
|
return { u: String(node) };
|
||||||
|
}
|
||||||
|
|
||||||
|
const key = (node: unknown): string => JSON.stringify(serializeXmlNode(node));
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Deep-clone a detached/owned Yjs XML node into a fresh node that can be inserted
|
||||||
|
* into ANOTHER document (Yjs types are bound to their doc, so cross-doc moves are
|
||||||
|
* impossible — we rebuild). Preserves nodeName, attributes, text+marks (via the
|
||||||
|
* XmlText delta) and the full child subtree.
|
||||||
|
*/
|
||||||
|
export function cloneXmlNode(node: XmlNode): Y.XmlElement | Y.XmlText {
|
||||||
|
if (node instanceof Y.XmlText) {
|
||||||
|
const t = new Y.XmlText();
|
||||||
|
const delta = node.toDelta();
|
||||||
|
if (delta.length) t.applyDelta(delta);
|
||||||
|
return t;
|
||||||
|
}
|
||||||
|
if (node instanceof Y.XmlElement) {
|
||||||
|
const el = new Y.XmlElement(node.nodeName);
|
||||||
|
const attrs = node.getAttributes() as Record<string, unknown>;
|
||||||
|
for (const k of Object.keys(attrs)) el.setAttribute(k, attrs[k] as string);
|
||||||
|
const kids = node.toArray().map((c) => cloneXmlNode(c as XmlNode));
|
||||||
|
if (kids.length) el.insert(0, kids);
|
||||||
|
return el;
|
||||||
|
}
|
||||||
|
// Best-effort for any other node type (XmlHook — does not occur in the
|
||||||
|
// Docmost block schema): an empty paragraph so the merge never crashes.
|
||||||
|
return new Y.XmlElement('paragraph');
|
||||||
|
}
|
||||||
|
|
||||||
|
type Op = { op: 'keep' } | { op: 'del' } | { op: 'ins'; bi: number };
|
||||||
|
|
||||||
|
/**
|
||||||
|
* LCS-based edit script turning sequence `a` (live block keys) into `b` (incoming
|
||||||
|
* block keys): a run of keep/del/ins ops. O(n*m) table — fine for page block
|
||||||
|
* counts.
|
||||||
|
*/
|
||||||
|
export function diffBlocks(a: string[], b: string[]): Op[] {
|
||||||
|
const n = a.length;
|
||||||
|
const m = b.length;
|
||||||
|
const dp = buildLcsTable(a, b);
|
||||||
|
const ops: Op[] = [];
|
||||||
|
let i = 0;
|
||||||
|
let j = 0;
|
||||||
|
while (i < n && j < m) {
|
||||||
|
if (a[i] === b[j]) {
|
||||||
|
ops.push({ op: 'keep' });
|
||||||
|
i++;
|
||||||
|
j++;
|
||||||
|
} else if (dp[i + 1][j] >= dp[i][j + 1]) {
|
||||||
|
ops.push({ op: 'del' });
|
||||||
|
i++;
|
||||||
|
} else {
|
||||||
|
ops.push({ op: 'ins', bi: j });
|
||||||
|
j++;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
while (i < n) {
|
||||||
|
ops.push({ op: 'del' });
|
||||||
|
i++;
|
||||||
|
}
|
||||||
|
while (j < m) {
|
||||||
|
ops.push({ op: 'ins', bi: j });
|
||||||
|
j++;
|
||||||
|
}
|
||||||
|
return ops;
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Merge `target` block children into `live`, mutating `live` in place with the
|
||||||
|
* minimal set of inserts/deletes. MUST be called inside a Yjs transaction.
|
||||||
|
* Returns the number of block operations applied (0 == content already identical).
|
||||||
|
*/
|
||||||
|
export function mergeXmlFragments(
|
||||||
|
live: Y.XmlFragment,
|
||||||
|
target: Y.XmlFragment,
|
||||||
|
): number {
|
||||||
|
const liveKids = live.toArray();
|
||||||
|
const targetKids = target.toArray();
|
||||||
|
const liveKeys = liveKids.map(key);
|
||||||
|
const targetKeys = targetKids.map(key);
|
||||||
|
|
||||||
|
const ops = diffBlocks(liveKeys, targetKeys);
|
||||||
|
|
||||||
|
let cursor = 0; // index into the LIVE fragment as we mutate it
|
||||||
|
let applied = 0;
|
||||||
|
for (const op of ops) {
|
||||||
|
if (op.op === 'keep') {
|
||||||
|
cursor++;
|
||||||
|
} else if (op.op === 'del') {
|
||||||
|
live.delete(cursor, 1); // remove the live block at the cursor; do not advance
|
||||||
|
applied++;
|
||||||
|
} else {
|
||||||
|
live.insert(cursor, [cloneXmlNode(targetKids[op.bi] as XmlNode)]);
|
||||||
|
cursor++;
|
||||||
|
applied++;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
return applied;
|
||||||
|
}
|
||||||
|
|
||||||
|
/** Outcome of a 3-way block merge: ops applied + same-block conflict count. */
|
||||||
|
export interface Merge3WayResult {
|
||||||
|
/** Number of block insert/delete operations spliced into `live`. */
|
||||||
|
applied: number;
|
||||||
|
/**
|
||||||
|
* Regions where the human AND git rewrote the SAME base block. The rule is
|
||||||
|
* deterministic (GIT WINS the region), so the human's version of those blocks
|
||||||
|
* is dropped from the live doc. `conflicts > 0` is the OBSERVABLE signal the
|
||||||
|
* caller uses to LOG the loss and pin the human baseline to page history (so it
|
||||||
|
* is recoverable), instead of the edit vanishing silently.
|
||||||
|
*/
|
||||||
|
conflicts: number;
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* THREE-WAY block merge: reconcile `live` toward `target` using `base` (the
|
||||||
|
* last-synced common ancestor) so a block only the human changed is KEPT and a
|
||||||
|
* block only git changed is taken — instead of git's version always winning
|
||||||
|
* (review #5). Conflicts (both changed the same block) resolve to git.
|
||||||
|
*
|
||||||
|
* Implementation: diff3Plan computes the merged block ORDER (picks from live or
|
||||||
|
* target); we materialize that as a virtual target fragment and reuse the 2-way
|
||||||
|
* `mergeXmlFragments` to splice it into `live` minimally (so untouched live block
|
||||||
|
* instances — and their in-flight edits — stay put). MUST be called inside a Yjs
|
||||||
|
* transaction. Returns the number of block operations applied. (Use
|
||||||
|
* `mergeXmlFragments3WayWithStats` when the SAME-BLOCK conflict count is needed.)
|
||||||
|
*/
|
||||||
|
export function mergeXmlFragments3Way(
|
||||||
|
live: Y.XmlFragment,
|
||||||
|
target: Y.XmlFragment,
|
||||||
|
base: Y.XmlFragment,
|
||||||
|
): number {
|
||||||
|
return mergeXmlFragments3WayWithStats(live, target, base).applied;
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* As `mergeXmlFragments3Way`, but also returns the SAME-BLOCK conflict count so
|
||||||
|
* the caller can make a "git won a concurrent same-block edit" event OBSERVABLE
|
||||||
|
* (the documented conflict contract: git wins deterministically, but the losing
|
||||||
|
* human content is never destroyed silently — it is logged and recoverable via
|
||||||
|
* page history).
|
||||||
|
*/
|
||||||
|
export function mergeXmlFragments3WayWithStats(
|
||||||
|
live: Y.XmlFragment,
|
||||||
|
target: Y.XmlFragment,
|
||||||
|
base: Y.XmlFragment,
|
||||||
|
): Merge3WayResult {
|
||||||
|
const liveKids = live.toArray();
|
||||||
|
const targetKids = target.toArray();
|
||||||
|
const liveKeys = liveKids.map(key);
|
||||||
|
const targetKeys = targetKids.map(key);
|
||||||
|
const baseKeys = base.toArray().map(key);
|
||||||
|
|
||||||
|
const { picks: plan, conflicts } = diff3PlanWithConflicts(
|
||||||
|
baseKeys,
|
||||||
|
liveKeys,
|
||||||
|
targetKeys,
|
||||||
|
);
|
||||||
|
|
||||||
|
// Build the merged block sequence in a throwaway doc, cloning from whichever
|
||||||
|
// side each pick came from, then 2-way merge it back into the live fragment.
|
||||||
|
const merged = new Y.Doc();
|
||||||
|
const mergedFrag = merged.getXmlFragment('default');
|
||||||
|
const nodes = plan.map((p) =>
|
||||||
|
cloneXmlNode(
|
||||||
|
(p.src === 'live' ? liveKids[p.index] : targetKids[p.index]) as XmlNode,
|
||||||
|
),
|
||||||
|
);
|
||||||
|
if (nodes.length) mergedFrag.insert(0, nodes);
|
||||||
|
|
||||||
|
return { applied: mergeXmlFragments(live, mergedFrag), conflicts };
|
||||||
|
}
|
||||||
@@ -0,0 +1,144 @@
|
|||||||
|
import { getSchema } from '@tiptap/core';
|
||||||
|
import { Schema } from '@tiptap/pm/model';
|
||||||
|
import { tiptapExtensions } from './collaboration.util';
|
||||||
|
// The canonical converter mirror's extension set. The schema mirror now lives in
|
||||||
|
// the single `@docmost/prosemirror-markdown` package (#293); the server jest
|
||||||
|
// config maps it to the package SOURCE (moduleNameMapper
|
||||||
|
// `^@docmost/prosemirror-markdown$`), so this reads the real mirror, not a build.
|
||||||
|
import { docmostExtensions as gitSyncExtensions } from '@docmost/prosemirror-markdown';
|
||||||
|
|
||||||
|
/**
|
||||||
|
* ATTRIBUTE-LEVEL SCHEMA CONTRACT (review #293, variant A).
|
||||||
|
*
|
||||||
|
* The document schema exists as three hand-synced copies (editor-ext =
|
||||||
|
* source-of-truth, plus the git-sync and mcp converter mirrors). The existing
|
||||||
|
* `schema-editor-ext-contract.test.ts` compares only node/mark TYPE NAMES, so a
|
||||||
|
* NEW ATTRIBUTE added to an existing node upstream slips through and its value is
|
||||||
|
* silently dropped on every git-sync round trip. That is a repeatedly-hit
|
||||||
|
* data-loss class (image caption #221, paragraph alignment #10, details `open`).
|
||||||
|
*
|
||||||
|
* This test closes the attribute gap MECHANICALLY: it builds the real canonical
|
||||||
|
* schema from the server's `tiptapExtensions` (the same set the collab write path
|
||||||
|
* uses) and the git-sync mirror schema, then asserts that for every node/mark the
|
||||||
|
* two schemas share, their ATTRIBUTE-KEY sets are equal — minus a committed
|
||||||
|
* allowlist of intentional, understood divergences. A forgotten attribute now
|
||||||
|
* fails CI loudly instead of losing data in production.
|
||||||
|
*
|
||||||
|
* WHY THIS ISN'T THE "fragile attribute compare" the sibling name-level contract
|
||||||
|
* (`packages/git-sync/test/schema-editor-ext-contract.test.ts`) deferred: that
|
||||||
|
* concern was about comparing raw extension CONFIGS, where editor-ext spreads
|
||||||
|
* global attributes (textAlign, id, …) across separate extensions and StarterKit
|
||||||
|
* contributes types the mirror gets elsewhere. We instead compare the RESOLVED
|
||||||
|
* ProseMirror `Schema` objects — `getSchema()` has already merged every
|
||||||
|
* addGlobalAttributes spread into concrete per-node attrs on both sides — so the
|
||||||
|
* compare is apples-to-apples (57 shared nodes/marks, only a handful of
|
||||||
|
* documented divergences) rather than config-shape noise.
|
||||||
|
*/
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Intentional, understood attribute divergences between the canonical schema and
|
||||||
|
* the git-sync mirror. Each entry MUST carry a reason. The test asserts the
|
||||||
|
* allowlist is not stale (every listed attr is actually still divergent), so this
|
||||||
|
* cannot rot into a silent escape hatch.
|
||||||
|
*
|
||||||
|
* Shape: { [nodeOrMarkName]: { canonicalOnly?: string[]; mirrorOnly?: string[] } }
|
||||||
|
*/
|
||||||
|
const ALLOWED_DIVERGENCES: Record<
|
||||||
|
string,
|
||||||
|
{ canonicalOnly?: string[]; mirrorOnly?: string[] }
|
||||||
|
> = {
|
||||||
|
// mirrorOnly: the converter mirror carries `align` on table cells/headers so a
|
||||||
|
// GFM column-alignment marker (:--, :-:, --:) can be reconstructed on export;
|
||||||
|
// editor-ext expresses cell alignment differently. Intentional, round-trip-used.
|
||||||
|
tableCell: { mirrorOnly: ['align'] },
|
||||||
|
tableHeader: { mirrorOnly: ['align'] },
|
||||||
|
// youtube: the mirror adds `align` (media alignment it renders as data-align)
|
||||||
|
// and does NOT carry editor-ext's `start` (video start-time). `start` is a
|
||||||
|
// PRE-EXISTING gap (a youtube embed's start offset is not preserved across a
|
||||||
|
// markdown round trip) — documented here so the contract is green for the known
|
||||||
|
// state and RED for any NEW drift. Follow-up: carry `start` through the mirror.
|
||||||
|
youtube: { mirrorOnly: ['align'], canonicalOnly: ['start'] },
|
||||||
|
// image.title: the mirror carries a `title` attr (used to round-trip the
|
||||||
|
// markdown image title ``) that editor-ext does not declare
|
||||||
|
// on its image node. Mirror-only and round-trip-used, not data loss. Intentional.
|
||||||
|
image: { mirrorOnly: ['title'] },
|
||||||
|
// highlight.colorName (a named-color alias alongside the color value) is a
|
||||||
|
// PRE-EXISTING mirror gap; the color value itself round-trips. Documented.
|
||||||
|
highlight: { canonicalOnly: ['colorName'] },
|
||||||
|
};
|
||||||
|
|
||||||
|
function attrKeys(schema: Schema): Map<string, Set<string>> {
|
||||||
|
const out = new Map<string, Set<string>>();
|
||||||
|
for (const [name, type] of Object.entries(schema.nodes)) {
|
||||||
|
out.set(name, new Set(Object.keys((type.spec as any).attrs ?? {})));
|
||||||
|
}
|
||||||
|
for (const [name, type] of Object.entries(schema.marks)) {
|
||||||
|
out.set(name, new Set(Object.keys((type.spec as any).attrs ?? {})));
|
||||||
|
}
|
||||||
|
return out;
|
||||||
|
}
|
||||||
|
|
||||||
|
function diff(a: Set<string>, b: Set<string>): string[] {
|
||||||
|
return [...a].filter((x) => !b.has(x)).sort();
|
||||||
|
}
|
||||||
|
|
||||||
|
describe('schema attribute contract: git-sync mirror vs canonical editor-ext', () => {
|
||||||
|
const canonical = attrKeys(getSchema(tiptapExtensions as never));
|
||||||
|
const mirror = attrKeys(getSchema(gitSyncExtensions as never));
|
||||||
|
|
||||||
|
it('builds meaningful schemas (guard against a vacuous pass)', () => {
|
||||||
|
expect(canonical.size).toBeGreaterThan(10);
|
||||||
|
expect(mirror.size).toBeGreaterThan(10);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('every shared node/mark has matching attribute keys (modulo the allowlist)', () => {
|
||||||
|
const drift: string[] = [];
|
||||||
|
for (const [name, canonAttrs] of canonical) {
|
||||||
|
const mirrorAttrs = mirror.get(name);
|
||||||
|
if (!mirrorAttrs) continue; // name-level gaps are the other test's job
|
||||||
|
const allow = ALLOWED_DIVERGENCES[name] ?? {};
|
||||||
|
const canonicalOnly = diff(canonAttrs, mirrorAttrs).filter(
|
||||||
|
(k) => !(allow.canonicalOnly ?? []).includes(k),
|
||||||
|
);
|
||||||
|
const mirrorOnly = diff(mirrorAttrs, canonAttrs).filter(
|
||||||
|
(k) => !(allow.mirrorOnly ?? []).includes(k),
|
||||||
|
);
|
||||||
|
if (canonicalOnly.length) {
|
||||||
|
drift.push(
|
||||||
|
`${name}: attrs in editor-ext but MISSING from git-sync mirror ` +
|
||||||
|
`(silently dropped on round trip): ${canonicalOnly.join(', ')}`,
|
||||||
|
);
|
||||||
|
}
|
||||||
|
if (mirrorOnly.length) {
|
||||||
|
drift.push(
|
||||||
|
`${name}: attrs in git-sync mirror but NOT in editor-ext ` +
|
||||||
|
`(mirror invented an attribute): ${mirrorOnly.join(', ')}`,
|
||||||
|
);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
expect(drift).toEqual([]);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('the allowlist is not stale (every listed divergence is still real)', () => {
|
||||||
|
const stale: string[] = [];
|
||||||
|
for (const [name, allow] of Object.entries(ALLOWED_DIVERGENCES)) {
|
||||||
|
const canonAttrs = canonical.get(name);
|
||||||
|
const mirrorAttrs = mirror.get(name);
|
||||||
|
if (!canonAttrs || !mirrorAttrs) {
|
||||||
|
stale.push(`${name}: no longer a shared node/mark`);
|
||||||
|
continue;
|
||||||
|
}
|
||||||
|
for (const k of allow.canonicalOnly ?? []) {
|
||||||
|
if (!(canonAttrs.has(k) && !mirrorAttrs.has(k))) {
|
||||||
|
stale.push(`${name}.canonicalOnly '${k}' is no longer divergent`);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
for (const k of allow.mirrorOnly ?? []) {
|
||||||
|
if (!(mirrorAttrs.has(k) && !canonAttrs.has(k))) {
|
||||||
|
stale.push(`${name}.mirrorOnly '${k}' is no longer divergent`);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
expect(stale).toEqual([]);
|
||||||
|
});
|
||||||
|
});
|
||||||
@@ -73,6 +73,32 @@ describe('agentSourceFields', () => {
|
|||||||
).toEqual({ lastUpdatedSource: 'agent', lastUpdatedAiChatId: null });
|
).toEqual({ lastUpdatedSource: 'agent', lastUpdatedAiChatId: null });
|
||||||
});
|
});
|
||||||
|
|
||||||
|
it("stamps ONLY the source column 'git-sync' (no chat key) for a git-sync write", () => {
|
||||||
|
// The git-sync data plane (issue #194 §8.1) has no internal ai_chats row, so
|
||||||
|
// it stamps the *Source column 'git-sync' and OMITS the chat key entirely
|
||||||
|
// (unlike the agent branch, which also writes aiChatId). Pinned directly here
|
||||||
|
// because the page.service.spec only exercises it indirectly.
|
||||||
|
expect(
|
||||||
|
agentSourceFields(
|
||||||
|
{ actor: 'git-sync', aiChatId: null },
|
||||||
|
'lastUpdatedSource',
|
||||||
|
'lastUpdatedAiChatId',
|
||||||
|
),
|
||||||
|
).toEqual({ lastUpdatedSource: 'git-sync' });
|
||||||
|
});
|
||||||
|
|
||||||
|
it("ignores any aiChatId on a git-sync write (chat key never written)", () => {
|
||||||
|
// Even if a non-null aiChatId is present, the git-sync branch must not emit
|
||||||
|
// the chat key.
|
||||||
|
expect(
|
||||||
|
agentSourceFields(
|
||||||
|
{ actor: 'git-sync', aiChatId: 'should-be-ignored' },
|
||||||
|
'createdSource',
|
||||||
|
'aiChatId',
|
||||||
|
),
|
||||||
|
).toEqual({ createdSource: 'git-sync' });
|
||||||
|
});
|
||||||
|
|
||||||
it('returns {} for a user write so the column keeps its default', () => {
|
it('returns {} for a user write so the column keeps its default', () => {
|
||||||
expect(
|
expect(
|
||||||
agentSourceFields(
|
agentSourceFields(
|
||||||
|
|||||||
@@ -9,6 +9,8 @@ import { ProvenanceSource } from '../../core/auth/dto/jwt-payload';
|
|||||||
* cannot fake an 'agent' marker.
|
* cannot fake an 'agent' marker.
|
||||||
*/
|
*/
|
||||||
export interface AuthProvenanceData {
|
export interface AuthProvenanceData {
|
||||||
|
// ProvenanceSource includes 'git-sync' — set by the in-process git-sync data
|
||||||
|
// plane (issue #194 §8.1) when it drives PageService writes; never from a request token.
|
||||||
actor: ProvenanceSource;
|
actor: ProvenanceSource;
|
||||||
aiChatId: string | null;
|
aiChatId: string | null;
|
||||||
}
|
}
|
||||||
@@ -60,6 +62,14 @@ export function agentSourceFields<S extends string, C extends string>(
|
|||||||
sourceKey: S,
|
sourceKey: S,
|
||||||
chatKey: C,
|
chatKey: C,
|
||||||
): Partial<Record<S, ProvenanceSource> & Record<C, string | null>> {
|
): Partial<Record<S, ProvenanceSource> & Record<C, string | null>> {
|
||||||
|
// git-sync data-plane write (issue #194 §8.1): stamp the source 'git-sync' with NO
|
||||||
|
// aiChatId (it has no internal ai_chats row). Mirrors the agent branch; each
|
||||||
|
// write has a single actor, so precedence is irrelevant here.
|
||||||
|
if (provenance?.actor === 'git-sync') {
|
||||||
|
return { [sourceKey]: 'git-sync' } as Partial<
|
||||||
|
Record<S, ProvenanceSource> & Record<C, string | null>
|
||||||
|
>;
|
||||||
|
}
|
||||||
if (provenance?.actor !== 'agent') return {};
|
if (provenance?.actor !== 'agent') return {};
|
||||||
return {
|
return {
|
||||||
[sourceKey]: 'agent',
|
[sourceKey]: 'agent',
|
||||||
|
|||||||
@@ -0,0 +1,18 @@
|
|||||||
|
/**
|
||||||
|
* Dynamic ESM import bridge for a CommonJS build.
|
||||||
|
*
|
||||||
|
* The server compiles with `module: commonjs`, and TypeScript downlevels a
|
||||||
|
* literal `import()` expression to `require()` — which cannot load an ESM-only
|
||||||
|
* package (`@docmost/mcp`, `@docmost/git-sync`). Indirecting through `new
|
||||||
|
* Function` hides the `import()` from the TS downleveler so the REAL dynamic
|
||||||
|
* `import()` survives to runtime and can load ESM from CommonJS.
|
||||||
|
*
|
||||||
|
* This is the single shared copy of that bridge. The per-package typed loaders
|
||||||
|
* (git-sync.loader.ts, docmost-client.loader.ts, mcp.service.ts) import this and
|
||||||
|
* keep their own typed `loadX()` wrappers (require.resolve + pathToFileURL +
|
||||||
|
* memoization) on top.
|
||||||
|
*/
|
||||||
|
export const esmImport = new Function(
|
||||||
|
'specifier',
|
||||||
|
'return import(specifier)',
|
||||||
|
) as (specifier: string) => Promise<unknown>;
|
||||||
@@ -0,0 +1,71 @@
|
|||||||
|
import { resolveRequestWorkspace } from './resolve-request-workspace';
|
||||||
|
|
||||||
|
// Unit tests for the shared self-hosted/cloud workspace resolver deduplicated out
|
||||||
|
// of DomainMiddleware + GitHttpService (architecture #11). They must behave
|
||||||
|
// identically, so this pins the single source of truth.
|
||||||
|
|
||||||
|
type AnyMock = jest.Mock;
|
||||||
|
|
||||||
|
function build(opts: {
|
||||||
|
selfHosted: boolean;
|
||||||
|
first?: { id: string } | null;
|
||||||
|
byHostname?: { id: string } | null;
|
||||||
|
}) {
|
||||||
|
const env = {
|
||||||
|
isSelfHosted: jest.fn(() => opts.selfHosted),
|
||||||
|
isCloud: jest.fn(() => !opts.selfHosted),
|
||||||
|
};
|
||||||
|
const repo = {
|
||||||
|
findFirst: jest.fn(async () => opts.first ?? null) as AnyMock,
|
||||||
|
findByHostname: jest.fn(async () => opts.byHostname ?? null) as AnyMock,
|
||||||
|
};
|
||||||
|
return { env, repo };
|
||||||
|
}
|
||||||
|
|
||||||
|
describe('resolveRequestWorkspace', () => {
|
||||||
|
it('self-hosted: returns the first/default workspace, ignoring the host', async () => {
|
||||||
|
const { env, repo } = build({ selfHosted: true, first: { id: 'ws-1' } });
|
||||||
|
const ws = await resolveRequestWorkspace(
|
||||||
|
env as any,
|
||||||
|
repo as any,
|
||||||
|
'anything.example.com',
|
||||||
|
);
|
||||||
|
expect(ws).toEqual({ id: 'ws-1' });
|
||||||
|
expect(repo.findFirst).toHaveBeenCalledTimes(1);
|
||||||
|
expect(repo.findByHostname).not.toHaveBeenCalled();
|
||||||
|
});
|
||||||
|
|
||||||
|
it('self-hosted: returns null when no workspace is configured', async () => {
|
||||||
|
const { env, repo } = build({ selfHosted: true, first: null });
|
||||||
|
expect(await resolveRequestWorkspace(env as any, repo as any, 'h')).toBeNull();
|
||||||
|
});
|
||||||
|
|
||||||
|
it('cloud: resolves by the host-header subdomain', async () => {
|
||||||
|
const { env, repo } = build({
|
||||||
|
selfHosted: false,
|
||||||
|
byHostname: { id: 'ws-acme' },
|
||||||
|
});
|
||||||
|
const ws = await resolveRequestWorkspace(
|
||||||
|
env as any,
|
||||||
|
repo as any,
|
||||||
|
'acme.example.com',
|
||||||
|
);
|
||||||
|
expect(ws).toEqual({ id: 'ws-acme' });
|
||||||
|
expect(repo.findByHostname).toHaveBeenCalledWith('acme');
|
||||||
|
expect(repo.findFirst).not.toHaveBeenCalled();
|
||||||
|
});
|
||||||
|
|
||||||
|
it('cloud: returns null for a blank/missing host (no throw)', async () => {
|
||||||
|
const { env, repo } = build({ selfHosted: false, byHostname: { id: 'x' } });
|
||||||
|
expect(await resolveRequestWorkspace(env as any, repo as any, undefined)).toBeNull();
|
||||||
|
expect(await resolveRequestWorkspace(env as any, repo as any, '')).toBeNull();
|
||||||
|
expect(repo.findByHostname).not.toHaveBeenCalled();
|
||||||
|
});
|
||||||
|
|
||||||
|
it('cloud: returns null when the subdomain matches no workspace', async () => {
|
||||||
|
const { env, repo } = build({ selfHosted: false, byHostname: null });
|
||||||
|
expect(
|
||||||
|
await resolveRequestWorkspace(env as any, repo as any, 'ghost.example.com'),
|
||||||
|
).toBeNull();
|
||||||
|
});
|
||||||
|
});
|
||||||
@@ -0,0 +1,35 @@
|
|||||||
|
import { WorkspaceRepo } from '@docmost/db/repos/workspace/workspace.repo';
|
||||||
|
import { Workspace } from '@docmost/db/types/entity.types';
|
||||||
|
import { EnvironmentService } from '../../integrations/environment/environment.service';
|
||||||
|
|
||||||
|
/**
|
||||||
|
* The ONE canonical way to resolve the workspace for an incoming request:
|
||||||
|
* - self-hosted (single workspace) -> the first/default workspace;
|
||||||
|
* - cloud (multi-tenant) -> resolved by the host-header subdomain.
|
||||||
|
* Returns null when none resolves (no workspace configured, or a blank/unknown
|
||||||
|
* subdomain on cloud). `isSelfHosted()` is `!isCloud()`, so exactly one branch is
|
||||||
|
* always taken.
|
||||||
|
*
|
||||||
|
* Extracted so the self-hosted/cloud branch is not hand-duplicated. Shared by
|
||||||
|
* `DomainMiddleware` (the normal /api request path) and `GitHttpService` (the raw
|
||||||
|
* root-mounted /git smart-HTTP host, which Nest middleware does NOT run for) so
|
||||||
|
* the two cannot drift.
|
||||||
|
*
|
||||||
|
* This helper does NOT catch DB errors — callers decide: DomainMiddleware lets a
|
||||||
|
* throw bubble (as before); GitHttpService wraps it to log + treat as
|
||||||
|
* unresolvable (-> 404). A blank/missing host on cloud resolves to null rather
|
||||||
|
* than throwing.
|
||||||
|
*/
|
||||||
|
export async function resolveRequestWorkspace(
|
||||||
|
environmentService: EnvironmentService,
|
||||||
|
workspaceRepo: WorkspaceRepo,
|
||||||
|
hostHeader: string | undefined,
|
||||||
|
): Promise<Workspace | null> {
|
||||||
|
if (environmentService.isSelfHosted()) {
|
||||||
|
return (await workspaceRepo.findFirst()) ?? null;
|
||||||
|
}
|
||||||
|
// Cloud (isSelfHosted === !isCloud, so this is the only remaining branch).
|
||||||
|
const subdomain = hostHeader ? hostHeader.split('.')[0] : '';
|
||||||
|
if (!subdomain) return null;
|
||||||
|
return (await workspaceRepo.findByHostname(subdomain)) ?? null;
|
||||||
|
}
|
||||||
@@ -1,7 +1,8 @@
|
|||||||
import { Injectable, NestMiddleware, NotFoundException } from '@nestjs/common';
|
import { Injectable, NestMiddleware } from '@nestjs/common';
|
||||||
import { FastifyRequest, FastifyReply } from 'fastify';
|
import { FastifyRequest, FastifyReply } from 'fastify';
|
||||||
import { EnvironmentService } from '../../integrations/environment/environment.service';
|
import { EnvironmentService } from '../../integrations/environment/environment.service';
|
||||||
import { WorkspaceRepo } from '@docmost/db/repos/workspace/workspace.repo';
|
import { WorkspaceRepo } from '@docmost/db/repos/workspace/workspace.repo';
|
||||||
|
import { resolveRequestWorkspace } from '../helpers/resolve-request-workspace';
|
||||||
|
|
||||||
@Injectable()
|
@Injectable()
|
||||||
export class DomainMiddleware implements NestMiddleware {
|
export class DomainMiddleware implements NestMiddleware {
|
||||||
@@ -14,30 +15,19 @@ export class DomainMiddleware implements NestMiddleware {
|
|||||||
res: FastifyReply['raw'],
|
res: FastifyReply['raw'],
|
||||||
next: () => void,
|
next: () => void,
|
||||||
) {
|
) {
|
||||||
if (this.environmentService.isSelfHosted()) {
|
// Shared self-hosted/cloud resolution (the SAME branch the /git host uses),
|
||||||
const workspace = await this.workspaceRepo.findFirst();
|
// so the logic cannot drift between the two.
|
||||||
if (!workspace) {
|
const workspace = await resolveRequestWorkspace(
|
||||||
//throw new NotFoundException('Workspace not found');
|
this.environmentService,
|
||||||
(req as any).workspaceId = null;
|
this.workspaceRepo,
|
||||||
return next();
|
req.headers.host,
|
||||||
}
|
);
|
||||||
|
|
||||||
// TODO: unify
|
|
||||||
(req as any).workspaceId = workspace.id;
|
|
||||||
(req as any).workspace = workspace;
|
|
||||||
} else if (this.environmentService.isCloud()) {
|
|
||||||
const header = req.headers.host;
|
|
||||||
const subdomain = header.split('.')[0];
|
|
||||||
|
|
||||||
const workspace = await this.workspaceRepo.findByHostname(subdomain);
|
|
||||||
|
|
||||||
if (!workspace) {
|
|
||||||
(req as any).workspaceId = null;
|
|
||||||
return next();
|
|
||||||
}
|
|
||||||
|
|
||||||
|
if (workspace) {
|
||||||
(req as any).workspaceId = workspace.id;
|
(req as any).workspaceId = workspace.id;
|
||||||
(req as any).workspace = workspace;
|
(req as any).workspace = workspace;
|
||||||
|
} else {
|
||||||
|
(req as any).workspaceId = null;
|
||||||
}
|
}
|
||||||
|
|
||||||
next();
|
next();
|
||||||
|
|||||||
@@ -1,329 +0,0 @@
|
|||||||
import { Injectable, Logger, OnModuleDestroy } from '@nestjs/common';
|
|
||||||
|
|
||||||
/**
|
|
||||||
* In-memory run-stream registry (#184 phase 1.5). A durable agent run tees its
|
|
||||||
* SSE frames here (via `pipeUIMessageStreamToResponse({ consumeSseStream })`)
|
|
||||||
* so a LATE tab — one that reloaded, or opened after the starter dropped — can
|
|
||||||
* attach through `GET /ai-chat/runs/:chatId/stream`, replay the frames buffered
|
|
||||||
* so far, and then follow the live tail as a normal streamer.
|
|
||||||
*
|
|
||||||
* This is deliberately single-process and best-effort: it holds nothing the DB
|
|
||||||
* does not (the run + assistant row are the source of truth), so a process
|
|
||||||
* restart simply drops in-flight entries and the client falls back to its
|
|
||||||
* restore + degraded-poll path. The async `attach` return type is the seam for a
|
|
||||||
* future phase-2 cross-process backend (Redis) — the interface does not change.
|
|
||||||
*/
|
|
||||||
|
|
||||||
/** How long a finished entry is retained for late attach (replay + immediate end). */
|
|
||||||
export const RUN_STREAM_RETAIN_FINISHED_MS = 30_000;
|
|
||||||
|
|
||||||
/** Per-run replay buffer cap. Past this the buffer is dropped (attach -> 204). */
|
|
||||||
export const RUN_STREAM_MAX_BUFFER_BYTES = 4 * 1024 * 1024;
|
|
||||||
|
|
||||||
// 2x the replay cap: a just-written 4MB replay burst alone can never trip the
|
|
||||||
// per-subscriber cap (see controller); only a genuinely stalled socket can.
|
|
||||||
export const SUBSCRIBER_MAX_BUFFERED_BYTES = 2 * RUN_STREAM_MAX_BUFFER_BYTES;
|
|
||||||
|
|
||||||
export interface RunStreamCallbacks {
|
|
||||||
onFrame: (frame: string) => void;
|
|
||||||
onEnd: () => void;
|
|
||||||
}
|
|
||||||
|
|
||||||
export interface RunStreamAttachment {
|
|
||||||
replay: string[];
|
|
||||||
finished: boolean;
|
|
||||||
start(): void; // drain pending frames (order preserved) and go live
|
|
||||||
unsubscribe(): void; // safe to call at any point, idempotent
|
|
||||||
}
|
|
||||||
|
|
||||||
interface Subscriber extends RunStreamCallbacks {
|
|
||||||
started: boolean;
|
|
||||||
pending: string[];
|
|
||||||
// Byte size of `pending`, capped at SUBSCRIBER_MAX_BUFFERED_BYTES. `start()` is
|
|
||||||
// called in the SAME tick as `attach()` today (see attach), so `pending` never
|
|
||||||
// holds more than one microtask of frames — but the async `attach` signature is
|
|
||||||
// a phase-2 seam: an await between attach and start would let a stalled paused
|
|
||||||
// subscriber buffer the WHOLE run here. The cap is the structural backstop.
|
|
||||||
pendingBytes: number;
|
|
||||||
overflowed: boolean;
|
|
||||||
pendingEnd: boolean;
|
|
||||||
}
|
|
||||||
|
|
||||||
interface Entry {
|
|
||||||
runId: string;
|
|
||||||
// The persisted assistant row id of this run (set at bind; undefined if the
|
|
||||||
// seed failed). Used by the attach anchor check (invariant 6).
|
|
||||||
assistantMessageId?: string;
|
|
||||||
frames: string[];
|
|
||||||
bytes: number;
|
|
||||||
overflowed: boolean;
|
|
||||||
finished: boolean;
|
|
||||||
subscribers: Set<Subscriber>;
|
|
||||||
retainTimer?: NodeJS.Timeout;
|
|
||||||
}
|
|
||||||
|
|
||||||
@Injectable()
|
|
||||||
export class AiChatStreamRegistryService implements OnModuleDestroy {
|
|
||||||
private readonly logger = new Logger(AiChatStreamRegistryService.name);
|
|
||||||
private readonly entries = new Map<string, Entry>(); // key: chatId
|
|
||||||
|
|
||||||
/**
|
|
||||||
* Register a fresh entry at the START of a run (before any frame), so a tab
|
|
||||||
* that attaches in the begin->seed window finds an entry to wait on. If an
|
|
||||||
* entry already exists for this chat (a previous, possibly still-live run whose
|
|
||||||
* tee loop is draining), it is terminated MIRRORING the done-path (invariant 3)
|
|
||||||
* so its subscribers are released and its retention timer is cleared; a late
|
|
||||||
* `done` from that old tee then fires against the closed-over old reference and,
|
|
||||||
* thanks to identity checks, never touches this new entry.
|
|
||||||
*/
|
|
||||||
open(chatId: string, runId: string): void {
|
|
||||||
const existing = this.entries.get(chatId);
|
|
||||||
if (existing) {
|
|
||||||
if (existing.retainTimer) {
|
|
||||||
clearTimeout(existing.retainTimer);
|
|
||||||
existing.retainTimer = undefined;
|
|
||||||
}
|
|
||||||
// Started subscribers get exactly one onEnd() and are removed; paused ones
|
|
||||||
// are marked pendingEnd (their start() will end them). finished=true guards
|
|
||||||
// any later done from the old tee loop from double-notifying.
|
|
||||||
this.terminateSubscribers(existing);
|
|
||||||
}
|
|
||||||
this.entries.set(chatId, {
|
|
||||||
runId,
|
|
||||||
frames: [],
|
|
||||||
bytes: 0,
|
|
||||||
overflowed: false,
|
|
||||||
finished: false,
|
|
||||||
subscribers: new Set<Subscriber>(),
|
|
||||||
});
|
|
||||||
}
|
|
||||||
|
|
||||||
/**
|
|
||||||
* Tee a run's SSE frame stream into its entry (called from consumeSseStream).
|
|
||||||
* No-op with a warning when there is no entry or the entry belongs to a
|
|
||||||
* different run (invariant 1). The reader loop is fire-and-forget: the tee
|
|
||||||
* branch outlives the client socket by design.
|
|
||||||
*/
|
|
||||||
bind(
|
|
||||||
chatId: string,
|
|
||||||
runId: string,
|
|
||||||
assistantMessageId: string | undefined,
|
|
||||||
stream: ReadableStream<string>,
|
|
||||||
): void {
|
|
||||||
const entry = this.entries.get(chatId);
|
|
||||||
if (!entry || entry.runId !== runId) {
|
|
||||||
// Invariant 1: only the matching run may mutate the entry.
|
|
||||||
this.logger.warn(
|
|
||||||
`bind: no matching run-stream entry for chat=${chatId} run=${runId}`,
|
|
||||||
);
|
|
||||||
return;
|
|
||||||
}
|
|
||||||
entry.assistantMessageId = assistantMessageId;
|
|
||||||
const reader = stream.getReader();
|
|
||||||
const pump = async (): Promise<void> => {
|
|
||||||
try {
|
|
||||||
for (;;) {
|
|
||||||
const { done, value } = await reader.read();
|
|
||||||
if (done) break;
|
|
||||||
this.ingestFrame(entry, value);
|
|
||||||
}
|
|
||||||
this.finalizeEntry(chatId, entry);
|
|
||||||
} catch {
|
|
||||||
// A read error is a terminal event too — release subscribers.
|
|
||||||
this.finalizeEntry(chatId, entry);
|
|
||||||
}
|
|
||||||
};
|
|
||||||
void pump();
|
|
||||||
}
|
|
||||||
|
|
||||||
/**
|
|
||||||
* Terminate a run's entry from the OUTER catch of the stream method (a failure
|
|
||||||
* before/while wiring the pipe, so `done` will never arrive). Identity-checked
|
|
||||||
* on runId (invariant 1); the shared terminal path is idempotent.
|
|
||||||
*/
|
|
||||||
abortEntry(chatId: string, runId: string): void {
|
|
||||||
const entry = this.entries.get(chatId);
|
|
||||||
if (!entry || entry.runId !== runId) return;
|
|
||||||
this.finalizeEntry(chatId, entry);
|
|
||||||
}
|
|
||||||
|
|
||||||
/**
|
|
||||||
* Attach to a run's stream. Async only for the phase-2 Redis seam — the body
|
|
||||||
* runs synchronously so the replay snapshot and the subscriber registration
|
|
||||||
* happen in ONE tick with no await between them (invariant 4): a frame ingested
|
|
||||||
* concurrently cannot slip into the gap and be lost or duplicated.
|
|
||||||
*
|
|
||||||
* Returns null (-> the caller answers 204) when:
|
|
||||||
* - there is no entry, or it overflowed (replay is gone);
|
|
||||||
* - expect=live with an anchor that does not match this run's assistant id
|
|
||||||
* (invariant 6: a stripped tab must never replay a FOREIGN run's transcript);
|
|
||||||
* - the run finished and the caller did not expect a live tail.
|
|
||||||
* A finished run with expect=live yields a replay-only attachment (no
|
|
||||||
* subscriber registered). Otherwise a paused subscriber is registered and the
|
|
||||||
* caller replays `replay`, then calls start() to drain and go live.
|
|
||||||
*/
|
|
||||||
async attach(
|
|
||||||
chatId: string,
|
|
||||||
expectLive: boolean,
|
|
||||||
anchor: string | undefined,
|
|
||||||
cb: RunStreamCallbacks,
|
|
||||||
): Promise<RunStreamAttachment | null> {
|
|
||||||
const entry = this.entries.get(chatId);
|
|
||||||
if (!entry || entry.overflowed) return null;
|
|
||||||
// Invariant 6: cross-run replay is forbidden. Before bind, assistantMessageId
|
|
||||||
// is undefined and mismatches any anchor -> 204 -> client restore+poll path.
|
|
||||||
if (expectLive && anchor && entry.assistantMessageId !== anchor) return null;
|
|
||||||
if (entry.finished && !expectLive) return null;
|
|
||||||
if (entry.finished && expectLive) {
|
|
||||||
// Replay-only: the run is done, no subscriber is registered.
|
|
||||||
return {
|
|
||||||
replay: entry.frames.slice(),
|
|
||||||
finished: true,
|
|
||||||
start: () => undefined,
|
|
||||||
unsubscribe: () => undefined,
|
|
||||||
};
|
|
||||||
}
|
|
||||||
|
|
||||||
const sub: Subscriber = {
|
|
||||||
onFrame: cb.onFrame,
|
|
||||||
onEnd: cb.onEnd,
|
|
||||||
started: false,
|
|
||||||
pending: [],
|
|
||||||
pendingBytes: 0,
|
|
||||||
overflowed: false,
|
|
||||||
pendingEnd: false,
|
|
||||||
};
|
|
||||||
entry.subscribers.add(sub);
|
|
||||||
// Snapshot in the SAME synchronous block as the registration (invariant 4).
|
|
||||||
const replay = entry.frames.slice();
|
|
||||||
// CONTRACT: the caller MUST call start() in the SAME tick as this attach()
|
|
||||||
// returns — no await between them. While a subscriber is paused, every frame
|
|
||||||
// is buffered in sub.pending; a delayed start() lets a whole run accumulate
|
|
||||||
// there. The pendingBytes cap (see ingestFrame) is the structural backstop if
|
|
||||||
// that contract is ever broken (e.g. the phase-2 Redis await seam).
|
|
||||||
return {
|
|
||||||
replay,
|
|
||||||
finished: false,
|
|
||||||
start: () => {
|
|
||||||
if (sub.overflowed) {
|
|
||||||
// The pending buffer overflowed while paused: end the stream instead of
|
|
||||||
// replaying a partial (a 204-equivalent post-attach degrade).
|
|
||||||
try {
|
|
||||||
sub.onEnd();
|
|
||||||
} catch {
|
|
||||||
// The socket is gone; nothing to end.
|
|
||||||
}
|
|
||||||
entry.subscribers.delete(sub);
|
|
||||||
return;
|
|
||||||
}
|
|
||||||
// Deliver frames buffered while paused, in order, then go live.
|
|
||||||
for (const frame of sub.pending) {
|
|
||||||
try {
|
|
||||||
sub.onFrame(frame);
|
|
||||||
} catch {
|
|
||||||
entry.subscribers.delete(sub);
|
|
||||||
return;
|
|
||||||
}
|
|
||||||
}
|
|
||||||
sub.pending = [];
|
|
||||||
sub.started = true;
|
|
||||||
if (sub.pendingEnd) {
|
|
||||||
try {
|
|
||||||
sub.onEnd();
|
|
||||||
} catch {
|
|
||||||
// The socket is gone; nothing to end.
|
|
||||||
}
|
|
||||||
entry.subscribers.delete(sub);
|
|
||||||
}
|
|
||||||
},
|
|
||||||
unsubscribe: () => {
|
|
||||||
entry.subscribers.delete(sub);
|
|
||||||
},
|
|
||||||
};
|
|
||||||
}
|
|
||||||
|
|
||||||
onModuleDestroy(): void {
|
|
||||||
for (const entry of this.entries.values()) {
|
|
||||||
if (entry.retainTimer) clearTimeout(entry.retainTimer);
|
|
||||||
}
|
|
||||||
this.entries.clear();
|
|
||||||
}
|
|
||||||
|
|
||||||
/** Buffer + fan-out a single frame. See invariant/overflow semantics inline. */
|
|
||||||
private ingestFrame(entry: Entry, frame: string): void {
|
|
||||||
entry.bytes += Buffer.byteLength(frame);
|
|
||||||
if (!entry.overflowed) {
|
|
||||||
entry.frames.push(frame);
|
|
||||||
if (entry.bytes > RUN_STREAM_MAX_BUFFER_BYTES) {
|
|
||||||
// The crossing frame was already counted AND (below) fanned out; only the
|
|
||||||
// replay buffer is dropped. After overflow no more frames are buffered,
|
|
||||||
// but live fan-out continues.
|
|
||||||
entry.overflowed = true;
|
|
||||||
entry.frames = [];
|
|
||||||
this.logger.warn(
|
|
||||||
`run-stream buffer overflow for run=${entry.runId}; ` +
|
|
||||||
`late attach will 204 until the run ends`,
|
|
||||||
);
|
|
||||||
}
|
|
||||||
}
|
|
||||||
for (const sub of entry.subscribers) {
|
|
||||||
if (sub.started) {
|
|
||||||
try {
|
|
||||||
sub.onFrame(frame);
|
|
||||||
} catch {
|
|
||||||
entry.subscribers.delete(sub);
|
|
||||||
}
|
|
||||||
} else {
|
|
||||||
sub.pending.push(frame);
|
|
||||||
sub.pendingBytes += Buffer.byteLength(frame);
|
|
||||||
if (sub.pendingBytes > SUBSCRIBER_MAX_BUFFERED_BYTES) {
|
|
||||||
// The paused subscriber's buffer overflowed — only possible if start()
|
|
||||||
// was delayed past the same-tick contract (the phase-2 await seam).
|
|
||||||
// Drop it rather than buffer the whole run; on start() it degrades to an
|
|
||||||
// immediate end (a 204-equivalent) instead of replaying a partial.
|
|
||||||
sub.overflowed = true;
|
|
||||||
sub.pending = [];
|
|
||||||
entry.subscribers.delete(sub);
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
/**
|
|
||||||
* Shared terminal path for done / read-error / external-abort. Idempotent: a
|
|
||||||
* second call (already finished) is a no-op, so an open()-replaced or
|
|
||||||
* abort-then-done entry is never double-armed or double-ended.
|
|
||||||
*/
|
|
||||||
private finalizeEntry(chatId: string, entry: Entry): void {
|
|
||||||
if (entry.finished) return;
|
|
||||||
this.terminateSubscribers(entry);
|
|
||||||
const timer = setTimeout(() => {
|
|
||||||
// Invariant 2: only delete OUR entry (a replacement may already own the key).
|
|
||||||
if (this.entries.get(chatId) === entry) this.entries.delete(chatId);
|
|
||||||
}, RUN_STREAM_RETAIN_FINISHED_MS);
|
|
||||||
timer.unref?.();
|
|
||||||
entry.retainTimer = timer;
|
|
||||||
}
|
|
||||||
|
|
||||||
/**
|
|
||||||
* Mark the entry finished and release its subscribers, mirroring the done-path:
|
|
||||||
* started subscribers get exactly one onEnd() and are removed; paused ones are
|
|
||||||
* flagged pendingEnd so their start() ends them. Deleting the current element
|
|
||||||
* during Set iteration is safe.
|
|
||||||
*/
|
|
||||||
private terminateSubscribers(entry: Entry): void {
|
|
||||||
entry.finished = true;
|
|
||||||
for (const sub of entry.subscribers) {
|
|
||||||
if (sub.started) {
|
|
||||||
try {
|
|
||||||
sub.onEnd();
|
|
||||||
} catch {
|
|
||||||
// The socket is gone; nothing to end.
|
|
||||||
}
|
|
||||||
entry.subscribers.delete(sub);
|
|
||||||
} else {
|
|
||||||
sub.pendingEnd = true;
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
@@ -1,388 +0,0 @@
|
|||||||
import {
|
|
||||||
AiChatStreamRegistryService,
|
|
||||||
RUN_STREAM_MAX_BUFFER_BYTES,
|
|
||||||
RUN_STREAM_RETAIN_FINISHED_MS,
|
|
||||||
RunStreamCallbacks,
|
|
||||||
} from './ai-chat-stream-registry.service';
|
|
||||||
|
|
||||||
/**
|
|
||||||
* Unit tests for the in-memory run-stream registry (#184 phase 1.5). The registry
|
|
||||||
* is the whole of the resumable-transport contract: replay ordering, paused ->
|
|
||||||
* live hand-off, overflow, retention, the anchor check (invariant 6), and the
|
|
||||||
* mirror-the-done-path replace semantics (invariant 3). Every enumerated case in
|
|
||||||
* the issue's task 1.5 has a test here.
|
|
||||||
*/
|
|
||||||
|
|
||||||
// A ReadableStream whose frames the test pushes explicitly, plus close/error.
|
|
||||||
function makePushStream(): {
|
|
||||||
stream: ReadableStream<string>;
|
|
||||||
push: (f: string) => void;
|
|
||||||
close: () => void;
|
|
||||||
error: (e?: unknown) => void;
|
|
||||||
} {
|
|
||||||
let controller!: ReadableStreamDefaultController<string>;
|
|
||||||
const stream = new ReadableStream<string>({
|
|
||||||
start(c) {
|
|
||||||
controller = c;
|
|
||||||
},
|
|
||||||
});
|
|
||||||
return {
|
|
||||||
stream,
|
|
||||||
push: (f) => controller.enqueue(f),
|
|
||||||
close: () => controller.close(),
|
|
||||||
error: (e) => controller.error(e ?? new Error('read error')),
|
|
||||||
};
|
|
||||||
}
|
|
||||||
|
|
||||||
// Let the fire-and-forget pump drain queued frames (reader.read() resolves on a
|
|
||||||
// macrotask boundary for an already-enqueued value).
|
|
||||||
const flush = (): Promise<void> => new Promise((r) => setTimeout(r, 0));
|
|
||||||
|
|
||||||
function collector(): {
|
|
||||||
cb: RunStreamCallbacks;
|
|
||||||
frames: string[];
|
|
||||||
ended: () => number;
|
|
||||||
} {
|
|
||||||
const frames: string[] = [];
|
|
||||||
let ends = 0;
|
|
||||||
return {
|
|
||||||
frames,
|
|
||||||
ended: () => ends,
|
|
||||||
cb: {
|
|
||||||
onFrame: (f) => frames.push(f),
|
|
||||||
onEnd: () => {
|
|
||||||
ends += 1;
|
|
||||||
},
|
|
||||||
},
|
|
||||||
};
|
|
||||||
}
|
|
||||||
|
|
||||||
describe('AiChatStreamRegistryService', () => {
|
|
||||||
const CHAT = 'chat-1';
|
|
||||||
let registry: AiChatStreamRegistryService;
|
|
||||||
|
|
||||||
beforeEach(() => {
|
|
||||||
registry = new AiChatStreamRegistryService();
|
|
||||||
jest.spyOn((registry as any).logger, 'warn').mockImplementation(() => {});
|
|
||||||
});
|
|
||||||
|
|
||||||
afterEach(() => {
|
|
||||||
registry.onModuleDestroy();
|
|
||||||
});
|
|
||||||
|
|
||||||
it('replays frames in arrival order (live attach)', async () => {
|
|
||||||
registry.open(CHAT, 'run-1');
|
|
||||||
const src = makePushStream();
|
|
||||||
registry.bind(CHAT, 'run-1', 'assist-1', src.stream);
|
|
||||||
src.push('a');
|
|
||||||
src.push('b');
|
|
||||||
src.push('c');
|
|
||||||
await flush();
|
|
||||||
|
|
||||||
const c = collector();
|
|
||||||
const att = await registry.attach(CHAT, false, undefined, c.cb);
|
|
||||||
expect(att).not.toBeNull();
|
|
||||||
expect(att!.replay).toEqual(['a', 'b', 'c']);
|
|
||||||
expect(att!.finished).toBe(false);
|
|
||||||
});
|
|
||||||
|
|
||||||
it('late attach gets the full prefix as replay plus the live tail', async () => {
|
|
||||||
registry.open(CHAT, 'run-1');
|
|
||||||
const src = makePushStream();
|
|
||||||
registry.bind(CHAT, 'run-1', 'assist-1', src.stream);
|
|
||||||
src.push('a');
|
|
||||||
src.push('b');
|
|
||||||
await flush();
|
|
||||||
|
|
||||||
const c = collector();
|
|
||||||
const att = (await registry.attach(CHAT, false, undefined, c.cb))!;
|
|
||||||
expect(att.replay).toEqual(['a', 'b']);
|
|
||||||
att.start();
|
|
||||||
// Live tail arrives after start().
|
|
||||||
src.push('c');
|
|
||||||
src.push('d');
|
|
||||||
await flush();
|
|
||||||
expect(c.frames).toEqual(['c', 'd']);
|
|
||||||
});
|
|
||||||
|
|
||||||
it('a paused subscriber receives frames buffered during pause in order, then live (no loss/reorder)', async () => {
|
|
||||||
registry.open(CHAT, 'run-1');
|
|
||||||
const src = makePushStream();
|
|
||||||
registry.bind(CHAT, 'run-1', 'assist-1', src.stream);
|
|
||||||
src.push('a');
|
|
||||||
await flush();
|
|
||||||
|
|
||||||
const c = collector();
|
|
||||||
// Attach (paused). Frames that arrive BEFORE start() must queue, not drop.
|
|
||||||
const att = (await registry.attach(CHAT, false, undefined, c.cb))!;
|
|
||||||
expect(att.replay).toEqual(['a']);
|
|
||||||
src.push('b'); // arrives while paused -> pending
|
|
||||||
src.push('c');
|
|
||||||
await flush();
|
|
||||||
expect(c.frames).toEqual([]); // nothing delivered yet (paused)
|
|
||||||
att.start(); // drains pending in order
|
|
||||||
expect(c.frames).toEqual(['b', 'c']);
|
|
||||||
src.push('d'); // now live
|
|
||||||
await flush();
|
|
||||||
expect(c.frames).toEqual(['b', 'c', 'd']);
|
|
||||||
});
|
|
||||||
|
|
||||||
it('a run that finishes while a subscriber is paused ends it on start()', async () => {
|
|
||||||
registry.open(CHAT, 'run-1');
|
|
||||||
const c = collector();
|
|
||||||
const att = (await registry.attach(CHAT, false, undefined, c.cb))!;
|
|
||||||
// Terminate the run while the subscriber is still paused.
|
|
||||||
registry.abortEntry(CHAT, 'run-1');
|
|
||||||
expect(c.ended()).toBe(0); // paused: not ended yet
|
|
||||||
att.start();
|
|
||||||
expect(c.ended()).toBe(1); // start() drains + ends
|
|
||||||
});
|
|
||||||
|
|
||||||
it('finished + expect=live returns a replay WITHOUT registering a subscriber', async () => {
|
|
||||||
registry.open(CHAT, 'run-1');
|
|
||||||
const src = makePushStream();
|
|
||||||
registry.bind(CHAT, 'run-1', 'assist-1', src.stream);
|
|
||||||
src.push('a');
|
|
||||||
src.push('b');
|
|
||||||
src.close();
|
|
||||||
await flush();
|
|
||||||
|
|
||||||
const c = collector();
|
|
||||||
const att = (await registry.attach(CHAT, true, undefined, c.cb))!;
|
|
||||||
expect(att.finished).toBe(true);
|
|
||||||
expect(att.replay).toEqual(['a', 'b']);
|
|
||||||
// No subscriber registered: start()/unsubscribe are no-ops and the entry has
|
|
||||||
// zero subscribers.
|
|
||||||
const entry = (registry as any).entries.get(CHAT);
|
|
||||||
expect(entry.subscribers.size).toBe(0);
|
|
||||||
att.start();
|
|
||||||
expect(c.frames).toEqual([]);
|
|
||||||
});
|
|
||||||
|
|
||||||
it('finished WITHOUT expect=live returns null', async () => {
|
|
||||||
registry.open(CHAT, 'run-1');
|
|
||||||
const src = makePushStream();
|
|
||||||
registry.bind(CHAT, 'run-1', 'assist-1', src.stream);
|
|
||||||
src.push('a');
|
|
||||||
src.close();
|
|
||||||
await flush();
|
|
||||||
|
|
||||||
const c = collector();
|
|
||||||
expect(await registry.attach(CHAT, false, undefined, c.cb)).toBeNull();
|
|
||||||
});
|
|
||||||
|
|
||||||
it('anchor mismatch with expect=live returns null (and null before bind sets assistantMessageId)', async () => {
|
|
||||||
registry.open(CHAT, 'run-1');
|
|
||||||
const c = collector();
|
|
||||||
// Before bind: assistantMessageId is undefined -> mismatches any anchor.
|
|
||||||
expect(
|
|
||||||
await registry.attach(CHAT, true, 'assist-1', c.cb),
|
|
||||||
).toBeNull();
|
|
||||||
|
|
||||||
const src = makePushStream();
|
|
||||||
registry.bind(CHAT, 'run-1', 'assist-1', src.stream);
|
|
||||||
src.push('a');
|
|
||||||
await flush();
|
|
||||||
// Wrong anchor -> null (cross-run replay forbidden, invariant 6).
|
|
||||||
expect(await registry.attach(CHAT, true, 'other-id', c.cb)).toBeNull();
|
|
||||||
});
|
|
||||||
|
|
||||||
it('matching anchor with expect=live attaches', async () => {
|
|
||||||
registry.open(CHAT, 'run-1');
|
|
||||||
const src = makePushStream();
|
|
||||||
registry.bind(CHAT, 'run-1', 'assist-1', src.stream);
|
|
||||||
src.push('a');
|
|
||||||
await flush();
|
|
||||||
|
|
||||||
const c = collector();
|
|
||||||
const att = await registry.attach(CHAT, true, 'assist-1', c.cb);
|
|
||||||
expect(att).not.toBeNull();
|
|
||||||
expect(att!.replay).toEqual(['a']);
|
|
||||||
});
|
|
||||||
|
|
||||||
it('overflow: attach returns null, but the LIVE subscriber keeps receiving (incl. the crossing frame)', async () => {
|
|
||||||
registry.open(CHAT, 'run-1');
|
|
||||||
const src = makePushStream();
|
|
||||||
registry.bind(CHAT, 'run-1', 'assist-1', src.stream);
|
|
||||||
|
|
||||||
// A live (started) subscriber attached before the flood.
|
|
||||||
const c = collector();
|
|
||||||
const att = (await registry.attach(CHAT, false, undefined, c.cb))!;
|
|
||||||
att.start();
|
|
||||||
|
|
||||||
const oneMb = 'x'.repeat(1024 * 1024);
|
|
||||||
// 5 x 1MB = 5MB > 4MB cap; the 5th frame is the one that crosses.
|
|
||||||
for (let i = 0; i < 5; i++) src.push(oneMb + i);
|
|
||||||
await flush();
|
|
||||||
|
|
||||||
const entry = (registry as any).entries.get(CHAT);
|
|
||||||
expect(entry.overflowed).toBe(true);
|
|
||||||
expect(entry.bytes).toBeGreaterThan(RUN_STREAM_MAX_BUFFER_BYTES);
|
|
||||||
// The live subscriber received ALL 5 frames, including the crossing one.
|
|
||||||
expect(c.frames).toHaveLength(5);
|
|
||||||
expect(c.frames[4]).toBe(oneMb + 4);
|
|
||||||
|
|
||||||
// A NEW attach after overflow gets null (replay buffer is gone).
|
|
||||||
const c2 = collector();
|
|
||||||
expect(await registry.attach(CHAT, false, undefined, c2.cb)).toBeNull();
|
|
||||||
});
|
|
||||||
|
|
||||||
it('a paused subscriber whose pending buffer overflows is dropped and ends on start(); other subscribers keep receiving', async () => {
|
|
||||||
registry.open(CHAT, 'run-1');
|
|
||||||
const src = makePushStream();
|
|
||||||
registry.bind(CHAT, 'run-1', 'assist-1', src.stream);
|
|
||||||
|
|
||||||
// A: paused (start() deliberately delayed to simulate the phase-2 await seam).
|
|
||||||
const a = collector();
|
|
||||||
const attA = (await registry.attach(CHAT, false, undefined, a.cb))!;
|
|
||||||
// B: live (started) — its delivery must be unaffected by A's overflow.
|
|
||||||
const b = collector();
|
|
||||||
const attB = (await registry.attach(CHAT, false, undefined, b.cb))!;
|
|
||||||
attB.start();
|
|
||||||
|
|
||||||
const oneMb = 'x'.repeat(1024 * 1024);
|
|
||||||
// 9 x 1MB = 9MB > 8MB per-subscriber cap; A's pending overflows, B streams live.
|
|
||||||
for (let i = 0; i < 9; i++) src.push(oneMb + i);
|
|
||||||
await flush();
|
|
||||||
|
|
||||||
const entry = (registry as any).entries.get(CHAT);
|
|
||||||
// A was dropped from the subscriber set on overflow; B (started) remains.
|
|
||||||
expect(entry.subscribers.size).toBe(1);
|
|
||||||
expect(a.frames).toEqual([]); // paused + overflowed: nothing was delivered
|
|
||||||
// B received every frame live (delivery unaffected by A's overflow).
|
|
||||||
expect(b.frames).toHaveLength(9);
|
|
||||||
|
|
||||||
// A's start() (arriving late) degrades to an immediate end, not a partial replay.
|
|
||||||
attA.start();
|
|
||||||
expect(a.frames).toEqual([]);
|
|
||||||
expect(a.ended()).toBe(1);
|
|
||||||
});
|
|
||||||
|
|
||||||
it('open() over a LIVE entry ends started subscribers exactly once and a late done does not touch the new entry (invariant 3)', async () => {
|
|
||||||
registry.open(CHAT, 'run-1');
|
|
||||||
const src = makePushStream();
|
|
||||||
registry.bind(CHAT, 'run-1', 'assist-1', src.stream);
|
|
||||||
src.push('a');
|
|
||||||
await flush();
|
|
||||||
|
|
||||||
const c = collector();
|
|
||||||
const att = (await registry.attach(CHAT, false, undefined, c.cb))!;
|
|
||||||
att.start(); // started subscriber on run-1
|
|
||||||
|
|
||||||
// run-2 starts on the same chat while run-1's tee is still reading.
|
|
||||||
registry.open(CHAT, 'run-2');
|
|
||||||
expect(c.ended()).toBe(1); // exactly one onEnd from the replace
|
|
||||||
|
|
||||||
const newEntry = (registry as any).entries.get(CHAT);
|
|
||||||
expect(newEntry.runId).toBe('run-2');
|
|
||||||
expect(newEntry.finished).toBe(false);
|
|
||||||
|
|
||||||
// The old tee now completes: its late done must NOT double-end nor delete the
|
|
||||||
// new entry.
|
|
||||||
src.push('b');
|
|
||||||
src.close();
|
|
||||||
await flush();
|
|
||||||
expect(c.ended()).toBe(1); // still exactly one
|
|
||||||
const still = (registry as any).entries.get(CHAT);
|
|
||||||
expect(still).toBe(newEntry);
|
|
||||||
expect(still.runId).toBe('run-2');
|
|
||||||
});
|
|
||||||
|
|
||||||
it('bind with a foreign runId is a no-op (invariant 1)', async () => {
|
|
||||||
registry.open(CHAT, 'run-1');
|
|
||||||
const src = makePushStream();
|
|
||||||
registry.bind(CHAT, 'WRONG-run', 'assist-x', src.stream);
|
|
||||||
src.push('a');
|
|
||||||
await flush();
|
|
||||||
const entry = (registry as any).entries.get(CHAT);
|
|
||||||
// Frames were NOT ingested (bind bailed), assistantMessageId untouched.
|
|
||||||
expect(entry.frames).toEqual([]);
|
|
||||||
expect(entry.assistantMessageId).toBeUndefined();
|
|
||||||
});
|
|
||||||
|
|
||||||
it('abortEntry with a foreign runId is a no-op (invariant 1)', async () => {
|
|
||||||
registry.open(CHAT, 'run-1');
|
|
||||||
registry.abortEntry(CHAT, 'WRONG-run');
|
|
||||||
const entry = (registry as any).entries.get(CHAT);
|
|
||||||
expect(entry.finished).toBe(false);
|
|
||||||
});
|
|
||||||
|
|
||||||
it('a throwing onFrame ejects only that subscriber; the ingest loop stays alive', async () => {
|
|
||||||
registry.open(CHAT, 'run-1');
|
|
||||||
const src = makePushStream();
|
|
||||||
registry.bind(CHAT, 'run-1', 'assist-1', src.stream);
|
|
||||||
|
|
||||||
const bad = collector();
|
|
||||||
const badAtt = (await registry.attach(CHAT, false, undefined, {
|
|
||||||
onFrame: () => {
|
|
||||||
throw new Error('boom');
|
|
||||||
},
|
|
||||||
onEnd: bad.cb.onEnd,
|
|
||||||
}))!;
|
|
||||||
badAtt.start();
|
|
||||||
|
|
||||||
const good = collector();
|
|
||||||
const goodAtt = (await registry.attach(CHAT, false, undefined, good.cb))!;
|
|
||||||
goodAtt.start();
|
|
||||||
|
|
||||||
src.push('a'); // bad throws on this frame -> ejected
|
|
||||||
src.push('b'); // good still receives both
|
|
||||||
await flush();
|
|
||||||
|
|
||||||
const entry = (registry as any).entries.get(CHAT);
|
|
||||||
expect(entry.subscribers.size).toBe(1); // bad ejected, good remains
|
|
||||||
expect(good.frames).toEqual(['a', 'b']);
|
|
||||||
});
|
|
||||||
});
|
|
||||||
|
|
||||||
/**
|
|
||||||
* Retention + replace timer behavior. Fake timers, and entries are finalized via
|
|
||||||
* the synchronous abortEntry() path so no stream pump / microtask juggling is
|
|
||||||
* needed.
|
|
||||||
*/
|
|
||||||
describe('AiChatStreamRegistryService retention timers', () => {
|
|
||||||
const CHAT = 'chat-r';
|
|
||||||
let registry: AiChatStreamRegistryService;
|
|
||||||
|
|
||||||
beforeEach(() => {
|
|
||||||
jest.useFakeTimers();
|
|
||||||
registry = new AiChatStreamRegistryService();
|
|
||||||
jest.spyOn((registry as any).logger, 'warn').mockImplementation(() => {});
|
|
||||||
});
|
|
||||||
|
|
||||||
afterEach(() => {
|
|
||||||
registry.onModuleDestroy();
|
|
||||||
jest.useRealTimers();
|
|
||||||
});
|
|
||||||
|
|
||||||
it('a finished entry is removed after the retention window', () => {
|
|
||||||
registry.open(CHAT, 'run-1');
|
|
||||||
registry.abortEntry(CHAT, 'run-1'); // finalize -> retention armed
|
|
||||||
expect((registry as any).entries.get(CHAT)).toBeDefined();
|
|
||||||
jest.advanceTimersByTime(RUN_STREAM_RETAIN_FINISHED_MS + 1);
|
|
||||||
expect((registry as any).entries.get(CHAT)).toBeUndefined();
|
|
||||||
});
|
|
||||||
|
|
||||||
it('retention deletes ONLY its own entry (invariant 2)', () => {
|
|
||||||
registry.open(CHAT, 'run-1');
|
|
||||||
registry.abortEntry(CHAT, 'run-1'); // arm retention for entry A
|
|
||||||
// Simulate the race where the key was replaced without clearing A's timer.
|
|
||||||
const sentinel = { marker: true };
|
|
||||||
(registry as any).entries.set(CHAT, sentinel);
|
|
||||||
jest.advanceTimersByTime(RUN_STREAM_RETAIN_FINISHED_MS + 1);
|
|
||||||
// A's timer saw entries.get(CHAT) !== A, so it did NOT delete the successor.
|
|
||||||
expect((registry as any).entries.get(CHAT)).toBe(sentinel);
|
|
||||||
});
|
|
||||||
|
|
||||||
it('open() over a retained entry clears its timer and the successor survives', () => {
|
|
||||||
registry.open(CHAT, 'run-1');
|
|
||||||
registry.abortEntry(CHAT, 'run-1'); // retained, timer armed
|
|
||||||
const clearSpy = jest.spyOn(global, 'clearTimeout');
|
|
||||||
registry.open(CHAT, 'run-2'); // must clear run-1's retain timer
|
|
||||||
expect(clearSpy).toHaveBeenCalled();
|
|
||||||
jest.advanceTimersByTime(RUN_STREAM_RETAIN_FINISHED_MS + 1);
|
|
||||||
const entry = (registry as any).entries.get(CHAT);
|
|
||||||
expect(entry).toBeDefined();
|
|
||||||
expect(entry.runId).toBe('run-2');
|
|
||||||
});
|
|
||||||
});
|
|
||||||
@@ -1,423 +0,0 @@
|
|||||||
import { ForbiddenException } from '@nestjs/common';
|
|
||||||
import { AiChatController } from './ai-chat.controller';
|
|
||||||
import type {
|
|
||||||
RunStreamAttachment,
|
|
||||||
RunStreamCallbacks,
|
|
||||||
} from './ai-chat-stream-registry.service';
|
|
||||||
import { SUBSCRIBER_MAX_BUFFERED_BYTES } from './ai-chat-stream-registry.service';
|
|
||||||
import type { User, Workspace } from '@docmost/db/types/entity.types';
|
|
||||||
|
|
||||||
/**
|
|
||||||
* Wiring spec for the #184 phase 1.5 attach endpoint
|
|
||||||
* (`GET /ai-chat/runs/:chatId/stream`). Owner-gated via assertOwnedChat; the
|
|
||||||
* registry is mocked so this exercises ONLY the controller's replay/live/204/
|
|
||||||
* cleanup wiring against a fake raw socket. Constructor order is (aiChatService,
|
|
||||||
* aiChatRunService, aiChatRepo, aiChatMessageRepo, aiTranscription, pageRepo,
|
|
||||||
* streamRegistry, environment).
|
|
||||||
*/
|
|
||||||
describe('AiChatController attach endpoint (#184 phase 1.5)', () => {
|
|
||||||
const user = { id: 'u1' } as User;
|
|
||||||
const workspace = { id: 'ws1' } as Workspace;
|
|
||||||
|
|
||||||
function makeRawRes() {
|
|
||||||
const raw: any = {
|
|
||||||
writableEnded: false,
|
|
||||||
writableLength: 0,
|
|
||||||
destroyed: false,
|
|
||||||
written: [] as string[],
|
|
||||||
head: null as any,
|
|
||||||
write: jest.fn((f: string) => {
|
|
||||||
raw.written.push(f);
|
|
||||||
return true;
|
|
||||||
}),
|
|
||||||
writeHead: jest.fn((code: number, headers: any) => {
|
|
||||||
raw.head = { code, headers };
|
|
||||||
return raw;
|
|
||||||
}),
|
|
||||||
flushHeaders: jest.fn(),
|
|
||||||
end: jest.fn(() => {
|
|
||||||
raw.writableEnded = true;
|
|
||||||
}),
|
|
||||||
destroy: jest.fn(() => {
|
|
||||||
raw.destroyed = true;
|
|
||||||
}),
|
|
||||||
on: jest.fn(),
|
|
||||||
once: jest.fn(),
|
|
||||||
};
|
|
||||||
const res: any = {
|
|
||||||
raw,
|
|
||||||
status: jest.fn(() => res),
|
|
||||||
send: jest.fn(),
|
|
||||||
hijack: jest.fn(),
|
|
||||||
};
|
|
||||||
return { res, raw };
|
|
||||||
}
|
|
||||||
|
|
||||||
function makeReq(destroyed = false) {
|
|
||||||
const handlers: Record<string, () => void> = {};
|
|
||||||
const raw: any = {
|
|
||||||
destroyed,
|
|
||||||
once: jest.fn((ev: string, fn: () => void) => {
|
|
||||||
handlers[ev] = fn;
|
|
||||||
}),
|
|
||||||
};
|
|
||||||
return { req: { raw } as any, raw, fireClose: () => handlers['close']?.() };
|
|
||||||
}
|
|
||||||
|
|
||||||
function makeAttachment(
|
|
||||||
over: Partial<RunStreamAttachment> = {},
|
|
||||||
): RunStreamAttachment {
|
|
||||||
return {
|
|
||||||
replay: [],
|
|
||||||
finished: false,
|
|
||||||
start: jest.fn(),
|
|
||||||
unsubscribe: jest.fn(),
|
|
||||||
...over,
|
|
||||||
};
|
|
||||||
}
|
|
||||||
|
|
||||||
function makeController(opts: {
|
|
||||||
chat?: unknown;
|
|
||||||
attachment?: RunStreamAttachment | null;
|
|
||||||
}) {
|
|
||||||
const aiChatRepo = { findById: jest.fn().mockResolvedValue(opts.chat) };
|
|
||||||
let capturedCb: RunStreamCallbacks | undefined;
|
|
||||||
const streamRegistry = {
|
|
||||||
attach: jest.fn(
|
|
||||||
(
|
|
||||||
_chatId: string,
|
|
||||||
_live: boolean,
|
|
||||||
_anchor: string | undefined,
|
|
||||||
cb: RunStreamCallbacks,
|
|
||||||
) => {
|
|
||||||
capturedCb = cb;
|
|
||||||
return Promise.resolve(
|
|
||||||
opts.attachment === undefined ? makeAttachment() : opts.attachment,
|
|
||||||
);
|
|
||||||
},
|
|
||||||
),
|
|
||||||
};
|
|
||||||
const environment = { isAiChatResumableStreamEnabled: () => true };
|
|
||||||
const controller = new AiChatController(
|
|
||||||
{} as never, // aiChatService
|
|
||||||
{} as never, // aiChatRunService
|
|
||||||
aiChatRepo as never,
|
|
||||||
{} as never, // aiChatMessageRepo
|
|
||||||
{} as never, // aiTranscription
|
|
||||||
{} as never, // pageRepo
|
|
||||||
streamRegistry as never,
|
|
||||||
environment as never,
|
|
||||||
);
|
|
||||||
return {
|
|
||||||
controller,
|
|
||||||
aiChatRepo,
|
|
||||||
streamRegistry,
|
|
||||||
getCb: () => capturedCb!,
|
|
||||||
};
|
|
||||||
}
|
|
||||||
|
|
||||||
const owned = { id: 'c1', creatorId: 'u1' };
|
|
||||||
|
|
||||||
it('owner-gates: a foreign chat throws ForbiddenException and never attaches', async () => {
|
|
||||||
const { controller, streamRegistry } = makeController({
|
|
||||||
chat: { id: 'c1', creatorId: 'someone-else' },
|
|
||||||
});
|
|
||||||
const { res } = makeRawRes();
|
|
||||||
const { req } = makeReq();
|
|
||||||
await expect(
|
|
||||||
controller.attachRunStream(
|
|
||||||
'c1',
|
|
||||||
undefined,
|
|
||||||
undefined,
|
|
||||||
req,
|
|
||||||
res,
|
|
||||||
user,
|
|
||||||
workspace,
|
|
||||||
),
|
|
||||||
).rejects.toBeInstanceOf(ForbiddenException);
|
|
||||||
expect(streamRegistry.attach).not.toHaveBeenCalled();
|
|
||||||
});
|
|
||||||
|
|
||||||
it('answers 204 when the registry has nothing to resume (no entry / finished / anchor-mismatch)', async () => {
|
|
||||||
const { controller } = makeController({ chat: owned, attachment: null });
|
|
||||||
const { res } = makeRawRes();
|
|
||||||
const { req } = makeReq();
|
|
||||||
await controller.attachRunStream(
|
|
||||||
'c1',
|
|
||||||
undefined,
|
|
||||||
undefined,
|
|
||||||
req,
|
|
||||||
res,
|
|
||||||
user,
|
|
||||||
workspace,
|
|
||||||
);
|
|
||||||
expect(res.status).toHaveBeenCalledWith(204);
|
|
||||||
expect(res.send).toHaveBeenCalled();
|
|
||||||
expect(res.hijack).not.toHaveBeenCalled();
|
|
||||||
});
|
|
||||||
|
|
||||||
it('threads expect=live and anchor through to the registry', async () => {
|
|
||||||
const { controller, streamRegistry } = makeController({
|
|
||||||
chat: owned,
|
|
||||||
attachment: null,
|
|
||||||
});
|
|
||||||
const { res } = makeRawRes();
|
|
||||||
const { req } = makeReq();
|
|
||||||
await controller.attachRunStream(
|
|
||||||
'c1',
|
|
||||||
'live',
|
|
||||||
'anchor-1',
|
|
||||||
req,
|
|
||||||
res,
|
|
||||||
user,
|
|
||||||
workspace,
|
|
||||||
);
|
|
||||||
expect(streamRegistry.attach).toHaveBeenCalledWith(
|
|
||||||
'c1',
|
|
||||||
true,
|
|
||||||
'anchor-1',
|
|
||||||
expect.anything(),
|
|
||||||
);
|
|
||||||
});
|
|
||||||
|
|
||||||
it('passes expect=false when the query is absent', async () => {
|
|
||||||
const { controller, streamRegistry } = makeController({
|
|
||||||
chat: owned,
|
|
||||||
attachment: null,
|
|
||||||
});
|
|
||||||
const { res } = makeRawRes();
|
|
||||||
const { req } = makeReq();
|
|
||||||
await controller.attachRunStream(
|
|
||||||
'c1',
|
|
||||||
undefined,
|
|
||||||
undefined,
|
|
||||||
req,
|
|
||||||
res,
|
|
||||||
user,
|
|
||||||
workspace,
|
|
||||||
);
|
|
||||||
expect(streamRegistry.attach).toHaveBeenCalledWith(
|
|
||||||
'c1',
|
|
||||||
false,
|
|
||||||
undefined,
|
|
||||||
expect.anything(),
|
|
||||||
);
|
|
||||||
});
|
|
||||||
|
|
||||||
it('hijacks, writes headers + replay, registers a close cleanup, then goes live', async () => {
|
|
||||||
const start = jest.fn();
|
|
||||||
const attachment = makeAttachment({
|
|
||||||
replay: ['f1', 'f2'],
|
|
||||||
finished: false,
|
|
||||||
start,
|
|
||||||
});
|
|
||||||
const { controller } = makeController({ chat: owned, attachment });
|
|
||||||
const { res, raw } = makeRawRes();
|
|
||||||
const { req } = makeReq();
|
|
||||||
await controller.attachRunStream(
|
|
||||||
'c1',
|
|
||||||
undefined,
|
|
||||||
undefined,
|
|
||||||
req,
|
|
||||||
res,
|
|
||||||
user,
|
|
||||||
workspace,
|
|
||||||
);
|
|
||||||
expect(res.hijack).toHaveBeenCalled();
|
|
||||||
expect(raw.writeHead).toHaveBeenCalledWith(
|
|
||||||
200,
|
|
||||||
expect.objectContaining({ 'content-type': 'text/event-stream' }),
|
|
||||||
);
|
|
||||||
expect(raw.written).toEqual(['f1', 'f2']); // replay
|
|
||||||
expect(start).toHaveBeenCalled(); // go live after replay
|
|
||||||
expect(req.raw.once).toHaveBeenCalledWith('close', expect.any(Function));
|
|
||||||
});
|
|
||||||
|
|
||||||
it('finished replay ends the response immediately without going live', async () => {
|
|
||||||
const start = jest.fn();
|
|
||||||
const attachment = makeAttachment({
|
|
||||||
replay: ['f1'],
|
|
||||||
finished: true,
|
|
||||||
start,
|
|
||||||
});
|
|
||||||
const { controller } = makeController({ chat: owned, attachment });
|
|
||||||
const { res, raw } = makeRawRes();
|
|
||||||
const { req } = makeReq();
|
|
||||||
await controller.attachRunStream(
|
|
||||||
'c1',
|
|
||||||
'live',
|
|
||||||
'a1',
|
|
||||||
req,
|
|
||||||
res,
|
|
||||||
user,
|
|
||||||
workspace,
|
|
||||||
);
|
|
||||||
expect(raw.written).toEqual(['f1']);
|
|
||||||
expect(raw.end).toHaveBeenCalled();
|
|
||||||
expect(start).not.toHaveBeenCalled(); // finished -> returns before start()
|
|
||||||
});
|
|
||||||
|
|
||||||
it('a close during the awaits (req.raw.destroyed) unsubscribes and writes nothing', async () => {
|
|
||||||
const attachment = makeAttachment({ replay: ['f1'] });
|
|
||||||
const { controller } = makeController({ chat: owned, attachment });
|
|
||||||
const { res, raw } = makeRawRes();
|
|
||||||
const { req } = makeReq(true); // destroyed already at registration time
|
|
||||||
await controller.attachRunStream(
|
|
||||||
'c1',
|
|
||||||
undefined,
|
|
||||||
undefined,
|
|
||||||
req,
|
|
||||||
res,
|
|
||||||
user,
|
|
||||||
workspace,
|
|
||||||
);
|
|
||||||
expect(attachment.unsubscribe).toHaveBeenCalled();
|
|
||||||
expect(raw.writeHead).not.toHaveBeenCalled();
|
|
||||||
expect(raw.written).toEqual([]);
|
|
||||||
});
|
|
||||||
|
|
||||||
it('the registered close handler unsubscribes the attachment', async () => {
|
|
||||||
const attachment = makeAttachment({ replay: [] });
|
|
||||||
const { controller } = makeController({ chat: owned, attachment });
|
|
||||||
const { res } = makeRawRes();
|
|
||||||
const { req, fireClose } = makeReq();
|
|
||||||
await controller.attachRunStream(
|
|
||||||
'c1',
|
|
||||||
undefined,
|
|
||||||
undefined,
|
|
||||||
req,
|
|
||||||
res,
|
|
||||||
user,
|
|
||||||
workspace,
|
|
||||||
);
|
|
||||||
expect(attachment.unsubscribe).not.toHaveBeenCalled();
|
|
||||||
fireClose(); // socket closed
|
|
||||||
expect(attachment.unsubscribe).toHaveBeenCalled();
|
|
||||||
});
|
|
||||||
|
|
||||||
it('onFrame destroys the socket when the buffered length exceeds the cap', async () => {
|
|
||||||
const attachment = makeAttachment({ replay: [] });
|
|
||||||
const { controller, getCb } = makeController({ chat: owned, attachment });
|
|
||||||
const { res, raw } = makeRawRes();
|
|
||||||
const { req } = makeReq();
|
|
||||||
await controller.attachRunStream(
|
|
||||||
'c1',
|
|
||||||
undefined,
|
|
||||||
undefined,
|
|
||||||
req,
|
|
||||||
res,
|
|
||||||
user,
|
|
||||||
workspace,
|
|
||||||
);
|
|
||||||
const cb = getCb();
|
|
||||||
// Normal live frame writes.
|
|
||||||
raw.writableLength = 0;
|
|
||||||
cb.onFrame('live-1');
|
|
||||||
expect(raw.written).toContain('live-1');
|
|
||||||
// A stalled socket over the cap is destroyed instead of buffering.
|
|
||||||
raw.writableLength = SUBSCRIBER_MAX_BUFFERED_BYTES + 1;
|
|
||||||
raw.write.mockClear();
|
|
||||||
cb.onFrame('too-much');
|
|
||||||
expect(raw.destroy).toHaveBeenCalled();
|
|
||||||
expect(raw.write).not.toHaveBeenCalled();
|
|
||||||
});
|
|
||||||
});
|
|
||||||
|
|
||||||
/**
|
|
||||||
* The begin-hook `open()` flag gate (#184 phase 1.5). `open()` lives ONLY in the
|
|
||||||
* stream() begin-hook, gated on the resumable flag. If it regressed, a flag-off
|
|
||||||
* turn would create an EMPTY registry entry (never bound, never finished) and a
|
|
||||||
* later attach would find a non-null paused attachment -> a hung SSE that never
|
|
||||||
* gets a frame and never ends, instead of a clean 204. These drive stream() only
|
|
||||||
* far enough to capture the runHooks it hands to the service, then invoke the
|
|
||||||
* begin-hook and assert whether the registry was opened.
|
|
||||||
*/
|
|
||||||
describe('AiChatController begin-hook open() flag gate (#184 phase 1.5)', () => {
|
|
||||||
const user = { id: 'u1' } as User;
|
|
||||||
const workspace = {
|
|
||||||
id: 'ws1',
|
|
||||||
settings: { ai: { chat: true, autonomousRuns: true } },
|
|
||||||
} as unknown as Workspace;
|
|
||||||
|
|
||||||
function makeController(opts: { resumable: boolean }) {
|
|
||||||
let capturedArgs: any;
|
|
||||||
const aiChatService = {
|
|
||||||
resolveRoleForRequest: jest.fn(async () => null),
|
|
||||||
getChatModel: jest.fn(async () => ({})),
|
|
||||||
stream: jest.fn(async (args: any) => {
|
|
||||||
capturedArgs = args;
|
|
||||||
}),
|
|
||||||
};
|
|
||||||
const aiChatRunService = {
|
|
||||||
getActiveForChat: jest.fn(async () => undefined),
|
|
||||||
beginRun: jest.fn(async () => ({
|
|
||||||
runId: 'run-1',
|
|
||||||
signal: new AbortController().signal,
|
|
||||||
})),
|
|
||||||
};
|
|
||||||
const streamRegistry = { open: jest.fn(), attach: jest.fn() };
|
|
||||||
const environment = {
|
|
||||||
isAiChatResumableStreamEnabled: () => opts.resumable,
|
|
||||||
};
|
|
||||||
const controller = new AiChatController(
|
|
||||||
aiChatService as never,
|
|
||||||
aiChatRunService as never,
|
|
||||||
{} as never, // aiChatRepo
|
|
||||||
{} as never, // aiChatMessageRepo
|
|
||||||
{} as never, // aiTranscription
|
|
||||||
{} as never, // pageRepo
|
|
||||||
streamRegistry as never,
|
|
||||||
environment as never,
|
|
||||||
);
|
|
||||||
return {
|
|
||||||
controller,
|
|
||||||
streamRegistry,
|
|
||||||
aiChatRunService,
|
|
||||||
getRunHooks: () => capturedArgs?.runHooks,
|
|
||||||
};
|
|
||||||
}
|
|
||||||
|
|
||||||
function makeReqRes() {
|
|
||||||
const req: any = {
|
|
||||||
raw: { sessionId: 'sess-1', once: jest.fn() },
|
|
||||||
body: {
|
|
||||||
messages: [
|
|
||||||
{ id: 'm1', role: 'user', parts: [{ type: 'text', text: 'hi' }] },
|
|
||||||
],
|
|
||||||
},
|
|
||||||
};
|
|
||||||
const res: any = {
|
|
||||||
raw: { once: jest.fn(), on: jest.fn(), headersSent: false, writableEnded: false },
|
|
||||||
hijack: jest.fn(),
|
|
||||||
};
|
|
||||||
return { req, res };
|
|
||||||
}
|
|
||||||
|
|
||||||
it('flag OFF: the begin-hook does NOT open a registry entry (no hung empty entry)', async () => {
|
|
||||||
const { controller, streamRegistry, aiChatRunService, getRunHooks } =
|
|
||||||
makeController({ resumable: false });
|
|
||||||
const { req, res } = makeReqRes();
|
|
||||||
await controller.stream(req, res, user, workspace);
|
|
||||||
|
|
||||||
const runHooks = getRunHooks();
|
|
||||||
expect(runHooks).toBeDefined();
|
|
||||||
const handle = await runHooks.begin('chat-1');
|
|
||||||
// The run still begins (the durable-run feature is independent of resume)...
|
|
||||||
expect(aiChatRunService.beginRun).toHaveBeenCalled();
|
|
||||||
expect(handle).toEqual({ runId: 'run-1', signal: expect.anything() });
|
|
||||||
// ...but with the flag off the registry entry is NEVER opened.
|
|
||||||
expect(streamRegistry.open).not.toHaveBeenCalled();
|
|
||||||
});
|
|
||||||
|
|
||||||
it('flag ON: the begin-hook opens the registry entry with (chatId, runId)', async () => {
|
|
||||||
const { controller, streamRegistry, getRunHooks } = makeController({
|
|
||||||
resumable: true,
|
|
||||||
});
|
|
||||||
const { req, res } = makeReqRes();
|
|
||||||
await controller.stream(req, res, user, workspace);
|
|
||||||
|
|
||||||
const runHooks = getRunHooks();
|
|
||||||
await runHooks.begin('chat-1');
|
|
||||||
expect(streamRegistry.open).toHaveBeenCalledWith('chat-1', 'run-1');
|
|
||||||
});
|
|
||||||
});
|
|
||||||
@@ -4,15 +4,11 @@ import {
|
|||||||
ConflictException,
|
ConflictException,
|
||||||
Controller,
|
Controller,
|
||||||
ForbiddenException,
|
ForbiddenException,
|
||||||
Get,
|
|
||||||
HttpCode,
|
HttpCode,
|
||||||
HttpException,
|
HttpException,
|
||||||
HttpStatus,
|
HttpStatus,
|
||||||
Logger,
|
Logger,
|
||||||
Param,
|
|
||||||
ParseUUIDPipe,
|
|
||||||
Post,
|
Post,
|
||||||
Query,
|
|
||||||
Req,
|
Req,
|
||||||
Res,
|
Res,
|
||||||
ServiceUnavailableException,
|
ServiceUnavailableException,
|
||||||
@@ -58,12 +54,6 @@ import {
|
|||||||
} from './dto/ai-chat.dto';
|
} from './dto/ai-chat.dto';
|
||||||
import { describeProviderError } from '../../integrations/ai/ai-error.util';
|
import { describeProviderError } from '../../integrations/ai/ai-error.util';
|
||||||
import { buildChatMarkdown } from './chat-markdown.util';
|
import { buildChatMarkdown } from './chat-markdown.util';
|
||||||
import {
|
|
||||||
AiChatStreamRegistryService,
|
|
||||||
SUBSCRIBER_MAX_BUFFERED_BYTES,
|
|
||||||
} from './ai-chat-stream-registry.service';
|
|
||||||
import { startSseHeartbeat } from './sse-resilience';
|
|
||||||
import { EnvironmentService } from '../../integrations/environment/environment.service';
|
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Per-user AI chat API (§6.1). Routes are POST to match this codebase's
|
* Per-user AI chat API (§6.1). Routes are POST to match this codebase's
|
||||||
@@ -82,11 +72,6 @@ export class AiChatController {
|
|||||||
private readonly aiChatMessageRepo: AiChatMessageRepo,
|
private readonly aiChatMessageRepo: AiChatMessageRepo,
|
||||||
private readonly aiTranscription: AiTranscriptionService,
|
private readonly aiTranscription: AiTranscriptionService,
|
||||||
private readonly pageRepo: PageRepo,
|
private readonly pageRepo: PageRepo,
|
||||||
// #184 phase 1.5. OPTIONAL so existing positional constructions (controller
|
|
||||||
// specs) compile unchanged; Nest always injects the real providers in
|
|
||||||
// production. Only touched on the resumable-stream (flag-on) path.
|
|
||||||
private readonly streamRegistry?: AiChatStreamRegistryService,
|
|
||||||
private readonly environment?: EnvironmentService,
|
|
||||||
) {}
|
) {}
|
||||||
|
|
||||||
/** List the requesting user's chats in this workspace (paginated). */
|
/** List the requesting user's chats in this workspace (paginated). */
|
||||||
@@ -248,102 +233,6 @@ export class AiChatController {
|
|||||||
return { stopped };
|
return { stopped };
|
||||||
}
|
}
|
||||||
|
|
||||||
/**
|
|
||||||
* Attach to a chat's live run stream (#184 phase 1.5). A late/reloaded tab
|
|
||||||
* replays the frames buffered so far and then follows the live tail as a normal
|
|
||||||
* streamer. Owner-gated via assertOwnedChat (same gate as getRun). When there is
|
|
||||||
* nothing to resume — no entry, a finished run without expect=live, an
|
|
||||||
* overflowed buffer, or an anchor that pins a DIFFERENT run — the endpoint
|
|
||||||
* answers 204, the ONLY "nothing to resume" signal the AI SDK's reconnect
|
|
||||||
* accepts (it maps 204 to a silent no-op). With AI_CHAT_RESUMABLE_STREAM off the
|
|
||||||
* registry is never populated, so attach always 204s.
|
|
||||||
*
|
|
||||||
* `expect=live` opts into replaying a finished-but-retained run (safe only when
|
|
||||||
* the client stripped the streaming tail); `anchor` is the client's assistant
|
|
||||||
* row id, which must match this run's (invariant 6) or a foreign run's
|
|
||||||
* transcript would be replayed into the store.
|
|
||||||
*/
|
|
||||||
@SkipTransform()
|
|
||||||
@UseGuards(JwtAuthGuard, UserThrottlerGuard)
|
|
||||||
@Throttle({ [AI_CHAT_THROTTLER]: { limit: 60, ttl: 60000 } })
|
|
||||||
@Get('runs/:chatId/stream')
|
|
||||||
async attachRunStream(
|
|
||||||
@Param('chatId', new ParseUUIDPipe()) chatId: string,
|
|
||||||
@Query('expect') expect: string | undefined,
|
|
||||||
@Query('anchor') anchor: string | undefined,
|
|
||||||
@Req() req: FastifyRequest,
|
|
||||||
@Res() res: FastifyReply,
|
|
||||||
@AuthUser() user: User,
|
|
||||||
@AuthWorkspace() workspace: Workspace,
|
|
||||||
): Promise<void> {
|
|
||||||
await this.assertOwnedChat(chatId, user, workspace); // same gate as getRun
|
|
||||||
let stopHeartbeat: () => void = () => undefined;
|
|
||||||
const attachment = await this.streamRegistry?.attach(
|
|
||||||
chatId,
|
|
||||||
expect === 'live',
|
|
||||||
anchor,
|
|
||||||
{
|
|
||||||
onFrame: (frame) => {
|
|
||||||
// Backpressure guard: 2x the replay cap, so the initial replay burst
|
|
||||||
// alone can never trip it; only a genuinely stalled socket can.
|
|
||||||
try {
|
|
||||||
if (res.raw.writableLength > SUBSCRIBER_MAX_BUFFERED_BYTES) {
|
|
||||||
res.raw.destroy(); // 'close' fires -> unsubscribe below
|
|
||||||
return;
|
|
||||||
}
|
|
||||||
if (!res.raw.writableEnded) res.raw.write(frame);
|
|
||||||
} catch {
|
|
||||||
res.raw.destroy();
|
|
||||||
}
|
|
||||||
},
|
|
||||||
onEnd: () => {
|
|
||||||
stopHeartbeat();
|
|
||||||
if (!res.raw.writableEnded) res.raw.end();
|
|
||||||
},
|
|
||||||
},
|
|
||||||
);
|
|
||||||
if (!attachment) {
|
|
||||||
res.status(204).send(); // the ONLY "nothing to resume" signal the SDK accepts
|
|
||||||
return;
|
|
||||||
}
|
|
||||||
res.hijack();
|
|
||||||
// Cleanup BEFORE any write (invariant 5): a torn-down socket must not orphan
|
|
||||||
// a paused subscriber whose pending queue would buffer the whole run.
|
|
||||||
req.raw.once('close', () => {
|
|
||||||
attachment.unsubscribe();
|
|
||||||
stopHeartbeat();
|
|
||||||
});
|
|
||||||
// A close emitted DURING the awaits above was missed by the listener — check.
|
|
||||||
// (Healthy pending GETs have req.raw.destroyed === false, so no false
|
|
||||||
// positives; returning without end() is fine — the socket is gone.)
|
|
||||||
if (req.raw.destroyed) {
|
|
||||||
attachment.unsubscribe();
|
|
||||||
return;
|
|
||||||
}
|
|
||||||
res.raw.on('error', () => undefined);
|
|
||||||
try {
|
|
||||||
res.raw.writeHead(200, {
|
|
||||||
'content-type': 'text/event-stream',
|
|
||||||
'cache-control': 'no-cache',
|
|
||||||
'x-vercel-ai-ui-message-stream': 'v1',
|
|
||||||
'x-accel-buffering': 'no',
|
|
||||||
// deliberately NO Connection/Keep-Alive (hop-by-hop; Safari/HTTP2)
|
|
||||||
});
|
|
||||||
res.raw.flushHeaders?.();
|
|
||||||
for (const frame of attachment.replay) res.raw.write(frame);
|
|
||||||
if (attachment.finished) {
|
|
||||||
res.raw.end();
|
|
||||||
return;
|
|
||||||
}
|
|
||||||
stopHeartbeat = startSseHeartbeat(res.raw, 15_000);
|
|
||||||
attachment.start(); // drain pending accumulated during replay, go live
|
|
||||||
} catch {
|
|
||||||
attachment.unsubscribe();
|
|
||||||
stopHeartbeat();
|
|
||||||
res.raw.destroy();
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
/** Rename a chat. */
|
/** Rename a chat. */
|
||||||
@HttpCode(HttpStatus.OK)
|
@HttpCode(HttpStatus.OK)
|
||||||
@Post('rename')
|
@Post('rename')
|
||||||
@@ -455,25 +344,13 @@ export class AiChatController {
|
|||||||
// its progress, and settle its terminal status — see AiChatRunService.
|
// its progress, and settle its terminal status — see AiChatRunService.
|
||||||
const runHooks: AiChatRunHooks | undefined = autonomousRuns
|
const runHooks: AiChatRunHooks | undefined = autonomousRuns
|
||||||
? {
|
? {
|
||||||
begin: async (chatId) => {
|
begin: (chatId) =>
|
||||||
const handle = await this.aiChatRunService.beginRun({
|
this.aiChatRunService.beginRun({
|
||||||
chatId,
|
chatId,
|
||||||
workspaceId: workspace.id,
|
workspaceId: workspace.id,
|
||||||
userId: user.id,
|
userId: user.id,
|
||||||
trigger: 'user',
|
trigger: 'user',
|
||||||
});
|
}),
|
||||||
// #184 phase 1.5: register the run-stream entry at BEGIN (before any
|
|
||||||
// frame) so a tab that attaches in the begin->seed window finds an
|
|
||||||
// entry to wait on. Gated on AI_CHAT_RESUMABLE_STREAM: with the flag
|
|
||||||
// off nothing is registered and attach always 204s.
|
|
||||||
if (
|
|
||||||
handle?.runId &&
|
|
||||||
this.environment?.isAiChatResumableStreamEnabled?.()
|
|
||||||
) {
|
|
||||||
this.streamRegistry?.open(chatId, handle.runId);
|
|
||||||
}
|
|
||||||
return handle;
|
|
||||||
},
|
|
||||||
onAssistantSeeded: (runId, messageId) =>
|
onAssistantSeeded: (runId, messageId) =>
|
||||||
this.aiChatRunService.linkAssistantMessage(
|
this.aiChatRunService.linkAssistantMessage(
|
||||||
runId,
|
runId,
|
||||||
|
|||||||
@@ -4,7 +4,6 @@ import { TokenModule } from '../auth/token.module';
|
|||||||
import { AiChatController } from './ai-chat.controller';
|
import { AiChatController } from './ai-chat.controller';
|
||||||
import { AiChatService } from './ai-chat.service';
|
import { AiChatService } from './ai-chat.service';
|
||||||
import { AiChatRunService } from './ai-chat-run.service';
|
import { AiChatRunService } from './ai-chat-run.service';
|
||||||
import { AiChatStreamRegistryService } from './ai-chat-stream-registry.service';
|
|
||||||
import { AiTranscriptionService } from './ai-transcription.service';
|
import { AiTranscriptionService } from './ai-transcription.service';
|
||||||
import { AiChatToolsService } from './tools/ai-chat-tools.service';
|
import { AiChatToolsService } from './tools/ai-chat-tools.service';
|
||||||
import { EmbeddingModule } from './embedding/embedding.module';
|
import { EmbeddingModule } from './embedding/embedding.module';
|
||||||
@@ -45,7 +44,6 @@ import { PublicShareChatToolsService } from './tools/public-share-chat-tools.ser
|
|||||||
providers: [
|
providers: [
|
||||||
AiChatService,
|
AiChatService,
|
||||||
AiChatRunService,
|
AiChatRunService,
|
||||||
AiChatStreamRegistryService,
|
|
||||||
AiTranscriptionService,
|
AiTranscriptionService,
|
||||||
AiChatToolsService,
|
AiChatToolsService,
|
||||||
PublicShareChatService,
|
PublicShareChatService,
|
||||||
|
|||||||
@@ -153,41 +153,6 @@ describe('buildSystemPrompt current-page context', () => {
|
|||||||
expect(prompt).not.toContain('pageId:');
|
expect(prompt).not.toContain('pageId:');
|
||||||
});
|
});
|
||||||
|
|
||||||
// #388: editor-selection flag. Only a FIXED one-liner is added — the selection
|
|
||||||
// TEXT (untrusted page content) must never reach the prompt.
|
|
||||||
const SELECTION_FLAG = 'currently has text SELECTED on this page';
|
|
||||||
|
|
||||||
it('adds the selection flag when a selection is present with a page', () => {
|
|
||||||
const prompt = buildSystemPrompt({
|
|
||||||
workspace,
|
|
||||||
openedPage: {
|
|
||||||
id: 'pg-123',
|
|
||||||
title: 'Doc',
|
|
||||||
selection: { text: 'SECRET-SELECTED-TEXT', blockIds: ['b1'] },
|
|
||||||
},
|
|
||||||
});
|
|
||||||
expect(prompt).toContain(SELECTION_FLAG);
|
|
||||||
// The selection TEXT itself is NEVER in the prompt.
|
|
||||||
expect(prompt).not.toContain('SECRET-SELECTED-TEXT');
|
|
||||||
expect(prompt).not.toContain('b1');
|
|
||||||
});
|
|
||||||
|
|
||||||
it('omits the selection flag when there is no selection', () => {
|
|
||||||
const prompt = buildSystemPrompt({
|
|
||||||
workspace,
|
|
||||||
openedPage: { id: 'pg-123', title: 'Doc' },
|
|
||||||
});
|
|
||||||
expect(prompt).not.toContain(SELECTION_FLAG);
|
|
||||||
});
|
|
||||||
|
|
||||||
it('omits the selection flag when selection is null', () => {
|
|
||||||
const prompt = buildSystemPrompt({
|
|
||||||
workspace,
|
|
||||||
openedPage: { id: 'pg-123', title: 'Doc', selection: null },
|
|
||||||
});
|
|
||||||
expect(prompt).not.toContain(SELECTION_FLAG);
|
|
||||||
});
|
|
||||||
|
|
||||||
it('escapes a malicious opened-page title so it cannot inject tags (F1)', () => {
|
it('escapes a malicious opened-page title so it cannot inject tags (F1)', () => {
|
||||||
const prompt = buildSystemPrompt({
|
const prompt = buildSystemPrompt({
|
||||||
workspace,
|
workspace,
|
||||||
|
|||||||
@@ -156,13 +156,8 @@ export interface BuildSystemPromptInput {
|
|||||||
* has an id, a CONTEXT line is added so the agent can resolve "this page" /
|
* has an id, a CONTEXT line is added so the agent can resolve "this page" /
|
||||||
* "the current page" to that pageId. The page is NOT fetched here — the agent
|
* "the current page" to that pageId. The page is NOT fetched here — the agent
|
||||||
* uses its CASL-enforced read/write page tools with the id when needed.
|
* uses its CASL-enforced read/write page tools with the id when needed.
|
||||||
*
|
|
||||||
* `selection` (#388) is present only when the user has a non-empty editor
|
|
||||||
* selection; the prompt adds ONLY a fixed one-line flag from it — the
|
|
||||||
* selection TEXT is untrusted page content and stays out of the prompt (it is
|
|
||||||
* surfaced solely via the getCurrentPage tool result).
|
|
||||||
*/
|
*/
|
||||||
openedPage?: { id?: string; title?: string; selection?: object | null } | null;
|
openedPage?: { id?: string; title?: string } | null;
|
||||||
/**
|
/**
|
||||||
* Admin-authored, per-EXTERNAL-MCP-server guidance ("how/when to use this
|
* Admin-authored, per-EXTERNAL-MCP-server guidance ("how/when to use this
|
||||||
* server's tools"), built by `McpClientsService.toolsFor` for servers that
|
* server's tools"), built by `McpClientsService.toolsFor` for servers that
|
||||||
@@ -314,14 +309,6 @@ export function buildSystemPrompt({
|
|||||||
? escapeAttr(openedPage.title)
|
? escapeAttr(openedPage.title)
|
||||||
: 'Untitled';
|
: 'Untitled';
|
||||||
context += `\nThe user is currently viewing the page "${title}" (pageId: ${pageId.trim()}). When they refer to "this page", "the current page", or similar, operate on that pageId — use the read/write page tools with it.`;
|
context += `\nThe user is currently viewing the page "${title}" (pageId: ${pageId.trim()}). When they refer to "this page", "the current page", or similar, operate on that pageId — use the read/write page tools with it.`;
|
||||||
// Editor-selection flag (#388). A FIXED one-liner only — the selection TEXT
|
|
||||||
// is untrusted collaborative-page content and must never enter the prompt; it
|
|
||||||
// is surfaced solely through the getCurrentPage tool result (SAFETY_FRAMEWORK
|
|
||||||
// treats a tool result as data). Nested under the page block so it is added
|
|
||||||
// only alongside a resolved page (a selection cannot outlive its page).
|
|
||||||
if (openedPage?.selection) {
|
|
||||||
context += `\nThe user currently has text SELECTED on this page — call getCurrentPage to see the selection. When they say "this", "here", "the selected text" or similar, they mean that selection.`;
|
|
||||||
}
|
|
||||||
}
|
}
|
||||||
|
|
||||||
// Interrupt-resume marker (#198). Added to the context section (inside the
|
// Interrupt-resume marker (#198). Added to the context section (inside the
|
||||||
|
|||||||
@@ -1,121 +0,0 @@
|
|||||||
import { Logger } from '@nestjs/common';
|
|
||||||
|
|
||||||
// Mock the AI SDK: the turn we drive is STOPPED during the pre-streamText setup
|
|
||||||
// phase, so no provider call must ever be made. convertToModelMessages is reached
|
|
||||||
// (before toolsFor) so it is stubbed to an empty transcript.
|
|
||||||
jest.mock('ai', () => ({
|
|
||||||
streamText: jest.fn(),
|
|
||||||
generateText: jest.fn(),
|
|
||||||
convertToModelMessages: jest.fn(async () => []),
|
|
||||||
stepCountIs: jest.fn(() => () => false),
|
|
||||||
}));
|
|
||||||
|
|
||||||
import { streamText } from 'ai';
|
|
||||||
import { AiChatService } from './ai-chat.service';
|
|
||||||
|
|
||||||
/**
|
|
||||||
* D2 — an explicit Stop DURING the external-MCP toolset build (the pre-streamText
|
|
||||||
* setup phase) must:
|
|
||||||
* (a) unwedge the turn (stream() rejects instead of hanging at step 0), and
|
|
||||||
* (b) finalize the run as 'aborted' via the outer catch's onSettled — never leak
|
|
||||||
* the run row as 'running' (which would 409 every later turn in this chat).
|
|
||||||
*
|
|
||||||
* The setup phase does NOT yet observe streamText's terminal callbacks, so before
|
|
||||||
* the fix a hung `toolsFor` ignored the run's abort signal and never finalized.
|
|
||||||
* `raceAgainstAbortAndTimeout(toolsFor, effectiveSignal, ...)` now rejects the
|
|
||||||
* moment the run's signal aborts; the catch re-throws (signal aborted), and the
|
|
||||||
* outer catch settles the run 'aborted'.
|
|
||||||
*/
|
|
||||||
describe('AiChatService.stream — abort during external-MCP setup finalizes the run (D2)', () => {
|
|
||||||
const streamTextMock = streamText as unknown as jest.Mock;
|
|
||||||
|
|
||||||
function makeService(mcpClients: { toolsFor: jest.Mock }) {
|
|
||||||
const aiChatRepo = {
|
|
||||||
findById: jest.fn(async () => ({ id: 'chat-1', workspaceId: 'ws-1' })),
|
|
||||||
insert: jest.fn(),
|
|
||||||
};
|
|
||||||
const aiChatMessageRepo = {
|
|
||||||
insert: jest.fn(async () => ({ id: 'msg-1' })),
|
|
||||||
findAllByChat: jest.fn(async () => []),
|
|
||||||
update: jest.fn(async () => ({ id: 'msg-1' })),
|
|
||||||
};
|
|
||||||
const aiSettings = { resolve: jest.fn(async () => ({})) };
|
|
||||||
const tools = { forUser: jest.fn(async () => ({})) };
|
|
||||||
const svc = new AiChatService(
|
|
||||||
{} as never, // ai
|
|
||||||
aiChatRepo as never,
|
|
||||||
aiChatMessageRepo as never,
|
|
||||||
{} as never, // aiChatPageSnapshotRepo
|
|
||||||
aiSettings as never,
|
|
||||||
tools as never,
|
|
||||||
mcpClients as never,
|
|
||||||
{} as never, // aiAgentRoleRepo
|
|
||||||
{} as never, // pageRepo (openPage undefined -> never touched)
|
|
||||||
{} as never, // pageAccess
|
|
||||||
{ isAiChatDeferredToolsEnabled: () => false } as never, // environment
|
|
||||||
);
|
|
||||||
return { svc, tools };
|
|
||||||
}
|
|
||||||
|
|
||||||
const body = {
|
|
||||||
chatId: 'chat-1',
|
|
||||||
messages: [
|
|
||||||
{ id: 'm1', role: 'user', parts: [{ type: 'text', text: 'hi' }] },
|
|
||||||
],
|
|
||||||
};
|
|
||||||
|
|
||||||
beforeEach(() => {
|
|
||||||
streamTextMock.mockReset();
|
|
||||||
jest.spyOn(Logger.prototype, 'log').mockImplementation(() => undefined as never);
|
|
||||||
jest.spyOn(Logger.prototype, 'warn').mockImplementation(() => undefined as never);
|
|
||||||
jest.spyOn(Logger.prototype, 'error').mockImplementation(() => undefined as never);
|
|
||||||
});
|
|
||||||
|
|
||||||
afterEach(() => jest.restoreAllMocks());
|
|
||||||
|
|
||||||
it('stops the hung toolset build, rejects, and settles the run "aborted" — never reaching streamText', async () => {
|
|
||||||
const runController = new AbortController();
|
|
||||||
// The build hangs (never resolves); the run is STOPPED mid-build. Aborting on a
|
|
||||||
// macrotask exercises the abort-listener path (a real user Stop during setup).
|
|
||||||
const toolsFor = jest.fn(() => {
|
|
||||||
setTimeout(() => runController.abort(new Error('user stop')), 0);
|
|
||||||
return new Promise(() => {}); // never settles — models a hung MCP build
|
|
||||||
});
|
|
||||||
const { svc } = makeService({ toolsFor });
|
|
||||||
|
|
||||||
const onSettled = jest.fn();
|
|
||||||
const begin = jest.fn(async () => ({
|
|
||||||
runId: 'run-1',
|
|
||||||
signal: runController.signal,
|
|
||||||
}));
|
|
||||||
|
|
||||||
const promise = svc.stream({
|
|
||||||
user: { id: 'user-1' } as never,
|
|
||||||
workspace: { id: 'ws-1' } as never,
|
|
||||||
sessionId: 'sess-1',
|
|
||||||
body: body as never,
|
|
||||||
res: { raw: {} } as never,
|
|
||||||
signal: new AbortController().signal, // socket signal (distinct from the run)
|
|
||||||
model: {} as never,
|
|
||||||
role: null,
|
|
||||||
runHooks: {
|
|
||||||
begin,
|
|
||||||
onAssistantSeeded: jest.fn(),
|
|
||||||
onStep: jest.fn(),
|
|
||||||
onSettled,
|
|
||||||
} as never,
|
|
||||||
});
|
|
||||||
|
|
||||||
// (a) The turn is UNWEDGED: it rejects (with the stop reason) instead of hanging.
|
|
||||||
await expect(promise).rejects.toThrow('user stop');
|
|
||||||
|
|
||||||
// (b) The run is finalized as 'aborted' with NO error message (a Stop, not a
|
|
||||||
// failure) — so the run row never leaks 'running'.
|
|
||||||
expect(onSettled).toHaveBeenCalledTimes(1);
|
|
||||||
expect(onSettled).toHaveBeenCalledWith('run-1', 'aborted', undefined);
|
|
||||||
|
|
||||||
// The build was reached, but the provider call was NEVER made (stopped at setup).
|
|
||||||
expect(toolsFor).toHaveBeenCalledTimes(1);
|
|
||||||
expect(streamTextMock).not.toHaveBeenCalled();
|
|
||||||
});
|
|
||||||
});
|
|
||||||
@@ -1,13 +1,4 @@
|
|||||||
import { ForbiddenException, Logger } from '@nestjs/common';
|
import { ForbiddenException } from '@nestjs/common';
|
||||||
// Mock ONLY streamText so a driven stream() call can capture the pipe-options
|
|
||||||
// object (consumeSseStream / generateMessageId). Everything else in the AI SDK
|
|
||||||
// stays REAL (requireActual), so the pure-helper suites in this file are
|
|
||||||
// unaffected — none of them call stream()/streamText.
|
|
||||||
jest.mock('ai', () => ({
|
|
||||||
...jest.requireActual('ai'),
|
|
||||||
streamText: jest.fn(),
|
|
||||||
}));
|
|
||||||
import { streamText } from 'ai';
|
|
||||||
import {
|
import {
|
||||||
AiChatService,
|
AiChatService,
|
||||||
compactToolOutput,
|
compactToolOutput,
|
||||||
@@ -16,7 +7,6 @@ import {
|
|||||||
rowToUiMessage,
|
rowToUiMessage,
|
||||||
prepareAgentStep,
|
prepareAgentStep,
|
||||||
flushAssistant,
|
flushAssistant,
|
||||||
stripNulChars,
|
|
||||||
chatStreamMetadata,
|
chatStreamMetadata,
|
||||||
accumulateStepUsage,
|
accumulateStepUsage,
|
||||||
isInterruptResume,
|
isInterruptResume,
|
||||||
@@ -449,45 +439,6 @@ describe('flushAssistant', () => {
|
|||||||
});
|
});
|
||||||
});
|
});
|
||||||
|
|
||||||
/**
|
|
||||||
* stripNulChars: a NUL (U+0000) is rejected by Postgres in BOTH the `content`
|
|
||||||
* (text) and `toolCalls`/`metadata` (jsonb) columns, so it must be stripped from
|
|
||||||
* every persisted string. String.fromCharCode(0) avoids embedding a raw NUL byte
|
|
||||||
* in this source file.
|
|
||||||
*/
|
|
||||||
describe('stripNulChars', () => {
|
|
||||||
const NUL = String.fromCharCode(0);
|
|
||||||
|
|
||||||
it('deep-strips NUL from strings in nested objects/arrays', () => {
|
|
||||||
const out = stripNulChars({
|
|
||||||
content: `a${NUL}b`,
|
|
||||||
parts: [{ type: 'text', text: `x${NUL}${NUL}y` }],
|
|
||||||
nested: [`p${NUL}q`, 42, null],
|
|
||||||
});
|
|
||||||
expect(out.content).toBe('ab');
|
|
||||||
expect((out.parts[0] as { text: string }).text).toBe('xy');
|
|
||||||
expect(out.nested[0]).toBe('pq');
|
|
||||||
expect(out.nested[1]).toBe(42);
|
|
||||||
expect(out.nested[2]).toBeNull();
|
|
||||||
expect(JSON.stringify(out).includes(NUL)).toBe(false);
|
|
||||||
});
|
|
||||||
|
|
||||||
it('returns the SAME reference when there is no NUL (no needless clone)', () => {
|
|
||||||
const input = { a: 'clean', b: [1, 2, { c: 'ok' }] };
|
|
||||||
expect(stripNulChars(input)).toBe(input);
|
|
||||||
});
|
|
||||||
|
|
||||||
it('flushAssistant produces a NUL-free row even when the turn text carries one', () => {
|
|
||||||
const f = flushAssistant([], `partial${NUL}answer`, 'error', {
|
|
||||||
error: `bo${NUL}om`,
|
|
||||||
});
|
|
||||||
expect(f.content).toBe('partialanswer');
|
|
||||||
const serialized =
|
|
||||||
f.content + JSON.stringify(f.toolCalls) + JSON.stringify(f.metadata);
|
|
||||||
expect(serialized.includes(NUL)).toBe(false);
|
|
||||||
});
|
|
||||||
});
|
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* chatStreamMetadata: attach metadata to the streamed assistant UI message per
|
* chatStreamMetadata: attach metadata to the streamed assistant UI message per
|
||||||
* part type — `chatId` on `start` (so the client adopts the real created chat id
|
* part type — `chatId` on `start` (so the client adopts the real created chat id
|
||||||
@@ -738,7 +689,6 @@ describe('AiChatService.resolveOpenPageContext (#159 current-page validation)',
|
|||||||
id: string;
|
id: string;
|
||||||
title: string;
|
title: string;
|
||||||
updatedAt: Date;
|
updatedAt: Date;
|
||||||
selection: unknown;
|
|
||||||
} | null>;
|
} | null>;
|
||||||
|
|
||||||
it('returns null when no page is open (no id)', async () => {
|
it('returns null when no page is open (no id)', async () => {
|
||||||
@@ -784,14 +734,8 @@ describe('AiChatService.resolveOpenPageContext (#159 current-page validation)',
|
|||||||
});
|
});
|
||||||
// The client claims it is on "Page A" but the id points at page B.
|
// The client claims it is on "Page A" but the id points at page B.
|
||||||
const result = await call(svc, { id: 'p-1', title: 'Page A' });
|
const result = await call(svc, { id: 'p-1', title: 'Page A' });
|
||||||
// updatedAt (#274 page-change fast path) is carried through from the DB row;
|
// updatedAt (#274 page-change fast path) is carried through from the DB row.
|
||||||
// selection is null when the client sent none (#388).
|
expect(result).toEqual({ id: 'p-1', title: 'Real Title B', updatedAt });
|
||||||
expect(result).toEqual({
|
|
||||||
id: 'p-1',
|
|
||||||
title: 'Real Title B',
|
|
||||||
updatedAt,
|
|
||||||
selection: null,
|
|
||||||
});
|
|
||||||
});
|
});
|
||||||
|
|
||||||
it('coerces a null DB title to an empty string', async () => {
|
it('coerces a null DB title to an empty string', async () => {
|
||||||
@@ -804,55 +748,8 @@ describe('AiChatService.resolveOpenPageContext (#159 current-page validation)',
|
|||||||
id: 'p-1',
|
id: 'p-1',
|
||||||
title: '',
|
title: '',
|
||||||
updatedAt,
|
updatedAt,
|
||||||
selection: null,
|
|
||||||
});
|
});
|
||||||
});
|
});
|
||||||
|
|
||||||
// #388: the selection rides ONLY on a successful page resolve, and is
|
|
||||||
// sanitized on the way through.
|
|
||||||
it('attaches the SANITIZED selection on a successful resolve', async () => {
|
|
||||||
const updatedAt = new Date('2026-07-02T10:00:00Z');
|
|
||||||
const svc = makeService({
|
|
||||||
page: { id: 'p-1', workspaceId: 'ws-1', title: 'Doc', updatedAt },
|
|
||||||
canView: true,
|
|
||||||
});
|
|
||||||
const result = await call(svc, {
|
|
||||||
id: 'p-1',
|
|
||||||
selection: {
|
|
||||||
text: 'fix this',
|
|
||||||
blockIds: ['b1', 123, 'y'.repeat(65)], // garbage stripped by sanitize
|
|
||||||
before: 'please ',
|
|
||||||
},
|
|
||||||
});
|
|
||||||
expect(result).toEqual({
|
|
||||||
id: 'p-1',
|
|
||||||
title: 'Doc',
|
|
||||||
updatedAt,
|
|
||||||
selection: { text: 'fix this', blockIds: ['b1'], before: 'please ' },
|
|
||||||
});
|
|
||||||
});
|
|
||||||
|
|
||||||
it('drops a blank/garbage selection to null on a successful resolve', async () => {
|
|
||||||
const updatedAt = new Date('2026-07-02T10:00:00Z');
|
|
||||||
const svc = makeService({
|
|
||||||
page: { id: 'p-1', workspaceId: 'ws-1', title: 'Doc', updatedAt },
|
|
||||||
canView: true,
|
|
||||||
});
|
|
||||||
expect(
|
|
||||||
await call(svc, { id: 'p-1', selection: { text: ' ' } }),
|
|
||||||
).toEqual({ id: 'p-1', title: 'Doc', updatedAt, selection: null });
|
|
||||||
});
|
|
||||||
|
|
||||||
it('selection does NOT survive a foreign/inaccessible page (dies with the page)', async () => {
|
|
||||||
// Forbidden page => the WHOLE context is null, so the selection is gone too.
|
|
||||||
const svc = makeService({
|
|
||||||
page: { id: 'p-1', workspaceId: 'ws-1', title: 'Restricted' },
|
|
||||||
canView: false,
|
|
||||||
});
|
|
||||||
expect(
|
|
||||||
await call(svc, { id: 'p-1', selection: { text: 'secret sel' } }),
|
|
||||||
).toBeNull();
|
|
||||||
});
|
|
||||||
});
|
});
|
||||||
|
|
||||||
/**
|
/**
|
||||||
@@ -1162,181 +1059,3 @@ describe('isInterruptResume', () => {
|
|||||||
expect(isInterruptResume(withPrev(null), true)).toBe(false);
|
expect(isInterruptResume(withPrev(null), true)).toBe(false);
|
||||||
});
|
});
|
||||||
});
|
});
|
||||||
|
|
||||||
/**
|
|
||||||
* #184 phase 1.5 — the run-wrapped pipe options (unit). Drives stream() to the
|
|
||||||
* pipe call with streamText mocked, capturing the options object, and asserts:
|
|
||||||
* - flag OFF while a runId IS present -> the LEGACY option shape (no
|
|
||||||
* consumeSseStream, no generateMessageId), and the registry is never touched.
|
|
||||||
* This is the exact dormancy guarantee this PR rests on.
|
|
||||||
* - flag ON + runId -> consumeSseStream tees into the registry and
|
|
||||||
* generateMessageId returns the seeded assistant DB row id.
|
|
||||||
* - flag ON but no runHooks (runId undefined) -> legacy (the runId gate).
|
|
||||||
* - flag ON + runId -> the outer catch releases the entry via abortEntry.
|
|
||||||
*/
|
|
||||||
describe('AiChatService.stream — resumable pipe options (#184 phase 1.5)', () => {
|
|
||||||
const streamTextMock = streamText as unknown as jest.Mock;
|
|
||||||
let pipeMock: jest.Mock;
|
|
||||||
|
|
||||||
beforeEach(() => {
|
|
||||||
streamTextMock.mockReset();
|
|
||||||
pipeMock = jest.fn();
|
|
||||||
streamTextMock.mockReturnValue({
|
|
||||||
consumeStream: jest.fn(),
|
|
||||||
pipeUIMessageStreamToResponse: pipeMock,
|
|
||||||
});
|
|
||||||
// Silence the service's diagnostic logging for a clean test run.
|
|
||||||
jest.spyOn(Logger.prototype, 'log').mockImplementation(() => undefined as never);
|
|
||||||
jest
|
|
||||||
.spyOn(Logger.prototype, 'error')
|
|
||||||
.mockImplementation(() => undefined as never);
|
|
||||||
jest
|
|
||||||
.spyOn(Logger.prototype, 'warn')
|
|
||||||
.mockImplementation(() => undefined as never);
|
|
||||||
});
|
|
||||||
|
|
||||||
afterEach(() => jest.restoreAllMocks());
|
|
||||||
|
|
||||||
// A raw-response stub sufficient for the post-streamText wiring.
|
|
||||||
function makeRes() {
|
|
||||||
return {
|
|
||||||
raw: {
|
|
||||||
writeHead: jest.fn(),
|
|
||||||
write: jest.fn(),
|
|
||||||
once: jest.fn(),
|
|
||||||
on: jest.fn(),
|
|
||||||
flushHeaders: jest.fn(),
|
|
||||||
writableEnded: false,
|
|
||||||
destroyed: false,
|
|
||||||
},
|
|
||||||
};
|
|
||||||
}
|
|
||||||
|
|
||||||
// Wire only the deps reached on the way to the pipe call, plus a spy registry.
|
|
||||||
function makeService(opts: { resumable: boolean }) {
|
|
||||||
const aiChatRepo = {
|
|
||||||
findById: jest.fn(async () => ({ id: 'chat-1', workspaceId: 'ws-1' })),
|
|
||||||
insert: jest.fn(),
|
|
||||||
};
|
|
||||||
const aiChatMessageRepo = {
|
|
||||||
// Both the user insert and the assistant seed return the same row id.
|
|
||||||
insert: jest.fn(async () => ({ id: 'msg-1' })),
|
|
||||||
findAllByChat: jest.fn(async () => []),
|
|
||||||
update: jest.fn(async () => ({ id: 'msg-1' })),
|
|
||||||
};
|
|
||||||
const aiSettings = { resolve: jest.fn(async () => ({})) };
|
|
||||||
const tools = { forUser: jest.fn(async () => ({})) };
|
|
||||||
const mcpClients = {
|
|
||||||
toolsFor: jest.fn(async () => ({
|
|
||||||
tools: {},
|
|
||||||
clients: [],
|
|
||||||
outcomes: [],
|
|
||||||
instructions: [],
|
|
||||||
})),
|
|
||||||
};
|
|
||||||
const streamRegistry = {
|
|
||||||
open: jest.fn(),
|
|
||||||
bind: jest.fn(),
|
|
||||||
abortEntry: jest.fn(),
|
|
||||||
};
|
|
||||||
const svc = new AiChatService(
|
|
||||||
{} as never, // ai (model is injected)
|
|
||||||
aiChatRepo as never,
|
|
||||||
aiChatMessageRepo as never,
|
|
||||||
{} as never, // aiChatPageSnapshotRepo
|
|
||||||
aiSettings as never,
|
|
||||||
tools as never,
|
|
||||||
mcpClients as never,
|
|
||||||
{} as never, // aiAgentRoleRepo
|
|
||||||
{} as never, // pageRepo (openPage undefined -> never touched)
|
|
||||||
{} as never, // pageAccess
|
|
||||||
{
|
|
||||||
isAiChatDeferredToolsEnabled: () => false,
|
|
||||||
isAiChatResumableStreamEnabled: () => opts.resumable,
|
|
||||||
} as never,
|
|
||||||
streamRegistry as never,
|
|
||||||
);
|
|
||||||
return { svc, streamRegistry };
|
|
||||||
}
|
|
||||||
|
|
||||||
const body = {
|
|
||||||
chatId: 'chat-1',
|
|
||||||
messages: [
|
|
||||||
{ id: 'm1', role: 'user', parts: [{ type: 'text', text: 'hi' }] },
|
|
||||||
],
|
|
||||||
};
|
|
||||||
|
|
||||||
const makeRunHooks = () => ({
|
|
||||||
begin: jest.fn(async () => ({
|
|
||||||
runId: 'run-1',
|
|
||||||
signal: new AbortController().signal,
|
|
||||||
})),
|
|
||||||
onAssistantSeeded: jest.fn(),
|
|
||||||
onStep: jest.fn(),
|
|
||||||
onSettled: jest.fn(),
|
|
||||||
});
|
|
||||||
|
|
||||||
async function drive(svc: AiChatService, hooks: unknown): Promise<void> {
|
|
||||||
await svc.stream({
|
|
||||||
user: { id: 'u1' } as never,
|
|
||||||
workspace: { id: 'ws-1' } as never,
|
|
||||||
sessionId: 's1',
|
|
||||||
body: body as never,
|
|
||||||
res: makeRes() as never,
|
|
||||||
signal: new AbortController().signal,
|
|
||||||
model: {} as never,
|
|
||||||
role: null,
|
|
||||||
runHooks: hooks as never,
|
|
||||||
});
|
|
||||||
}
|
|
||||||
|
|
||||||
it('flag OFF + runId present: LEGACY option shape (no consumeSseStream / generateMessageId); registry untouched', async () => {
|
|
||||||
const { svc, streamRegistry } = makeService({ resumable: false });
|
|
||||||
await drive(svc, makeRunHooks());
|
|
||||||
expect(pipeMock).toHaveBeenCalledTimes(1);
|
|
||||||
const options = pipeMock.mock.calls[0][1];
|
|
||||||
// The dormancy guarantee: a live run with the flag off tees NOTHING and does
|
|
||||||
// not stamp a message id — byte-for-byte the pre-1.5 wire.
|
|
||||||
expect(options.consumeSseStream).toBeUndefined();
|
|
||||||
expect(options.generateMessageId).toBeUndefined();
|
|
||||||
expect(streamRegistry.bind).not.toHaveBeenCalled();
|
|
||||||
expect(streamRegistry.abortEntry).not.toHaveBeenCalled();
|
|
||||||
});
|
|
||||||
|
|
||||||
it('flag ON + runId: consumeSseStream tees into the registry; generateMessageId returns the seeded row id', async () => {
|
|
||||||
const { svc, streamRegistry } = makeService({ resumable: true });
|
|
||||||
await drive(svc, makeRunHooks());
|
|
||||||
const options = pipeMock.mock.calls[0][1];
|
|
||||||
expect(typeof options.consumeSseStream).toBe('function');
|
|
||||||
expect(typeof options.generateMessageId).toBe('function');
|
|
||||||
// generateMessageId stamps the seeded assistant DB row id.
|
|
||||||
expect(options.generateMessageId()).toBe('msg-1');
|
|
||||||
// consumeSseStream binds the tee: (chatId, runId, assistantId, stream).
|
|
||||||
const fakeStream = {} as ReadableStream<string>;
|
|
||||||
options.consumeSseStream({ stream: fakeStream });
|
|
||||||
expect(streamRegistry.bind).toHaveBeenCalledWith(
|
|
||||||
'chat-1',
|
|
||||||
'run-1',
|
|
||||||
'msg-1',
|
|
||||||
fakeStream,
|
|
||||||
);
|
|
||||||
});
|
|
||||||
|
|
||||||
it('flag ON but NO runHooks (runId undefined): pipe options stay legacy (the runId gate)', async () => {
|
|
||||||
const { svc, streamRegistry } = makeService({ resumable: true });
|
|
||||||
await drive(svc, undefined);
|
|
||||||
const options = pipeMock.mock.calls[0][1];
|
|
||||||
expect(options.consumeSseStream).toBeUndefined();
|
|
||||||
expect(options.generateMessageId).toBeUndefined();
|
|
||||||
expect(streamRegistry.bind).not.toHaveBeenCalled();
|
|
||||||
});
|
|
||||||
|
|
||||||
it('flag ON + runId: the outer catch calls abortEntry when the stream throws', async () => {
|
|
||||||
const { svc, streamRegistry } = makeService({ resumable: true });
|
|
||||||
streamTextMock.mockImplementation(() => {
|
|
||||||
throw new Error('boom');
|
|
||||||
});
|
|
||||||
await expect(drive(svc, makeRunHooks())).rejects.toThrow('boom');
|
|
||||||
expect(streamRegistry.abortEntry).toHaveBeenCalledWith('chat-1', 'run-1');
|
|
||||||
});
|
|
||||||
});
|
|
||||||
|
|||||||
@@ -32,7 +32,6 @@ import {
|
|||||||
import { AiChatToolsService } from './tools/ai-chat-tools.service';
|
import { AiChatToolsService } from './tools/ai-chat-tools.service';
|
||||||
import { McpClientsService } from './external-mcp/mcp-clients.service';
|
import { McpClientsService } from './external-mcp/mcp-clients.service';
|
||||||
import { EnvironmentService } from '../../integrations/environment/environment.service';
|
import { EnvironmentService } from '../../integrations/environment/environment.service';
|
||||||
import { AiChatStreamRegistryService } from './ai-chat-stream-registry.service';
|
|
||||||
import { buildSystemPrompt } from './ai-chat.prompt';
|
import { buildSystemPrompt } from './ai-chat.prompt';
|
||||||
import {
|
import {
|
||||||
CORE_TOOL_KEYS,
|
CORE_TOOL_KEYS,
|
||||||
@@ -43,10 +42,6 @@ import {
|
|||||||
} from './tools/tool-tiers';
|
} from './tools/tool-tiers';
|
||||||
import { RunAlreadyActiveError } from './ai-chat-run.service';
|
import { RunAlreadyActiveError } from './ai-chat-run.service';
|
||||||
import { computePageChange } from './page-change/page-change.util';
|
import { computePageChange } from './page-change/page-change.util';
|
||||||
import {
|
|
||||||
sanitizeSelection,
|
|
||||||
type SelectionContext,
|
|
||||||
} from './tools/current-page.util';
|
|
||||||
import { roleModelOverride } from './roles/role-model-config';
|
import { roleModelOverride } from './roles/role-model-config';
|
||||||
import {
|
import {
|
||||||
startSseHeartbeat,
|
startSseHeartbeat,
|
||||||
@@ -58,15 +53,6 @@ import {
|
|||||||
// multi-search research questions are not cut off mid-investigation.
|
// multi-search research questions are not cut off mid-investigation.
|
||||||
const MAX_AGENT_STEPS = 20;
|
const MAX_AGENT_STEPS = 20;
|
||||||
|
|
||||||
// Wall-clock ceiling for building the external MCP toolset during the per-turn
|
|
||||||
// setup phase (before streamText owns the lifecycle). Defense-in-depth ABOVE the
|
|
||||||
// per-server connect bound in mcp-clients.service (CONNECT_TIMEOUT_MS): even if
|
|
||||||
// that per-server timeout regressed, this outer deadline — together with the run's
|
|
||||||
// abort signal — guarantees the setup phase can never wedge a turn at step 0 (the
|
|
||||||
// production hang) and the run always finalizes. Generous: the per-server bound
|
|
||||||
// should fire first in practice; this only backstops a total build stall.
|
|
||||||
const MCP_TOOLSET_BUILD_DEADLINE_MS = 60_000;
|
|
||||||
|
|
||||||
// System-prompt addendum injected ONLY on the final step (see prepareAgentStep).
|
// System-prompt addendum injected ONLY on the final step (see prepareAgentStep).
|
||||||
// It forbids further tool calls and tells the model to synthesize the best
|
// It forbids further tool calls and tells the model to synthesize the best
|
||||||
// answer it can from what it already gathered, so a tool-heavy turn never ends
|
// answer it can from what it already gathered, so a tool-heavy turn never ends
|
||||||
@@ -185,78 +171,6 @@ export function sameInstant(
|
|||||||
return ta === tb;
|
return ta === tb;
|
||||||
}
|
}
|
||||||
|
|
||||||
/**
|
|
||||||
* Race `work` against an abort signal AND a wall-clock deadline, so a hung
|
|
||||||
* external-MCP toolset build during the pre-streamText setup phase can NEITHER
|
|
||||||
* wedge the turn NOR make it un-stoppable, and the run always finalizes. It
|
|
||||||
* - resolves with `work`'s value when it settles first;
|
|
||||||
* - REJECTS EARLY if `signal` aborts (with `signal.reason` when that is an Error,
|
|
||||||
* else a generic `Error('aborted')`) — so an explicit Stop is honored mid-setup;
|
|
||||||
* - REJECTS EARLY if `deadlineMs` elapses (defense-in-depth backstop);
|
|
||||||
* - invokes `onLateResolve(value)` when `work` settles AFTER the race was already
|
|
||||||
* lost, so the caller can release any resources that abandoned value owns
|
|
||||||
* (e.g. close leased MCP clients that would otherwise leak their sockets).
|
|
||||||
*
|
|
||||||
* A rejection handler is attached to `work` so a late rejection is never an
|
|
||||||
* unhandledRejection; the timer is unref'd and cleared once the race settles.
|
|
||||||
*/
|
|
||||||
export function raceAgainstAbortAndTimeout<T>(
|
|
||||||
work: Promise<T>,
|
|
||||||
signal: AbortSignal,
|
|
||||||
deadlineMs: number,
|
|
||||||
onLateResolve?: (value: T) => void,
|
|
||||||
): Promise<T> {
|
|
||||||
return new Promise<T>((resolve, reject) => {
|
|
||||||
let settled = false;
|
|
||||||
const cleanup = () => {
|
|
||||||
clearTimeout(timer);
|
|
||||||
signal.removeEventListener('abort', onAbort);
|
|
||||||
};
|
|
||||||
const onAbort = () => {
|
|
||||||
if (settled) return;
|
|
||||||
settled = true;
|
|
||||||
cleanup();
|
|
||||||
reject(
|
|
||||||
signal.reason instanceof Error ? signal.reason : new Error('aborted'),
|
|
||||||
);
|
|
||||||
};
|
|
||||||
const timer = setTimeout(() => {
|
|
||||||
if (settled) return;
|
|
||||||
settled = true;
|
|
||||||
cleanup();
|
|
||||||
reject(new Error(`setup timed out after ${deadlineMs}ms`));
|
|
||||||
}, deadlineMs);
|
|
||||||
// Do not keep the process alive just for this setup-deadline timer.
|
|
||||||
timer.unref?.();
|
|
||||||
if (signal.aborted) {
|
|
||||||
onAbort();
|
|
||||||
} else {
|
|
||||||
signal.addEventListener('abort', onAbort, { once: true });
|
|
||||||
}
|
|
||||||
work.then(
|
|
||||||
(value) => {
|
|
||||||
if (settled) {
|
|
||||||
// The race was already lost (abort/deadline): hand the abandoned value to
|
|
||||||
// the caller so it can release the resources that value owns.
|
|
||||||
onLateResolve?.(value);
|
|
||||||
return;
|
|
||||||
}
|
|
||||||
settled = true;
|
|
||||||
cleanup();
|
|
||||||
resolve(value);
|
|
||||||
},
|
|
||||||
(err: unknown) => {
|
|
||||||
// A late rejection after the race is already handled — swallow so it is
|
|
||||||
// never an unhandledRejection.
|
|
||||||
if (settled) return;
|
|
||||||
settled = true;
|
|
||||||
cleanup();
|
|
||||||
reject(err instanceof Error ? err : new Error(String(err)));
|
|
||||||
},
|
|
||||||
);
|
|
||||||
});
|
|
||||||
}
|
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Payload accepted from the client `useChat` POST body. We do NOT bind a strict
|
* Payload accepted from the client `useChat` POST body. We do NOT bind a strict
|
||||||
* DTO (the global ValidationPipe whitelist would strip the useChat-specific
|
* DTO (the global ValidationPipe whitelist would strip the useChat-specific
|
||||||
@@ -274,12 +188,7 @@ export interface AiChatStreamBody {
|
|||||||
// page" refers to; the page itself is never fetched server-side here. The id
|
// page" refers to; the page itself is never fetched server-side here. The id
|
||||||
// is attacker-controllable but harmless: the agent reads/writes via its
|
// is attacker-controllable but harmless: the agent reads/writes via its
|
||||||
// CASL-enforced page tools, which 403 on a page the user cannot access.
|
// CASL-enforced page tools, which 403 on a page the user cannot access.
|
||||||
//
|
openPage?: { id?: string; title?: string } | null;
|
||||||
// `selection` is the user's editor selection snapshotted client-side at send
|
|
||||||
// time (#388). It is CLIENT-controlled and UNTRUSTED — a loose `unknown` here
|
|
||||||
// (the body is parsed off req.body without a DTO) that is type-checked and
|
|
||||||
// capped by `sanitizeSelection` before it is ever surfaced to the model.
|
|
||||||
openPage?: { id?: string; title?: string; selection?: unknown } | null;
|
|
||||||
// Set by the client "send now" action (#198): this turn immediately follows a
|
// Set by the client "send now" action (#198): this turn immediately follows a
|
||||||
// user interruption of the previous turn. A hint only — the server re-confirms
|
// user interruption of the previous turn. A hint only — the server re-confirms
|
||||||
// it against persisted history (`isInterruptResume`) before injecting the
|
// it against persisted history (`isInterruptResume`) before injecting the
|
||||||
@@ -367,10 +276,6 @@ export class AiChatService implements OnModuleInit {
|
|||||||
// Reads the AI_CHAT_DEFERRED_TOOLS toggle (#332). Injected last so existing
|
// Reads the AI_CHAT_DEFERRED_TOOLS toggle (#332). Injected last so existing
|
||||||
// positional constructor callers (tests) only append one stub.
|
// positional constructor callers (tests) only append one stub.
|
||||||
private readonly environment: EnvironmentService,
|
private readonly environment: EnvironmentService,
|
||||||
// #184 phase 1.5 run-stream registry. OPTIONAL so existing positional
|
|
||||||
// constructions (int-specs) compile unchanged; Nest always injects the real
|
|
||||||
// provider in production. Only ever touched on the run-wrapped + flag-on path.
|
|
||||||
private readonly streamRegistry?: AiChatStreamRegistryService,
|
|
||||||
) {}
|
) {}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
@@ -455,18 +360,10 @@ export class AiChatService implements OnModuleInit {
|
|||||||
* page, or any non-Forbidden access-check fault, returns null.
|
* page, or any non-Forbidden access-check fault, returns null.
|
||||||
*/
|
*/
|
||||||
private async resolveOpenPageContext(
|
private async resolveOpenPageContext(
|
||||||
openPage:
|
openPage: { id?: string; title?: string } | null | undefined,
|
||||||
| { id?: string; title?: string; selection?: unknown }
|
|
||||||
| null
|
|
||||||
| undefined,
|
|
||||||
workspace: Workspace,
|
workspace: Workspace,
|
||||||
user: User,
|
user: User,
|
||||||
): Promise<{
|
): Promise<{ id: string; title: string; updatedAt: Date } | null> {
|
||||||
id: string;
|
|
||||||
title: string;
|
|
||||||
updatedAt: Date;
|
|
||||||
selection: SelectionContext | null;
|
|
||||||
} | null> {
|
|
||||||
const candidatePageId = openPage?.id;
|
const candidatePageId = openPage?.id;
|
||||||
if (!candidatePageId) return null;
|
if (!candidatePageId) return null;
|
||||||
const page = await this.pageRepo.findById(candidatePageId);
|
const page = await this.pageRepo.findById(candidatePageId);
|
||||||
@@ -488,18 +385,7 @@ export class AiChatService implements OnModuleInit {
|
|||||||
// updatedAt is the page's last-modified instant, used by the #274 per-turn
|
// updatedAt is the page's last-modified instant, used by the #274 per-turn
|
||||||
// page-change detection as a cheap fast path (unchanged instant => skip the
|
// page-change detection as a cheap fast path (unchanged instant => skip the
|
||||||
// render + diff). The system-prompt / tool consumers ignore the extra field.
|
// render + diff). The system-prompt / tool consumers ignore the extra field.
|
||||||
//
|
return { id: page.id, title: page.title ?? '', updatedAt: page.updatedAt };
|
||||||
// The sanitized editor selection (#388) is attached ONLY here, on a
|
|
||||||
// successful page resolve: the fail-closed branches above return null for the
|
|
||||||
// WHOLE context, so a selection can never outlive a foreign/missing/deleted
|
|
||||||
// page (decision 3). Downstream consumers that don't care (detectPageChange,
|
|
||||||
// snapshotOpenPage) ignore the extra field, same as updatedAt.
|
|
||||||
return {
|
|
||||||
id: page.id,
|
|
||||||
title: page.title ?? '',
|
|
||||||
updatedAt: page.updatedAt,
|
|
||||||
selection: sanitizeSelection(openPage?.selection),
|
|
||||||
};
|
|
||||||
}
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
@@ -785,40 +671,10 @@ export class AiChatService implements OnModuleInit {
|
|||||||
instructions: [],
|
instructions: [],
|
||||||
};
|
};
|
||||||
try {
|
try {
|
||||||
// Bound the external-MCP toolset build by BOTH the run's abort signal and
|
external = await this.mcpClients.toolsFor(workspace.id);
|
||||||
// a generous wall-clock deadline. This is the pre-streamText setup phase,
|
|
||||||
// which streamText's terminal callbacks do NOT yet govern — so without this
|
|
||||||
// a hung build would hang the turn at step 0 forever (the production hang),
|
|
||||||
// unobservant of an explicit Stop. The deadline is defense-in-depth ABOVE
|
|
||||||
// the per-server connect bound in mcp-clients.service. On a LATE resolve
|
|
||||||
// (the race was already lost) close the abandoned toolset's leased clients
|
|
||||||
// so their transports are not leaked.
|
|
||||||
external = await raceAgainstAbortAndTimeout(
|
|
||||||
this.mcpClients.toolsFor(workspace.id),
|
|
||||||
effectiveSignal,
|
|
||||||
MCP_TOOLSET_BUILD_DEADLINE_MS,
|
|
||||||
(late) => {
|
|
||||||
void Promise.all(
|
|
||||||
late.clients.map((c) => c.close().catch(() => undefined)),
|
|
||||||
);
|
|
||||||
},
|
|
||||||
);
|
|
||||||
} catch (err) {
|
} catch (err) {
|
||||||
// An explicit Stop reached the RUN's signal DURING setup: re-throw so the
|
// Building the external toolset must never break the turn; proceed with
|
||||||
// outer catch finalizes the run as aborted — never swallow a Stop. Gated on
|
// Docmost-only tools. Never log URLs/headers — short message only.
|
||||||
// `runId`: the re-throw exists ONLY to finalize the run, which exists only
|
|
||||||
// in autonomous mode. On the legacy path (no runId) `effectiveSignal` is the
|
|
||||||
// SOCKET signal (it aborts on a client disconnect); re-throwing there would
|
|
||||||
// change prior behavior and make the controller write JSON to an already-
|
|
||||||
// closed socket (it only attaches res.raw.on('error') in autonomous mode).
|
|
||||||
// So legacy keeps its prior behavior — warn + proceed, and streamText then
|
|
||||||
// observes the aborted socket signal.
|
|
||||||
if (runId && effectiveSignal.aborted) {
|
|
||||||
throw err;
|
|
||||||
}
|
|
||||||
// Otherwise a down/slow server (build timeout or other fault) must never
|
|
||||||
// break the turn: proceed with Docmost-only tools. Never log URLs/headers —
|
|
||||||
// short message only.
|
|
||||||
this.logger.warn(
|
this.logger.warn(
|
||||||
`External MCP toolset unavailable: ${
|
`External MCP toolset unavailable: ${
|
||||||
err instanceof Error ? err.message : 'unknown error'
|
err instanceof Error ? err.message : 'unknown error'
|
||||||
@@ -1318,35 +1174,6 @@ export class AiChatService implements OnModuleInit {
|
|||||||
// as the cumulative authoritative usage so the client never jumps DOWN.
|
// as the cumulative authoritative usage so the client never jumps DOWN.
|
||||||
let cumulativeStepUsage: ChatStreamUsage | undefined;
|
let cumulativeStepUsage: ChatStreamUsage | undefined;
|
||||||
result.pipeUIMessageStreamToResponse(res.raw, {
|
result.pipeUIMessageStreamToResponse(res.raw, {
|
||||||
// #184 phase 1.5: run-wrapped mode only — the legacy path (flag off) stays
|
|
||||||
// byte-for-byte identical, including the absence of start.messageId. Both
|
|
||||||
// fields are gated on `runId` (present only for a durable run) AND the
|
|
||||||
// AI_CHAT_RESUMABLE_STREAM flag; the seed `assistantId` is unconditional,
|
|
||||||
// so gating on `assistantId` alone would change the legacy wire.
|
|
||||||
...(runId && this.environment?.isAiChatResumableStreamEnabled?.()
|
|
||||||
? {
|
|
||||||
// Tee the SSE frames into the run-stream registry so late tabs can
|
|
||||||
// attach (replay + live tail).
|
|
||||||
consumeSseStream: ({
|
|
||||||
stream,
|
|
||||||
}: {
|
|
||||||
stream: ReadableStream<string>;
|
|
||||||
}) =>
|
|
||||||
this.streamRegistry?.bind(
|
|
||||||
chatId,
|
|
||||||
runId!,
|
|
||||||
assistantId,
|
|
||||||
stream,
|
|
||||||
),
|
|
||||||
// Stamp the persisted assistant row's DB id onto the streamed
|
|
||||||
// message so every tab renders the SAME id as the DB row (id-based
|
|
||||||
// reconciliation). Seeding is best-effort: when it failed, let the
|
|
||||||
// client generate the id.
|
|
||||||
...(assistantId
|
|
||||||
? { generateMessageId: () => assistantId }
|
|
||||||
: {}),
|
|
||||||
}
|
|
||||||
: {}),
|
|
||||||
headers: { 'X-Accel-Buffering': 'no' },
|
headers: { 'X-Accel-Buffering': 'no' },
|
||||||
// Surface the authoritative chatId on the streamed assistant UI message so
|
// Surface the authoritative chatId on the streamed assistant UI message so
|
||||||
// the client adopts the REAL id of the row we created, instead of guessing
|
// the client adopts the REAL id of the row we created, instead of guessing
|
||||||
@@ -1412,25 +1239,12 @@ export class AiChatService implements OnModuleInit {
|
|||||||
// finalizeRun (onSettled) is idempotent — a settle here and a settle from a
|
// finalizeRun (onSettled) is idempotent — a settle here and a settle from a
|
||||||
// streamText callback collapse to a single terminal write.
|
// streamText callback collapse to a single terminal write.
|
||||||
if (runId) {
|
if (runId) {
|
||||||
// #184 phase 1.5: a failure here means the tee `done` will never arrive,
|
|
||||||
// so release the registry entry's subscribers explicitly — otherwise an
|
|
||||||
// attached tab hangs forever. Same flag gate as the tee wiring above.
|
|
||||||
if (this.environment?.isAiChatResumableStreamEnabled?.()) {
|
|
||||||
this.streamRegistry?.abortEntry(chatId, runId);
|
|
||||||
}
|
|
||||||
// Distinguish an explicit Stop (the run's signal aborted during setup) from
|
|
||||||
// a real failure, so the run settles with the correct terminal status
|
|
||||||
// instead of always 'error'. onSettled/finalizeRun is idempotent, so this
|
|
||||||
// is safe even if a streamText callback also settles the run.
|
|
||||||
const settleStatus = effectiveSignal.aborted ? 'aborted' : 'error';
|
|
||||||
await runHooks?.onSettled?.(
|
await runHooks?.onSettled?.(
|
||||||
runId,
|
runId,
|
||||||
settleStatus,
|
'error',
|
||||||
settleStatus === 'aborted'
|
err instanceof Error
|
||||||
? undefined
|
? err.message
|
||||||
: err instanceof Error
|
: 'Agent run failed before streaming started',
|
||||||
? err.message
|
|
||||||
: 'Agent run failed before streaming started',
|
|
||||||
);
|
);
|
||||||
}
|
}
|
||||||
throw err;
|
throw err;
|
||||||
@@ -1876,45 +1690,6 @@ export async function applyFinalize(
|
|||||||
});
|
});
|
||||||
}
|
}
|
||||||
|
|
||||||
/**
|
|
||||||
* Deep-strip NUL characters (`\u0000`) from every string in a value, returning
|
|
||||||
* the SAME reference when nothing changed (so the no-NUL common case allocates
|
|
||||||
* nothing). Postgres rejects a NUL in BOTH `text` and `jsonb` columns ("invalid
|
|
||||||
* input syntax for type json" / "unsupported Unicode escape sequence"), so a
|
|
||||||
* stray NUL in model output or a tool result — e.g. a truncated multibyte read
|
|
||||||
* of a web page — otherwise fails EVERY persist of the assistant row, silently
|
|
||||||
* dropping that turn's content from the DB while the live stream still shows it.
|
|
||||||
* Applied at the flushAssistant choke point so content + toolCalls + metadata are
|
|
||||||
* all covered. Exported for the unit test.
|
|
||||||
*/
|
|
||||||
export function stripNulChars<T>(value: T): T {
|
|
||||||
if (typeof value === 'string') {
|
|
||||||
return (value.includes('\u0000')
|
|
||||||
? value.replace(/\u0000/g, '')
|
|
||||||
: value) as T;
|
|
||||||
}
|
|
||||||
if (Array.isArray(value)) {
|
|
||||||
let changed = false;
|
|
||||||
const out = value.map((v) => {
|
|
||||||
const s = stripNulChars(v);
|
|
||||||
if (s !== v) changed = true;
|
|
||||||
return s;
|
|
||||||
});
|
|
||||||
return (changed ? out : value) as T;
|
|
||||||
}
|
|
||||||
if (value && typeof value === 'object') {
|
|
||||||
let changed = false;
|
|
||||||
const out: Record<string, unknown> = {};
|
|
||||||
for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
|
|
||||||
const s = stripNulChars(v);
|
|
||||||
if (s !== v) changed = true;
|
|
||||||
out[k] = s;
|
|
||||||
}
|
|
||||||
return (changed ? out : value) as T;
|
|
||||||
}
|
|
||||||
return value;
|
|
||||||
}
|
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* PURE assistant-row builder (#183 step-granular durability). Given the turn's
|
* PURE assistant-row builder (#183 step-granular durability). Given the turn's
|
||||||
* accumulated steps + the in-progress (not-yet-finished) text + the lifecycle
|
* accumulated steps + the in-progress (not-yet-finished) text + the lifecycle
|
||||||
@@ -1984,16 +1759,12 @@ export function flushAssistant(
|
|||||||
};
|
};
|
||||||
}
|
}
|
||||||
|
|
||||||
// Strip NUL chars from the whole row before persisting: Postgres rejects a NUL
|
return {
|
||||||
// in both the `content` (text) and `toolCalls`/`metadata` (jsonb) columns, and a
|
|
||||||
// single stray NUL in model/tool output would otherwise fail EVERY write of this
|
|
||||||
// row and silently drop the turn's content from the DB (see stripNulChars).
|
|
||||||
return stripNulChars({
|
|
||||||
content: stepsText + trailing,
|
content: stepsText + trailing,
|
||||||
toolCalls: serializeSteps(finished),
|
toolCalls: serializeSteps(finished),
|
||||||
metadata,
|
metadata,
|
||||||
status,
|
status,
|
||||||
});
|
};
|
||||||
}
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
|
|||||||
@@ -181,25 +181,25 @@ describe('mcp timeout env helpers', () => {
|
|||||||
else process.env.AI_MCP_CALL_TIMEOUT_MS = ORIG_CALL;
|
else process.env.AI_MCP_CALL_TIMEOUT_MS = ORIG_CALL;
|
||||||
});
|
});
|
||||||
|
|
||||||
it('mcpStreamTimeoutMs defaults to 1 min and honors a positive override', () => {
|
it('mcpStreamTimeoutMs defaults to 5 min and honors a positive override', () => {
|
||||||
delete process.env.AI_MCP_STREAM_TIMEOUT_MS;
|
delete process.env.AI_MCP_STREAM_TIMEOUT_MS;
|
||||||
|
expect(mcpStreamTimeoutMs()).toBe(300_000);
|
||||||
|
process.env.AI_MCP_STREAM_TIMEOUT_MS = '60000';
|
||||||
expect(mcpStreamTimeoutMs()).toBe(60_000);
|
expect(mcpStreamTimeoutMs()).toBe(60_000);
|
||||||
process.env.AI_MCP_STREAM_TIMEOUT_MS = '90000';
|
|
||||||
expect(mcpStreamTimeoutMs()).toBe(90_000);
|
|
||||||
for (const bad of ['0', '-1', 'x', '']) {
|
for (const bad of ['0', '-1', 'x', '']) {
|
||||||
process.env.AI_MCP_STREAM_TIMEOUT_MS = bad;
|
process.env.AI_MCP_STREAM_TIMEOUT_MS = bad;
|
||||||
expect(mcpStreamTimeoutMs()).toBe(60_000);
|
expect(mcpStreamTimeoutMs()).toBe(300_000);
|
||||||
}
|
}
|
||||||
});
|
});
|
||||||
|
|
||||||
it('mcpCallTimeoutMs defaults to 2 min and honors a positive override', () => {
|
it('mcpCallTimeoutMs defaults to 15 min and honors a positive override', () => {
|
||||||
delete process.env.AI_MCP_CALL_TIMEOUT_MS;
|
delete process.env.AI_MCP_CALL_TIMEOUT_MS;
|
||||||
|
expect(mcpCallTimeoutMs()).toBe(900_000);
|
||||||
|
process.env.AI_MCP_CALL_TIMEOUT_MS = '120000';
|
||||||
expect(mcpCallTimeoutMs()).toBe(120_000);
|
expect(mcpCallTimeoutMs()).toBe(120_000);
|
||||||
process.env.AI_MCP_CALL_TIMEOUT_MS = '180000';
|
|
||||||
expect(mcpCallTimeoutMs()).toBe(180_000);
|
|
||||||
for (const bad of ['0', '-1', 'x', '']) {
|
for (const bad of ['0', '-1', 'x', '']) {
|
||||||
process.env.AI_MCP_CALL_TIMEOUT_MS = bad;
|
process.env.AI_MCP_CALL_TIMEOUT_MS = bad;
|
||||||
expect(mcpCallTimeoutMs()).toBe(120_000);
|
expect(mcpCallTimeoutMs()).toBe(900_000);
|
||||||
}
|
}
|
||||||
});
|
});
|
||||||
});
|
});
|
||||||
|
|||||||
@@ -1,237 +0,0 @@
|
|||||||
import { McpClientsService } from './mcp-clients.service';
|
|
||||||
|
|
||||||
/**
|
|
||||||
* D1 — a HUNG MCP handshake must not POISON the per-workspace build cache.
|
|
||||||
*
|
|
||||||
* THE BUG (production hang): `createMCPClient` (inside the private `connect`) is
|
|
||||||
* NOT bounded by a timeout and — like @ai-sdk/mcp's tool calls — its promise does
|
|
||||||
* NOT settle on abort. A transient network blip mid-handshake made connect hang
|
|
||||||
* FOREVER. Because getOrBuildEntry caches the build PROMISE, that never-settling
|
|
||||||
* connect wedged EVERY later turn for the workspace (each awaited the same pending
|
|
||||||
* build) — step_count stuck at 0, run row leaking 'running', chat 409ing forever.
|
|
||||||
*
|
|
||||||
* THE FIX: `connectWithTimeout` races `connect` against a SETTLING timeout
|
|
||||||
* (CONNECT_TIMEOUT_MS). On timeout it REJECTS, so buildEntry catches it, records
|
|
||||||
* the server `ok:false`, and the build COMPLETES with that server skipped — the
|
|
||||||
* cache is never poisoned and a subsequent `toolsFor` returns instead of hanging.
|
|
||||||
*
|
|
||||||
* REACHABILITY NOTE: the smallest network-free path that exercises the fix is to
|
|
||||||
* spy on the private `connect` (the same harness the namespacing spec uses) —
|
|
||||||
* `connectWithTimeout` wraps exactly that call, so a never-resolving `connect`
|
|
||||||
* models a never-settling `createMCPClient` precisely, without DNS/sockets.
|
|
||||||
*
|
|
||||||
* Fake timers prove the timeout fires WITHOUT real waiting.
|
|
||||||
*/
|
|
||||||
|
|
||||||
// Mirrors the private CONNECT_TIMEOUT_MS constant in mcp-clients.service.ts.
|
|
||||||
const CONNECT_TIMEOUT_MS = 5000;
|
|
||||||
|
|
||||||
interface FakeServer {
|
|
||||||
id: string;
|
|
||||||
name: string;
|
|
||||||
transport: string;
|
|
||||||
url: string;
|
|
||||||
headersEnc: string | null;
|
|
||||||
toolAllowlist: string[] | null;
|
|
||||||
instructions?: string | null;
|
|
||||||
}
|
|
||||||
|
|
||||||
function server(
|
|
||||||
over: Partial<FakeServer> & { id: string; name: string },
|
|
||||||
): FakeServer {
|
|
||||||
return {
|
|
||||||
transport: 'http',
|
|
||||||
url: 'https://example.com/mcp',
|
|
||||||
headersEnc: null,
|
|
||||||
toolAllowlist: null,
|
|
||||||
...over,
|
|
||||||
};
|
|
||||||
}
|
|
||||||
|
|
||||||
function buildService(servers: FakeServer[]) {
|
|
||||||
const repoStub = { listEnabled: jest.fn().mockResolvedValue(servers) };
|
|
||||||
const service = new McpClientsService(repoStub as never, {} as never);
|
|
||||||
// Silence the expected "server unavailable" warning.
|
|
||||||
jest
|
|
||||||
.spyOn(
|
|
||||||
(service as unknown as { logger: { warn: (...a: unknown[]) => void } })
|
|
||||||
.logger,
|
|
||||||
'warn',
|
|
||||||
)
|
|
||||||
.mockImplementation(() => undefined);
|
|
||||||
return service;
|
|
||||||
}
|
|
||||||
|
|
||||||
// Spy on the private `connect` with a per-server implementation.
|
|
||||||
function stubConnect(
|
|
||||||
service: McpClientsService,
|
|
||||||
impl: (s: FakeServer) => Promise<unknown>,
|
|
||||||
) {
|
|
||||||
return jest
|
|
||||||
.spyOn(
|
|
||||||
service as unknown as { connect: (s: FakeServer) => Promise<unknown> },
|
|
||||||
'connect',
|
|
||||||
)
|
|
||||||
.mockImplementation(impl);
|
|
||||||
}
|
|
||||||
|
|
||||||
describe('McpClientsService.connectWithTimeout — hung connect does not poison the cache (D1)', () => {
|
|
||||||
beforeEach(() => jest.useFakeTimers());
|
|
||||||
afterEach(() => {
|
|
||||||
jest.clearAllTimers();
|
|
||||||
jest.useRealTimers();
|
|
||||||
jest.restoreAllMocks();
|
|
||||||
});
|
|
||||||
|
|
||||||
it('buildEntry completes (server recorded ok:false) when connect never settles, and toolsFor does not hang', async () => {
|
|
||||||
const svc = buildService([server({ id: 'id-hung', name: 'hung' })]);
|
|
||||||
// connect NEVER settles — models a wedged createMCPClient handshake.
|
|
||||||
stubConnect(svc, () => new Promise<never>(() => {}));
|
|
||||||
|
|
||||||
const toolsetPromise = svc.toolsFor('ws-1');
|
|
||||||
// Drive fake time past the connect bound so connectWithTimeout rejects and
|
|
||||||
// buildEntry catches it (records ok:false) — flushing the microtasks.
|
|
||||||
await jest.advanceTimersByTimeAsync(CONNECT_TIMEOUT_MS + 1);
|
|
||||||
|
|
||||||
const toolset = await toolsetPromise;
|
|
||||||
// The build COMPLETED with the bad server skipped (no tools, ok:false).
|
|
||||||
expect(Object.keys(toolset.tools)).toHaveLength(0);
|
|
||||||
expect(toolset.outcomes).toEqual([
|
|
||||||
{ name: 'hung', ok: false, reason: 'MCP connect timed out after 5000ms' },
|
|
||||||
]);
|
|
||||||
await Promise.all(toolset.clients.map((c) => c.close()));
|
|
||||||
|
|
||||||
// The cache is NOT poisoned: a subsequent turn returns (served from the warm
|
|
||||||
// cached entry) instead of awaiting a never-settling build.
|
|
||||||
const again = await svc.toolsFor('ws-1');
|
|
||||||
expect(Object.keys(again.tools)).toHaveLength(0);
|
|
||||||
await Promise.all(again.clients.map((c) => c.close()));
|
|
||||||
});
|
|
||||||
|
|
||||||
it('a hung server is skipped but a healthy server in the SAME build still contributes its tools', async () => {
|
|
||||||
const svc = buildService([
|
|
||||||
server({ id: 'id-hung', name: 'hung' }),
|
|
||||||
server({ id: 'id-ok', name: 'ok' }),
|
|
||||||
]);
|
|
||||||
const okClient = {
|
|
||||||
tools: () => Promise.resolve({ search: { description: 'x' } }),
|
|
||||||
close: jest.fn().mockResolvedValue(undefined),
|
|
||||||
};
|
|
||||||
stubConnect(svc, (s) =>
|
|
||||||
s.id === 'id-hung'
|
|
||||||
? new Promise<never>(() => {})
|
|
||||||
: Promise.resolve(okClient),
|
|
||||||
);
|
|
||||||
|
|
||||||
const toolsetPromise = svc.toolsFor('ws-2');
|
|
||||||
await jest.advanceTimersByTimeAsync(CONNECT_TIMEOUT_MS + 1);
|
|
||||||
|
|
||||||
const toolset = await toolsetPromise;
|
|
||||||
// Healthy server's tool survives (namespaced); hung server recorded ok:false.
|
|
||||||
expect(Object.keys(toolset.tools)).toEqual(['ok_search']);
|
|
||||||
expect(toolset.outcomes).toEqual([
|
|
||||||
{ name: 'hung', ok: false, reason: 'MCP connect timed out after 5000ms' },
|
|
||||||
{ name: 'ok', ok: true },
|
|
||||||
]);
|
|
||||||
await Promise.all(toolset.clients.map((c) => c.close()));
|
|
||||||
});
|
|
||||||
|
|
||||||
it('closes the ORPHANED client when connect resolves LATE (after the timeout)', async () => {
|
|
||||||
const svc = buildService([server({ id: 'id-late', name: 'late' })]);
|
|
||||||
const lateClient = {
|
|
||||||
tools: () => Promise.resolve({}),
|
|
||||||
close: jest.fn().mockResolvedValue(undefined),
|
|
||||||
};
|
|
||||||
// connect resolves only AFTER the connect bound has already elapsed, so
|
|
||||||
// connectWithTimeout has already rejected and must close this orphan.
|
|
||||||
stubConnect(
|
|
||||||
svc,
|
|
||||||
() =>
|
|
||||||
new Promise((resolve) => {
|
|
||||||
setTimeout(() => resolve(lateClient), CONNECT_TIMEOUT_MS * 2);
|
|
||||||
}),
|
|
||||||
);
|
|
||||||
|
|
||||||
const toolsetPromise = svc.toolsFor('ws-3');
|
|
||||||
// Fire the timeout: the build completes with the server skipped.
|
|
||||||
await jest.advanceTimersByTimeAsync(CONNECT_TIMEOUT_MS + 1);
|
|
||||||
const toolset = await toolsetPromise;
|
|
||||||
expect(toolset.outcomes[0]?.ok).toBe(false);
|
|
||||||
expect(lateClient.close).not.toHaveBeenCalled();
|
|
||||||
|
|
||||||
// Now let the late connect resolve — the orphan must be closed, not leaked.
|
|
||||||
await jest.advanceTimersByTimeAsync(CONNECT_TIMEOUT_MS * 2);
|
|
||||||
expect(lateClient.close).toHaveBeenCalledTimes(1);
|
|
||||||
|
|
||||||
await Promise.all(toolset.clients.map((c) => c.close()));
|
|
||||||
});
|
|
||||||
});
|
|
||||||
|
|
||||||
describe('McpClientsService.buildEntry — closes a connected client whose tools() fails (leak fix)', () => {
|
|
||||||
beforeEach(() => jest.useFakeTimers());
|
|
||||||
afterEach(() => {
|
|
||||||
jest.clearAllTimers();
|
|
||||||
jest.useRealTimers();
|
|
||||||
jest.restoreAllMocks();
|
|
||||||
});
|
|
||||||
|
|
||||||
it('connect succeeds but tools() REJECTS: the client is close()d exactly once and the server is skipped, while a healthy server still contributes', async () => {
|
|
||||||
const svc = buildService([
|
|
||||||
server({ id: 'id-bad', name: 'bad' }),
|
|
||||||
server({ id: 'id-ok', name: 'ok' }),
|
|
||||||
]);
|
|
||||||
// The bad server connects fine, then tools() rejects — the client would leak if
|
|
||||||
// buildEntry did not close it in the per-server catch (it was never registered).
|
|
||||||
const badClient = {
|
|
||||||
tools: () => Promise.reject(new Error('tools listing failed')),
|
|
||||||
close: jest.fn().mockResolvedValue(undefined),
|
|
||||||
};
|
|
||||||
const okClient = {
|
|
||||||
tools: () => Promise.resolve({ search: { description: 'x' } }),
|
|
||||||
close: jest.fn().mockResolvedValue(undefined),
|
|
||||||
};
|
|
||||||
stubConnect(svc, (s) =>
|
|
||||||
s.id === 'id-bad' ? Promise.resolve(badClient) : Promise.resolve(okClient),
|
|
||||||
);
|
|
||||||
|
|
||||||
const toolset = await svc.toolsFor('ws-4');
|
|
||||||
|
|
||||||
// The orphaned (never-registered) client is closed exactly once — no leak.
|
|
||||||
expect(badClient.close).toHaveBeenCalledTimes(1);
|
|
||||||
// Healthy server survives; bad server recorded ok:false and skipped.
|
|
||||||
expect(Object.keys(toolset.tools)).toEqual(['ok_search']);
|
|
||||||
expect(toolset.outcomes).toEqual([
|
|
||||||
{ name: 'bad', ok: false, reason: 'tools listing failed' },
|
|
||||||
{ name: 'ok', ok: true },
|
|
||||||
]);
|
|
||||||
|
|
||||||
// The healthy (registered) client is NOT closed by the loop — it is owned by the
|
|
||||||
// cache entry and stays warm (closed only on eviction/teardown, not on lease
|
|
||||||
// release). Releasing the lease keeps it warm since the entry is not evicted.
|
|
||||||
expect(okClient.close).not.toHaveBeenCalled();
|
|
||||||
await Promise.all(toolset.clients.map((c) => c.close()));
|
|
||||||
expect(okClient.close).not.toHaveBeenCalled();
|
|
||||||
// The failed client is never double-closed.
|
|
||||||
expect(badClient.close).toHaveBeenCalledTimes(1);
|
|
||||||
});
|
|
||||||
|
|
||||||
it('connect succeeds but tools() HANGS (times out): the client is close()d once and the server is skipped', async () => {
|
|
||||||
const svc = buildService([server({ id: 'id-slow', name: 'slow' })]);
|
|
||||||
const slowClient = {
|
|
||||||
// tools() never settles -> withTimeout rejects after CONNECT_TIMEOUT_MS.
|
|
||||||
tools: () => new Promise<Record<string, never>>(() => {}),
|
|
||||||
close: jest.fn().mockResolvedValue(undefined),
|
|
||||||
};
|
|
||||||
stubConnect(svc, () => Promise.resolve(slowClient));
|
|
||||||
|
|
||||||
const toolsetPromise = svc.toolsFor('ws-5');
|
|
||||||
// Drive fake time past the tools() bound so withTimeout rejects.
|
|
||||||
await jest.advanceTimersByTimeAsync(CONNECT_TIMEOUT_MS + 1);
|
|
||||||
const toolset = await toolsetPromise;
|
|
||||||
|
|
||||||
expect(slowClient.close).toHaveBeenCalledTimes(1);
|
|
||||||
expect(Object.keys(toolset.tools)).toHaveLength(0);
|
|
||||||
expect(toolset.outcomes[0]?.ok).toBe(false);
|
|
||||||
await Promise.all(toolset.clients.map((c) => c.close()));
|
|
||||||
});
|
|
||||||
});
|
|
||||||
@@ -195,7 +195,7 @@ export class McpClientsService {
|
|||||||
): Promise<{ ok: true; tools: string[] } | { ok: false; error: string }> {
|
): Promise<{ ok: true; tools: string[] } | { ok: false; error: string }> {
|
||||||
let client: McpClient | undefined;
|
let client: McpClient | undefined;
|
||||||
try {
|
try {
|
||||||
client = await this.connectWithTimeout(server, CONNECT_TIMEOUT_MS);
|
client = await this.connect(server);
|
||||||
const raw = await withTimeout(client.tools(), CONNECT_TIMEOUT_MS);
|
const raw = await withTimeout(client.tools(), CONNECT_TIMEOUT_MS);
|
||||||
return { ok: true, tools: Object.keys(raw) };
|
return { ok: true, tools: Object.keys(raw) };
|
||||||
} catch (err) {
|
} catch (err) {
|
||||||
@@ -256,18 +256,10 @@ export class McpClientsService {
|
|||||||
const instructions: McpServerInstruction[] = [];
|
const instructions: McpServerInstruction[] = [];
|
||||||
|
|
||||||
for (const server of servers) {
|
for (const server of servers) {
|
||||||
// Track the connected client OUTSIDE the try so the catch can close it when
|
|
||||||
// it was obtained but not yet registered in `clients` (e.g. tools() threw or
|
|
||||||
// timed out after a successful connect). `registered` flips only once the
|
|
||||||
// client is owned by `clients` (closed at entry teardown), so the catch never
|
|
||||||
// double-closes a registered client.
|
|
||||||
let client: McpClient | undefined;
|
|
||||||
let registered = false;
|
|
||||||
try {
|
try {
|
||||||
client = await this.connectWithTimeout(server, CONNECT_TIMEOUT_MS);
|
const client = await this.connect(server);
|
||||||
const raw = await withTimeout(client.tools(), CONNECT_TIMEOUT_MS);
|
const raw = await withTimeout(client.tools(), CONNECT_TIMEOUT_MS);
|
||||||
clients.push(client);
|
clients.push(client);
|
||||||
registered = true;
|
|
||||||
const allow = server.toolAllowlist;
|
const allow = server.toolAllowlist;
|
||||||
const picked =
|
const picked =
|
||||||
Array.isArray(allow) && allow.length > 0 ? pick(raw, allow) : raw;
|
Array.isArray(allow) && allow.length > 0 ? pick(raw, allow) : raw;
|
||||||
@@ -298,15 +290,9 @@ export class McpClientsService {
|
|||||||
});
|
});
|
||||||
}
|
}
|
||||||
} catch (err) {
|
} catch (err) {
|
||||||
// A failed server is skipped — the turn proceeds with the rest. If connect
|
// A failed server is skipped — the turn proceeds with the rest. Log a
|
||||||
// returned a live client but a later step (tools()) threw, that client was
|
// short warning (never the URL/headers) so ops can see degradation, and
|
||||||
// never registered in `clients`, so close it here or its transport/socket
|
// record the outcome so the UI can show "tool X unavailable".
|
||||||
// leaks (compounding every 60s cache rebuild during a flaky-server outage).
|
|
||||||
if (client && !registered) {
|
|
||||||
void client.close().catch(() => undefined);
|
|
||||||
}
|
|
||||||
// Log a short warning (never the URL/headers) so ops can see degradation,
|
|
||||||
// and record the outcome so the UI can show "tool X unavailable".
|
|
||||||
const reason = shortError(err);
|
const reason = shortError(err);
|
||||||
this.logger.warn(
|
this.logger.warn(
|
||||||
`External MCP server "${server.name}" unavailable: ${reason}`,
|
`External MCP server "${server.name}" unavailable: ${reason}`,
|
||||||
@@ -397,55 +383,6 @@ export class McpClientsService {
|
|||||||
return client;
|
return client;
|
||||||
}
|
}
|
||||||
|
|
||||||
/**
|
|
||||||
* Race {@link connect} against a SETTLING timeout so a hung MCP handshake can
|
|
||||||
* never POISON the per-workspace build cache. `createMCPClient` (inside connect)
|
|
||||||
* is NOT bounded internally, and — exactly like @ai-sdk/mcp's tool calls
|
|
||||||
* (see wrapToolWithCallTimeout) — its promise does NOT settle on abort. So a
|
|
||||||
* transient network blip mid-handshake can make connect hang FOREVER. Because
|
|
||||||
* getOrBuildEntry caches the build PROMISE, a never-settling connect would then
|
|
||||||
* wedge EVERY later turn for the workspace (each awaits the same pending build,
|
|
||||||
* step_count stuck at 0, run row leaks 'running', chat 409s forever). Bounding
|
|
||||||
* connect here guarantees buildEntry always gets a client OR a rejection within
|
|
||||||
* `ms` — so the build completes (bad server skipped) and the cache stays clean.
|
|
||||||
*
|
|
||||||
* If connect resolves LATE (after we already rejected on the timeout), we close
|
|
||||||
* the orphaned client so its transport/socket is not leaked.
|
|
||||||
*/
|
|
||||||
private connectWithTimeout(
|
|
||||||
server: Pick<AiMcpServer, 'transport' | 'url' | 'headersEnc'>,
|
|
||||||
ms: number,
|
|
||||||
): Promise<McpClient> {
|
|
||||||
return new Promise<McpClient>((resolve, reject) => {
|
|
||||||
let settled = false;
|
|
||||||
const timer = setTimeout(() => {
|
|
||||||
settled = true;
|
|
||||||
reject(new Error(`MCP connect timed out after ${ms}ms`));
|
|
||||||
}, ms);
|
|
||||||
// Do not keep the process alive just for this connect-timeout timer.
|
|
||||||
timer.unref?.();
|
|
||||||
this.connect(server).then(
|
|
||||||
(client) => {
|
|
||||||
if (settled) {
|
|
||||||
// The race was already lost to the timeout: close the orphaned client
|
|
||||||
// so its socket is not leaked, and drop the late result.
|
|
||||||
void client.close().catch(() => undefined);
|
|
||||||
return;
|
|
||||||
}
|
|
||||||
clearTimeout(timer);
|
|
||||||
settled = true;
|
|
||||||
resolve(client);
|
|
||||||
},
|
|
||||||
(err: unknown) => {
|
|
||||||
if (settled) return; // late rejection after the timeout — already handled
|
|
||||||
clearTimeout(timer);
|
|
||||||
settled = true;
|
|
||||||
reject(err instanceof Error ? err : new Error(String(err)));
|
|
||||||
},
|
|
||||||
);
|
|
||||||
});
|
|
||||||
}
|
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Decrypt the stored auth headers. Returns undefined when none are set. The
|
* Decrypt the stored auth headers. Returns undefined when none are set. The
|
||||||
* plaintext headers live only in this returned object and are passed straight
|
* plaintext headers live only in this returned object and are passed straight
|
||||||
@@ -523,12 +460,12 @@ export function validateResolvedAddresses(addrs: readonly LookupAddress[]): {
|
|||||||
*/
|
*/
|
||||||
function buildPinnedDispatcher(): Agent {
|
function buildPinnedDispatcher(): Agent {
|
||||||
// External-MCP traffic uses a DEDICATED, shorter silence timeout
|
// External-MCP traffic uses a DEDICATED, shorter silence timeout
|
||||||
// (`AI_MCP_STREAM_TIMEOUT_MS`, default 1 min) — deliberately tighter than the
|
// (`AI_MCP_STREAM_TIMEOUT_MS`, default 5 min) — deliberately tighter than the
|
||||||
// chat provider's 15-min `streamTimeoutMs()` — so a byte-silent/hung MCP
|
// chat provider's 15-min `streamTimeoutMs()` — so a byte-silent/hung MCP
|
||||||
// upstream is broken in ~1 min instead of 15. We keep the keep-alive options
|
// upstream is broken in ~5 min instead of 15. We keep the keep-alive options
|
||||||
// from `streamingDispatcherOptions()` but OVERRIDE headers/body timeouts.
|
// from `streamingDispatcherOptions()` but OVERRIDE headers/body timeouts.
|
||||||
// Accepted trade-off: a legitimately long but byte-silent single tool call,
|
// Accepted trade-off: a legitimately long but byte-silent single tool call,
|
||||||
// and an SSE transport idling >1 min BETWEEN tool calls, are also cut here; the
|
// and an SSE transport idling >5 min BETWEEN tool calls, are also cut here; the
|
||||||
// per-call total cap (wrapToolsWithCallTimeout, `AI_MCP_CALL_TIMEOUT_MS`) is the
|
// per-call total cap (wrapToolsWithCallTimeout, `AI_MCP_CALL_TIMEOUT_MS`) is the
|
||||||
// complementary guard for chatty-but-stuck calls that keep the socket warm yet
|
// complementary guard for chatty-but-stuck calls that keep the socket warm yet
|
||||||
// never return.
|
// never return.
|
||||||
|
|||||||
@@ -651,69 +651,3 @@ describe('AiChatToolsService #294 changed execute wirings', () => {
|
|||||||
expect(calls.tableUpdateCell).toEqual([['p1', '#0', 1, 2, 'x']]);
|
expect(calls.tableUpdateCell).toEqual([['p1', '#0', 1, 2, 'x']]);
|
||||||
});
|
});
|
||||||
});
|
});
|
||||||
|
|
||||||
/**
|
|
||||||
* getCurrentPage selection contract (#388): the tool surfaces the selection that
|
|
||||||
* was sanitized + nested onto the resolved open-page context (last forUser arg).
|
|
||||||
* No page => selection is null. The tool never fetches or verifies anything — it
|
|
||||||
* just projects the resolved context.
|
|
||||||
*/
|
|
||||||
describe('AiChatToolsService getCurrentPage selection (#388)', () => {
|
|
||||||
const tokenServiceStub = {
|
|
||||||
generateAccessToken: jest.fn().mockResolvedValue('access-token'),
|
|
||||||
generateCollabToken: jest.fn().mockResolvedValue('collab-token'),
|
|
||||||
};
|
|
||||||
|
|
||||||
let service: AiChatToolsService;
|
|
||||||
|
|
||||||
beforeEach(() => {
|
|
||||||
jest.spyOn(loader, 'loadDocmostMcp').mockResolvedValue(
|
|
||||||
mockLoaded(function () {
|
|
||||||
return {} as DocmostClientLike;
|
|
||||||
} as unknown as loader.DocmostClientCtor),
|
|
||||||
);
|
|
||||||
service = new AiChatToolsService(
|
|
||||||
tokenServiceStub as never,
|
|
||||||
{} as never,
|
|
||||||
{} as never,
|
|
||||||
{} as never,
|
|
||||||
{} as never,
|
|
||||||
{
|
|
||||||
asSink: () => ({ put: jest.fn(), has: jest.fn(), evict: jest.fn() }),
|
|
||||||
} as never,
|
|
||||||
);
|
|
||||||
});
|
|
||||||
|
|
||||||
afterEach(() => jest.restoreAllMocks());
|
|
||||||
|
|
||||||
const buildTools = (openedPage: unknown) =>
|
|
||||||
service.forUser(
|
|
||||||
{ id: 'user-1', email: 'u@example.com', workspaceId: 'ws-1' } as never,
|
|
||||||
'session-1',
|
|
||||||
'ws-1',
|
|
||||||
'chat-1',
|
|
||||||
openedPage as never,
|
|
||||||
);
|
|
||||||
|
|
||||||
it('returns the nested selection from the resolved context', async () => {
|
|
||||||
const selection = { text: 'fix this', blockIds: ['b1'], before: 'a ' };
|
|
||||||
const tools = await buildTools({ id: 'p1', title: 'Doc', selection });
|
|
||||||
expect(await tools.getCurrentPage.execute({} as never, {} as never)).toEqual(
|
|
||||||
{ page: { id: 'p1', title: 'Doc' }, selection },
|
|
||||||
);
|
|
||||||
});
|
|
||||||
|
|
||||||
it('returns selection: null when the context has no selection', async () => {
|
|
||||||
const tools = await buildTools({ id: 'p1', title: 'Doc' });
|
|
||||||
expect(await tools.getCurrentPage.execute({} as never, {} as never)).toEqual(
|
|
||||||
{ page: { id: 'p1', title: 'Doc' }, selection: null },
|
|
||||||
);
|
|
||||||
});
|
|
||||||
|
|
||||||
it('returns { page: null, selection: null } when no page is open', async () => {
|
|
||||||
const tools = await buildTools(null);
|
|
||||||
expect(await tools.getCurrentPage.execute({} as never, {} as never)).toEqual(
|
|
||||||
{ page: null, selection: null },
|
|
||||||
);
|
|
||||||
});
|
|
||||||
});
|
|
||||||
|
|||||||
@@ -13,10 +13,7 @@ import {
|
|||||||
type DocmostClientLike,
|
type DocmostClientLike,
|
||||||
type SharedToolSpec,
|
type SharedToolSpec,
|
||||||
} from './docmost-client.loader';
|
} from './docmost-client.loader';
|
||||||
import {
|
import { resolveCurrentPageResult } from './current-page.util';
|
||||||
resolveCurrentPageResult,
|
|
||||||
type SelectionContext,
|
|
||||||
} from './current-page.util';
|
|
||||||
import { parseNodeArg } from './parse-node-arg';
|
import { parseNodeArg } from './parse-node-arg';
|
||||||
import { modelFriendlyInput } from './model-friendly-input';
|
import { modelFriendlyInput } from './model-friendly-input';
|
||||||
import { SandboxStore } from '../../../integrations/sandbox/sandbox.store';
|
import { SandboxStore } from '../../../integrations/sandbox/sandbox.store';
|
||||||
@@ -156,13 +153,8 @@ export class AiChatToolsService {
|
|||||||
// The page the user currently has open (from the request context), exposed
|
// The page the user currently has open (from the request context), exposed
|
||||||
// to the model via getCurrentPage. Optional and last so existing callers
|
// to the model via getCurrentPage. Optional and last so existing callers
|
||||||
// keep compiling. Kept proxy-robust: the model can CALL for the current
|
// keep compiling. Kept proxy-robust: the model can CALL for the current
|
||||||
// page instead of relying on it surviving in the system prompt text. The
|
// page instead of relying on it surviving in the system prompt text.
|
||||||
// `selection` (#388) is already sanitized + nested by resolveOpenPageContext.
|
openedPage?: { id?: string; title?: string } | null,
|
||||||
openedPage?: {
|
|
||||||
id?: string;
|
|
||||||
title?: string;
|
|
||||||
selection?: SelectionContext | null;
|
|
||||||
} | null,
|
|
||||||
): Promise<Record<string, Tool>> {
|
): Promise<Record<string, Tool>> {
|
||||||
// Build the per-user loopback client (carrying the access + collab
|
// Build the per-user loopback client (carrying the access + collab
|
||||||
// provenance tokens) and load the shared tool-spec registry. Client
|
// provenance tokens) and load the shared tool-spec registry. Client
|
||||||
@@ -317,15 +309,9 @@ export class AiChatToolsService {
|
|||||||
getCurrentPage: tool({
|
getCurrentPage: tool({
|
||||||
description:
|
description:
|
||||||
'Return the page the user is currently viewing — i.e. what "this page", ' +
|
'Return the page the user is currently viewing — i.e. what "this page", ' +
|
||||||
'"the current page", or "here" refers to — plus the text the user ' +
|
'"the current page", or "here" refers to. Returns the page id and title, ' +
|
||||||
'currently has SELECTED on that page (what "this", "here", "the selected ' +
|
'or null if the user is not currently on a page. Call this first whenever ' +
|
||||||
'fragment" refers to), or selection: null when nothing is selected. The ' +
|
'the user refers to the current page without giving an explicit id.',
|
||||||
'selection is a client-side snapshot taken when the user sent the message ' +
|
|
||||||
'and includes the ids of the blocks it covers plus surrounding context; ' +
|
|
||||||
'it is NOT verified server-side — locate it in the page (searchInPage / ' +
|
|
||||||
'getNode) before editing. Returns page: null if the user is not currently ' +
|
|
||||||
'on a page. Call this first whenever the user refers to the current page ' +
|
|
||||||
'or a selected fragment without giving an explicit id.',
|
|
||||||
inputSchema: modelFriendlyInput({}),
|
inputSchema: modelFriendlyInput({}),
|
||||||
execute: async () => resolveCurrentPageResult(openedPage),
|
execute: async () => resolveCurrentPageResult(openedPage),
|
||||||
}),
|
}),
|
||||||
|
|||||||
@@ -1,180 +1,43 @@
|
|||||||
import {
|
import { resolveCurrentPageResult } from './current-page.util';
|
||||||
resolveCurrentPageResult,
|
|
||||||
sanitizeSelection,
|
|
||||||
} from './current-page.util';
|
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Unit tests for resolveCurrentPageResult (pure function). Mirrors the
|
* Unit tests for resolveCurrentPageResult (pure function). Mirrors the
|
||||||
* getCurrentPage tool's contract: { page: null, selection: null } when no page
|
* getCurrentPage tool's contract: { page: null } when no page is open (no id),
|
||||||
* is open (no id), otherwise { page: { id, title }, selection } with title
|
* otherwise { page: { id, title } } with title defaulting to ''.
|
||||||
* defaulting to '' and the selection passed through from the resolved context.
|
|
||||||
*/
|
*/
|
||||||
describe('resolveCurrentPageResult', () => {
|
describe('resolveCurrentPageResult', () => {
|
||||||
it('returns { page: null, selection: null } when openedPage is undefined', () => {
|
it('returns { page: null } when openedPage is undefined', () => {
|
||||||
expect(resolveCurrentPageResult(undefined)).toEqual({
|
expect(resolveCurrentPageResult(undefined)).toEqual({ page: null });
|
||||||
page: null,
|
|
||||||
selection: null,
|
|
||||||
});
|
|
||||||
});
|
});
|
||||||
|
|
||||||
it('returns { page: null, selection: null } when openedPage is null', () => {
|
it('returns { page: null } when openedPage is null', () => {
|
||||||
expect(resolveCurrentPageResult(null)).toEqual({
|
expect(resolveCurrentPageResult(null)).toEqual({ page: null });
|
||||||
page: null,
|
|
||||||
selection: null,
|
|
||||||
});
|
|
||||||
});
|
});
|
||||||
|
|
||||||
it('returns { page: null, selection: null } when openedPage has no id', () => {
|
it('returns { page: null } when openedPage has no id', () => {
|
||||||
expect(resolveCurrentPageResult({})).toEqual({
|
expect(resolveCurrentPageResult({})).toEqual({ page: null });
|
||||||
page: null,
|
expect(resolveCurrentPageResult({ title: 'x' })).toEqual({ page: null });
|
||||||
selection: null,
|
|
||||||
});
|
|
||||||
expect(resolveCurrentPageResult({ title: 'x' })).toEqual({
|
|
||||||
page: null,
|
|
||||||
selection: null,
|
|
||||||
});
|
|
||||||
});
|
});
|
||||||
|
|
||||||
it('returns { page: null, selection: null } when id is an empty string', () => {
|
it('returns { page: null } when id is an empty string', () => {
|
||||||
expect(resolveCurrentPageResult({ id: '' })).toEqual({
|
expect(resolveCurrentPageResult({ id: '' })).toEqual({ page: null });
|
||||||
page: null,
|
|
||||||
selection: null,
|
|
||||||
});
|
|
||||||
});
|
});
|
||||||
|
|
||||||
it('drops the selection when there is no page (selection dies with the page)', () => {
|
it('returns the page id and title when both are present', () => {
|
||||||
// Even if a selection somehow rode along without a page id, a null page
|
|
||||||
// always yields a null selection.
|
|
||||||
expect(
|
|
||||||
resolveCurrentPageResult({ selection: { text: 'orphan' } }),
|
|
||||||
).toEqual({ page: null, selection: null });
|
|
||||||
});
|
|
||||||
|
|
||||||
it('returns the page id and title with a null selection by default', () => {
|
|
||||||
expect(resolveCurrentPageResult({ id: 'p1', title: 'Hello' })).toEqual({
|
expect(resolveCurrentPageResult({ id: 'p1', title: 'Hello' })).toEqual({
|
||||||
page: { id: 'p1', title: 'Hello' },
|
page: { id: 'p1', title: 'Hello' },
|
||||||
selection: null,
|
|
||||||
});
|
|
||||||
});
|
|
||||||
|
|
||||||
it('passes the nested selection through verbatim', () => {
|
|
||||||
const selection = {
|
|
||||||
text: 'fix this',
|
|
||||||
blockIds: ['b1'],
|
|
||||||
before: 'please ',
|
|
||||||
after: ' now',
|
|
||||||
};
|
|
||||||
expect(
|
|
||||||
resolveCurrentPageResult({ id: 'p1', title: 'Hello', selection }),
|
|
||||||
).toEqual({
|
|
||||||
page: { id: 'p1', title: 'Hello' },
|
|
||||||
selection,
|
|
||||||
});
|
});
|
||||||
});
|
});
|
||||||
|
|
||||||
it('defaults title to "" when it is missing', () => {
|
it('defaults title to "" when it is missing', () => {
|
||||||
expect(resolveCurrentPageResult({ id: 'p1' })).toEqual({
|
expect(resolveCurrentPageResult({ id: 'p1' })).toEqual({
|
||||||
page: { id: 'p1', title: '' },
|
page: { id: 'p1', title: '' },
|
||||||
selection: null,
|
|
||||||
});
|
});
|
||||||
});
|
});
|
||||||
|
|
||||||
it('keeps an explicit empty-string title as ""', () => {
|
it('keeps an explicit empty-string title as ""', () => {
|
||||||
expect(resolveCurrentPageResult({ id: 'p1', title: '' })).toEqual({
|
expect(resolveCurrentPageResult({ id: 'p1', title: '' })).toEqual({
|
||||||
page: { id: 'p1', title: '' },
|
page: { id: 'p1', title: '' },
|
||||||
selection: null,
|
|
||||||
});
|
});
|
||||||
});
|
});
|
||||||
});
|
});
|
||||||
|
|
||||||
/**
|
|
||||||
* Unit tests for sanitizeSelection (#388). The selection is an attacker-
|
|
||||||
* controllable client snapshot: every field is type-checked and capped, and
|
|
||||||
* anything that is not a real selection collapses to null. It is NEVER verified
|
|
||||||
* against the page content (decision 5 — a hint, not ground truth).
|
|
||||||
*/
|
|
||||||
describe('sanitizeSelection', () => {
|
|
||||||
it('accepts a well-formed payload unchanged', () => {
|
|
||||||
const raw = {
|
|
||||||
text: 'the selected fragment',
|
|
||||||
truncated: true,
|
|
||||||
blockIds: ['b1', 'b2'],
|
|
||||||
before: 'context before ',
|
|
||||||
after: ' context after',
|
|
||||||
};
|
|
||||||
expect(sanitizeSelection(raw)).toEqual(raw);
|
|
||||||
});
|
|
||||||
|
|
||||||
it('returns null for non-objects', () => {
|
|
||||||
expect(sanitizeSelection(null)).toBeNull();
|
|
||||||
expect(sanitizeSelection(undefined)).toBeNull();
|
|
||||||
expect(sanitizeSelection('text')).toBeNull();
|
|
||||||
expect(sanitizeSelection(42)).toBeNull();
|
|
||||||
expect(sanitizeSelection([])).toBeNull();
|
|
||||||
});
|
|
||||||
|
|
||||||
it('returns null when text is missing, non-string or blank-after-trim', () => {
|
|
||||||
expect(sanitizeSelection({})).toBeNull();
|
|
||||||
expect(sanitizeSelection({ text: 123 })).toBeNull();
|
|
||||||
expect(sanitizeSelection({ text: '' })).toBeNull();
|
|
||||||
expect(sanitizeSelection({ text: ' \n ' })).toBeNull();
|
|
||||||
});
|
|
||||||
|
|
||||||
it('keeps only text when the other fields are garbage', () => {
|
|
||||||
expect(
|
|
||||||
sanitizeSelection({
|
|
||||||
text: 'hello',
|
|
||||||
truncated: 'yes',
|
|
||||||
blockIds: 'nope',
|
|
||||||
before: 5,
|
|
||||||
after: {},
|
|
||||||
}),
|
|
||||||
).toEqual({ text: 'hello' });
|
|
||||||
});
|
|
||||||
|
|
||||||
it('caps text at 4000 and forces truncated', () => {
|
|
||||||
const raw = { text: 'a'.repeat(5000) };
|
|
||||||
const out = sanitizeSelection(raw)!;
|
|
||||||
expect(out.text).toHaveLength(4000);
|
|
||||||
expect(out.truncated).toBe(true);
|
|
||||||
});
|
|
||||||
|
|
||||||
it('does not set truncated for text under the cap', () => {
|
|
||||||
expect(sanitizeSelection({ text: 'short' })).toEqual({ text: 'short' });
|
|
||||||
});
|
|
||||||
|
|
||||||
it('slices blockIds to 20 and drops non-string / oversized ids', () => {
|
|
||||||
const ids = Array.from({ length: 30 }, (_, i) => `b${i}`);
|
|
||||||
const out = sanitizeSelection({
|
|
||||||
text: 'x',
|
|
||||||
blockIds: [...ids, 123, '', 'y'.repeat(65)],
|
|
||||||
})!;
|
|
||||||
// The 30 valid ids cap to the first 20; the number, empty string and the
|
|
||||||
// 65-char id are dropped before the slice.
|
|
||||||
expect(out.blockIds).toHaveLength(20);
|
|
||||||
expect(out.blockIds).toEqual(ids.slice(0, 20));
|
|
||||||
});
|
|
||||||
|
|
||||||
it('keeps a 64-char id but drops a 65-char one (boundary)', () => {
|
|
||||||
const ok = 'z'.repeat(64);
|
|
||||||
const tooLong = 'z'.repeat(65);
|
|
||||||
expect(
|
|
||||||
sanitizeSelection({ text: 'x', blockIds: [ok, tooLong] })!.blockIds,
|
|
||||||
).toEqual([ok]);
|
|
||||||
});
|
|
||||||
|
|
||||||
it('omits blockIds entirely when none survive', () => {
|
|
||||||
const out = sanitizeSelection({ text: 'x', blockIds: [123, ''] })!;
|
|
||||||
expect(out.blockIds).toBeUndefined();
|
|
||||||
});
|
|
||||||
|
|
||||||
it('caps before/after at 200 chars and drops empty ones', () => {
|
|
||||||
const out = sanitizeSelection({
|
|
||||||
text: 'x',
|
|
||||||
before: 'b'.repeat(300),
|
|
||||||
after: '',
|
|
||||||
})!;
|
|
||||||
expect(out.before).toHaveLength(200);
|
|
||||||
expect(out.after).toBeUndefined();
|
|
||||||
});
|
|
||||||
});
|
|
||||||
|
|||||||
@@ -1,91 +1,21 @@
|
|||||||
export interface SelectionContext {
|
|
||||||
text: string;
|
|
||||||
truncated?: boolean;
|
|
||||||
blockIds?: string[];
|
|
||||||
before?: string;
|
|
||||||
after?: string;
|
|
||||||
}
|
|
||||||
|
|
||||||
// Server-side caps for the client-reported selection. Intentionally >= the
|
|
||||||
// client caps: the client pre-trims for a small wire, but this layer re-checks
|
|
||||||
// everything because the payload is attacker-controllable.
|
|
||||||
const TEXT_CAP = 4000;
|
|
||||||
const CONTEXT_CAP = 200;
|
|
||||||
const MAX_BLOCK_IDS = 20;
|
|
||||||
const BLOCK_ID_CAP = 64;
|
|
||||||
|
|
||||||
// Sanitize the client-reported selection: type-check every field, cap sizes
|
|
||||||
// (text 4000, before/after 200, blockIds 20 x 64 chars), drop garbage to null.
|
|
||||||
// The selection is a CLIENT-side snapshot — never verified against the page
|
|
||||||
// content (#159 lesson: treat as a hint, not ground truth). The agent is told
|
|
||||||
// (getCurrentPage's description) to localize it before editing.
|
|
||||||
export function sanitizeSelection(raw: unknown): SelectionContext | null {
|
|
||||||
if (!raw || typeof raw !== 'object') return null;
|
|
||||||
const r = raw as Record<string, unknown>;
|
|
||||||
|
|
||||||
// text is the only required field; anything else is a non-selection.
|
|
||||||
if (typeof r.text !== 'string' || r.text.trim().length === 0) return null;
|
|
||||||
let text = r.text;
|
|
||||||
let truncated = r.truncated === true;
|
|
||||||
if (text.length > TEXT_CAP) {
|
|
||||||
text = text.slice(0, TEXT_CAP);
|
|
||||||
truncated = true;
|
|
||||||
}
|
|
||||||
|
|
||||||
const result: SelectionContext = { text };
|
|
||||||
if (truncated) result.truncated = true;
|
|
||||||
|
|
||||||
if (Array.isArray(r.blockIds)) {
|
|
||||||
// Keep only well-formed, in-range ids (an oversize id is DROPPED, not
|
|
||||||
// truncated — a mangled id is worse than a missing one), then cap the count.
|
|
||||||
const ids = r.blockIds
|
|
||||||
.filter(
|
|
||||||
(x): x is string =>
|
|
||||||
typeof x === 'string' && x.length > 0 && x.length <= BLOCK_ID_CAP,
|
|
||||||
)
|
|
||||||
.slice(0, MAX_BLOCK_IDS);
|
|
||||||
if (ids.length > 0) result.blockIds = ids;
|
|
||||||
}
|
|
||||||
|
|
||||||
if (typeof r.before === 'string' && r.before.length > 0) {
|
|
||||||
result.before = r.before.slice(0, CONTEXT_CAP);
|
|
||||||
}
|
|
||||||
if (typeof r.after === 'string' && r.after.length > 0) {
|
|
||||||
result.after = r.after.slice(0, CONTEXT_CAP);
|
|
||||||
}
|
|
||||||
|
|
||||||
return result;
|
|
||||||
}
|
|
||||||
|
|
||||||
export interface CurrentPageInput {
|
export interface CurrentPageInput {
|
||||||
id?: string;
|
id?: string;
|
||||||
title?: string;
|
title?: string;
|
||||||
// The already-sanitized selection nested onto the resolved open-page context
|
|
||||||
// by resolveOpenPageContext (never the raw client value). Passed through to
|
|
||||||
// the tool result verbatim; null when nothing is selected.
|
|
||||||
selection?: SelectionContext | null;
|
|
||||||
}
|
}
|
||||||
|
|
||||||
export interface CurrentPageResult {
|
export interface CurrentPageResult {
|
||||||
page: { id: string; title: string } | null;
|
page: { id: string; title: string } | null;
|
||||||
selection: SelectionContext | null; // null when nothing is selected or no page
|
|
||||||
}
|
}
|
||||||
|
|
||||||
// Resolve the "current page" tool result from the client-supplied open-page
|
// Resolve the "current page" tool result from the client-supplied open-page
|
||||||
// context. Returns { page: null, selection: null } when no page is open (no id),
|
// context. Returns { page: null } when no page is open (no id), otherwise the
|
||||||
// otherwise the page id + title (title defaults to '' when absent) plus the
|
// page id + title (title defaults to '' when absent). Mirrors the getCurrentPage
|
||||||
// selection already sanitized+nested by resolveOpenPageContext. A null page
|
// tool's contract so it can be unit-tested without the ESM Docmost client.
|
||||||
// always yields a null selection (the selection dies with the page). Mirrors the
|
|
||||||
// getCurrentPage tool's contract so it can be unit-tested without the ESM
|
|
||||||
// Docmost client.
|
|
||||||
export function resolveCurrentPageResult(
|
export function resolveCurrentPageResult(
|
||||||
openedPage?: CurrentPageInput | null,
|
openedPage?: CurrentPageInput | null,
|
||||||
): CurrentPageResult {
|
): CurrentPageResult {
|
||||||
if (!openedPage?.id) {
|
if (!openedPage?.id) {
|
||||||
return { page: null, selection: null };
|
return { page: null };
|
||||||
}
|
}
|
||||||
return {
|
return { page: { id: openedPage.id, title: openedPage.title ?? '' } };
|
||||||
page: { id: openedPage.id, title: openedPage.title ?? '' },
|
|
||||||
selection: openedPage.selection ?? null,
|
|
||||||
};
|
|
||||||
}
|
}
|
||||||
|
|||||||
@@ -1,4 +1,5 @@
|
|||||||
import { pathToFileURL } from 'node:url';
|
import { pathToFileURL } from 'node:url';
|
||||||
|
import { esmImport } from '../../../common/helpers/esm-import';
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Minimal structural type for the `DocmostClient` class we consume from the
|
* Minimal structural type for the `DocmostClient` class we consume from the
|
||||||
@@ -256,14 +257,8 @@ interface DocmostMcpModule {
|
|||||||
SHARED_TOOL_SPECS: Record<string, SharedToolSpec>;
|
SHARED_TOOL_SPECS: Record<string, SharedToolSpec>;
|
||||||
}
|
}
|
||||||
|
|
||||||
// TS with module:commonjs downlevels a literal `import()` to `require()`, which
|
// The CJS->ESM dynamic-import bridge lives in one shared helper
|
||||||
// cannot load the ESM-only `@docmost/mcp` package. Indirect through Function so
|
// (common/helpers/esm-import.ts). The typed `loadDocmostMcp()` wrapper stays here.
|
||||||
// the real dynamic `import()` survives compilation and can load ESM from
|
|
||||||
// CommonJS at runtime (same trick as integrations/mcp/mcp.service.ts).
|
|
||||||
const esmImport = new Function(
|
|
||||||
'specifier',
|
|
||||||
'return import(specifier)',
|
|
||||||
) as (specifier: string) => Promise<unknown>;
|
|
||||||
|
|
||||||
// Memoize the in-flight/loaded module so the dynamic import runs at most once.
|
// Memoize the in-flight/loaded module so the dynamic import runs at most once.
|
||||||
let modulePromise: Promise<DocmostMcpModule> | null = null;
|
let modulePromise: Promise<DocmostMcpModule> | null = null;
|
||||||
|
|||||||
@@ -98,8 +98,7 @@ export const INLINE_TOOL_TIERS: Record<
|
|||||||
},
|
},
|
||||||
getCurrentPage: {
|
getCurrentPage: {
|
||||||
tier: 'core',
|
tier: 'core',
|
||||||
catalogLine:
|
catalogLine: 'getCurrentPage — the page the user is currently viewing.',
|
||||||
'getCurrentPage — the page the user is currently viewing and their current text selection on it.',
|
|
||||||
},
|
},
|
||||||
// NOTE: getPage and listPages moved to @docmost/mcp's SHARED_TOOL_SPECS
|
// NOTE: getPage and listPages moved to @docmost/mcp's SHARED_TOOL_SPECS
|
||||||
// (#294); they carry their own tier ('core') + catalogLine there.
|
// (#294); they carry their own tier ('core') + catalogLine there.
|
||||||
|
|||||||
@@ -3,8 +3,12 @@
|
|||||||
* from the SIGNED token claim (never a request body), so 'agent' is unspoofable.
|
* from the SIGNED token claim (never a request body), so 'agent' is unspoofable.
|
||||||
* Single source of truth so a typo like 'agnet' can't slip through as a bare
|
* Single source of truth so a typo like 'agnet' can't slip through as a bare
|
||||||
* string (#143 review). Distinct from `ActorType` (auth principal kind).
|
* string (#143 review). Distinct from `ActorType` (auth principal kind).
|
||||||
|
*
|
||||||
|
* 'git-sync' marks writes made by the git-sync data plane (issue #194 §8.1). It NEVER
|
||||||
|
* travels in a user-facing token; it is set in-process on the collab connection
|
||||||
|
* context by the native datasource, so it cannot be spoofed from a request.
|
||||||
*/
|
*/
|
||||||
export type ProvenanceSource = 'user' | 'agent';
|
export type ProvenanceSource = 'user' | 'agent' | 'git-sync';
|
||||||
|
|
||||||
export enum JwtType {
|
export enum JwtType {
|
||||||
ACCESS = 'access',
|
ACCESS = 'access',
|
||||||
@@ -26,7 +30,8 @@ export type JwtPayload = {
|
|||||||
// normal user token (treated as 'user'); set only when the internal agent
|
// normal user token (treated as 'user'); set only when the internal agent
|
||||||
// mints a provenance access token so REST writes (create/rename/move page,
|
// mints a provenance access token so REST writes (create/rename/move page,
|
||||||
// comment create/resolve) record a non-spoofable 'agent' marker (§6.5 / §15
|
// comment create/resolve) record a non-spoofable 'agent' marker (§6.5 / §15
|
||||||
// C3 / §14 N2).
|
// C3 / §14 N2). (git-sync writes use the in-process actor, not a token — see
|
||||||
|
// the ProvenanceSource note.)
|
||||||
actor?: ProvenanceSource;
|
actor?: ProvenanceSource;
|
||||||
// Nullable: an external MCP agent has no internal ai_chats row, so it carries
|
// Nullable: an external MCP agent has no internal ai_chats row, so it carries
|
||||||
// an 'agent' actor with a null aiChatId.
|
// an 'agent' actor with a null aiChatId.
|
||||||
@@ -39,7 +44,8 @@ export type JwtCollabPayload = {
|
|||||||
type: 'collab';
|
type: 'collab';
|
||||||
// Optional agent-edit provenance, signed into the collab token. Absent for
|
// Optional agent-edit provenance, signed into the collab token. Absent for
|
||||||
// the human collab path (treated as 'user'); set only when the internal agent
|
// the human collab path (treated as 'user'); set only when the internal agent
|
||||||
// mints a provenance collab token (§6.6 / §15 C2).
|
// mints a provenance collab token (§6.6 / §15 C2). 'git-sync' (in ProvenanceSource)
|
||||||
|
// is accepted for type-compatibility with the in-process git-sync write path.
|
||||||
actor?: ProvenanceSource;
|
actor?: ProvenanceSource;
|
||||||
// Nullable: an external MCP agent has no internal ai_chats row, so it carries
|
// Nullable: an external MCP agent has no internal ai_chats row, so it carries
|
||||||
// an 'agent' actor with a null aiChatId.
|
// an 'agent' actor with a null aiChatId.
|
||||||
|
|||||||
@@ -23,21 +23,8 @@ import { hashPassword } from '../../../common/helpers';
|
|||||||
* unthrottled password-guessing oracle.
|
* unthrottled password-guessing oracle.
|
||||||
*/
|
*/
|
||||||
|
|
||||||
// bcrypt cost-12 hashing/compare takes ~300ms idle but multiple seconds when
|
|
||||||
// parallel jest workers saturate all CPU cores; the 5s default flakes.
|
|
||||||
jest.setTimeout(30_000);
|
|
||||||
|
|
||||||
const WORKSPACE_ID = 'ws-1';
|
const WORKSPACE_ID = 'ws-1';
|
||||||
|
|
||||||
let passwordHash: string;
|
|
||||||
|
|
||||||
// Hoist the expensive work: compute ONE bcrypt cost-12 hash shared by all
|
|
||||||
// tests instead of five. The hash is a read-only string and each test builds
|
|
||||||
// its own user object around it, so sharing is safe.
|
|
||||||
beforeAll(async () => {
|
|
||||||
passwordHash = await hashPassword('correct-horse');
|
|
||||||
}, 30_000);
|
|
||||||
|
|
||||||
// Build an AuthService with the dependencies verifyUserCredentials/login touch
|
// Build an AuthService with the dependencies verifyUserCredentials/login touch
|
||||||
// stubbed, and a userRepo whose findByEmail is overridable per test. Only the
|
// stubbed, and a userRepo whose findByEmail is overridable per test. Only the
|
||||||
// collaborators actually reached on these paths need real behaviour; the rest
|
// collaborators actually reached on these paths need real behaviour; the rest
|
||||||
@@ -108,6 +95,7 @@ describe('AuthService.verifyUserCredentials (live credentials-mismatch contract)
|
|||||||
it('DISABLED user -> throws exactly CREDENTIALS_MISMATCH_MESSAGE (no password oracle)', async () => {
|
it('DISABLED user -> throws exactly CREDENTIALS_MISMATCH_MESSAGE (no password oracle)', async () => {
|
||||||
// A deactivated user must be indistinguishable from a wrong password: same
|
// A deactivated user must be indistinguishable from a wrong password: same
|
||||||
// message, before any password comparison.
|
// message, before any password comparison.
|
||||||
|
const passwordHash = await hashPassword('correct-horse');
|
||||||
const disabledUser = {
|
const disabledUser = {
|
||||||
id: 'u-1',
|
id: 'u-1',
|
||||||
email: 'disabled@example.com',
|
email: 'disabled@example.com',
|
||||||
@@ -129,6 +117,7 @@ describe('AuthService.verifyUserCredentials (live credentials-mismatch contract)
|
|||||||
});
|
});
|
||||||
|
|
||||||
it('WRONG password -> throws exactly CREDENTIALS_MISMATCH_MESSAGE', async () => {
|
it('WRONG password -> throws exactly CREDENTIALS_MISMATCH_MESSAGE', async () => {
|
||||||
|
const passwordHash = await hashPassword('correct-horse');
|
||||||
const user = {
|
const user = {
|
||||||
id: 'u-1',
|
id: 'u-1',
|
||||||
email: 'user@example.com',
|
email: 'user@example.com',
|
||||||
@@ -150,6 +139,7 @@ describe('AuthService.verifyUserCredentials (live credentials-mismatch contract)
|
|||||||
});
|
});
|
||||||
|
|
||||||
it('CORRECT credentials -> resolves the matched user (no side effects here)', async () => {
|
it('CORRECT credentials -> resolves the matched user (no side effects here)', async () => {
|
||||||
|
const passwordHash = await hashPassword('correct-horse');
|
||||||
const user = {
|
const user = {
|
||||||
id: 'u-1',
|
id: 'u-1',
|
||||||
email: 'user@example.com',
|
email: 'user@example.com',
|
||||||
@@ -189,6 +179,7 @@ describe('AuthService.login (live credentials-mismatch contract via verifyUserCr
|
|||||||
});
|
});
|
||||||
|
|
||||||
it('WRONG password -> login throws exactly CREDENTIALS_MISMATCH_MESSAGE', async () => {
|
it('WRONG password -> login throws exactly CREDENTIALS_MISMATCH_MESSAGE', async () => {
|
||||||
|
const passwordHash = await hashPassword('correct-horse');
|
||||||
const user = {
|
const user = {
|
||||||
id: 'u-1',
|
id: 'u-1',
|
||||||
email: 'user@example.com',
|
email: 'user@example.com',
|
||||||
@@ -210,6 +201,7 @@ describe('AuthService.login (live credentials-mismatch contract via verifyUserCr
|
|||||||
});
|
});
|
||||||
|
|
||||||
it('CORRECT credentials -> login mints the session (the side-effecting path)', async () => {
|
it('CORRECT credentials -> login mints the session (the side-effecting path)', async () => {
|
||||||
|
const passwordHash = await hashPassword('correct-horse');
|
||||||
const user = {
|
const user = {
|
||||||
id: 'u-1',
|
id: 'u-1',
|
||||||
email: 'user@example.com',
|
email: 'user@example.com',
|
||||||
|
|||||||
@@ -1,8 +1,11 @@
|
|||||||
import { BadRequestException } from '@nestjs/common';
|
import { BadRequestException } from '@nestjs/common';
|
||||||
import { PageService } from './page.service';
|
import { PageService } from './page.service';
|
||||||
import { MovePageDto } from '../dto/move-page.dto';
|
import { MovePageDto } from '../dto/move-page.dto';
|
||||||
import { Page } from '@docmost/db/types/entity.types';
|
import { CreatePageDto } from '../dto/create-page.dto';
|
||||||
|
import { UpdatePageDto } from '../dto/update-page.dto';
|
||||||
|
import { Page, User } from '@docmost/db/types/entity.types';
|
||||||
import { DEFAULT_TEMPORARY_NOTE_HOURS } from '../constants/temporary-note.constants';
|
import { DEFAULT_TEMPORARY_NOTE_HOURS } from '../constants/temporary-note.constants';
|
||||||
|
import { AuthProvenanceData } from '../../../common/decorators/auth-provenance.decorator';
|
||||||
|
|
||||||
// Direct instantiation with stub deps. The Test.createTestingModule form failed
|
// Direct instantiation with stub deps. The Test.createTestingModule form failed
|
||||||
// to resolve the @InjectKysely()/@InjectQueue() tokens at compile(), and this
|
// to resolve the @InjectKysely()/@InjectQueue() tokens at compile(), and this
|
||||||
@@ -496,4 +499,295 @@ describe('PageService', () => {
|
|||||||
expect(db.selectFrom).not.toHaveBeenCalled();
|
expect(db.selectFrom).not.toHaveBeenCalled();
|
||||||
});
|
});
|
||||||
});
|
});
|
||||||
|
|
||||||
|
describe('git-sync provenance stamping (#1)', () => {
|
||||||
|
const GIT_SYNC: AuthProvenanceData = { actor: 'git-sync', aiChatId: null };
|
||||||
|
const USER_PROVENANCE: AuthProvenanceData = { actor: 'user', aiChatId: null };
|
||||||
|
|
||||||
|
describe('create()', () => {
|
||||||
|
// Build a service whose insertPage/generalQueue are observable and whose
|
||||||
|
// nextPagePosition (a DB query) is stubbed, so create() reaches insertPage
|
||||||
|
// without a real database.
|
||||||
|
const makeService = () => {
|
||||||
|
const insertedPage = { id: 'page-1', slugId: 'slug-1' };
|
||||||
|
const pageRepo = {
|
||||||
|
insertPage: jest.fn().mockResolvedValue(insertedPage),
|
||||||
|
};
|
||||||
|
// add() is fire-and-forget (the service .catch()es it); resolve so no
|
||||||
|
// unhandled rejection leaks.
|
||||||
|
const generalQueue = { add: jest.fn().mockResolvedValue(undefined) };
|
||||||
|
|
||||||
|
const svc = new PageService(
|
||||||
|
pageRepo as any, // pageRepo
|
||||||
|
{} as any, // pagePermissionRepo
|
||||||
|
{} as any, // attachmentRepo
|
||||||
|
{} as any, // db
|
||||||
|
{} as any, // storageService
|
||||||
|
{} as any, // attachmentQueue
|
||||||
|
{} as any, // aiQueue
|
||||||
|
generalQueue as any, // generalQueue
|
||||||
|
{} as any, // eventEmitter
|
||||||
|
{} as any, // collaborationGateway
|
||||||
|
{} as any, // watcherService
|
||||||
|
{} as any, // transclusionService
|
||||||
|
);
|
||||||
|
|
||||||
|
// nextPagePosition runs a kysely query; stub it so create() never hits
|
||||||
|
// the db. No DTO content is provided, so parseProsemirrorContent is
|
||||||
|
// skipped entirely (content/textContent/ydoc stay undefined).
|
||||||
|
jest.spyOn(svc, 'nextPagePosition').mockResolvedValue('a0');
|
||||||
|
|
||||||
|
return { svc, pageRepo };
|
||||||
|
};
|
||||||
|
|
||||||
|
const createDto: CreatePageDto = {
|
||||||
|
title: 'New page',
|
||||||
|
spaceId: 'space-1',
|
||||||
|
} as any;
|
||||||
|
|
||||||
|
it("stamps lastUpdatedSource:'git-sync' on the insertPage payload", async () => {
|
||||||
|
const { svc, pageRepo } = makeService();
|
||||||
|
|
||||||
|
await svc.create('user-1', 'ws-1', createDto, GIT_SYNC);
|
||||||
|
|
||||||
|
expect(pageRepo.insertPage).toHaveBeenCalledTimes(1);
|
||||||
|
expect(pageRepo.insertPage).toHaveBeenCalledWith(
|
||||||
|
expect.objectContaining({ lastUpdatedSource: 'git-sync' }),
|
||||||
|
);
|
||||||
|
// git-sync carries no aiChatId (unlike the agent branch).
|
||||||
|
const payload = pageRepo.insertPage.mock.calls[0][0];
|
||||||
|
expect(payload.lastUpdatedAiChatId).toBeUndefined();
|
||||||
|
// The human stays the responsible author.
|
||||||
|
expect(payload.creatorId).toBe('user-1');
|
||||||
|
expect(payload.lastUpdatedById).toBe('user-1');
|
||||||
|
});
|
||||||
|
|
||||||
|
it('leaves the source column unset for a plain user create', async () => {
|
||||||
|
const { svc, pageRepo } = makeService();
|
||||||
|
|
||||||
|
await svc.create('user-1', 'ws-1', createDto, USER_PROVENANCE);
|
||||||
|
|
||||||
|
const payload = pageRepo.insertPage.mock.calls[0][0];
|
||||||
|
expect(payload.lastUpdatedSource).toBeUndefined();
|
||||||
|
});
|
||||||
|
});
|
||||||
|
|
||||||
|
describe('update() (rename)', () => {
|
||||||
|
const makeService = () => {
|
||||||
|
const pageRepo = {
|
||||||
|
updatePage: jest.fn().mockResolvedValue({ numUpdatedRows: 1n }),
|
||||||
|
// update() re-reads the row at the end to return the refreshed page.
|
||||||
|
findById: jest.fn().mockResolvedValue({ id: 'page-1' }),
|
||||||
|
};
|
||||||
|
const generalQueue = { add: jest.fn().mockResolvedValue(undefined) };
|
||||||
|
const aiQueue = { add: jest.fn().mockResolvedValue(undefined) };
|
||||||
|
|
||||||
|
const svc = new PageService(
|
||||||
|
pageRepo as any, // pageRepo
|
||||||
|
{} as any, // pagePermissionRepo
|
||||||
|
{} as any, // attachmentRepo
|
||||||
|
{} as any, // db
|
||||||
|
{} as any, // storageService
|
||||||
|
{} as any, // attachmentQueue
|
||||||
|
aiQueue as any, // aiQueue
|
||||||
|
generalQueue as any, // generalQueue
|
||||||
|
{} as any, // eventEmitter
|
||||||
|
{} as any, // collaborationGateway
|
||||||
|
{} as any, // watcherService
|
||||||
|
{} as any, // transclusionService
|
||||||
|
);
|
||||||
|
|
||||||
|
return { svc, pageRepo };
|
||||||
|
};
|
||||||
|
|
||||||
|
const page: Page = {
|
||||||
|
id: 'page-1',
|
||||||
|
slugId: 'slug-1',
|
||||||
|
spaceId: 'space-1',
|
||||||
|
workspaceId: 'ws-1',
|
||||||
|
title: 'Old title',
|
||||||
|
icon: null,
|
||||||
|
parentPageId: null,
|
||||||
|
contributorIds: [],
|
||||||
|
} as any;
|
||||||
|
|
||||||
|
const user: User = { id: 'user-1' } as any;
|
||||||
|
|
||||||
|
it("stamps lastUpdatedSource:'git-sync' on the updatePage payload", async () => {
|
||||||
|
const { svc, pageRepo } = makeService();
|
||||||
|
const dto: UpdatePageDto = { title: 'New title' } as any;
|
||||||
|
|
||||||
|
await svc.update(page, dto, user, GIT_SYNC);
|
||||||
|
|
||||||
|
expect(pageRepo.updatePage).toHaveBeenCalledTimes(1);
|
||||||
|
const payload = pageRepo.updatePage.mock.calls[0][0];
|
||||||
|
expect(payload.lastUpdatedSource).toBe('git-sync');
|
||||||
|
expect(payload.lastUpdatedAiChatId).toBeUndefined();
|
||||||
|
// The acting user stays the responsible author.
|
||||||
|
expect(payload.lastUpdatedById).toBe('user-1');
|
||||||
|
});
|
||||||
|
|
||||||
|
it('leaves the source column unset for a plain user rename', async () => {
|
||||||
|
const { svc, pageRepo } = makeService();
|
||||||
|
const dto: UpdatePageDto = { title: 'New title' } as any;
|
||||||
|
|
||||||
|
await svc.update(page, dto, user, USER_PROVENANCE);
|
||||||
|
|
||||||
|
const payload = pageRepo.updatePage.mock.calls[0][0];
|
||||||
|
expect(payload.lastUpdatedSource).toBeUndefined();
|
||||||
|
});
|
||||||
|
});
|
||||||
|
|
||||||
|
describe('movePage()', () => {
|
||||||
|
const SPACE_ID = 'space-1';
|
||||||
|
const VALID_POSITION = 'a0';
|
||||||
|
|
||||||
|
const makeService = () => {
|
||||||
|
const pageRepo = {
|
||||||
|
findById: jest.fn().mockResolvedValue({
|
||||||
|
id: 'dest-parent',
|
||||||
|
deletedAt: null,
|
||||||
|
spaceId: SPACE_ID,
|
||||||
|
}),
|
||||||
|
updatePage: jest.fn().mockResolvedValue({ numUpdatedRows: 1n }),
|
||||||
|
};
|
||||||
|
const eventEmitter = { emit: jest.fn() };
|
||||||
|
|
||||||
|
// movePage now runs the cycle-check + UPDATE inside executeTx(this.db),
|
||||||
|
// i.e. this.db.transaction().execute(fn => fn(trx)). A permissive
|
||||||
|
// chainable Proxy stands in for the Kysely trx so the per-space
|
||||||
|
// advisory-lock `sql``.execute(trx)` resolves and updatePage runs.
|
||||||
|
const trxStub: any = new Proxy(function () {}, {
|
||||||
|
get: (_t, p) =>
|
||||||
|
p === 'then'
|
||||||
|
? undefined
|
||||||
|
: p === 'execute' || p === 'executeTakeFirst'
|
||||||
|
? () => Promise.resolve([])
|
||||||
|
: () => trxStub,
|
||||||
|
});
|
||||||
|
const db = {
|
||||||
|
transaction: () => ({ execute: (fn: any) => fn(trxStub) }),
|
||||||
|
};
|
||||||
|
|
||||||
|
const svc = new PageService(
|
||||||
|
pageRepo as any, // pageRepo
|
||||||
|
{} as any, // pagePermissionRepo
|
||||||
|
{} as any, // attachmentRepo
|
||||||
|
db as any, // db
|
||||||
|
{} as any, // storageService
|
||||||
|
{} as any, // attachmentQueue
|
||||||
|
{} as any, // aiQueue
|
||||||
|
{} as any, // generalQueue
|
||||||
|
eventEmitter as any, // eventEmitter
|
||||||
|
{} as any, // collaborationGateway
|
||||||
|
{} as any, // watcherService
|
||||||
|
{} as any, // transclusionService
|
||||||
|
);
|
||||||
|
|
||||||
|
// No cycle: the destination's ancestor chain does not contain the moved
|
||||||
|
// page, so movePage reaches updatePage.
|
||||||
|
jest
|
||||||
|
.spyOn(svc, 'getPageBreadCrumbs')
|
||||||
|
.mockResolvedValue([{ id: 'dest-parent' }, { id: 'root' }] as any);
|
||||||
|
|
||||||
|
return { svc, pageRepo };
|
||||||
|
};
|
||||||
|
|
||||||
|
const movedPage: Page = {
|
||||||
|
id: 'page-1',
|
||||||
|
parentPageId: 'old-parent',
|
||||||
|
spaceId: SPACE_ID,
|
||||||
|
workspaceId: 'ws-1',
|
||||||
|
slugId: 'slug-1',
|
||||||
|
title: 'Page 1',
|
||||||
|
icon: null,
|
||||||
|
} as any;
|
||||||
|
|
||||||
|
const dto: MovePageDto = {
|
||||||
|
pageId: 'page-1',
|
||||||
|
position: VALID_POSITION,
|
||||||
|
parentPageId: 'dest-parent',
|
||||||
|
};
|
||||||
|
|
||||||
|
it("stamps lastUpdatedSource:'git-sync' on the updatePage payload", async () => {
|
||||||
|
const { svc, pageRepo } = makeService();
|
||||||
|
|
||||||
|
await svc.movePage(dto, movedPage, GIT_SYNC);
|
||||||
|
|
||||||
|
expect(pageRepo.updatePage).toHaveBeenCalledTimes(1);
|
||||||
|
const payload = pageRepo.updatePage.mock.calls[0][0];
|
||||||
|
expect(payload.lastUpdatedSource).toBe('git-sync');
|
||||||
|
expect(payload.lastUpdatedAiChatId).toBeUndefined();
|
||||||
|
});
|
||||||
|
|
||||||
|
it('leaves the source column unset for a plain user move', async () => {
|
||||||
|
const { svc, pageRepo } = makeService();
|
||||||
|
|
||||||
|
await svc.movePage(dto, movedPage, USER_PROVENANCE);
|
||||||
|
|
||||||
|
const payload = pageRepo.updatePage.mock.calls[0][0];
|
||||||
|
expect(payload.lastUpdatedSource).toBeUndefined();
|
||||||
|
});
|
||||||
|
});
|
||||||
|
|
||||||
|
describe('removePage()', () => {
|
||||||
|
// removePage forwards a `source` 4th arg to pageRepo.removePage: 'git-sync'
|
||||||
|
// for a git-sync-driven soft-delete (so the change-listener loop-guard skips
|
||||||
|
// its own write), undefined otherwise.
|
||||||
|
const makeService = () => {
|
||||||
|
const pageRepo = {
|
||||||
|
removePage: jest.fn().mockResolvedValue(undefined),
|
||||||
|
};
|
||||||
|
|
||||||
|
const svc = new PageService(
|
||||||
|
pageRepo as any, // pageRepo
|
||||||
|
{} as any, // pagePermissionRepo
|
||||||
|
{} as any, // attachmentRepo
|
||||||
|
{} as any, // db
|
||||||
|
{} as any, // storageService
|
||||||
|
{} as any, // attachmentQueue
|
||||||
|
{} as any, // aiQueue
|
||||||
|
{} as any, // generalQueue
|
||||||
|
{} as any, // eventEmitter
|
||||||
|
{} as any, // collaborationGateway
|
||||||
|
{} as any, // watcherService
|
||||||
|
{} as any, // transclusionService
|
||||||
|
);
|
||||||
|
|
||||||
|
return { svc, pageRepo };
|
||||||
|
};
|
||||||
|
|
||||||
|
it("forwards 'git-sync' as the source for a git-sync soft-delete", async () => {
|
||||||
|
const { svc, pageRepo } = makeService();
|
||||||
|
|
||||||
|
await svc.removePage('page-1', 'user-1', 'ws-1', GIT_SYNC);
|
||||||
|
|
||||||
|
expect(pageRepo.removePage).toHaveBeenCalledTimes(1);
|
||||||
|
const [pageId, userId, workspaceId, source] =
|
||||||
|
pageRepo.removePage.mock.calls[0];
|
||||||
|
expect(pageId).toBe('page-1');
|
||||||
|
expect(userId).toBe('user-1');
|
||||||
|
expect(workspaceId).toBe('ws-1');
|
||||||
|
expect(source).toBe('git-sync');
|
||||||
|
});
|
||||||
|
|
||||||
|
it('forwards undefined as the source for a plain user delete', async () => {
|
||||||
|
const { svc, pageRepo } = makeService();
|
||||||
|
|
||||||
|
await svc.removePage('page-1', 'user-1', 'ws-1', USER_PROVENANCE);
|
||||||
|
|
||||||
|
const [, , , source] = pageRepo.removePage.mock.calls[0];
|
||||||
|
expect(source).toBeUndefined();
|
||||||
|
});
|
||||||
|
|
||||||
|
it('forwards undefined as the source when no provenance is given', async () => {
|
||||||
|
const { svc, pageRepo } = makeService();
|
||||||
|
|
||||||
|
await svc.removePage('page-1', 'user-1', 'ws-1');
|
||||||
|
|
||||||
|
const [, , , source] = pageRepo.removePage.mock.calls[0];
|
||||||
|
expect(source).toBeUndefined();
|
||||||
|
});
|
||||||
|
});
|
||||||
|
});
|
||||||
});
|
});
|
||||||
|
|||||||
@@ -950,6 +950,12 @@ export class PageService {
|
|||||||
// Optional agent-edit provenance (from the signed access claim). Stamps the
|
// Optional agent-edit provenance (from the signed access claim). Stamps the
|
||||||
// source marker when the agent moves a page via REST (§6.6 REST path).
|
// source marker when the agent moves a page via REST (§6.6 REST path).
|
||||||
provenance?: AuthProvenanceData,
|
provenance?: AuthProvenanceData,
|
||||||
|
// Optional responsible author. When set (git-sync), the move is ATTRIBUTED
|
||||||
|
// to that account via `lastUpdatedById` — parity with create/delete/rename,
|
||||||
|
// which all stamp the service user. A normal user move omits it, leaving
|
||||||
|
// `lastUpdatedById` untouched (a reparent is not a content edit, so the
|
||||||
|
// existing author is preserved — unchanged behavior).
|
||||||
|
actorUserId?: string,
|
||||||
) {
|
) {
|
||||||
// validate position value by attempting to generate a key
|
// validate position value by attempting to generate a key
|
||||||
try {
|
try {
|
||||||
@@ -1019,6 +1025,9 @@ export class PageService {
|
|||||||
{
|
{
|
||||||
position: dto.position,
|
position: dto.position,
|
||||||
parentPageId: parentPageId,
|
parentPageId: parentPageId,
|
||||||
|
// Attribute a git-initiated move to the service account (parity with
|
||||||
|
// create/delete/rename). Omitted for normal user moves -> unchanged.
|
||||||
|
...(actorUserId ? { lastUpdatedById: actorUserId } : {}),
|
||||||
// Agent-edit provenance: annotate the source on an agent move. A
|
// Agent-edit provenance: annotate the source on an agent move. A
|
||||||
// normal user request leaves the existing source value unchanged.
|
// normal user request leaves the existing source value unchanged.
|
||||||
...agentSourceFields(
|
...agentSourceFields(
|
||||||
@@ -1291,8 +1300,18 @@ export class PageService {
|
|||||||
pageId: string,
|
pageId: string,
|
||||||
userId: string,
|
userId: string,
|
||||||
workspaceId: string,
|
workspaceId: string,
|
||||||
|
// Optional provenance. A git-sync-driven soft-delete stamps
|
||||||
|
// `lastUpdatedSource = 'git-sync'` so the change-listener loop-guard skips
|
||||||
|
// its own write (mirrors the create/update/move provenance branches above).
|
||||||
|
provenance?: AuthProvenanceData,
|
||||||
): Promise<void> {
|
): Promise<void> {
|
||||||
await this.pageRepo.removePage(pageId, userId, workspaceId);
|
const isGitSync = provenance?.actor === 'git-sync';
|
||||||
|
await this.pageRepo.removePage(
|
||||||
|
pageId,
|
||||||
|
userId,
|
||||||
|
workspaceId,
|
||||||
|
isGitSync ? 'git-sync' : undefined,
|
||||||
|
);
|
||||||
}
|
}
|
||||||
|
|
||||||
private async parseProsemirrorContent(
|
private async parseProsemirrorContent(
|
||||||
|
|||||||
@@ -15,4 +15,12 @@ export class UpdateSpaceDto extends PartialType(CreateSpaceDto) {
|
|||||||
@IsOptional()
|
@IsOptional()
|
||||||
@IsBoolean()
|
@IsBoolean()
|
||||||
allowViewerComments: boolean;
|
allowViewerComments: boolean;
|
||||||
|
|
||||||
|
@IsOptional()
|
||||||
|
@IsBoolean()
|
||||||
|
gitSyncEnabled?: boolean;
|
||||||
|
|
||||||
|
@IsOptional()
|
||||||
|
@IsBoolean()
|
||||||
|
autoMergeConflicts?: boolean;
|
||||||
}
|
}
|
||||||
|
|||||||
@@ -22,4 +22,199 @@ describe('SpaceService', () => {
|
|||||||
it('should be defined', () => {
|
it('should be defined', () => {
|
||||||
expect(service).toBeDefined();
|
expect(service).toBeDefined();
|
||||||
});
|
});
|
||||||
|
|
||||||
|
describe('updateSpace gitSyncEnabled', () => {
|
||||||
|
const workspaceId = 'ws-1';
|
||||||
|
const spaceId = 'space-1';
|
||||||
|
|
||||||
|
// executeTx runs the callback immediately with a passthrough trx so the
|
||||||
|
// repo calls happen inline; mirrors how the sibling sharing/comments flags
|
||||||
|
// are persisted.
|
||||||
|
const buildService = (settingsBefore: Record<string, any>) => {
|
||||||
|
const spaceRepo = {
|
||||||
|
findById: jest.fn().mockResolvedValue({
|
||||||
|
id: spaceId,
|
||||||
|
name: 'Space',
|
||||||
|
slug: 'space',
|
||||||
|
description: '',
|
||||||
|
settings: settingsBefore,
|
||||||
|
}),
|
||||||
|
updateGitSyncSettings: jest.fn().mockResolvedValue({}),
|
||||||
|
updateSharingSettings: jest.fn().mockResolvedValue({}),
|
||||||
|
updateCommentSettings: jest.fn().mockResolvedValue({}),
|
||||||
|
updateSpace: jest
|
||||||
|
.fn()
|
||||||
|
.mockResolvedValue({ id: spaceId, name: 'Space', slug: 'space' }),
|
||||||
|
slugExists: jest.fn().mockResolvedValue(false),
|
||||||
|
};
|
||||||
|
const auditService = { log: jest.fn() };
|
||||||
|
|
||||||
|
const svc = new SpaceService(
|
||||||
|
spaceRepo as any,
|
||||||
|
{} as any, // spaceMemberService
|
||||||
|
{} as any, // shareRepo
|
||||||
|
{} as any, // workspaceRepo
|
||||||
|
{} as any, // licenseCheckService
|
||||||
|
{} as any, // db
|
||||||
|
{} as any, // attachmentQueue
|
||||||
|
auditService as any,
|
||||||
|
);
|
||||||
|
|
||||||
|
// executeTx is invoked via the imported helper; patch it on the module.
|
||||||
|
jest
|
||||||
|
.spyOn(require('@docmost/db/utils'), 'executeTx')
|
||||||
|
.mockImplementation(async (_db: any, cb: any) => cb({} as any));
|
||||||
|
|
||||||
|
return { svc, spaceRepo, auditService };
|
||||||
|
};
|
||||||
|
|
||||||
|
it('persists gitSyncEnabled via updateGitSyncSettings(enabled)', async () => {
|
||||||
|
const { svc, spaceRepo } = buildService({});
|
||||||
|
|
||||||
|
await svc.updateSpace(
|
||||||
|
{ spaceId, gitSyncEnabled: true } as any,
|
||||||
|
workspaceId,
|
||||||
|
);
|
||||||
|
|
||||||
|
expect(spaceRepo.updateGitSyncSettings).toHaveBeenCalledWith(
|
||||||
|
spaceId,
|
||||||
|
workspaceId,
|
||||||
|
'enabled',
|
||||||
|
true,
|
||||||
|
expect.anything(),
|
||||||
|
);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('does not call updateGitSyncSettings when flag is undefined', async () => {
|
||||||
|
const { svc, spaceRepo } = buildService({});
|
||||||
|
|
||||||
|
await svc.updateSpace({ spaceId } as any, workspaceId);
|
||||||
|
|
||||||
|
expect(spaceRepo.updateGitSyncSettings).not.toHaveBeenCalled();
|
||||||
|
});
|
||||||
|
|
||||||
|
// --- audit delta on the git-sync toggle (test-strategy Module 4 / item #5)
|
||||||
|
// updateSpace builds a before/after delta only when a flag's value actually
|
||||||
|
// changes, and only logs an audit event when that delta is non-empty. These
|
||||||
|
// assert that contract specifically for gitSyncEnabled.
|
||||||
|
it('writes a SPACE_UPDATED audit delta on a REAL gitSyncEnabled change (false -> true)', async () => {
|
||||||
|
// Prior persisted state: gitSync.enabled = false; the request flips it on.
|
||||||
|
const { svc, auditService } = buildService({ gitSync: { enabled: false } });
|
||||||
|
|
||||||
|
await svc.updateSpace(
|
||||||
|
{ spaceId, gitSyncEnabled: true } as any,
|
||||||
|
workspaceId,
|
||||||
|
);
|
||||||
|
|
||||||
|
expect(auditService.log).toHaveBeenCalledTimes(1);
|
||||||
|
expect(auditService.log).toHaveBeenCalledWith(
|
||||||
|
expect.objectContaining({
|
||||||
|
resourceId: spaceId,
|
||||||
|
spaceId,
|
||||||
|
changes: {
|
||||||
|
before: expect.objectContaining({ gitSyncEnabled: false }),
|
||||||
|
after: expect.objectContaining({ gitSyncEnabled: true }),
|
||||||
|
},
|
||||||
|
}),
|
||||||
|
);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('also records the delta when no prior gitSync settings exist (undefined -> true defaults prev to false)', async () => {
|
||||||
|
// No gitSync key at all: prev resolves to the `?? false` default, so
|
||||||
|
// enabling it is still a real change and is audited.
|
||||||
|
const { svc, auditService } = buildService({});
|
||||||
|
|
||||||
|
await svc.updateSpace(
|
||||||
|
{ spaceId, gitSyncEnabled: true } as any,
|
||||||
|
workspaceId,
|
||||||
|
);
|
||||||
|
|
||||||
|
expect(auditService.log).toHaveBeenCalledTimes(1);
|
||||||
|
const call = auditService.log.mock.calls[0][0];
|
||||||
|
expect(call.changes.before.gitSyncEnabled).toBe(false);
|
||||||
|
expect(call.changes.after.gitSyncEnabled).toBe(true);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('does NOT write an audit delta on a no-op gitSyncEnabled (same value true -> true)', async () => {
|
||||||
|
// Prior persisted state already true; the request sets the same value.
|
||||||
|
// updateGitSyncSettings still runs (idempotent persist), but nothing is
|
||||||
|
// added to the before/after delta, so no audit event is emitted.
|
||||||
|
const { svc, spaceRepo, auditService } = buildService({
|
||||||
|
gitSync: { enabled: true },
|
||||||
|
});
|
||||||
|
|
||||||
|
await svc.updateSpace(
|
||||||
|
{ spaceId, gitSyncEnabled: true } as any,
|
||||||
|
workspaceId,
|
||||||
|
);
|
||||||
|
|
||||||
|
expect(spaceRepo.updateGitSyncSettings).toHaveBeenCalledTimes(1);
|
||||||
|
expect(auditService.log).not.toHaveBeenCalled();
|
||||||
|
});
|
||||||
|
|
||||||
|
// --- autoMergeConflicts: a SECOND key in the SAME `gitSync` jsonb object,
|
||||||
|
// persisted the same way as `enabled` (the repo's jsonb-merge keeps siblings).
|
||||||
|
it('persists autoMergeConflicts via updateGitSyncSettings(autoMergeConflicts)', async () => {
|
||||||
|
const { svc, spaceRepo } = buildService({});
|
||||||
|
|
||||||
|
await svc.updateSpace(
|
||||||
|
{ spaceId, autoMergeConflicts: true } as any,
|
||||||
|
workspaceId,
|
||||||
|
);
|
||||||
|
|
||||||
|
expect(spaceRepo.updateGitSyncSettings).toHaveBeenCalledWith(
|
||||||
|
spaceId,
|
||||||
|
workspaceId,
|
||||||
|
'autoMergeConflicts',
|
||||||
|
true,
|
||||||
|
expect.anything(),
|
||||||
|
);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('does not call updateGitSyncSettings when autoMergeConflicts is undefined', async () => {
|
||||||
|
const { svc, spaceRepo } = buildService({});
|
||||||
|
|
||||||
|
await svc.updateSpace({ spaceId } as any, workspaceId);
|
||||||
|
|
||||||
|
expect(spaceRepo.updateGitSyncSettings).not.toHaveBeenCalled();
|
||||||
|
});
|
||||||
|
|
||||||
|
it('writes a SPACE_UPDATED audit delta on a REAL autoMergeConflicts change (false -> true)', async () => {
|
||||||
|
// Prior persisted state: gitSync.autoMergeConflicts = false; flip it on.
|
||||||
|
const { svc, auditService } = buildService({
|
||||||
|
gitSync: { autoMergeConflicts: false },
|
||||||
|
});
|
||||||
|
|
||||||
|
await svc.updateSpace(
|
||||||
|
{ spaceId, autoMergeConflicts: true } as any,
|
||||||
|
workspaceId,
|
||||||
|
);
|
||||||
|
|
||||||
|
expect(auditService.log).toHaveBeenCalledTimes(1);
|
||||||
|
expect(auditService.log).toHaveBeenCalledWith(
|
||||||
|
expect.objectContaining({
|
||||||
|
resourceId: spaceId,
|
||||||
|
spaceId,
|
||||||
|
changes: {
|
||||||
|
before: expect.objectContaining({ autoMergeConflicts: false }),
|
||||||
|
after: expect.objectContaining({ autoMergeConflicts: true }),
|
||||||
|
},
|
||||||
|
}),
|
||||||
|
);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('does NOT write an audit delta on a no-op autoMergeConflicts (same value true -> true)', async () => {
|
||||||
|
const { svc, spaceRepo, auditService } = buildService({
|
||||||
|
gitSync: { autoMergeConflicts: true },
|
||||||
|
});
|
||||||
|
|
||||||
|
await svc.updateSpace(
|
||||||
|
{ spaceId, autoMergeConflicts: true } as any,
|
||||||
|
workspaceId,
|
||||||
|
);
|
||||||
|
|
||||||
|
expect(spaceRepo.updateGitSyncSettings).toHaveBeenCalledTimes(1);
|
||||||
|
expect(auditService.log).not.toHaveBeenCalled();
|
||||||
|
});
|
||||||
|
});
|
||||||
});
|
});
|
||||||
|
|||||||
@@ -213,6 +213,41 @@ export class SpaceService {
|
|||||||
);
|
);
|
||||||
}
|
}
|
||||||
|
|
||||||
|
if (typeof updateSpaceDto.gitSyncEnabled !== 'undefined') {
|
||||||
|
const prev = settingsBefore?.gitSync?.enabled ?? false;
|
||||||
|
if (prev !== updateSpaceDto.gitSyncEnabled) {
|
||||||
|
before.gitSyncEnabled = prev;
|
||||||
|
after.gitSyncEnabled = updateSpaceDto.gitSyncEnabled;
|
||||||
|
}
|
||||||
|
|
||||||
|
await this.spaceRepo.updateGitSyncSettings(
|
||||||
|
updateSpaceDto.spaceId,
|
||||||
|
workspaceId,
|
||||||
|
'enabled',
|
||||||
|
updateSpaceDto.gitSyncEnabled,
|
||||||
|
trx,
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
if (typeof updateSpaceDto.autoMergeConflicts !== 'undefined') {
|
||||||
|
const prev = settingsBefore?.gitSync?.autoMergeConflicts ?? false;
|
||||||
|
if (prev !== updateSpaceDto.autoMergeConflicts) {
|
||||||
|
before.autoMergeConflicts = prev;
|
||||||
|
after.autoMergeConflicts = updateSpaceDto.autoMergeConflicts;
|
||||||
|
}
|
||||||
|
|
||||||
|
// Merges into the SAME `gitSync` jsonb object as `enabled` (the repo's
|
||||||
|
// jsonb-merge preserves sibling keys), so toggling one never clobbers the
|
||||||
|
// other.
|
||||||
|
await this.spaceRepo.updateGitSyncSettings(
|
||||||
|
updateSpaceDto.spaceId,
|
||||||
|
workspaceId,
|
||||||
|
'autoMergeConflicts',
|
||||||
|
updateSpaceDto.autoMergeConflicts,
|
||||||
|
trx,
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
updatedSpace = await this.spaceRepo.updateSpace(
|
updatedSpace = await this.spaceRepo.updateSpace(
|
||||||
{
|
{
|
||||||
name: updateSpaceDto.name,
|
name: updateSpaceDto.name,
|
||||||
|
|||||||
@@ -0,0 +1,157 @@
|
|||||||
|
import {
|
||||||
|
Kysely,
|
||||||
|
CamelCasePlugin,
|
||||||
|
DummyDriver,
|
||||||
|
PostgresAdapter,
|
||||||
|
PostgresIntrospector,
|
||||||
|
PostgresQueryCompiler,
|
||||||
|
CompiledQuery,
|
||||||
|
} from 'kysely';
|
||||||
|
import { PageRepo } from './page.repo';
|
||||||
|
import type { KyselyDB } from '../../types/kysely.types';
|
||||||
|
|
||||||
|
/**
|
||||||
|
* SQL-builder unit test for the git-sync provenance stamp on PageRepo's
|
||||||
|
* soft-delete / restore paths (PR #119 review). Both `removePage` and
|
||||||
|
* `restorePage` take an optional `lastUpdatedSource` arg and conditionally fold
|
||||||
|
* it into the recursive-subtree `UPDATE pages SET ...` via
|
||||||
|
* `...(lastUpdatedSource ? { lastUpdatedSource } : {})`. The change-listener
|
||||||
|
* loop-guard reads `last_updated_source = 'git-sync'` to recognize git-sync's own
|
||||||
|
* writes and skip the echo cycle; this test guards that the stamp is present when
|
||||||
|
* the arg is supplied and ABSENT when it is omitted (an ordinary user delete must
|
||||||
|
* not clobber the column).
|
||||||
|
*
|
||||||
|
* Harness: the same compile-only Kysely/DummyDriver pattern as
|
||||||
|
* space.repo.spec.ts, plus the production `CamelCasePlugin` (so the compiled SQL
|
||||||
|
* carries the real snake_case column names, e.g. `last_updated_source`) and a
|
||||||
|
* thin driver that returns ONE fixed row for every query. The fixed row is what
|
||||||
|
* lets the repo's guard reads (root snapshot / recursive descendants / restore
|
||||||
|
* target) resolve non-empty so execution reaches the subtree UPDATE we assert on
|
||||||
|
* — a bare DummyDriver returns no rows and both methods short-circuit before the
|
||||||
|
* update. We never hit a real database; we capture each compiled statement via
|
||||||
|
* Kysely's `log` hook and inspect the `update "pages" set ...` SQL.
|
||||||
|
*/
|
||||||
|
describe('PageRepo — git-sync provenance on soft-delete / restore SQL', () => {
|
||||||
|
// A single row shaped to satisfy every column the repo reads off its guard
|
||||||
|
// queries. `parentPageId: null` keeps restorePage on the simple path (no
|
||||||
|
// parent-detach UPDATE), so the only `update "pages"` statement is the one we
|
||||||
|
// assert on.
|
||||||
|
const FIXED_ROW = {
|
||||||
|
id: 'p1',
|
||||||
|
slugId: 's1',
|
||||||
|
title: 'Doc',
|
||||||
|
icon: null,
|
||||||
|
position: 'a0',
|
||||||
|
spaceId: 'space-1',
|
||||||
|
parentPageId: null,
|
||||||
|
deletedAt: null,
|
||||||
|
};
|
||||||
|
|
||||||
|
class FixedRowDriver extends DummyDriver {
|
||||||
|
async acquireConnection(): Promise<any> {
|
||||||
|
return {
|
||||||
|
async executeQuery() {
|
||||||
|
return { rows: [{ ...FIXED_ROW }] };
|
||||||
|
},
|
||||||
|
// eslint-disable-next-line @typescript-eslint/no-empty-function
|
||||||
|
async *streamQuery() {},
|
||||||
|
};
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
interface Captured {
|
||||||
|
sql: string;
|
||||||
|
parameters: readonly unknown[];
|
||||||
|
}
|
||||||
|
|
||||||
|
// Compile-only Kysely on the Postgres dialect (CamelCasePlugin for real column
|
||||||
|
// names) whose `log` hook records every executed statement's compiled SQL.
|
||||||
|
function makeRepoCapturingSql() {
|
||||||
|
const captured: Captured[] = [];
|
||||||
|
const db = new Kysely<any>({
|
||||||
|
dialect: {
|
||||||
|
createAdapter: () => new PostgresAdapter(),
|
||||||
|
createDriver: () => new FixedRowDriver(),
|
||||||
|
createIntrospector: (d) => new PostgresIntrospector(d),
|
||||||
|
createQueryCompiler: () => new PostgresQueryCompiler(),
|
||||||
|
},
|
||||||
|
plugins: [new CamelCasePlugin()],
|
||||||
|
log: (event) => {
|
||||||
|
if (event.level === 'query') {
|
||||||
|
const q = event.query as CompiledQuery;
|
||||||
|
captured.push({ sql: q.sql, parameters: q.parameters });
|
||||||
|
}
|
||||||
|
},
|
||||||
|
});
|
||||||
|
|
||||||
|
const repo = new PageRepo(
|
||||||
|
db as unknown as KyselyDB,
|
||||||
|
{} as any,
|
||||||
|
{ emit: jest.fn() } as any,
|
||||||
|
);
|
||||||
|
// Find the single subtree UPDATE on pages (collapse whitespace for matching).
|
||||||
|
const getUpdatePagesSql = (): Captured | undefined =>
|
||||||
|
captured
|
||||||
|
.map((c) => ({ ...c, sql: c.sql.replace(/\s+/g, ' ') }))
|
||||||
|
.find((c) => /update "pages" set/i.test(c.sql));
|
||||||
|
return { repo, getUpdatePagesSql };
|
||||||
|
}
|
||||||
|
|
||||||
|
describe('removePage', () => {
|
||||||
|
it("stamps last_updated_source = 'git-sync' on the subtree soft-delete when the provenance arg is supplied", async () => {
|
||||||
|
const { repo, getUpdatePagesSql } = makeRepoCapturingSql();
|
||||||
|
|
||||||
|
await repo.removePage('p1', 'user-1', 'ws-1', 'git-sync');
|
||||||
|
|
||||||
|
const update = getUpdatePagesSql();
|
||||||
|
expect(update).toBeDefined();
|
||||||
|
// The provenance column is in the UPDATE's SET clause...
|
||||||
|
expect(update!.sql).toContain('"last_updated_source" =');
|
||||||
|
// ...with the 'git-sync' marker as the bound value.
|
||||||
|
expect(update!.parameters).toContain('git-sync');
|
||||||
|
// Sanity: it is still the soft-delete UPDATE (sets deleted_at too).
|
||||||
|
expect(update!.sql).toContain('"deleted_at" =');
|
||||||
|
});
|
||||||
|
|
||||||
|
it('OMITS last_updated_source from the soft-delete when the provenance arg is undefined', async () => {
|
||||||
|
const { repo, getUpdatePagesSql } = makeRepoCapturingSql();
|
||||||
|
|
||||||
|
await repo.removePage('p1', 'user-1', 'ws-1');
|
||||||
|
|
||||||
|
const update = getUpdatePagesSql();
|
||||||
|
expect(update).toBeDefined();
|
||||||
|
// Ordinary user delete: the column must NOT be touched (keeps prior value).
|
||||||
|
expect(update!.sql).not.toContain('last_updated_source');
|
||||||
|
expect(update!.parameters).not.toContain('git-sync');
|
||||||
|
// It is still the soft-delete UPDATE.
|
||||||
|
expect(update!.sql).toContain('"deleted_at" =');
|
||||||
|
});
|
||||||
|
});
|
||||||
|
|
||||||
|
describe('restorePage', () => {
|
||||||
|
it("stamps last_updated_source = 'git-sync' on the subtree restore when the provenance arg is supplied", async () => {
|
||||||
|
const { repo, getUpdatePagesSql } = makeRepoCapturingSql();
|
||||||
|
|
||||||
|
await repo.restorePage('p1', 'ws-1', 'git-sync');
|
||||||
|
|
||||||
|
const update = getUpdatePagesSql();
|
||||||
|
expect(update).toBeDefined();
|
||||||
|
expect(update!.sql).toContain('"last_updated_source" =');
|
||||||
|
expect(update!.parameters).toContain('git-sync');
|
||||||
|
// Sanity: it is the restore UPDATE (clears deleted_at).
|
||||||
|
expect(update!.sql).toContain('"deleted_at" =');
|
||||||
|
});
|
||||||
|
|
||||||
|
it('OMITS last_updated_source from the restore when the provenance arg is undefined', async () => {
|
||||||
|
const { repo, getUpdatePagesSql } = makeRepoCapturingSql();
|
||||||
|
|
||||||
|
await repo.restorePage('p1', 'ws-1');
|
||||||
|
|
||||||
|
const update = getUpdatePagesSql();
|
||||||
|
expect(update).toBeDefined();
|
||||||
|
expect(update!.sql).not.toContain('last_updated_source');
|
||||||
|
expect(update!.parameters).not.toContain('git-sync');
|
||||||
|
expect(update!.sql).toContain('"deleted_at" =');
|
||||||
|
});
|
||||||
|
});
|
||||||
|
});
|
||||||
@@ -349,6 +349,11 @@ export class PageRepo {
|
|||||||
pageId: string,
|
pageId: string,
|
||||||
deletedById: string,
|
deletedById: string,
|
||||||
workspaceId: string,
|
workspaceId: string,
|
||||||
|
// Optional provenance marker. When the soft-delete is driven by an automated
|
||||||
|
// data plane (e.g. git-sync), stamp `lastUpdatedSource` so the change-listener
|
||||||
|
// loop-guard recognizes it as its own write and does not schedule an echo
|
||||||
|
// cycle. Omitted for ordinary user deletes (column keeps its prior value).
|
||||||
|
lastUpdatedSource?: string,
|
||||||
): Promise<void> {
|
): Promise<void> {
|
||||||
const currentDate = new Date();
|
const currentDate = new Date();
|
||||||
|
|
||||||
@@ -399,6 +404,7 @@ export class PageRepo {
|
|||||||
.set({
|
.set({
|
||||||
deletedById: deletedById,
|
deletedById: deletedById,
|
||||||
deletedAt: currentDate,
|
deletedAt: currentDate,
|
||||||
|
...(lastUpdatedSource ? { lastUpdatedSource } : {}),
|
||||||
})
|
})
|
||||||
.where('id', 'in', pageIds)
|
.where('id', 'in', pageIds)
|
||||||
.where('deletedAt', 'is', null)
|
.where('deletedAt', 'is', null)
|
||||||
@@ -429,7 +435,14 @@ export class PageRepo {
|
|||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
async restorePage(pageId: string, workspaceId: string): Promise<void> {
|
async restorePage(
|
||||||
|
pageId: string,
|
||||||
|
workspaceId: string,
|
||||||
|
// See removePage: stamp `lastUpdatedSource` for automated (git-sync) restores
|
||||||
|
// so the change-listener loop-guard skips the echo cycle. Omitted for
|
||||||
|
// ordinary user restores.
|
||||||
|
lastUpdatedSource?: string,
|
||||||
|
): Promise<void> {
|
||||||
// First, check if the page being restored has a deleted parent
|
// First, check if the page being restored has a deleted parent
|
||||||
const pageToRestore = await this.db
|
const pageToRestore = await this.db
|
||||||
.selectFrom('pages')
|
.selectFrom('pages')
|
||||||
@@ -480,7 +493,12 @@ export class PageRepo {
|
|||||||
// On restore, disarm the death timer: pulling a note out of trash means
|
// On restore, disarm the death timer: pulling a note out of trash means
|
||||||
// "keep it". Otherwise a deadline now in the past would re-trash it on the
|
// "keep it". Otherwise a deadline now in the past would re-trash it on the
|
||||||
// next cleanup sweep.
|
// next cleanup sweep.
|
||||||
.set({ deletedById: null, deletedAt: null, temporaryExpiresAt: null })
|
.set({
|
||||||
|
deletedById: null,
|
||||||
|
deletedAt: null,
|
||||||
|
temporaryExpiresAt: null,
|
||||||
|
...(lastUpdatedSource ? { lastUpdatedSource } : {}),
|
||||||
|
})
|
||||||
.where('id', 'in', pageIds)
|
.where('id', 'in', pageIds)
|
||||||
.execute();
|
.execute();
|
||||||
|
|
||||||
|
|||||||
@@ -0,0 +1,146 @@
|
|||||||
|
import {
|
||||||
|
Kysely,
|
||||||
|
DummyDriver,
|
||||||
|
PostgresAdapter,
|
||||||
|
PostgresIntrospector,
|
||||||
|
PostgresQueryCompiler,
|
||||||
|
CompiledQuery,
|
||||||
|
} from 'kysely';
|
||||||
|
import { SpaceRepo } from './space.repo';
|
||||||
|
import type { KyselyDB } from '../../types/kysely.types';
|
||||||
|
|
||||||
|
/**
|
||||||
|
* SQL-builder unit test for the jsonb-merge invariant of
|
||||||
|
* SpaceRepo.updateGitSyncSettings (review comment #694 / test-strategy item #6).
|
||||||
|
*
|
||||||
|
* The merge is RAW SQL, so a behavioural test would need a live Postgres — which
|
||||||
|
* is intentionally out of scope here (the reviewer's own §13.3 was deferred for
|
||||||
|
* the same reason). Instead we follow the existing repo-spec convention
|
||||||
|
* (ai-agent-roles.repo.spec.ts) of NOT executing: we compile the query with a
|
||||||
|
* DummyDriver Postgres dialect and assert the generated SQL preserves sibling
|
||||||
|
* keys. The structural invariant the SQL must encode:
|
||||||
|
*
|
||||||
|
* settings := COALESCE(settings, '{}') || jsonb_build_object('gitSync', ...)
|
||||||
|
* gitSync := COALESCE(settings->'gitSync', '{}') || jsonb_build_object(key, value)
|
||||||
|
*
|
||||||
|
* The OUTER `||` merges into the existing top-level `settings`, so a sibling
|
||||||
|
* top-level key (e.g. `sharing`) is preserved. The INNER COALESCE merges into
|
||||||
|
* the existing `gitSync` object, so a sibling key inside gitSync (e.g. `other`)
|
||||||
|
* is preserved. A naive `set settings = jsonb_build_object('gitSync', ...)`
|
||||||
|
* would clobber both — this test guards exactly that regression.
|
||||||
|
*/
|
||||||
|
describe('SpaceRepo.updateGitSyncSettings — jsonb merge SQL', () => {
|
||||||
|
// A real Kysely on the Postgres dialect, but with a DummyDriver: it compiles
|
||||||
|
// queries to real Postgres SQL without ever opening a connection.
|
||||||
|
function makeCompileOnlyDb() {
|
||||||
|
return new Kysely<any>({
|
||||||
|
dialect: {
|
||||||
|
createAdapter: () => new PostgresAdapter(),
|
||||||
|
createDriver: () => new DummyDriver(),
|
||||||
|
createIntrospector: (db) => new PostgresIntrospector(db),
|
||||||
|
createQueryCompiler: () => new PostgresQueryCompiler(),
|
||||||
|
},
|
||||||
|
});
|
||||||
|
}
|
||||||
|
|
||||||
|
// Build the repo over the compile-only db. The repo terminates the query with
|
||||||
|
// `.executeTakeFirst()`, so we wrap every kysely builder in a Proxy: when the
|
||||||
|
// repo finally calls `executeTakeFirst`, we `.compile()` that same builder
|
||||||
|
// ourselves to capture the exact SQL it was about to run, then delegate.
|
||||||
|
function makeRepoCapturingSql() {
|
||||||
|
const db = makeCompileOnlyDb();
|
||||||
|
let captured: CompiledQuery | undefined;
|
||||||
|
|
||||||
|
// kysely builders are immutable — each .set()/.where()/.returningAll()
|
||||||
|
// returns a NEW builder — so re-wrap any chainable result.
|
||||||
|
const wrap = (b: any): any =>
|
||||||
|
new Proxy(b, {
|
||||||
|
get(target, prop, receiver) {
|
||||||
|
const value = Reflect.get(target, prop, receiver);
|
||||||
|
if (typeof value !== 'function') return value;
|
||||||
|
return (...callArgs: unknown[]) => {
|
||||||
|
// Capture the SQL at the terminal execute call.
|
||||||
|
if (
|
||||||
|
(prop === 'executeTakeFirst' || prop === 'execute') &&
|
||||||
|
typeof target.compile === 'function'
|
||||||
|
) {
|
||||||
|
captured = target.compile();
|
||||||
|
}
|
||||||
|
const result = value.apply(target, callArgs);
|
||||||
|
if (
|
||||||
|
result &&
|
||||||
|
typeof result === 'object' &&
|
||||||
|
typeof (result as any).compile === 'function'
|
||||||
|
) {
|
||||||
|
return wrap(result);
|
||||||
|
}
|
||||||
|
return result;
|
||||||
|
};
|
||||||
|
},
|
||||||
|
});
|
||||||
|
|
||||||
|
const originalUpdateTable = db.updateTable.bind(db);
|
||||||
|
jest
|
||||||
|
.spyOn(db, 'updateTable')
|
||||||
|
.mockImplementation((...args: Parameters<typeof originalUpdateTable>) =>
|
||||||
|
wrap(originalUpdateTable(...args)),
|
||||||
|
);
|
||||||
|
|
||||||
|
const repo = new SpaceRepo(db as unknown as KyselyDB, {} as any);
|
||||||
|
return { repo, getCaptured: () => captured };
|
||||||
|
}
|
||||||
|
|
||||||
|
it("compiles a jsonb merge that preserves sibling top-level and gitSync keys", async () => {
|
||||||
|
const { repo, getCaptured } = makeRepoCapturingSql();
|
||||||
|
|
||||||
|
// DummyDriver yields no rows; executeTakeFirst resolves to undefined. The
|
||||||
|
// SQL is fully compiled by then, which is all we assert.
|
||||||
|
await repo.updateGitSyncSettings('space-1', 'ws-1', 'enabled', true);
|
||||||
|
|
||||||
|
const compiled = getCaptured();
|
||||||
|
expect(compiled).toBeDefined();
|
||||||
|
// The raw SQL template carries newlines/indentation; collapse whitespace so
|
||||||
|
// the structural assertions are not coupled to source formatting.
|
||||||
|
const sql = compiled!.sql.replace(/\s+/g, ' ');
|
||||||
|
|
||||||
|
// OUTER merge into the existing settings object -> sibling top-level keys
|
||||||
|
// (e.g. `sharing`) survive (NOT a bare jsonb_build_object assignment).
|
||||||
|
expect(sql).toContain(`set "settings" = COALESCE(settings, '{}'::jsonb) ||`);
|
||||||
|
// INNER merge into the existing gitSync object -> sibling gitSync keys
|
||||||
|
// (e.g. `other`) survive.
|
||||||
|
expect(sql).toContain(
|
||||||
|
`jsonb_build_object('gitSync', COALESCE(settings->'gitSync', '{}'::jsonb) ||`,
|
||||||
|
);
|
||||||
|
// The pref key is set via jsonb_build_object on the inner object, with the
|
||||||
|
// key as a BOUND, ::text-cast PARAMETER (not sql.raw) — security fix #5.
|
||||||
|
expect(sql).toMatch(/jsonb_build_object\(\$\d+::text,/);
|
||||||
|
// Scoped to the row + workspace.
|
||||||
|
expect(sql).toContain(`where "id" =`);
|
||||||
|
expect(sql).toContain(`and "workspaceId" =`);
|
||||||
|
|
||||||
|
// Sanity: this is NOT a clobbering assignment (no top-level
|
||||||
|
// `set "settings" = jsonb_build_object(` without the COALESCE/merge).
|
||||||
|
expect(sql).not.toContain(`set "settings" = jsonb_build_object(`);
|
||||||
|
|
||||||
|
// The pref VALUE stays inlined via sql.lit, but the KEY is now a bound
|
||||||
|
// parameter, so id + workspaceId + the key are all bound (updatedAt is a Date).
|
||||||
|
expect(compiled!.parameters).toContain('space-1');
|
||||||
|
expect(compiled!.parameters).toContain('ws-1');
|
||||||
|
expect(compiled!.parameters).toContain('enabled');
|
||||||
|
});
|
||||||
|
|
||||||
|
it('binds the prefKey as a ::text parameter (no sql.raw splice) and inlines prefValue via sql.lit', async () => {
|
||||||
|
const { repo, getCaptured } = makeRepoCapturingSql();
|
||||||
|
|
||||||
|
await repo.updateGitSyncSettings('space-1', 'ws-1', 'enabled', false);
|
||||||
|
|
||||||
|
const compiled = getCaptured()!;
|
||||||
|
const sql = compiled.sql.replace(/\s+/g, ' ');
|
||||||
|
// The key is a bound `$N::text` parameter; the value is the sql.lit literal.
|
||||||
|
expect(sql).toMatch(/jsonb_build_object\(\$\d+::text, false\)/);
|
||||||
|
// The literal key must NOT be spliced into the statement text (the footgun).
|
||||||
|
expect(sql).not.toContain(`'enabled'`);
|
||||||
|
// The key rides as a bound parameter instead.
|
||||||
|
expect(compiled.parameters).toContain('enabled');
|
||||||
|
});
|
||||||
|
});
|
||||||
@@ -111,6 +111,34 @@ export class SpaceRepo {
|
|||||||
.executeTakeFirst();
|
.executeTakeFirst();
|
||||||
}
|
}
|
||||||
|
|
||||||
|
async updateGitSyncSettings(
|
||||||
|
spaceId: string,
|
||||||
|
workspaceId: string,
|
||||||
|
prefKey: string,
|
||||||
|
prefValue: string | boolean,
|
||||||
|
trx?: KyselyTransaction,
|
||||||
|
) {
|
||||||
|
const db = dbOrTx(this.db, trx);
|
||||||
|
return db
|
||||||
|
.updateTable('spaces')
|
||||||
|
.set({
|
||||||
|
// The jsonb key is a BOUND PARAMETER (`${prefKey}::text`), not
|
||||||
|
// `sql.raw(prefKey)`. The callers here only ever pass the literals
|
||||||
|
// 'enabled' / 'autoMergeConflicts', but sql.raw would splice the string
|
||||||
|
// straight into the statement — a latent SQL-injection footgun the moment
|
||||||
|
// a future caller passes a request-derived key. Parameterizing closes it
|
||||||
|
// with no behaviour change for the current literal callers.
|
||||||
|
settings: sql`COALESCE(settings, '{}'::jsonb)
|
||||||
|
|| jsonb_build_object('gitSync', COALESCE(settings->'gitSync', '{}'::jsonb)
|
||||||
|
|| jsonb_build_object(${prefKey}::text, ${sql.lit(prefValue)}))`,
|
||||||
|
updatedAt: new Date(),
|
||||||
|
})
|
||||||
|
.where('id', '=', spaceId)
|
||||||
|
.where('workspaceId', '=', workspaceId)
|
||||||
|
.returningAll()
|
||||||
|
.executeTakeFirst();
|
||||||
|
}
|
||||||
|
|
||||||
async updateCommentSettings(
|
async updateCommentSettings(
|
||||||
spaceId: string,
|
spaceId: string,
|
||||||
workspaceId: string,
|
workspaceId: string,
|
||||||
|
|||||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user