confluence-mdx: callout 블록 reverse sync 패치를 수정합니다

confluence-mdx/bin/reverse_sync/patch_builder.py

@@ -110,6 +110,10 @@ def _resolve_mapping_for_change(
     if mapping is not None and mapping.children:
         child = _resolve_child_mapping(old_plain, mapping, id_to_mapping)
         if child is not None:
+            # callout 블록은 direct 전략 시 _convert_callout_inner가
+            # <li><p> 구조를 생성할 수 없으므로 containing 전략 사용
+            if change.old_block.type == 'callout':
+                return ('containing', mapping)
             return ('direct', child)
         # 블록 텍스트가 parent에 포함되는지 확인
         _old_ns = strip_for_compare(old_plain)

confluence-mdx/bin/reverse_sync/xhtml_patcher.py

@@ -333,7 +333,12 @@ def _apply_text_changes(element: Tag, old_text: str, new_text: str):
 
         # _map_text_range는 half-open [start, end)를 사용하므로,
         # 마지막 non-empty 노드에서는 end를 확장하여 trailing insert를 포함한다.
-        effective_end = node_end + 1 if i == last_nonempty_idx else node_end
+        # 단, 텍스트 노드가 old_text 전체를 커버하지 않는 경우(예: callout 내부
+        # 코드 블록이 ac:plain-text-body로 제외된 경우) +1이 비텍스트 영역에
+        # 침범하여 잘못된 문자가 포함되는 것을 방지한다.
+        effective_end = (node_end + 1
+                         if i == last_nonempty_idx and node_end >= len(old_stripped)
+                         else node_end)
         # 블록 경계에서는 include_insert_at_end/exclude_insert_at_start로
         # insert를 올바른 노드에 할당한다.
         include_at_end = i in claim_end_set and i != last_nonempty_idx

confluence-mdx/tests/reverse-sync/544112828/improved.mdx

@@ -0,0 +1,316 @@
+---
+title: 'User Agent'
+confluenceUrl: 'https://querypie.atlassian.net/wiki/spaces/QM/pages/544112828/User+Agent'
+---
+
+import { Callout } from 'nextra/components'
+
+# User Agent
+
+QueryPie Agent를 설치하면, DataGrip, DBeaver와 같은 SQL Client, iTerm/SecureCRT와 같은 SSH Client, Lens, k9s와 같은 3rd Party 애플리케이션을 사용할 수 있습니다.
+
+### 에이전트 앱 다운로드 및 실행하기
+
+#### 1. QueryPie 로그인 후 우측 상단 프로필을 클릭하여 `Agent Download` 버튼을 클릭합니다.
+
+<figure data-layout="center" data-align="center">
+<img src="/user-manual/user-agent/screenshot-20240804-173002.png" alt="QueryPie Web &gt; 프로필 메뉴" width="760" />
+<figcaption>
+QueryPie Web &gt; 프로필 메뉴
+</figcaption>
+</figure>
+
+#### 2. 사용 중인 PC 운영체제에 맞는 설치 파일을 다운로드합니다.
+
+QueryPie Agent Downloads 팝업창의 Step 1 에서, 사용 중인 PC 운영체제에 맞는 설치 파일을 다운로드합니다.
+Step 3 섹션에 표시된 QueryPie URL을 복사해 둡니다.
+
+<figure data-layout="center" data-align="center">
+<img src="/user-manual/user-agent/image-20240723-154847.png" alt="QueryPie Web &gt; Agent Downloads 팝업창" width="760" />
+<figcaption>
+QueryPie Web &gt; Agent Downloads 팝업창
+</figcaption>
+</figure>
+
+<Callout type="info">
+QueryPie Agent는 Mac, Windows, Linux OS를 지원합니다.
+</Callout>
+
+#### 3. 다운로드받은 QueryPie Agent 설치 프로그램을 실행하여 설치를 완료합니다.
+
+<figure data-layout="center" data-align="center">
+<img src="/user-manual/user-agent/screenshot-20240804-174002.png" alt="Mac OS 설치 프로그램" width="760" />
+<figcaption>
+Mac OS 설치 프로그램
+</figcaption>
+</figure>
+
+#### 4. 설치된 QueryPie Agent를 실행합니다.
+
+QueryPie Host 입력란에 미리 복사해뒀던 QueryPie URL을 입력하고 `Next` 버튼을 클릭하면 로그인 화면으로 진입하게 됩니다.
+
+<figure data-layout="center" data-align="center">
+<img src="/user-manual/user-agent/agent-03.png" alt="Agent &gt; QueryPie Host 입력" width="760" />
+<figcaption>
+Agent &gt; QueryPie Host 입력
+</figcaption>
+</figure>
+
+### QueryPie Agent에 로그인하기
+
+#### 1. Agent 앱 내 로그인 화면에서 `Login` 버튼을 클릭합니다.
+
+<figure data-layout="center" data-align="center">
+<img src="/user-manual/user-agent/screenshot-20240804-173713.png" alt="screenshot-20240804-173713.png" width="760" />
+</figure>
+
+#### 2. 웹 브라우저가 열리면, 로그인 페이지에서 인증정보를 입력하고, `Continue` 버튼을 클릭합니다.
+
+<figure data-layout="center" data-align="center">
+<img src="/user-manual/user-agent/screenshot-20240729-171236.png" alt="QueryPie Web &gt; Agent Login Page" width="760" />
+<figcaption>
+QueryPie Web &gt; Agent Login Page
+</figcaption>
+</figure>
+
+#### 3. 로그인을 성공하면 아래와 같이 로그인 성공 화면이 표시되며 이후 Agent로 돌아갑니다.
+
+<figure data-layout="center" data-align="center">
+<img src="/user-manual/user-agent/screenshot-20240729-171314.png" alt="QueryPie Web &gt; Agent Login Success Page" width="764" />
+<figcaption>
+QueryPie Web &gt; Agent Login Success Page
+</figcaption>
+</figure>
+
+#### 4. Agent 열기를 명시적으로 수행하여 인증정보를 Agent로 전달합니다.
+
+<figure data-layout="center" data-align="center">
+<img src="/user-manual/user-agent/screenshot-20240804-174209.png" alt="Chrome - Agent App 열기 모달" width="760" />
+<figcaption>
+Chrome - Agent App 열기 모달
+</figcaption>
+</figure>
+
+### 에이전트로 데이터베이스 접속하기
+
+#### 1. Agent 앱 내 Database 탭에서 권한 있는 커넥션들의 접속 정보를 확인합니다.
+
+로그인이 정상적으로 완료되면 Agent 앱 내 Database 탭에서 권한 있는 커넥션들의 접속 정보를 확인할 수 있습니다.
+접속할 커넥션에 할당된 `Port` 를 클릭하면, 해당 커넥션의 `Proxy Credentials` 정보를 확인할 수 있습니다.
+
+<figure data-layout="center" data-align="center">
+<img src="/user-manual/user-agent/screenshot-20240730-151001.png" alt="Agent &gt; DB Connection Information" width="764" />
+<figcaption>
+Agent &gt; DB Connection Information
+</figcaption>
+</figure>
+
+#### 2. 위의 접속 정보를 3rd Party 클라이언트에 입력하면 DB 커넥션 접속이 가능합니다.
+
+<figure data-layout="center" data-align="center">
+<img src="/user-manual/user-agent/agent-07.png" alt="3rd Party Client를 이용한 DB 커넥션 접속" width="764" />
+<figcaption>
+3rd Party Client를 이용한 DB 커넥션 접속
+</figcaption>
+</figure>
+
+
+### 에이전트를 통한 서버 접속
+
+로그인이 정상적으로 완료되면 Agent 앱 내 Server 탭에서 권한 있는 서버를 확인할 수 있습니다.
+
+#### 1. 서버 역할 선택하기
+
+사용자 프로필 영역 하단의 `Role` 버튼을 클릭하여 원하는 역할을 고르고 `OK` 버튼을 클릭하세요. `Default` 역할을 선택하는 경우, Workflow &gt; Server Access Request 요청에 의해 할당받은 서버 권한을 사용합니다.
+
+<figure data-layout="center" data-align="center">
+<img src="/user-manual/user-agent/screenshot-20240730-162653.png" alt="Agent &gt; Server &gt; Select a Role" width="764" />
+<figcaption>
+Agent &gt; Server &gt; Select a Role
+</figcaption>
+</figure>
+
+<Callout type="info">
+역할이 두 개 이상이라면, Agent 로그인 후 Server 기능 사용을 위해 역할 선택을 먼저 완료해야 합니다.
+</Callout>
+
+#### 2. Agent로 서버 접속하기
+
+접속할 서버를 우클릭 후 `Open Connection with` 메뉴를 선택하여, 사용하려는 터미널 툴을 선택합니다.
+
+<figure data-layout="center" data-align="center">
+<img src="/user-manual/user-agent/screenshot-20240730-161729.png" alt="Agent &gt; Server &gt; Open Connection with" width="760" />
+<figcaption>
+Agent &gt; Server &gt; Open Connection with
+</figcaption>
+</figure>
+
+이후 해당 서버에 접속 가능한 계정이 여러 개라면, Account 선택창이 열립니다.
+사용하려는 계정을 선택하고, 필요 시 비밀번호를 입력한 뒤, `OK` 버튼을 클릭하여 세션을 엽니다.
+
+<figure data-layout="center" data-align="center">
+<img src="/user-manual/user-agent/screenshot-20240730-162532.png" alt="Agent &gt; Server &gt; Open New Session" width="746" />
+<figcaption>
+Agent &gt; Server &gt; Open New Session
+</figcaption>
+</figure>
+
+#### 3. Seamless SSH 설정하기
+
+Seamless SSH란 기존 터미널 사용성을 그대로 유지하면서 QueryPie를 통해 서버에 접속할 수 있는 기능입니다.
+다음 방법으로 `.ssh` 폴더에 `config` 파일을 생성하여 손쉽게 Seamless SSH를 설정할 수 있습니다.
+
+##### 3.1. 터미널을 열고, `.ssh` 폴더로 이동합니다.
+
+```
+$ cd .ssh
+```
+
+##### 3.2. `.ssh` 폴더에서 `config` 파일을 생성하기 위해 vi 에디터를 엽니다.
+
+```
+$ vi config
+```
+
+##### 3.3. 아래의 내용을 입력 후, `Esc` 와 `:wq` 를 입력하여 변경사항을 저장하고, vi 에디터를 종료합니다.
+
+```
+Host {{Server Name}}
+  Hostname {{Server URL}}
+  Port {{Server SSH Port}}
+  ProxyCommand qpa ssh %r %h %p
+```
+
+<Callout type="info">
+`config` 파일 작성 시 Seamless SSH 설정하고자 하는 서버마다 서버 이름, URL, 포트를 입력함으로써 서버를 특정합니다.
+서버 간 URL, 포트가 겹치지 않는 경우 아래와 같이 입력해도 접속할 수 있습니다.
+```
+Host *
+  ProxyCommand qpa ssh %r %h %p
+```
+</Callout>
+
+##### 3.4. 이상으로 설정이 완료됩니다.
+
+Agent &gt; Server 탭에서 역할을 선택하면 기존 ssh 명령어로 서버에 접속할 수 있습니다.
+```
+$ ssh deploy@{{Server Name}}
+```
+
+
+### 에이전트를 통한 쿠버네티스 접속
+
+<figure data-layout="center" data-align="center">
+<img src="/user-manual/user-agent/kubernetes-agent-access-flow.png" alt="kubernetes-agent-access-flow.png" width="764" />
+</figure>
+
+권한을 부여 받은 사용자는 에이전트 실행 시 현재 정책에 따른 `kubeconfig` 파일이 자동으로 수신됩니다.
+이를 통해 Kubernetes Client (kubectl, lens, k9s 등) 툴로 Kubernetes API 리소스에 접근할 수 있습니다.
+
+에이전트에서는 접근 가능한 클러스트 리스트를 표시하며, 각 클러스터에 적용된 정책을 확인할 수 있습니다.
+또한 설정 메뉴를 통해 `kubeconfig` 파일의 위치를 확인하고, 파일의 경로를 변경할 수 있습니다.
+
+#### 1. Kubernetes 역할 선택하기
+
+사용자 프로필 영역 하단의 `Role` 버튼을 클릭하면 역할 선택 모달이 열립니다.
+원하는 역할을 고르고 `OK` 버튼을 클릭하세요.
+
+<figure data-layout="center" data-align="center">
+<img src="/user-manual/user-agent/screenshot-20240730-152705.png" alt="Agent &gt; Kubernetes &gt; Select a Role" width="760" />
+<figcaption>
+Agent &gt; Kubernetes &gt; Select a Role
+</figcaption>
+</figure>
+
+<Callout type="info">
+역할이 두 개 이상이라면, Agent 로그인 후 Kubernetes 기능 사용을 위해 역할 선택을 먼저 완료해야 합니다.
+</Callout>
+
+
+#### 2. Policy 조회하기
+
+선택된 역할에 따라 접근 가능한 리소스가 표시됩니다.
+각 클러스터 우측의 `🔍` 버튼을 누르면 Policy Information 팝업창이 나타나며 이곳에서 해당 클러스터에 적용된 정책 목록을 자세히 확인할 수 있습니다.
+
+<figure data-layout="center" data-align="center">
+<img src="/user-manual/user-agent/screenshot-20240730-161141.png" alt="Agent &gt; Policy Information" width="760" />
+<figcaption>
+Agent &gt; Policy Information
+</figcaption>
+</figure>
+
+#### 3. Kubeconfig 경로 설정하기
+
+Agent 설정 메뉴에서 `KubeConfig Path` 버튼을 클릭하여 Kubeconfig 경로 설정 모달을 엽니다.
+
+<figure data-layout="center" data-align="center">
+<img src="/user-manual/user-agent/screenshot-20240730-154623.png" alt="Agent &gt; Settings &gt; Configure Kubeconfig Path" width="764" />
+<figcaption>
+Agent &gt; Settings &gt; Configure Kubeconfig Path
+</figcaption>
+</figure>
+
+* **Path Configuration** : Kubeconfig 파일 저장 경로를 사용자가 지정할 수 있습니다.
+    * 기본값은 `$HOME/.kube/querypie-kubeconfig` 입니다.
+    * 경로 필드 우측 `Upload` 버튼을 누르면 로컬 파일 경로를 지정할 수 있는 팝업이 나타납니다.
+
+
+<figure data-layout="center" data-align="center">
+<img src="/user-manual/user-agent/screenshot-20240730-163530.png" alt="경로 지정 팝업" width="760" />
+<figcaption>
+경로 지정 팝업
+</figcaption>
+</figure>
+
+* **Where** : 우측의 `🔽` 버튼을 클릭하여 원하는 폴더를 지정합니다.
+* **Save As** : Kubeconfig 파일의 이름을 입력합니다. 변경하지 않으면 기본값으로 적용됩니다.
+* **Command Line** : KUBECONFIG 환경 변수를 선언하기 위한 커맨드 라인을 제공합니다.
+
+1) KUBECONFIG 환경 변수를 최초 설정하는 경우, 명령 줄 내의 디폴트 "`${KUBECONFIG}`" 값을 사용 전에 "`${HOME}/.kube/config`"로 변경해야 합니다.
+```
+export KUBECONFIG="${HOME}/.kube/config:${HOME}/.kube/querypie-kubeconfig"
+```
+
+2) QueryPie에서 제공된 사용자 지정 kubeconfig 경로를 변경한 경우 새 경로로 환경 변수를 다시 선언해야 합니다.
+```
+export KUBECONFIG="${KUBECONFIG}:<user-specified-path>"
+```
+
+3) 보다 자세한 kubeconfig에 대한 내용은 다음 링크를 참조하시기 바랍니다.
+
+* 참고: [kubeconfig 파일 병합](https://kubernetes.io/ko/docs/concepts/configuration/organize-cluster-access-kubeconfig/#kubeconfig-%ED%8C%8C%EC%9D%BC-%EB%B3%91%ED%95%A9)
+* 참고: [KUBECONFIG 환경 변수 설정](https://kubernetes.io/ko/docs/tasks/access-application-cluster/configure-access-multiple-clusters/#kubeconfig-%ED%99%98%EA%B2%BD-%EB%B3%80%EC%88%98-%EC%84%A4%EC%A0%95)
+
+4) `Copy`로 커맨드라인을 복사해 클라이언트에 선언하고 컨텍스트를 접근 가능한 클러스터로 스위칭할 수 있습니다.
+```
+export KUBECONFIG="${KUBECONFIG}:${HOME}/.kube/querypie-kubeconfig"
+```
+
+
+### QueryPie Agent 세팅 초기화하기
+
+세팅을 초기화하면 입력하였던 QueryPie Host 정보가 초기화되어 다시 입력할 수 있게 됩니다.
+#### Agent 내 설정 메뉴에서 초기화
+
+프로필 영역 우측 `⚙️` 버튼을 클릭하여 설정 메뉴를 엽니다. `Reset All Settings` 버튼을 클릭합니다.
+
+<figure data-layout="center" data-align="center">
+<img src="/user-manual/user-agent/screenshot-20240730-153518.png" alt="Agent &gt; Settings" width="361" />
+<figcaption>
+Agent &gt; Settings
+</figcaption>
+</figure>
+
+
+#### (Mac) 메뉴 막대 내 앱 메뉴에서 초기화
+
+메뉴 막대에서 QueryPie Agent 아이콘을 클릭하여 앱 메뉴를 엽니다. `Reset All Settings` 버튼을 클릭합니다.
+
+<figure data-layout="center" data-align="center">
+<img src="/user-manual/user-agent/screenshot-20240730-153524.png" alt="Agent &gt; App menu" width="363" />
+<figcaption>
+Agent &gt; App menu
+</figcaption>
+</figure>
+
+