altair823-org/inkling
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 18 Wiki Activity

sync 도움말 — SyncHelpModal + ConflictModal inline + README 동기화 섹션 재작성 #33

Merged
altair823 merged 9 commits from worktree-v034-sync-help into main 2026-05-10 14:59:08 +00:00
Conversation 3 Commits 9 Files Changed 10 +1144 -22
altair823 commented 2026-05-10 14:54:03 +00:00
Owner
Copy Link

v0.3.0 Cut E (양방향 sync) dogfood 첫 시도 (v0.3.3 hotfix 직후) 의 결과로, 사용자가 conflict 시나리오에 막힌 순간 도움받을 곳이 부재한 갭을 메운다. 3 표면 (in-app modal + ConflictModal inline + README) 통합.

주요 변경

신규 — SyncHelpModal (4 anchor 섹션)

설정 → 동기화 저장소 → "도움말" 버튼 또는 ConflictModal 의 "자세히 보기 →" 링크에서 진입.

  • #main-conflict — 편집/편집, 삭제/편집, AI 결과 충돌 3 케이스의 결정 트리
  • #auto — fetch+rebase / 첫 sync 순서 / push 거부 자동 처리 / 자동 sync 주기
  • #silent — 시계 어긋남 (NTP) / 동시 수정 회피 / 자동 sync 실패 silent
  • #setup — URL 형식 (SSH/HTTPS, 잘못된 git@https:// 사례) / 인증 (SSH key, OS credential helper) / 연결 테스트 실패 troubleshoot / URL 재설정

ConflictModal 패턴 정합 (overlay onClick + body stopPropagation, X 버튼 aria-label="닫기", zIndex 110 으로 ConflictModal 100 위에 stack).

갱신 — ConflictModal

각 conflict row 에 local/remote inline 설명 ("내 것 사용" / "원격 사용" 의미) + (옵션) "자세히 보기 →" 링크 (onOpenHelp callback). onOpenHelp prop optional → 기존 caller (App.test, SettingsPage.test) type-clean 유지.

갱신 — SyncSection

"도움말" 버튼 (URL row 마지막) + SyncHelpModal mount + ConflictModal 의 onOpenHelp wiring. busy (저장/테스트/sync 진행) 중에도 도움말은 reachable (read-only).

갱신 — README.md

stale "원격 백업 (F6-L2)" 섹션 (v0.2.1 MVP 시점 — 트레이 "지금 동기화" + 수동 git init) 통째 재작성 → "동기화 (Git, F21 Cut E)". 일회 설정 / 일상 사용 / 충돌 해결 (3 케이스) / Silent risk / Troubleshoot. in-app SyncHelpModal 과 동일 정보 (다만 산문체).

게이트

  • 단위 727 → 738 PASS (+11): SyncHelpModal 7 + ConflictModal 회귀 3 + SyncSection 회귀 1
  • typecheck 0 errors
  • 신규 npm dep 0
  • 1 pre-existing 무관 flake (tests/unit/SyncService.test.ts Windows tmpdir EPERM, 본 PR 무영향)

Spec / Plan

  • Spec: docs/superpowers/specs/2026-05-10-sync-help-design.md
  • Plan: docs/superpowers/plans/2026-05-10-sync-help.md (4 task TDD)

후속 (deferred)

  • ESC key handler (현재 ConflictModal 도 X + overlay 만, 일관성 유지). 도입 시 modal 두 컴포넌트 동시 처리
  • SyncHelpAnchor literal union 의 ConflictModal.tsx duplicate 제거 (import 로 통일)
  • 1주 dogfood soak 후 도움말 텍스트 정합성 1차 갱신 (실제 사용자 경험과 어긋난 부분 보강)

비포함 (YAGNI)

  • 'both' choice (Cut E 정책 deferred)
  • 다국어 (앱 한국어 only)
  • 스크린샷 / GIF
  • ConflictModal diff 시각 개선 (별개 task)
v0.3.0 Cut E (양방향 sync) dogfood 첫 시도 (v0.3.3 hotfix 직후) 의 결과로, 사용자가 conflict 시나리오에 막힌 순간 도움받을 곳이 부재한 갭을 메운다. 3 표면 (in-app modal + ConflictModal inline + README) 통합. ## 주요 변경 ### 신규 — `SyncHelpModal` (4 anchor 섹션) `설정 → 동기화 저장소 → "도움말"` 버튼 또는 ConflictModal 의 "자세히 보기 →" 링크에서 진입. - `#main-conflict` — 편집/편집, 삭제/편집, AI 결과 충돌 3 케이스의 결정 트리 - `#auto` — fetch+rebase / 첫 sync 순서 / push 거부 자동 처리 / 자동 sync 주기 - `#silent` — 시계 어긋남 (NTP) / 동시 수정 회피 / 자동 sync 실패 silent - `#setup` — URL 형식 (SSH/HTTPS, 잘못된 git@https:// 사례) / 인증 (SSH key, OS credential helper) / 연결 테스트 실패 troubleshoot / URL 재설정 ConflictModal 패턴 정합 (overlay onClick + body stopPropagation, X 버튼 `aria-label="닫기"`, zIndex 110 으로 ConflictModal 100 위에 stack). ### 갱신 — `ConflictModal` 각 conflict row 에 local/remote inline 설명 ("내 것 사용" / "원격 사용" 의미) + (옵션) "자세히 보기 →" 링크 (onOpenHelp callback). `onOpenHelp` prop optional → 기존 caller (App.test, SettingsPage.test) type-clean 유지. ### 갱신 — `SyncSection` "도움말" 버튼 (URL row 마지막) + `SyncHelpModal` mount + `ConflictModal` 의 `onOpenHelp` wiring. busy (저장/테스트/sync 진행) 중에도 도움말은 reachable (read-only). ### 갱신 — `README.md` stale "원격 백업 (F6-L2)" 섹션 (v0.2.1 MVP 시점 — 트레이 "지금 동기화" + 수동 `git init`) 통째 재작성 → "동기화 (Git, F21 Cut E)". 일회 설정 / 일상 사용 / 충돌 해결 (3 케이스) / Silent risk / Troubleshoot. in-app SyncHelpModal 과 동일 정보 (다만 산문체). ## 게이트 - 단위 727 → **738 PASS** (+11): SyncHelpModal 7 + ConflictModal 회귀 3 + SyncSection 회귀 1 - typecheck 0 errors - 신규 npm dep 0 - 1 pre-existing 무관 flake (`tests/unit/SyncService.test.ts` Windows tmpdir EPERM, 본 PR 무영향) ## Spec / Plan - Spec: `docs/superpowers/specs/2026-05-10-sync-help-design.md` - Plan: `docs/superpowers/plans/2026-05-10-sync-help.md` (4 task TDD) ## 후속 (deferred) - ESC key handler (현재 ConflictModal 도 X + overlay 만, 일관성 유지). 도입 시 modal 두 컴포넌트 동시 처리 - `SyncHelpAnchor` literal union 의 ConflictModal.tsx duplicate 제거 (import 로 통일) - 1주 dogfood soak 후 도움말 텍스트 정합성 1차 갱신 (실제 사용자 경험과 어긋난 부분 보강) ## 비포함 (YAGNI) - 'both' choice (Cut E 정책 deferred) - 다국어 (앱 한국어 only) - 스크린샷 / GIF - ConflictModal diff 시각 개선 (별개 task)
altair823 added 8 commits 2026-05-10 14:54:04 +00:00
docs(spec): sync 도움말 v0.3.4 — SyncHelpModal + ConflictModal inline + README e8c6b94d2e 
3 표면 (in-app modal + ConflictModal inline + README) 통합 도움말.
4 시나리오 카테고리: 메인 conflict / 자동 처리 / silent risk / setup·인증.
ConflictModal local/remote 각 옵션 inline 설명 + "자세히 보기" 링크 →
SyncHelpModal anchor jump.

다기기 dogfood 의 핵심 가치 검증 (sync) 인데 막힌 순간 도움말 부재 →
v0.3.0 Cut E + v0.3.3 hotfix 기반 공식 도움말.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
docs(plan): sync 도움말 4-task TDD 구현 계획 976d53ccfc 
Task 1: SyncHelpModal 신규 (4 anchor 섹션)
Task 2: ConflictModal inline 설명 + onOpenHelp optional prop
Task 3: SyncSection 도움말 버튼 + modal mount + ConflictModal wiring
Task 4: README "원격 백업" → "동기화 (Git, Cut E)" 통째 재작성

각 task TDD (test → impl → typecheck → commit), 단위 +11.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
feat(sync-help): SyncHelpModal 4 anchor 섹션 (메인 conflict / 자동 / silent / setup) 5e55cd3469
feat(sync-help): ConflictModal inline 설명 + 자세히 보기 링크 (onOpenHelp prop) 54ef394bb4
feat(sync-help): SyncSection 도움말 버튼 + SyncHelpModal mount + ConflictModal onOpenHelp wiring a5e1c1de35
fix(sync-help): SyncSection 도움말 버튼 busy 중 disable 해제 8cd6382902 
리뷰 minor 반영. busy (저장/테스트/sync 진행) 시 정확히 사용자가
도움말이 가장 필요한 시점이라 disable 회수. read-only 컴포넌트라
race risk 0.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
docs: README 동기화 섹션 Cut E 반영 — 양방향 sync + ConflictModal + Silent risk + Troubleshoot dca1def87c
chore: package-lock.json version 0.3.1 → 0.3.3 catch-up d686c661ba 
v0.3.3 hotfix 시 package.json 만 bump 됐고 lockfile 미동기화.
v0.3.4 진입 시 npm install 로 자동 동기화됨. cleanup commit.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
claude-reviewer-01 requested changes 2026-05-10 14:55:33 +00:00
claude-reviewer-01 left a comment
Member
Copy Link

회차 1 — final integration review 결과 1 actionable 발견.

Actionable (Minor):

src/renderer/inbox/components/ConflictModal.tsx:8 — onOpenHelp?: (anchor: 'main-conflict' | 'auto' | 'silent' | 'setup') => void 가 SyncHelpModal.tsx:3 의 SyncHelpAnchor 타입을 literal 로 duplicate. 두 파일이 동일 디렉터리 sibling 이고 SyncHelpAnchor 가 이미 export 되어 있으므로 import 1줄로 단일 source of truth 가능. 향후 anchor 추가 시 두 파일 동시 수정 누락 risk 가 있고 TS 가 catch 하지 않음. 수정 권장:

import type { SyncHelpAnchor } from './SyncHelpModal.js';

interface Props {
  onClose: () => void;
  onResolved: () => void;
  onOpenHelp?: (anchor: SyncHelpAnchor) => void;
}

Deferred (PR body 에 이미 명시):

  • ESC key handler 부재 — ConflictModal 도 X + overlay 만 (프로젝트 전반 패턴). 본 PR 에서 도입하면 SyncHelpModal 만 일관성 깨고, 양쪽 도입은 v0.3.4 sync-help scope 외. 후속 cut.
  • 1주 dogfood soak 후 텍스트 정합성 갱신.

Strengths (회차 등록 의무 이행):

  • Spec verbatim 충실 (3 표면 모두 plan 의 코드/콘텐츠 그대로).
  • TDD 절제: SyncHelpModal 7 + ConflictModal 회귀 3 + SyncSection 회귀 1 (최소 + 정확).
  • 통합 wire-through 깔끔: zIndex 100→110 stack, optional onOpenHelp 로 기존 caller backward-compatible, showHelp object replace 로 anchor 자연 cleanup.
  • 8cd6382 hotfix (도움말 버튼 busy 중 disable 해제) — 사용자 가장 막힌 순간 도움말 reachable, 적절한 follow-up.
  • README 의 stale F6-L2 섹션 정리 + in-app 과 콘텐츠 정합.
회차 1 — final integration review 결과 1 actionable 발견. **Actionable (Minor)**: `src/renderer/inbox/components/ConflictModal.tsx:8` — `onOpenHelp?: (anchor: 'main-conflict' | 'auto' | 'silent' | 'setup') => void` 가 `SyncHelpModal.tsx:3` 의 `SyncHelpAnchor` 타입을 literal 로 duplicate. 두 파일이 동일 디렉터리 sibling 이고 `SyncHelpAnchor` 가 이미 export 되어 있으므로 import 1줄로 단일 source of truth 가능. 향후 anchor 추가 시 두 파일 동시 수정 누락 risk 가 있고 TS 가 catch 하지 않음. 수정 권장: ```tsx import type { SyncHelpAnchor } from './SyncHelpModal.js'; interface Props { onClose: () => void; onResolved: () => void; onOpenHelp?: (anchor: SyncHelpAnchor) => void; } ``` **Deferred (PR body 에 이미 명시)**: - ESC key handler 부재 — ConflictModal 도 X + overlay 만 (프로젝트 전반 패턴). 본 PR 에서 도입하면 SyncHelpModal 만 일관성 깨고, 양쪽 도입은 v0.3.4 sync-help scope 외. 후속 cut. - 1주 dogfood soak 후 텍스트 정합성 갱신. **Strengths** (회차 등록 의무 이행): - Spec verbatim 충실 (3 표면 모두 plan 의 코드/콘텐츠 그대로). - TDD 절제: SyncHelpModal 7 + ConflictModal 회귀 3 + SyncSection 회귀 1 (최소 + 정확). - 통합 wire-through 깔끔: zIndex 100→110 stack, optional onOpenHelp 로 기존 caller backward-compatible, showHelp object replace 로 anchor 자연 cleanup. - 8cd6382 hotfix (도움말 버튼 busy 중 disable 해제) — 사용자 가장 막힌 순간 도움말 reachable, 적절한 follow-up. - README 의 stale F6-L2 섹션 정리 + in-app 과 콘텐츠 정합.
altair823 added 1 commit 2026-05-10 14:56:31 +00:00
refactor(sync-help): ConflictModal — SyncHelpAnchor import 로 literal duplicate 제거 9d6f5bfacc 
PR #33 회차 1 review 반영. 두 파일 sibling 인데 anchor union 두 곳 정의 →
import type 1줄로 단일 source of truth. 향후 anchor 추가 시 두 파일 동시
수정 누락 risk + TS 가 catch 하지 않던 silent drift risk 제거.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
claude-reviewer-01 approved these changes 2026-05-10 14:56:46 +00:00
claude-reviewer-01 left a comment
Member
Copy Link

회차 2 — 회차 1 actionable (ConflictModal literal union duplicate) 반영 (commit 9d6f5bf, import type { SyncHelpAnchor } from './SyncHelpModal.js').

검증:

  • 단위 18 PASS (ConflictModal 6 + SyncSection 5 + SyncHelpModal 7)
  • typecheck 0 errors
  • diff 최소 (+2/-1, 단일 파일)

Deferred 항목 (ESC handler, dogfood soak 후 텍스트 갱신) 은 PR body 에 명시된 대로 후속.

추가 actionable 없음. 머지 동의.

회차 2 — 회차 1 actionable (ConflictModal literal union duplicate) 반영 (commit 9d6f5bf, `import type { SyncHelpAnchor } from './SyncHelpModal.js'`). 검증: - 단위 18 PASS (ConflictModal 6 + SyncSection 5 + SyncHelpModal 7) - typecheck 0 errors - diff 최소 (+2/-1, 단일 파일) Deferred 항목 (ESC handler, dogfood soak 후 텍스트 갱신) 은 PR body 에 명시된 대로 후속. 추가 actionable 없음. 머지 동의.
claude-reviewer-01 approved these changes 2026-05-10 14:57:30 +00:00
altair823 merged commit f2db82b6d6 into main 2026-05-10 14:59:08 +00:00
altair823 deleted branch worktree-v034-sync-help 2026-05-10 14:59:09 +00:00
Sign in to join this conversation.
Reviewers
No Reviewers
claude-reviewer-01
Labels
No items
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
altair823 claude-reviewer-01
No Assignees
2 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: altair823-org/inkling#33
Delete Branch "worktree-v034-sync-help"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?