diff --git a/.gitignore b/.gitignore index 3554a7fd..8b732868 100644 --- a/.gitignore +++ b/.gitignore @@ -55,3 +55,4 @@ coverage/ # package-lock.json # yarn.lock .worktrees/ +cli/claude_karma_cli.egg-info/ diff --git a/.gitmodules b/.gitmodules new file mode 100644 index 00000000..6c5fe5d8 --- /dev/null +++ b/.gitmodules @@ -0,0 +1,3 @@ +[submodule "git-radio"] + path = git-radio + url = https://github.com/JayantDevkar/git-radio.git diff --git a/api/collectors.py b/api/collectors.py index b50cd244..62bf0a4d 100644 --- a/api/collectors.py +++ b/api/collectors.py @@ -10,9 +10,10 @@ from datetime import datetime from typing import Any, Dict, List, Optional, Set -from command_helpers import classify_invocation, is_command_category, is_skill_category +from command_helpers import category_from_base_directory, classify_invocation, is_command_category, is_skill_category from config import FILE_TOOL_MAPPINGS from models import AssistantMessage, Session, ToolUseBlock, UserMessage +from utils import extract_prompt_from_content from models.conversation import ConversationEntity from utils import FileOperation, extract_file_operation, normalize_key @@ -45,6 +46,12 @@ class ConversationData: skills: Counter = field(default_factory=Counter) commands: Counter = field(default_factory=Counter) + # Skill categories extracted from JSONL path ("Base directory for this skill:" lines). + # Maps skill_name → category string (e.g. "custom_skill", "user_command", "plugin_skill"). + # This is a secondary source of truth — more reliable than local classify_invocation() + # for remote sessions where the plugin may not be installed locally. + skill_categories: Dict[str, str] = field(default_factory=dict) + # File activity file_operations: List[FileOperation] = field(default_factory=list) @@ -54,6 +61,7 @@ class ConversationData: # Initial prompt initial_prompt: Optional[str] = None + initial_prompt_images: List[Dict[str, str]] = field(default_factory=list) @dataclass @@ -84,6 +92,7 @@ class SessionData: # Subagent spawning info task_tool_to_type: Dict[str, str] = field(default_factory=dict) # tool_use_id -> subagent_type + task_tool_to_name: Dict[str, str] = field(default_factory=dict) # tool_use_id -> display_name task_descriptions: Dict[str, str] = field( default_factory=dict ) # normalized_desc -> subagent_type @@ -148,6 +157,7 @@ def _extract_file_operation( ) + def _collect_conversation_data_core( entity: ConversationEntity, actor: str, @@ -170,6 +180,10 @@ def _collect_conversation_data_core( """ data = ConversationData() + # Track the last Skill tool invocation so we can look for the base directory + # in the next UserMessage (Claude Code injects skill content as a user turn). + _pending_skill_name: Optional[str] = None + for msg in entity.iter_messages(): # Extract context from any message git_branch = getattr(msg, "git_branch", None) @@ -180,13 +194,37 @@ def _collect_conversation_data_core( if cwd: data.working_directories.add(cwd) - # User message - get initial prompt + # User message - get initial prompt and check for skill base directory if isinstance(msg, UserMessage): if data.initial_prompt is None: content = msg.content or "" # Skip tool result and internal messages if not msg.is_tool_result and not msg.is_internal_message: - data.initial_prompt = content[:5000] if content else None + prompt = extract_prompt_from_content(content) if content else None + # Skip empty prompts (e.g., bare command invocations without args) + if prompt: + data.initial_prompt = prompt[:5000] + if msg.image_attachments: + data.initial_prompt_images = list(msg.image_attachments) + + # If we had a pending Skill invocation, check if this message carries + # the base directory line injected by Claude Code. + if _pending_skill_name is not None: + content = msg.content or "" + if "Base directory for this skill:" in content: + try: + # Extract first line after the marker + marker = "Base directory for this skill:" + idx = content.index(marker) + after = content[idx + len(marker):] + first_line = after.strip().splitlines()[0].strip() if after.strip() else "" + if first_line: + cat = category_from_base_directory(first_line) + if cat: + data.skill_categories[_pending_skill_name] = cat + except (ValueError, IndexError): + pass + _pending_skill_name = None # Assistant message - extract tools and file operations elif isinstance(msg, AssistantMessage): @@ -204,11 +242,17 @@ def _collect_conversation_data_core( data.skills[skill_name] += 1 elif is_command_category(kind): data.commands[skill_name] += 1 + # Track for base-directory lookahead in next UserMessage + _pending_skill_name = skill_name # Extract file operations using shared utility file_op = _extract_file_operation(block, msg.timestamp, actor, actor_type) if file_op: data.file_operations.append(file_op) + else: + # Non-user, non-assistant message clears the pending skill tracker + # (the injected content always comes in the very next message) + _pending_skill_name = None return data @@ -239,8 +283,10 @@ def collect_agent_data(agent: ConversationEntity) -> ConversationData: if data.initial_prompt is None: for msg in agent.iter_messages(): if isinstance(msg, UserMessage) and msg.content: - data.initial_prompt = msg.content[:5000] - break + prompt = extract_prompt_from_content(msg.content) + if prompt: + data.initial_prompt = prompt[:5000] + break return data @@ -291,7 +337,12 @@ def collect_session_data(session: Session, include_subagents: bool = False) -> S content = msg.content or "" # Skip tool result messages if not (content.strip().startswith("{") and "'tool_use_id':" in content): - data.initial_prompt = content[:5000] if content else None + prompt = extract_prompt_from_content(content) if content else None + # Skip empty prompts (e.g., bare command invocations without args) + if prompt: + data.initial_prompt = prompt[:5000] + if msg.image_attachments: + data.initial_prompt_images = list(msg.image_attachments) # Assistant message processing elif isinstance(msg, AssistantMessage): @@ -330,21 +381,24 @@ def collect_session_data(session: Session, include_subagents: bool = False) -> S if file_op: data.file_operations.append(file_op) - # Extract Task -> subagent_type mapping + # Extract Task -> subagent_type and name mappings if tool_name in ("Task", "Agent"): - subagent_type = block.input.get("subagent_type") - if subagent_type: - data.task_tool_to_type[block.id] = subagent_type - # Store both description and prompt for fallback matching - # The subagent's initial_prompt comes from Task's "prompt" field, - # not the "description" field, so we need to match by prompt - prompt = block.input.get("prompt", "")[:100] - if prompt: - data.task_descriptions[normalize_key(prompt)] = subagent_type - # Also store description as secondary fallback - desc = block.input.get("description", "")[:100] - if desc: - data.task_descriptions[normalize_key(desc)] = subagent_type + subagent_type = block.input.get("subagent_type") or "general-purpose" + data.task_tool_to_type[block.id] = subagent_type + # Store both description and prompt for fallback matching + # The subagent's initial_prompt comes from Task's "prompt" field, + # not the "description" field, so we need to match by prompt + prompt = block.input.get("prompt", "")[:100] + if prompt: + data.task_descriptions[normalize_key(prompt)] = subagent_type + # Also store description as secondary fallback + desc = block.input.get("description", "")[:100] + if desc: + data.task_descriptions[normalize_key(desc)] = subagent_type + # Extract display name from `name` input field + agent_display_name = block.input.get("name") + if agent_display_name: + data.task_tool_to_name[block.id] = agent_display_name # Collect subagent data if requested if include_subagents: @@ -404,7 +458,9 @@ class SubagentInfo: skills_used: Counter commands_used: Counter initial_prompt: Optional[str] + initial_prompt_images: List[Dict[str, str]] subagent_type: Optional[str] + display_name: Optional[str] message_count: int @@ -422,8 +478,9 @@ def collect_subagent_info( Returns: List of SubagentInfo for each subagent """ - # Build agent_id -> subagent_type mapping from tool results + # Build agent_id -> subagent_type and agent_id -> display_name mappings from tool results agent_id_to_type: Dict[str, str] = {} + agent_id_to_name: Dict[str, str] = {} for tool_use_id, subagent_type in session_data.task_tool_to_type.items(): result_data = tool_results.get(tool_use_id) @@ -434,33 +491,25 @@ def collect_subagent_info( ): agent_id_to_type[result_data.spawned_agent_id] = subagent_type + for tool_use_id, display_name in session_data.task_tool_to_name.items(): + result_data = tool_results.get(tool_use_id) + if ( + result_data + and hasattr(result_data, "spawned_agent_id") + and result_data.spawned_agent_id + ): + agent_id_to_name[result_data.spawned_agent_id] = display_name + subagents_info: List[SubagentInfo] = [] for subagent in session.list_subagents(): - # Count tools, skills, and commands for this subagent - single pass - tool_counts: Counter = Counter() - skill_counts: Counter = Counter() - command_counts: Counter = Counter() - initial_prompt = None - - for msg in subagent.iter_messages(): - if isinstance(msg, UserMessage): - if initial_prompt is None: - initial_prompt = msg.content[:5000] if msg.content else None - elif isinstance(msg, AssistantMessage): - for block in msg.content_blocks: - if isinstance(block, ToolUseBlock): - tool_counts[block.name] += 1 - - # Extract skill/command names from Skill tool inputs - if block.name == "Skill" and block.input: - skill_name = block.input.get("skill") - if skill_name: - kind = classify_invocation(skill_name, source="skill_tool") - if is_skill_category(kind): - skill_counts[skill_name] += 1 - elif is_command_category(kind): - command_counts[skill_name] += 1 + # Collect all subagent data in a single pass via collect_agent_data + agent_data = collect_agent_data(subagent) + tool_counts = agent_data.tool_counts + skill_counts = agent_data.skills + command_counts = agent_data.commands + initial_prompt = agent_data.initial_prompt + initial_prompt_images = list(agent_data.initial_prompt_images) # Match subagent to Task invocation subagent_type = agent_id_to_type.get(subagent.agent_id) @@ -489,7 +538,9 @@ def collect_subagent_info( skills_used=skill_counts, commands_used=command_counts, initial_prompt=initial_prompt, + initial_prompt_images=initial_prompt_images, subagent_type=subagent_type, + display_name=agent_id_to_name.get(subagent.agent_id), message_count=subagent.message_count, ) ) diff --git a/api/command_helpers/__init__.py b/api/command_helpers/__init__.py index 8758c929..6c150607 100644 --- a/api/command_helpers/__init__.py +++ b/api/command_helpers/__init__.py @@ -17,6 +17,7 @@ from .categories import ( InvocationCategory, + category_from_base_directory, is_command_category, is_skill_category, ) @@ -42,16 +43,20 @@ _entry_map_cache, _entry_type_cache, _expand_name_cache, + _is_custom_skill, _is_plugin_skill, _plugin_skill_cache, classify_invocation, expand_plugin_short_name, + is_custom_skill_local, + is_plugin_installed_locally, is_plugin_skill, ) __all__ = [ # categories "InvocationCategory", + "category_from_base_directory", "is_skill_category", "is_command_category", # cli_js @@ -64,6 +69,8 @@ # plugins "classify_invocation", "expand_plugin_short_name", + "is_custom_skill_local", + "is_plugin_installed_locally", "is_plugin_skill", # parsing "parse_command_from_content", diff --git a/api/command_helpers/categories.py b/api/command_helpers/categories.py index 346a6c51..3a3f1ad0 100644 --- a/api/command_helpers/categories.py +++ b/api/command_helpers/categories.py @@ -19,13 +19,14 @@ "plugin_skill", "plugin_command", "custom_skill", + "inherited_skill", "user_command", "agent", ] # Categories that go into session_skills table _SKILL_CATEGORIES: frozenset[str] = frozenset( - {"bundled_skill", "plugin_skill", "custom_skill"} + {"bundled_skill", "plugin_skill", "custom_skill", "inherited_skill"} ) # Categories that go into session_commands table _COMMAND_CATEGORIES: frozenset[str] = frozenset({"builtin_command", "user_command", "plugin_command"}) @@ -39,3 +40,25 @@ def is_skill_category(kind: str) -> bool: def is_command_category(kind: str) -> bool: """Return True for any category that belongs in the commands bucket.""" return kind in _COMMAND_CATEGORIES + + +def category_from_base_directory(base_dir: str) -> str | None: + """Infer skill category from a 'Base directory for this skill:' path. + + Claude Code injects this line into the UserMessage that follows a Skill + tool invocation. The path segment reliably identifies the category: + ~/.claude/plugins/cache/.../commands/ → plugin_command + ~/.claude/plugins/cache/... → plugin_skill + ~/.claude/skills/... → custom_skill + ~/.claude/commands/... → user_command + """ + # Check plugin paths first — they also contain /skills/ or /commands/ + if "/plugins/cache/" in base_dir: + if "/commands/" in base_dir: + return "plugin_command" + return "plugin_skill" + if "/skills/" in base_dir: + return "custom_skill" + if "/commands/" in base_dir: + return "user_command" + return None diff --git a/api/command_helpers/cli_js.py b/api/command_helpers/cli_js.py index 982a73b8..514ae47a 100644 --- a/api/command_helpers/cli_js.py +++ b/api/command_helpers/cli_js.py @@ -178,13 +178,21 @@ def _find_cli_js_path() -> Path | None: if claude_bin: try: resolved = Path(claude_bin).resolve() - # npm global: .../bin/claude → .../lib/node_modules/@anthropic-ai/claude-code/cli.js - cli_js = resolved.parent.parent / "lib" / "node_modules" / "@anthropic-ai" / "claude-code" / "cli.js" - if cli_js.is_file(): - return cli_js - # Direct symlink to cli.js (e.g., Homebrew) - if resolved.name == "cli.js" and resolved.is_file(): - return resolved + if "Caskroom" in str(resolved): + logger.debug( + "Homebrew Cask install detected (%s) — no cli.js available; " + "using hardcoded command sets as fallback", + resolved, + ) + # Cask distributes a native binary, not Node.js — skip npm traversal + else: + # npm global: .../bin/claude → .../lib/node_modules/@anthropic-ai/claude-code/cli.js + cli_js = resolved.parent.parent / "lib" / "node_modules" / "@anthropic-ai" / "claude-code" / "cli.js" + if cli_js.is_file(): + return cli_js + # Direct symlink to cli.js (e.g., Homebrew) + if resolved.name == "cli.js" and resolved.is_file(): + return resolved except (OSError, ValueError): pass diff --git a/api/command_helpers/plugins.py b/api/command_helpers/plugins.py index 1ffb6ad7..ea3a92c1 100644 --- a/api/command_helpers/plugins.py +++ b/api/command_helpers/plugins.py @@ -22,6 +22,32 @@ logger = logging.getLogger(__name__) _custom_skill_cache: TTLCache[str, bool] = TTLCache(maxsize=128, ttl=60) +_inherited_skill_cache: TTLCache[str, bool] = TTLCache(maxsize=128, ttl=60) + + +def _is_inherited_skill(name: str) -> bool: + """Check if a name corresponds to an inherited plugin skill on disk. + + Inherited skills live at ~/.claude/skills/{name}/SKILL.md and contain + an ``inherited_from:`` key in their YAML frontmatter. Only the first + 512 bytes are read to avoid loading large skill files. + """ + if name in _inherited_skill_cache: + return _inherited_skill_cache[name] + + from config import settings + + skill_file = settings.skills_dir / name / "SKILL.md" + if not skill_file.is_file(): + _inherited_skill_cache[name] = False + return False + try: + head = skill_file.read_text(encoding="utf-8", errors="ignore")[:512] + result = head.startswith("---") and "inherited_from:" in head + except OSError: + result = False + _inherited_skill_cache[name] = result + return result def _is_custom_skill(name: str) -> bool: @@ -277,6 +303,29 @@ def is_plugin_skill(name: str) -> bool: return _is_plugin_skill(name) +def is_plugin_installed_locally(name: str) -> bool: + """Check if a plugin directory exists in the local plugins cache. + + Unlike ``is_plugin_skill`` this does NOT return True for colon-containing + names — it only checks the filesystem for the directory. + + Args: + name: Plugin name (e.g. 'superpowers', 'oh-my-claudecode'). + """ + return _is_plugin_skill(name) + + +def is_custom_skill_local(name: str) -> bool: + """Check if a custom skill file exists on disk. + + Looks for: + - ~/.claude/skills/{name}/SKILL.md + - ~/.claude/skills/{name}/skill.md + - ~/.claude/skills/{name}.md + """ + return _is_custom_skill(name) + + def classify_invocation(name: str, *, source: str = "") -> str: """Classify a command/skill invocation name into one of 6 categories. @@ -319,6 +368,8 @@ def classify_invocation(name: str, *, source: str = "") -> str: return "builtin_command" if ":" in name: return _classify_colon_name(name) + if _is_inherited_skill(name): + return "inherited_skill" if _is_custom_skill(name): return "custom_skill" if _is_plugin_skill(name): diff --git a/api/config.py b/api/config.py index 6e4df965..b91035ae 100644 --- a/api/config.py +++ b/api/config.py @@ -97,7 +97,7 @@ class Settings(BaseSettings): ) cors_allow_credentials: bool = Field(default=True, description="Allow credentials in CORS") cors_allow_methods: List[str] = Field( - default=["GET", "POST", "PUT", "DELETE", "OPTIONS"], + default=["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"], description="Allowed HTTP methods for CORS", ) cors_allow_headers: List[str] = Field( diff --git a/api/db/__init__.py b/api/db/__init__.py index 82efba2c..93e47546 100644 --- a/api/db/__init__.py +++ b/api/db/__init__.py @@ -8,16 +8,18 @@ The JSONL files remain the source of truth. SQLite is a rebuildable cache. """ -from .connection import close_db, create_read_connection, get_read_db, get_writer_db -from .indexer import is_db_ready, run_periodic_sync, sync_all_projects, sync_project +from .connection import close_db, create_read_connection, create_writer_connection, get_read_db, get_writer_db +from .indexer import is_db_ready, run_periodic_sync, sync_all_projects, sync_project, trigger_remote_reindex __all__ = [ "get_writer_db", "get_read_db", "create_read_connection", + "create_writer_connection", "close_db", "sync_all_projects", "sync_project", "is_db_ready", "run_periodic_sync", + "trigger_remote_reindex", ] diff --git a/api/db/connection.py b/api/db/connection.py index df29e612..185503c5 100644 --- a/api/db/connection.py +++ b/api/db/connection.py @@ -66,8 +66,8 @@ def get_writer_db() -> sqlite3.Connection: conn = sqlite3.connect( str(db_path), - check_same_thread=False, timeout=10.0, + check_same_thread=False, ) conn.row_factory = sqlite3.Row @@ -83,6 +83,28 @@ def get_writer_db() -> sqlite3.Connection: return _writer +def create_writer_connection() -> sqlite3.Connection: + """ + Create a fresh read-write connection (NOT singleton). + + Used by background threads (indexer, periodic sync) that need their own + isolated writer connection. Caller is responsible for closing. + + Unlike get_writer_db(), this does NOT call ensure_schema() — the schema + is guaranteed to exist from startup. + """ + db_path = get_db_path() + + conn = sqlite3.connect( + str(db_path), + timeout=10.0, + check_same_thread=False, + ) + conn.row_factory = sqlite3.Row + _apply_pragmas(conn, readonly=False) + return conn + + def create_read_connection() -> sqlite3.Connection: """ Create a new read-only connection for request handling. @@ -99,6 +121,7 @@ def create_read_connection() -> sqlite3.Connection: f"file:{db_path}?mode=ro", uri=True, timeout=5.0, + check_same_thread=False, ) conn.row_factory = sqlite3.Row _apply_pragmas(conn, readonly=True) diff --git a/api/db/indexer.py b/api/db/indexer.py index 4958046c..8c5dfc5b 100644 --- a/api/db/indexer.py +++ b/api/db/indexer.py @@ -26,6 +26,8 @@ # Ensure api/ is on the import path (needed when called from background thread) sys.path.insert(0, str(Path(__file__).parent.parent)) +from command_helpers import category_from_base_directory + logger = logging.getLogger(__name__) # Module-level state @@ -33,6 +35,7 @@ _indexing_lock = threading.Lock() _last_health: dict = {} _last_sync_complete: float = 0.0 +_reindex_lock = threading.Lock() # Separate lock for on-demand remote reindex def is_db_ready() -> bool: @@ -159,6 +162,16 @@ def sync_all_projects(conn: sqlite3.Connection) -> dict: logger.warning("Error syncing worktree %s: %s", wt_dir.name, e) stats["errors"] += 1 + # Third pass: remote sessions from Syncthing sync + try: + remote_stats = index_remote_sessions(conn) + stats["total"] += remote_stats.get("total", 0) + stats["indexed"] += remote_stats.get("indexed", 0) + stats["skipped"] += remote_stats.get("skipped", 0) + stats["errors"] += remote_stats.get("errors", 0) + except Exception as e: + logger.warning("Error indexing remote sessions: %s", e) + # Clean up stale sessions (files deleted from disk) _cleanup_stale_sessions(conn, projects_dir) @@ -271,6 +284,582 @@ def sync_project( return stats +def _load_manifest_classifications(encoded_dir: Path) -> dict[str, str]: + """Load skill_classifications from a remote project's manifest.json. + + Returns a mapping of invocation name → InvocationCategory string + (e.g. {'feature-dev:feature-dev': 'plugin_command'}). + Returns empty dict if manifest doesn't exist or lacks the field. + + Uses validate_manifest() to ensure the manifest is safe before reading. + """ + manifest_path = encoded_dir / "manifest.json" + if not manifest_path.exists(): + return {} + try: + from services.file_validator import validate_manifest + manifest, reason = validate_manifest(manifest_path) + if manifest is None: + logger.warning("Invalid manifest at %s: %s", manifest_path, reason) + return {} + return manifest.skill_classifications + except Exception as e: + logger.warning("Error loading manifest at %s: %s", manifest_path, e) + return {} + + +def _load_manifest_skill_definitions(encoded_dir: Path) -> dict: + """Load skill_definitions from a remote project's manifest.json. + + Returns a dict of skill_name → {content, description, category, base_directory}. + Returns empty dict if manifest doesn't exist or lacks the field. + """ + manifest_path = encoded_dir / "manifest.json" + if not manifest_path.exists(): + return {} + try: + from services.file_validator import validate_manifest + + manifest, reason = validate_manifest(manifest_path) + if manifest is None: + logger.warning("Invalid manifest at %s: %s", manifest_path, reason) + return {} + # Convert SkillDefinitionEntry models to plain dicts + return { + name: entry.model_dump() if hasattr(entry, "model_dump") else entry + for name, entry in manifest.skill_definitions.items() + } + except Exception as e: + logger.warning("Error loading manifest skill definitions at %s: %s", manifest_path, e) + return {} + + +def _apply_manifest_skill_definitions( + conn: sqlite3.Connection, + skill_definitions: dict, + source_user_id: str, + source_machine_id: str, +) -> None: + """Write manifest-provided skill definitions to the skill_definitions table. + + Called once per manifest (not per session). Manifest content takes precedence + over heuristic JSONL extraction because it was read directly from the + exporting machine's filesystem. + + Hard-overrides content and category (manifest is authoritative). + Uses COALESCE for description and base_directory (preserves existing + values when the manifest entry has nulls, e.g. no YAML frontmatter). + Sets extracted_from_session to NULL since this content is from the filesystem. + """ + for skill_name, entry in skill_definitions.items(): + content = entry.get("content") if isinstance(entry, dict) else None + if not content: + continue # Skip entries without content + + category = entry.get("category", "plugin_skill") + description = entry.get("description") + base_directory = entry.get("base_directory") + + try: + conn.execute( + """ + INSERT INTO skill_definitions + (skill_name, source_user_id, source_machine_id, category, + content, base_directory, description, extracted_from_session, + updated_at) + VALUES (?, ?, ?, ?, ?, ?, ?, NULL, datetime('now')) + ON CONFLICT(skill_name, source_user_id) DO UPDATE SET + content = excluded.content, + category = excluded.category, + base_directory = COALESCE(excluded.base_directory, skill_definitions.base_directory), + description = COALESCE(excluded.description, skill_definitions.description), + updated_at = datetime('now') + """, + ( + skill_name, + source_user_id, + source_machine_id, + category, + content, + base_directory, + description, + ), + ) + except Exception as e: + logger.debug( + "Error writing manifest skill definition for %s: %s", skill_name, e + ) + + +def index_remote_sessions(conn: sqlite3.Connection) -> dict: + """ + Index remote sessions from Syncthing-synced directories into SQLite. + + Walks ~/.claude_karma/remote-sessions/{user_id}/{encoded_name}/sessions/ + and upserts session rows with source='remote'. Skips local user's outbox. + + Reads skill_classifications from each project's manifest.json to correctly + classify remote skills vs commands (instead of relying on local plugin cache). + + Returns: + Dict with sync statistics: total, indexed, skipped, errors + """ + from config import settings + from services.remote_sessions import get_project_mapping + + stats = {"total": 0, "indexed": 0, "skipped": 0, "errors": 0} + + remote_base = settings.karma_base / "remote-sessions" + if not remote_base.exists(): + return stats + + mapping = get_project_mapping() + + # Load current mtimes for remote sessions + rows = conn.execute("SELECT uuid, jsonl_mtime FROM sessions WHERE source = 'remote'").fetchall() + db_mtimes = {row["uuid"]: row["jsonl_mtime"] for row in rows} + + local_user = None + config_path = settings.karma_base / "sync-config.json" + if config_path.exists(): + try: + import json as _json + local_user = _json.loads(config_path.read_text()).get("user_id") + except Exception: + pass + + from services.remote_sessions import _load_remote_titles, _resolve_user_id + + for user_dir in remote_base.iterdir(): + if not user_dir.is_dir(): + continue + dir_name = user_dir.name + resolved_uid = _resolve_user_id(user_dir, conn=conn) + + # If resolved_uid still looks like a hostname (contains '.'), try to + # find the canonical member name from sync_members by matching device_id. + # This handles the case where no manifest.json exists yet (member hasn't + # packaged sessions, only received them from us). + if "." in resolved_uid: + try: + from repositories.member_repo import MemberRepository + # Look up member by member_tag pattern in v4 schema + row = conn.execute( + "SELECT member_tag FROM sync_members WHERE member_tag = ?", + (resolved_uid,), + ).fetchone() + if row: + resolved_uid = row[0] + except Exception: + pass # DB lookup failed — keep resolved_uid as-is + + # Fixup stale remote_user_id values (e.g. hostname → clean user_id) + if dir_name != resolved_uid: + updated = conn.execute( + "UPDATE sessions SET remote_user_id = ? WHERE remote_user_id = ? AND source = 'remote'", + (resolved_uid, dir_name), + ).rowcount + if updated: + logger.info("Corrected remote_user_id '%s' → '%s' for %d sessions", dir_name, resolved_uid, updated) + + # Skip local user's outbox (check both dir name and resolved id) + if dir_name == local_user or resolved_uid == local_user: + continue + + for encoded_dir in user_dir.iterdir(): + if not encoded_dir.is_dir(): + continue + encoded_name = encoded_dir.name + # Mapping keys use dir_name (filesystem identity) + local_encoded = mapping.get((dir_name, encoded_name), encoded_name) + + sessions_dir = encoded_dir / "sessions" + if not sessions_dir.exists(): + continue + + # Load manifest classifications once per (dir_name, project) + classification_overrides = _load_manifest_classifications(encoded_dir) + + # Load titles once per (dir_name, project) for remote session title display + titles_map = _load_remote_titles(dir_name, encoded_name) + + # Force re-index when manifest/titles have been updated since last index. + # Without this, the mtime-based skip would prevent reclassification of + # sessions already indexed (their JSONL files haven't changed). + force_reindex = False + # Check both manifest.json (classifications) and titles.json (session titles) + metadata_files = [] + if classification_overrides: + manifest_path = encoded_dir / "manifest.json" + if manifest_path.exists(): + metadata_files.append(manifest_path) + if titles_map: + titles_path = encoded_dir / "titles.json" + if titles_path.exists(): + metadata_files.append(titles_path) + + if metadata_files: + oldest_indexed = conn.execute( + "SELECT MIN(indexed_at) FROM sessions WHERE remote_user_id IN (?, ?) AND project_encoded_name = ? AND source = 'remote'", + (resolved_uid, dir_name, local_encoded), + ).fetchone() + if oldest_indexed and oldest_indexed[0]: + from datetime import datetime, timezone + try: + indexed_dt = datetime.fromisoformat(oldest_indexed[0]) + for meta_file in metadata_files: + meta_mtime = meta_file.stat().st_mtime + meta_dt = datetime.fromtimestamp(meta_mtime, tz=timezone.utc).replace(tzinfo=None) + if meta_dt > indexed_dt: + force_reindex = True + break + except (ValueError, OSError): + pass + + # Apply manifest skill definitions once per project (before per-session loop). + # Manifest content is authoritative — takes precedence over JSONL heuristics. + manifest_skill_defs = _load_manifest_skill_definitions(encoded_dir) + if manifest_skill_defs: + _apply_manifest_skill_definitions( + conn, manifest_skill_defs, + source_user_id=resolved_uid, + source_machine_id=dir_name, + ) + + for jsonl_path in sessions_dir.glob("*.jsonl"): + if jsonl_path.name.startswith("agent-"): + continue + + uuid = jsonl_path.stem + stats["total"] += 1 + + try: + file_stat = jsonl_path.stat() + current_mtime = file_stat.st_mtime + current_size = file_stat.st_size + + if not force_reindex and uuid in db_mtimes and abs(db_mtimes[uuid] - current_mtime) < 0.001: + stats["skipped"] += 1 + continue + + # Validate file before indexing + from services.file_validator import quarantine_file, validate_received_file + valid, reason = validate_received_file(jsonl_path) + if not valid: + quarantine_file(jsonl_path, reason, member_name=resolved_uid) + logger.warning( + "Rejected remote file %s from %s: %s", jsonl_path.name, resolved_uid, reason + ) + try: + from repositories.event_repo import EventRepository + from domain.events import SyncEvent, SyncEventType + EventRepository().log(conn, SyncEvent( + event_type=SyncEventType.session_received, + member_tag=resolved_uid, + project_git_identity=local_encoded, + session_uuid=uuid, + detail={"reason": reason, "file": jsonl_path.name, "rejected": True}, + )) + except Exception: + pass # Best-effort logging + stats["errors"] += 1 + continue + + _index_session( + conn, + jsonl_path, + local_encoded, + current_mtime, + current_size, + source="remote", + remote_user_id=resolved_uid, + remote_machine_id=dir_name, + claude_base_dir=encoded_dir, + classification_overrides=classification_overrides, + session_titles_override=[titles_map[uuid]] if uuid in titles_map else None, + ) + stats["indexed"] += 1 + + # Extract skill definitions from this remote session (best-effort). + # Runs for every indexed session; ON CONFLICT DO NOTHING makes it idempotent. + _extract_skill_definitions_from_session( + conn, + jsonl_path, + source_user_id=resolved_uid, + source_machine_id=dir_name, + session_uuid=uuid, + claude_base_dir=encoded_dir, + classification_overrides=classification_overrides, + ) + + # Log session_received for truly new sessions (not re-index). + # Dedup against sync_events to prevent duplicates from concurrent + # indexer runs (reindex_all + trigger_remote_reindex use separate locks). + if uuid not in db_mtimes: + try: + from repositories.event_repo import EventRepository + from domain.events import SyncEvent, SyncEventType + already_logged = conn.execute( + "SELECT 1 FROM sync_events WHERE event_type = 'session_received' AND session_uuid = ? LIMIT 1", + (uuid,), + ).fetchone() + if not already_logged: + team_names = conn.execute( + "SELECT team_name FROM sync_projects WHERE encoded_name = ?", + (local_encoded,), + ).fetchall() + event_repo = EventRepository() + if team_names: + for (tn,) in team_names: + event_repo.log(conn, SyncEvent( + event_type=SyncEventType.session_received, + team_name=tn, + member_tag=resolved_uid, + project_git_identity=local_encoded, + session_uuid=uuid, + )) + else: + event_repo.log(conn, SyncEvent( + event_type=SyncEventType.session_received, + member_tag=resolved_uid, + project_git_identity=local_encoded, + session_uuid=uuid, + )) + except Exception: + pass # Best-effort logging + except Exception as e: + logger.debug("Error indexing remote session %s: %s", uuid, e) + stats["errors"] += 1 + + # --------------------------------------------------------------- + # v4 inbox scan: karma-out--{member_tag}--{suffix}/ directories + # --------------------------------------------------------------- + karma_base = settings.karma_base + local_member_tag = None + try: + import json as _json + cfg_path = karma_base / "sync-config.json" + if cfg_path.exists(): + cfg = _json.loads(cfg_path.read_text()) + uid = cfg.get("user_id", "") + mtag = cfg.get("machine_tag", "") + if uid and mtag: + local_member_tag = f"{uid}.{mtag}" + except Exception: + pass + + for inbox_dir in karma_base.iterdir(): + if not inbox_dir.is_dir(): + continue + dname = inbox_dir.name + if not dname.startswith("karma-out--"): + continue + # Parse: karma-out--{member_tag}--{folder_suffix} + rest = dname[len("karma-out--"):] + parts = rest.split("--", 1) + if len(parts) != 2: + continue + inbox_member_tag, inbox_suffix = parts + + # Skip our own outbox (we only want inboxes from teammates) + if local_member_tag and inbox_member_tag == local_member_tag: + continue + + sessions_dir = inbox_dir / "sessions" + if not sessions_dir.exists(): + continue + + # Resolve local project encoded_name via git_identity. + # Step 1: Look up the real git_identity from sync_projects using folder_suffix + # Step 2: Match that git_identity against local projects table + local_encoded = inbox_suffix # fallback + try: + # Get git_identity from sync_projects (the source of truth) + sp_row = conn.execute( + "SELECT git_identity FROM sync_projects " + "WHERE folder_suffix = ? AND status = 'shared' LIMIT 1", + (inbox_suffix,), + ).fetchone() + if sp_row and sp_row[0]: + sync_git_id = sp_row[0].rstrip("/").lower() + if sync_git_id.endswith(".git"): + sync_git_id = sync_git_id[:-4] + + # Match against local projects by git_identity + local_rows = conn.execute( + "SELECT encoded_name, git_identity FROM projects " + "WHERE git_identity IS NOT NULL" + ).fetchall() + for (enc, local_git) in local_rows: + lg = (local_git or "").rstrip("/").lower() + if lg.endswith(".git"): + lg = lg[:-4] + # Match: one contains the other (handles short vs full URLs) + if lg and (lg in sync_git_id or sync_git_id in lg + or lg.endswith(sync_git_id) + or sync_git_id.endswith(lg)): + local_encoded = enc + break + except Exception: + pass + + # Fallback: try get_project_mapping() + if local_encoded == inbox_suffix: + local_encoded = mapping.get( + (inbox_member_tag, inbox_suffix), inbox_suffix + ) + + # Fallback: try sync_projects.encoded_name directly (stored at share time) + if local_encoded == inbox_suffix: + try: + enc_row = conn.execute( + "SELECT encoded_name FROM sync_projects " + "WHERE folder_suffix = ? LIMIT 1", + (inbox_suffix,), + ).fetchone() + if enc_row and enc_row[0]: + local_encoded = enc_row[0] + except Exception: + pass + + classification_overrides = _load_manifest_classifications(inbox_dir) + titles_map = _load_remote_titles(inbox_member_tag, local_encoded) + + force_reindex = False + metadata_files = [] + if classification_overrides: + mf = inbox_dir / "manifest.json" + if mf.exists(): + metadata_files.append(mf) + if titles_map: + tf = inbox_dir / "titles.json" + if tf.exists(): + metadata_files.append(tf) + if metadata_files: + oldest_indexed = conn.execute( + "SELECT MIN(indexed_at) FROM sessions WHERE remote_user_id = ? AND project_encoded_name = ? AND source = 'remote'", + (inbox_member_tag, local_encoded), + ).fetchone() + if oldest_indexed and oldest_indexed[0]: + from datetime import datetime as _dt2, timezone as _tz2 + try: + indexed_dt = _dt2.fromisoformat(oldest_indexed[0]) + for mf2 in metadata_files: + mtime2 = mf2.stat().st_mtime + mdt2 = _dt2.fromtimestamp(mtime2, tz=_tz2.utc).replace(tzinfo=None) + if mdt2 > indexed_dt: + force_reindex = True + break + except (ValueError, OSError): + pass + + manifest_skill_defs = _load_manifest_skill_definitions(inbox_dir) + if manifest_skill_defs: + _apply_manifest_skill_definitions( + conn, manifest_skill_defs, + source_user_id=inbox_member_tag, + source_machine_id=inbox_member_tag, + ) + + for jsonl_path in sessions_dir.glob("*.jsonl"): + if jsonl_path.name.startswith("agent-"): + continue + uuid = jsonl_path.stem + stats["total"] += 1 + try: + file_stat = jsonl_path.stat() + current_mtime = file_stat.st_mtime + + if not force_reindex and uuid in db_mtimes and abs(db_mtimes[uuid] - current_mtime) < 0.001: + stats["skipped"] += 1 + continue + + from services.file_validator import quarantine_file, validate_received_file + valid, reason = validate_received_file(jsonl_path) + if not valid: + quarantine_file(jsonl_path, reason, member_name=inbox_member_tag) + stats["errors"] += 1 + continue + + _index_session( + conn, + jsonl_path, + local_encoded, + current_mtime, + file_stat.st_size, + source="remote", + remote_user_id=inbox_member_tag, + remote_machine_id=inbox_member_tag, + claude_base_dir=inbox_dir, + classification_overrides=classification_overrides, + session_titles_override=[titles_map[uuid]] if uuid in titles_map else None, + ) + stats["indexed"] += 1 + + if uuid not in db_mtimes: + try: + from repositories.event_repo import EventRepository + from domain.events import SyncEvent, SyncEventType + already_logged = conn.execute( + "SELECT 1 FROM sync_events WHERE event_type = 'session_received' AND session_uuid = ? LIMIT 1", + (uuid,), + ).fetchone() + if not already_logged: + team_names = conn.execute( + "SELECT team_name FROM sync_projects WHERE folder_suffix = ?", + (inbox_suffix,), + ).fetchall() + event_repo = EventRepository() + for (tn,) in team_names: + event_repo.log(conn, SyncEvent( + event_type=SyncEventType.session_received, + team_name=tn, + member_tag=inbox_member_tag, + project_git_identity=local_encoded, + session_uuid=uuid, + )) + except Exception: + pass + except Exception as e: + logger.debug("Error indexing v4 inbox session %s: %s", uuid, e) + stats["errors"] += 1 + + conn.commit() + return stats + + +def trigger_remote_reindex() -> dict: + """Trigger an immediate remote session reindex. + + Called after sync actions (folder acceptance, device pairing) so that + newly arrived remote sessions appear in the dashboard without waiting + for the periodic 5-minute reindex cycle. + + Uses a separate lock to avoid blocking the full periodic indexer. + Skips silently if a reindex is already in progress. + + Returns: + Dict with sync statistics, or {"status": "skipped"} if already running. + """ + if not _reindex_lock.acquire(blocking=False): + return {"status": "skipped"} + try: + from .connection import create_writer_connection + + conn = create_writer_connection() + try: + stats = index_remote_sessions(conn) + logger.info("On-demand remote reindex complete: %s", stats) + return stats + finally: + conn.close() + except Exception as e: + logger.warning("On-demand remote reindex failed: %s", e) + return {"status": "error", "error": str(e)} + finally: + _reindex_lock.release() + + def _index_session( conn: sqlite3.Connection, jsonl_path: Path, @@ -280,6 +869,12 @@ def _index_session( project_path_override: Optional[str] = None, session_source: Optional[str] = None, source_encoded_name: Optional[str] = None, + source: Optional[str] = None, + remote_user_id: Optional[str] = None, + remote_machine_id: Optional[str] = None, + claude_base_dir: Optional[Path] = None, + classification_overrides: Optional[dict[str, str]] = None, + session_titles_override: Optional[list[str]] = None, ) -> None: """ Extract metadata from a session JSONL and upsert into SQLite. @@ -292,6 +887,14 @@ def _index_session( session_source: Tag session with this source (e.g., "desktop") source_encoded_name: The actual directory name where the JSONL lives (differs from encoded_name for remapped worktree sessions) + source: Session source type ("local" or "remote") + remote_user_id: User ID of remote machine (for remote sessions) + remote_machine_id: Machine ID of remote machine (for remote sessions) + classification_overrides: Manifest-provided name→category map for remote sessions. + When present, overrides local classify_invocation() results to fix + misclassification of remote skills/commands. + session_titles_override: Titles from external source (e.g., titles.json) to use + when the JSONL doesn't contain title data (remote sessions). """ from models import Session from utils import get_initial_prompt @@ -299,7 +902,7 @@ def _index_session( uuid = jsonl_path.stem # Parse session (triggers _load_metadata via property access) - session = Session.from_path(jsonl_path) + session = Session.from_path(jsonl_path, claude_base_dir=claude_base_dir) # Skip empty sessions if session.message_count == 0: @@ -319,10 +922,93 @@ def _index_session( skills_used = session.get_skills_used() skills_mentioned = session.get_skills_mentioned() commands_used = session.get_commands_used() + + # Build JSONL-extracted category map by scanning messages for + # "Base directory for this skill:" lines (secondary override source). + # Priority: manifest override > JSONL-path category > local classify_invocation() + jsonl_categories: dict[str, str] = {} + try: + from models.message import AssistantMessage as _AM, UserMessage as _UM + from models.content import ToolUseBlock as _TUB + + _msgs = list(session.iter_messages()) + for _i, _msg in enumerate(_msgs): + if not isinstance(_msg, _AM): + continue + for _blk in _msg.content_blocks: + if not (isinstance(_blk, _TUB) and _blk.name == "Skill" and _blk.input): + continue + _sn = _blk.input.get("skill") + if not _sn: + continue + for _j in range(_i + 1, min(_i + 8, len(_msgs))): + _nm = _msgs[_j] + if not isinstance(_nm, _UM): + continue + _nc = _nm.content or "" + if "Base directory for this skill:" not in _nc: + continue + try: + _marker = "Base directory for this skill:" + _idx = _nc.index(_marker) + _after = _nc[_idx + len(_marker):] + _lines = _after.strip().splitlines() + if _lines: + _bd = _lines[0].strip() + _cat = category_from_base_directory(_bd) + if _cat: + jsonl_categories[_sn] = _cat + except (ValueError, IndexError): + pass + break + except Exception as _e: + logger.debug("Error extracting JSONL categories for %s: %s", uuid, _e) + + # Reclassify skills/commands using manifest overrides (remote sessions only). + # The local classify_invocation() may get colon-format names wrong when the + # plugin isn't installed locally (defaults to "plugin_skill"). The manifest + # carries the correct classification from the exporting machine. + # Apply JSONL-extracted categories first (lower priority than manifest). + if jsonl_categories and not classification_overrides: + # No manifest — use JSONL-path categories alone + classification_overrides = jsonl_categories + elif jsonl_categories and classification_overrides: + # Merge: manifest takes precedence, JSONL fills gaps + merged = dict(jsonl_categories) + merged.update(classification_overrides) + classification_overrides = merged + + if classification_overrides: + from command_helpers import is_command_category, is_skill_category + + # Make mutable copies + skills_used = dict(skills_used) + skills_mentioned = dict(skills_mentioned) + commands_used = dict(commands_used) + + # Check skills that should be commands (both invoked and mentioned) + for skill_dict in (skills_used, skills_mentioned): + for key in list(skill_dict.keys()): + name, inv_source = key + override = classification_overrides.get(name) + if override and is_command_category(override): + # Move from skills → commands + count = skill_dict.pop(key) + commands_used[(name, inv_source)] = commands_used.get((name, inv_source), 0) + count + + # Check commands that should be skills + for key in list(commands_used.keys()): + name, inv_source = key + override = classification_overrides.get(name) + if override and is_skill_category(override): + # Move from commands → skills + count = commands_used.pop(key) + skills_used[(name, inv_source)] = skills_used.get((name, inv_source), 0) + count + models_used = list(session.get_models_used()) git_branches = list(session.get_git_branches()) - session_titles = session.session_titles or [] - initial_prompt = get_initial_prompt(session, max_length=500) + session_titles = session.session_titles or session_titles_override or [] + initial_prompt = get_initial_prompt(session) # Count subagents via filesystem (fast, no JSONL parse) subagent_count = 0 @@ -350,6 +1036,7 @@ def _index_session( session_titles, is_continuation_marker, was_compacted, compaction_count, file_snapshot_count, subagent_count, jsonl_mtime, jsonl_size, session_source, source_encoded_name, + source, remote_user_id, remote_machine_id, indexed_at ) VALUES ( ?, ?, ?, ?, @@ -359,6 +1046,7 @@ def _index_session( ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, + ?, ?, ?, datetime('now') ) """, @@ -389,6 +1077,9 @@ def _index_session( size, session_source, source_encoded_name, + source or "local", + remote_user_id, + remote_machine_id, ), ) @@ -467,29 +1158,26 @@ def _index_session( conn.execute("DELETE FROM subagent_invocations WHERE session_uuid = ?", (uuid,)) if subagent_count > 0: try: - from services.subagent_types import get_all_subagent_types + from services.subagent_types import get_all_subagent_metadata - subagent_types = get_all_subagent_types(jsonl_path, subagents_dir) + subagent_types, subagent_names = get_all_subagent_metadata(jsonl_path, subagents_dir) for subagent in session.list_subagents(): subagent_type = subagent_types.get(subagent.agent_id, "_unknown") - if subagent_type == "_unknown": - logger.debug( - "Skipping unclassified subagent %s in session %s", subagent.agent_id, uuid - ) - continue + display_name = subagent_names.get(subagent.agent_id) usage = subagent.get_usage_summary() duration = 0.0 if subagent.start_time and subagent.end_time: duration = (subagent.end_time - subagent.start_time).total_seconds() conn.execute( """INSERT INTO subagent_invocations - (session_uuid, agent_id, subagent_type, input_tokens, - output_tokens, cost_usd, duration_seconds, started_at) - VALUES (?, ?, ?, ?, ?, ?, ?, ?)""", + (session_uuid, agent_id, subagent_type, agent_display_name, + input_tokens, output_tokens, cost_usd, duration_seconds, started_at) + VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)""", ( uuid, subagent.agent_id, subagent_type, + display_name, usage.total_input, usage.output_tokens, usage.calculate_cost(), @@ -531,6 +1219,9 @@ def _index_session( # Normalize short-form plugin names skill_name = expand_plugin_short_name(skill_name) kind = classify_invocation(skill_name, source="skill_tool") + # Override with manifest classification for remote sessions + if classification_overrides and skill_name in classification_overrides: + kind = classification_overrides[skill_name] source = "skill_tool" if is_skill_category(kind): key = (skill_name, source) @@ -564,6 +1255,185 @@ def _index_session( logger.warning("Error indexing subagent invocations for %s: %s", uuid, e) + +def _parse_yaml_description(content: str) -> Optional[str]: + """Extract description field from YAML frontmatter (between --- markers).""" + try: + if not content.startswith("---"): + return None + end = content.index("---", 3) + frontmatter = content[3:end].strip() + for line in frontmatter.splitlines(): + if line.startswith("description:"): + return line[len("description:"):].strip().strip('"').strip("'") + except (ValueError, IndexError): + pass + return None + + +def _extract_skill_definitions_from_session( + conn: sqlite3.Connection, + jsonl_path: Path, + source_user_id: Optional[str], + source_machine_id: Optional[str], + session_uuid: str, + claude_base_dir: Optional[Path] = None, + classification_overrides: Optional[dict[str, str]] = None, +) -> None: + """Extract skill definitions (content + metadata) from a session's JSONL messages. + + Two-pass extraction: + Pass 1: Look for 'Base directory for this skill:' marker in the next + UserMessage (injected by Claude Code). Derives category from path. + Pass 2: If no category from marker, fall back to manifest classification_overrides. + Uses the raw UserMessage content as skill body when it looks like markdown. + + Persists custom_skill, user_command, and remote plugin_skill definitions. + Skips local plugin_skill and bundled categories. + Upserts new definitions into skill_definitions; skips if already present. + + Best-effort: all errors are logged as warnings, never raised. + """ + try: + from models import Session + from models.message import AssistantMessage, UserMessage + from models.content import ToolUseBlock + + session = Session.from_path(jsonl_path, claude_base_dir=claude_base_dir) + + # Collect messages into a list for adjacent-message lookahead + messages = list(session.iter_messages()) + + for i, msg in enumerate(messages): + if not isinstance(msg, AssistantMessage): + continue + + for block in msg.content_blocks: + if not (isinstance(block, ToolUseBlock) and block.name == "Skill" and block.input): + continue + + skill_name = block.input.get("skill") + if not skill_name: + continue + + # Skip if definition already exists WITH content + existing_content = conn.execute( + "SELECT content FROM skill_definitions WHERE skill_name = ? AND source_user_id = ?", + (skill_name, source_user_id or "__local__"), + ).fetchone() + if existing_content and existing_content[0]: + continue # Already have content, no need to re-extract + + # Pass 1: Look ahead for the "Base directory for this skill:" marker + base_dir: Optional[str] = None + content_text: Optional[str] = None + description: Optional[str] = None + category: Optional[str] = None + next_user_content: Optional[str] = None + + # Lookahead window: ProgressMessages can sit between + # the Skill tool_use and the injected UserMessage content, + # so scan up to 8 messages ahead. + for j in range(i + 1, min(i + 8, len(messages))): + next_msg = messages[j] + if not isinstance(next_msg, UserMessage): + continue + next_content = next_msg.content or "" + + if "Base directory for this skill:" in next_content: + try: + marker = "Base directory for this skill:" + idx = next_content.index(marker) + after = next_content[idx + len(marker):] + lines = after.strip().splitlines() + if lines: + base_dir = lines[0].strip() + if len(lines) > 1: + content_text = "\n".join(lines[1:]).strip() or None + except (ValueError, IndexError): + pass + + if base_dir: + category = category_from_base_directory(base_dir) + if content_text: + description = _parse_yaml_description(content_text) + break # Found the marker message + + # Save the latest non-marker UserMessage for pass 2 fallback + next_user_content = next_content + + # Pass 2: If no category from marker, try manifest classification_overrides + if category is None and classification_overrides and skill_name in classification_overrides: + category = classification_overrides[skill_name] + # Content is the full UserMessage text (Claude Code injects the raw + # SKILL.md contents when the "Base directory" marker is absent) + if next_user_content and next_user_content.strip(): + # Skip tool result wrapper text (e.g. "Launching skill: pdf") + raw = next_user_content.strip() + # Only use content if it looks like skill markdown (has heading or frontmatter) + if raw.startswith("---") or raw.startswith("#") or len(raw) > 200: + content_text = raw + description = _parse_yaml_description(content_text) + + # Pass 3: Fallback for unclassified plugin-style skills (name contains ":") + if category is None and ":" in skill_name: + category = "plugin_skill" + # Try to grab content from next UserMessage (skill body injected by Claude Code) + if not content_text and next_user_content and next_user_content.strip(): + raw = next_user_content.strip() + if raw.startswith("---") or raw.startswith("#") or len(raw) > 200: + content_text = raw + description = _parse_yaml_description(content_text) + + # Persist custom_skill, user_command, and remote plugin_skill definitions. + # Remote plugin skills need definitions for the "Inherit Skill" feature. + is_remote = source_user_id and source_user_id != "__local__" + if category not in ("custom_skill", "user_command"): + if not (category == "plugin_skill" and is_remote): + continue + + conn.execute( + """ + INSERT INTO skill_definitions + (skill_name, source_user_id, source_machine_id, category, + content, base_directory, description, extracted_from_session, + updated_at) + VALUES (?, COALESCE(?, '__local__'), ?, ?, ?, ?, ?, ?, datetime('now')) + ON CONFLICT(skill_name, source_user_id) DO UPDATE SET + content = COALESCE(NULLIF(excluded.content, ''), skill_definitions.content), + base_directory = COALESCE(excluded.base_directory, skill_definitions.base_directory), + description = COALESCE(excluded.description, skill_definitions.description), + extracted_from_session = CASE + WHEN excluded.content IS NOT NULL AND excluded.content != '' + AND (skill_definitions.content IS NULL OR skill_definitions.content = '') + THEN excluded.extracted_from_session + ELSE skill_definitions.extracted_from_session + END, + updated_at = CASE + WHEN excluded.content IS NOT NULL AND excluded.content != '' + AND (skill_definitions.content IS NULL OR skill_definitions.content = '') + THEN datetime('now') + ELSE skill_definitions.updated_at + END + """, + ( + skill_name, + source_user_id, + source_machine_id, + category, + content_text, + base_dir, + description, + session_uuid, + ), + ) + + except Exception as e: + logger.warning( + "Error extracting skill definitions from session %s: %s", session_uuid, e + ) + + def _detect_project_path(session, encoded_name: str) -> Optional[str]: """ Detect the real project path from session data or encoded name. @@ -599,11 +1469,12 @@ def _cleanup_stale_sessions(conn: sqlite3.Connection, projects_dir: Path) -> Non """ import os - # Get all sessions grouped by their actual source directory + # Get all non-remote sessions grouped by their actual source directory # source_encoded_name is set for worktree-remapped sessions; # for normal sessions it's NULL and we use project_encoded_name + # Remote sessions live outside projects_dir, so skip them here. session_rows = conn.execute( - "SELECT uuid, COALESCE(source_encoded_name, project_encoded_name) as source_dir FROM sessions" + "SELECT uuid, COALESCE(source_encoded_name, project_encoded_name) as source_dir FROM sessions WHERE COALESCE(source, 'local') != 'remote'" ).fetchall() # Group by source directory @@ -737,6 +1608,14 @@ def _update_project_summaries(conn: sqlite3.Connection) -> None: """ ).fetchall() + # Pre-fetch already-known git identities to avoid redundant subprocess calls + known_git_ids = { + r[0]: r[1] + for r in conn.execute( + "SELECT encoded_name, git_identity FROM projects WHERE git_identity IS NOT NULL" + ).fetchall() + } + for row in rows: encoded_name = row[0] session_count = row[1] @@ -750,15 +1629,32 @@ def _update_project_summaries(conn: sqlite3.Connection) -> None: project_path = _resolve_project_path(encoded_name, [r[0] for r in path_rows]) slug = compute_project_slug(encoded_name, project_path) - display_name = Path(project_path).name if project_path else encoded_name + display_name = Path(project_path).name if project_path else None + + # Detect git identity for cross-machine project matching (skip if already known) + git_identity = known_git_ids.get(encoded_name) + if git_identity is None and project_path: + try: + from utils.git import detect_git_identity + git_identity = detect_git_identity(project_path) + except Exception: + pass + + # For remote-only projects (no project_path), derive display_name + # from git_identity so it reads nicely (e.g. "claude-code-karma" + # instead of the raw encoded_name). + if display_name is None and git_identity: + display_name = git_identity.split("/")[-1] + if display_name is None: + display_name = encoded_name conn.execute( """ INSERT OR REPLACE INTO projects - (encoded_name, project_path, slug, display_name, session_count, last_activity) - VALUES (?, ?, ?, ?, ?, ?) + (encoded_name, project_path, slug, display_name, git_identity, session_count, last_activity) + VALUES (?, ?, ?, ?, ?, ?, ?) """, - (encoded_name, project_path, slug, display_name, session_count, last_activity), + (encoded_name, project_path, slug, display_name, git_identity, session_count, last_activity), ) conn.commit() @@ -857,11 +1753,14 @@ async def run_periodic_sync(interval_seconds: int = 300) -> None: while True: await asyncio.sleep(interval_seconds) try: - from .connection import get_writer_db + from .connection import create_writer_connection - conn = get_writer_db() - stats = await asyncio.to_thread(sync_all_projects, conn) - logger.info("Periodic reindex complete: %s", stats) + conn = create_writer_connection() + try: + stats = await asyncio.to_thread(sync_all_projects, conn) + logger.info("Periodic reindex complete: %s", stats) + finally: + conn.close() except Exception as e: logger.warning("Periodic reindex failed: %s", e) @@ -873,13 +1772,16 @@ def run_background_sync() -> None: Called during API startup to build/refresh the index without blocking request handling. """ - from .connection import get_writer_db + from .connection import create_writer_connection try: logger.info("Starting background index sync...") - conn = get_writer_db() - stats = sync_all_projects(conn) - logger.info("Background sync complete: %s", stats) + conn = create_writer_connection() + try: + stats = sync_all_projects(conn) + logger.info("Background sync complete: %s", stats) + finally: + conn.close() except Exception as e: logger.error("Background sync failed: %s", e) # Still mark as ready so the API falls back to old code path diff --git a/api/db/queries.py b/api/db/queries.py index 57125141..c07637f1 100644 --- a/api/db/queries.py +++ b/api/db/queries.py @@ -78,6 +78,45 @@ def _query_per_item_trend( return result +def _resolve_user_names(conn: sqlite3.Connection, user_ids: list[str]) -> dict[str, str]: + """Resolve user_ids to display names from sync_members table.""" + if not user_ids: + return {} + placeholders = ",".join("?" * len(user_ids)) + rows = conn.execute( + f"SELECT DISTINCT device_id, member_tag as name FROM sync_members WHERE device_id IN ({placeholders})", + user_ids, + ).fetchall() + return {row["device_id"]: row["name"] for row in rows} + + +def _query_per_user_trend( + conn: sqlite3.Connection, + from_clause: str, + where: str, + params: dict, + count_expr: str = "COUNT(*)", +) -> dict[str, list[dict]]: + """Per-user daily trend. Returns {user_id: [{date, count}, ...]}.""" + and_or_where = "AND" if where else "WHERE" + rows = conn.execute( + f"""SELECT COALESCE(s.remote_user_id, '_local') as user_id, + {_tz_date()} as date, {count_expr} as count + {from_clause} + {where} + {and_or_where} s.start_time IS NOT NULL + GROUP BY user_id, {_tz_date()} + ORDER BY user_id, date""", + params, + ).fetchall() + result: dict[str, list[dict]] = {} + for row in rows: + result.setdefault(row["user_id"], []).append( + {"date": row["date"], "count": row["count"]} + ) + return result + + def query_all_sessions( conn: sqlite3.Connection, search: Optional[str] = None, @@ -85,10 +124,12 @@ def query_all_sessions( branch: Optional[str] = None, scope: str = "both", status: str = "all", + source: str = "all", start_dt: Optional[datetime] = None, end_dt: Optional[datetime] = None, limit: int = 200, offset: int = 0, + user: Optional[str] = None, ) -> dict: """ Query sessions from SQLite with filtering, sorting, and pagination. @@ -119,6 +160,14 @@ def query_all_sessions( conditions.append("s.end_time <= :end_dt") params["end_dt"] = end_dt.isoformat() + if source and source != "all": + conditions.append("s.source = :source") + params["source"] = source + + if user: + conditions.append("s.remote_user_id = :user") + params["user"] = user + # Search via FTS5 fts_join = "" if search: @@ -209,7 +258,8 @@ def query_all_sessions( s.input_tokens, s.output_tokens, s.total_cost, s.initial_prompt, s.git_branch, s.models_used, s.session_titles, s.is_continuation_marker, s.was_compacted, - s.subagent_count, s.session_source + s.subagent_count, s.session_source, + s.source, s.remote_user_id, s.remote_machine_id FROM sessions s {fts_join} {where} @@ -479,11 +529,29 @@ def query_analytics( time_rows = conn.execute(f"SELECT start_time FROM sessions s {time_where}", params).fetchall() start_times = [row["start_time"] for row in time_rows] + # 4b. Start times with user_id for per-user breakdowns + time_user_rows = conn.execute( + f"""SELECT COALESCE(s.remote_user_id, '_local') as user_id, s.start_time + FROM sessions s + {time_where}""", + params, + ).fetchall() + start_times_with_user = [ + {"user_id": row["user_id"], "start_time": row["start_time"]} + for row in time_user_rows + ] + + # 5. Resolve user display names from sync_members + user_ids = list({e["user_id"] for e in start_times_with_user if e["user_id"] != "_local"}) + user_names = _resolve_user_names(conn, user_ids) if user_ids else {} + return { "totals": totals, "tools": tools, "models_used_list": models_used_list, "start_times": start_times, + "start_times_with_user": start_times_with_user, + "user_names": user_names, } @@ -531,7 +599,10 @@ def _query_item_usage( {count_expr} COUNT(DISTINCT {alias}.session_uuid) as session_count, MAX(s.end_time) as last_used, - GROUP_CONCAT(DISTINCT {alias}.invocation_source) as invocation_sources + GROUP_CONCAT(DISTINCT {alias}.invocation_source) as invocation_sources, + SUM(CASE WHEN s.source = 'remote' THEN {alias}.count ELSE 0 END) as remote_count, + SUM(CASE WHEN s.source != 'remote' THEN {alias}.count ELSE 0 END) as local_count, + GROUP_CONCAT(DISTINCT CASE WHEN s.source = 'remote' THEN s.remote_user_id END) as remote_user_ids FROM {table} {alias} JOIN sessions s ON {alias}.session_uuid = s.uuid {_where} @@ -587,7 +658,8 @@ def query_sessions_by_skill( s.uuid, s.slug, s.project_encoded_name, s.project_path, s.message_count, s.start_time, s.end_time, s.duration_seconds, s.models_used, s.subagent_count, s.initial_prompt, - s.git_branch, s.session_titles + s.git_branch, s.session_titles, + s.session_source, s.source, s.remote_user_id, s.remote_machine_id FROM sessions s JOIN session_skills sk ON s.uuid = sk.session_uuid WHERE sk.skill_name = :skill AND sk.invocation_source != 'text_detection' @@ -639,7 +711,9 @@ def _query_item_detail( param_name = "item" item_param = {param_name: item_value} - mention_exclusion = f"AND {alias}.invocation_source != 'text_detection'" if track_mentions else "" + mention_exclusion = ( + f"AND {alias}.invocation_source != 'text_detection'" if track_mentions else "" + ) # Main session stats main_row = conn.execute( @@ -695,7 +769,12 @@ def _query_item_detail( item_param, ).fetchone()[0] - if main_calls == 0 and sub_calls == 0 and mentioned_calls == 0 and command_triggered_calls == 0: + if ( + main_calls == 0 + and sub_calls == 0 + and mentioned_calls == 0 + and command_triggered_calls == 0 + ): return None else: if main_calls == 0 and sub_calls == 0: @@ -764,6 +843,7 @@ def _query_item_detail( s.message_count, s.start_time, s.end_time, s.duration_seconds, s.models_used, s.subagent_count, s.initial_prompt, s.git_branch, s.session_titles, + s.session_source, s.source, s.remote_user_id, s.remote_machine_id, agg.has_main, agg.has_sub, agg.agent_ids, ss.invocation_sources FROM sessions s @@ -1037,11 +1117,25 @@ def _query_item_usage_trend( first_used = time_row["first_used"] if time_row else None last_used = time_row["last_used"] if time_row else None + # Per-user trend + trend_by_user = _query_per_user_trend( + conn, + from_clause=from_clause, + where=where_items, + params=params, + count_expr=f"SUM({table}.count)", + ) + # Resolve user names + trend_user_ids = [uid for uid in trend_by_user if uid != "_local"] + user_names = _resolve_user_names(conn, trend_user_ids) if trend_user_ids else {} + return { "total": total, "by_item": by_item, "trend": trend, "trend_by_item": trend_by_item, + "trend_by_user": trend_by_user, + "user_names": user_names, "first_used": first_used, "last_used": last_used, } @@ -1126,7 +1220,8 @@ def query_project_sessions( s.initial_prompt, s.git_branch, s.session_titles, s.is_continuation_marker, s.was_compacted, s.input_tokens, s.output_tokens, s.total_cost, s.compaction_count, - s.session_source + s.session_source, + s.source, s.remote_user_id, s.remote_machine_id FROM sessions s {fts_join} WHERE {where} @@ -1366,7 +1461,7 @@ def query_continuation_session( def query_session_by_message_uuid(conn: sqlite3.Connection, message_uuid: str) -> dict | None: """Look up a session by a message UUID it contains.""" row = conn.execute( - """SELECT mu.session_uuid, s.slug, s.project_encoded_name + """SELECT mu.session_uuid, s.slug, s.project_encoded_name, s.source_encoded_name FROM message_uuids mu JOIN sessions s ON mu.session_uuid = s.uuid WHERE mu.message_uuid = :msg_uuid""", @@ -1820,6 +1915,15 @@ def query_agent_usage_trend( count_expr="COUNT(*)", ) + trend_by_user = _query_per_user_trend( + conn, + from_clause="FROM subagent_invocations si JOIN sessions s ON si.session_uuid = s.uuid", + where=where, + params=params, + count_expr="COUNT(*)", + ) + user_names = _resolve_user_names(conn, [u for u in trend_by_user if u != "_local"]) + # First/last used time_row = conn.execute( f"""SELECT MIN(s.start_time) as first_used, MAX(s.start_time) as last_used @@ -1837,6 +1941,8 @@ def query_agent_usage_trend( "by_item": by_item, "trend": trend, "trend_by_item": trend_by_item, + "trend_by_user": trend_by_user, + "user_names": user_names, "first_used": first_used, "last_used": last_used, } @@ -2021,7 +2127,8 @@ def query_agent_history( si.duration_seconds, si.input_tokens, si.output_tokens, - si.cost_usd + si.cost_usd, + si.agent_display_name FROM subagent_invocations si JOIN sessions s ON si.session_uuid = s.uuid WHERE si.subagent_type = :type @@ -2055,7 +2162,8 @@ def query_sessions_by_agent( s.uuid, s.slug, s.project_encoded_name, s.project_path, s.message_count, s.start_time, s.end_time, s.duration_seconds, s.models_used, s.subagent_count, s.initial_prompt, - s.git_branch, s.session_titles + s.git_branch, s.session_titles, + s.session_source, s.source, s.remote_user_id, s.remote_machine_id FROM sessions s JOIN (SELECT DISTINCT session_uuid FROM subagent_invocations WHERE subagent_type = :type) si ON s.uuid = si.session_uuid @@ -2830,6 +2938,7 @@ def query_sessions_by_mcp_server( s.message_count, s.start_time, s.end_time, s.duration_seconds, s.models_used, s.subagent_count, s.initial_prompt, s.git_branch, s.session_titles, + s.session_source, s.source, s.remote_user_id, s.remote_machine_id, agg.has_main, agg.has_sub, agg.agent_ids FROM sessions s JOIN aggregated_sessions agg ON s.uuid = agg.session_uuid @@ -2964,6 +3073,15 @@ def query_mcp_tool_usage_trend( count_expr="SUM(st.count)", ) + trend_by_user = _query_per_user_trend( + conn, + from_clause="FROM session_tools st JOIN sessions s ON st.session_uuid = s.uuid", + where=where, + params=params, + count_expr="SUM(st.count)", + ) + user_names = _resolve_user_names(conn, [u for u in trend_by_user if u != "_local"]) + # First/last used time_row = conn.execute( f"""SELECT MIN(s.start_time) as first_used, MAX(s.start_time) as last_used @@ -2981,6 +3099,8 @@ def query_mcp_tool_usage_trend( "by_item": by_item, "trend": trend, "trend_by_item": trend_by_item, + "trend_by_user": trend_by_user, + "user_names": user_names, "first_used": first_used, "last_used": last_used, } @@ -3079,6 +3199,15 @@ def query_builtin_tool_usage_trend( count_expr="SUM(st.count)", ) + trend_by_user = _query_per_user_trend( + conn, + from_clause="FROM session_tools st JOIN sessions s ON st.session_uuid = s.uuid", + where=where, + params=params, + count_expr="SUM(st.count)", + ) + user_names = _resolve_user_names(conn, [u for u in trend_by_user if u != "_local"]) + # First/last used time_row = conn.execute( f"""SELECT MIN(s.start_time) as first_used, MAX(s.start_time) as last_used @@ -3093,6 +3222,8 @@ def query_builtin_tool_usage_trend( "by_item": by_item, "trend": trend, "trend_by_item": trend_by_item, + "trend_by_user": trend_by_user, + "user_names": user_names, "first_used": time_row["first_used"] if time_row else None, "last_used": time_row["last_used"] if time_row else None, } @@ -3315,6 +3446,7 @@ def query_sessions_by_mcp_tool( s.message_count, s.start_time, s.end_time, s.duration_seconds, s.models_used, s.subagent_count, s.initial_prompt, s.git_branch, s.session_titles, + s.session_source, s.source, s.remote_user_id, s.remote_machine_id, agg.has_main, agg.has_sub, agg.agent_ids FROM sessions s JOIN aggregated_sessions agg ON s.uuid = agg.session_uuid @@ -3793,6 +3925,7 @@ def query_sessions_by_builtin_server( s.message_count, s.start_time, s.end_time, s.duration_seconds, s.models_used, s.subagent_count, s.initial_prompt, s.git_branch, s.session_titles, + s.session_source, s.source, s.remote_user_id, s.remote_machine_id, agg.has_main, agg.has_sub, agg.agent_ids FROM sessions s JOIN aggregated_sessions agg ON s.uuid = agg.session_uuid @@ -3868,6 +4001,7 @@ def query_sessions_by_builtin_tool( s.message_count, s.start_time, s.end_time, s.duration_seconds, s.models_used, s.subagent_count, s.initial_prompt, s.git_branch, s.session_titles, + s.session_source, s.source, s.remote_user_id, s.remote_machine_id, agg.has_main, agg.has_sub, agg.agent_ids FROM sessions s JOIN aggregated_sessions agg ON s.uuid = agg.session_uuid @@ -3954,3 +4088,359 @@ def query_subagent_command_usage( params, ).fetchall() return [dict(row) for row in rows] + + +# --------------------------------------------------------------------------- +# Parse-once: Session detail & tool breakdown queries +# --------------------------------------------------------------------------- + + +def query_session_detail(conn: sqlite3.Connection, uuid: str) -> dict | None: + """ + Fetch all SessionDetail fields available in the DB for a single session. + + Returns a dict ready to be mapped to the SessionDetail schema, or None + if the session is not in the DB. + """ + # 1. Core session row + row = conn.execute( + """SELECT uuid, slug, project_encoded_name, project_path, + message_count, start_time, end_time, duration_seconds, + input_tokens, output_tokens, cache_creation_tokens, cache_read_tokens, + total_cost, initial_prompt, git_branch, models_used, + session_titles, is_continuation_marker, was_compacted, + compaction_count, file_snapshot_count, subagent_count, + session_source, source, remote_user_id, remote_machine_id, + jsonl_mtime + FROM sessions WHERE uuid = ?""", + (uuid,), + ).fetchone() + if not row: + return None + + session = dict(row) + + # Parse JSON columns + session["models_used"] = _parse_json_list(session.get("models_used")) + session["session_titles"] = _parse_json_list(session.get("session_titles")) + + # Compute derived fields + input_tokens = session.get("input_tokens") or 0 + cache_read = session.get("cache_read_tokens") or 0 + denom = input_tokens + cache_read + session["cache_hit_rate"] = cache_read / denom if denom > 0 else 0.0 + + git_branch = session.get("git_branch") + session["git_branches"] = [git_branch] if git_branch else [] + + project_path = session.get("project_path") or "" + session["working_directories"] = [project_path] if project_path else [] + session["project_display_name"] = Path(project_path).name if project_path else None + + # 2. Tool counts + tool_rows = conn.execute( + "SELECT tool_name, count FROM session_tools WHERE session_uuid = ?", + (uuid,), + ).fetchall() + session["tools_used"] = {r["tool_name"]: r["count"] for r in tool_rows} + + # 3. Skill usage (with invocation_source) + skill_rows = conn.execute( + "SELECT skill_name, invocation_source, count FROM session_skills WHERE session_uuid = ?", + (uuid,), + ).fetchall() + session["skills_used_raw"] = [ + (r["skill_name"], r["invocation_source"], r["count"]) for r in skill_rows + ] + + # 4. Command usage (with invocation_source) + cmd_rows = conn.execute( + "SELECT command_name, invocation_source, count FROM session_commands WHERE session_uuid = ?", + (uuid,), + ).fetchall() + session["commands_used_raw"] = [ + (r["command_name"], r["invocation_source"], r["count"]) for r in cmd_rows + ] + + # 5. Leaf UUIDs (for project_context_leaf_uuids display) + leaf_rows = conn.execute( + "SELECT leaf_uuid FROM session_leaf_refs WHERE session_uuid = ?", + (uuid,), + ).fetchall() + session["project_context_leaf_uuids"] = [r["leaf_uuid"] for r in leaf_rows] + + # 6. Chain detection + session["has_chain"] = query_session_has_chain(conn, uuid) + + return session + + +def query_session_tool_breakdown( + conn: sqlite3.Connection, uuid: str +) -> tuple[dict[str, int] | None, dict[str, int]]: + """ + Fetch session + subagent tool counts from DB. + + Returns (session_tool_counts, subagent_tool_counts). + Returns (None, {}) if session not found. + """ + # Session tools + session_rows = conn.execute( + "SELECT tool_name, count FROM session_tools WHERE session_uuid = ?", + (uuid,), + ).fetchall() + session_counts = {r["tool_name"]: r["count"] for r in session_rows} + + # Subagent tools (aggregated across all invocations) + subagent_rows = conn.execute( + """SELECT sat.tool_name, SUM(sat.count) as count + FROM subagent_tools sat + JOIN subagent_invocations si ON sat.invocation_id = si.id + WHERE si.session_uuid = ? + GROUP BY sat.tool_name""", + (uuid,), + ).fetchall() + subagent_counts = {r["tool_name"]: r["count"] for r in subagent_rows} + + # Only check existence when both are empty (distinguish "no tools" from "no session") + if not session_counts and not subagent_counts: + exists = conn.execute( + "SELECT 1 FROM sessions WHERE uuid = ?", (uuid,) + ).fetchone() + if not exists: + return None, {} + + return session_counts, subagent_counts + + +# --------------------------------------------------------------------------- +# Sync member query helpers +# --------------------------------------------------------------------------- + + +def _batched_in_query( + conn: sqlite3.Connection, + sql_template: str, + items: list, + extra_params: list | None = None, + batch_size: int = 500, +) -> list: + """Execute query with IN clause in batches to avoid SQLITE_MAX_VARIABLE_NUMBER. + + ``sql_template`` must contain a ``{placeholders}`` token that will be + replaced with the comma-separated ``?`` markers for each batch. + ``extra_params``, if given, are prepended to each batch's parameter list. + """ + if not items: + return [] + results: list = [] + prefix = extra_params or [] + for i in range(0, len(items), batch_size): + batch = items[i : i + batch_size] + placeholders = ",".join("?" * len(batch)) + sql = sql_template.format(placeholders=placeholders) + results.extend(conn.execute(sql, prefix + batch).fetchall()) + return results + + +def query_member_session_count( + conn: sqlite3.Connection, encoded_name: str +) -> int: + """Count sessions for a given project encoded_name.""" + row = conn.execute( + "SELECT COUNT(*) FROM sessions WHERE project_encoded_name = ?", + (encoded_name,), + ).fetchone() + return row[0] if row else 0 + + +def query_member_local_session_count( + conn: sqlite3.Connection, encoded_name: str +) -> int: + """Count local (non-remote) sessions for a given project encoded_name.""" + row = conn.execute( + "SELECT COUNT(*) FROM sessions WHERE project_encoded_name = ? " + "AND (source IS NULL OR source != 'remote')", + (encoded_name,), + ).fetchone() + return row[0] if row else 0 + + +def query_member_sent_count( + conn: sqlite3.Connection, member_tag: str +) -> int: + """Count 'session_packaged' sync events for a member.""" + row = conn.execute( + "SELECT COUNT(*) FROM sync_events " + "WHERE event_type = 'session_packaged' AND member_tag = ?", + (member_tag,), + ).fetchone() + return row[0] if row else 0 + + +def query_member_received_count( + conn: sqlite3.Connection, member_tag: str +) -> int: + """Count 'session_received' sync events for a member.""" + row = conn.execute( + "SELECT COUNT(*) FROM sync_events " + "WHERE event_type = 'session_received' AND member_tag = ?", + (member_tag,), + ).fetchone() + return row[0] if row else 0 + + +def query_member_remote_sessions_count( + conn: sqlite3.Connection, member_tag: str, project_encoded_names: list[str] +) -> int: + """Count remote sessions attributed to a member across projects. + + Uses batched IN clause to handle large project lists safely. + """ + if not project_encoded_names: + return 0 + rows = _batched_in_query( + conn, + "SELECT COUNT(*) FROM sessions WHERE source = 'remote' " + "AND remote_user_id = ? AND project_encoded_name IN ({placeholders})", + list(project_encoded_names), + extra_params=[member_tag], + ) + return rows[0][0] if rows else 0 + + +def query_member_total_sessions( + conn: sqlite3.Connection, project_encoded_names: list[str] +) -> int: + """Count total sessions across a set of projects. + + Uses batched IN clause to handle large project lists safely. + """ + if not project_encoded_names: + return 0 + rows = _batched_in_query( + conn, + "SELECT COUNT(*) FROM sessions WHERE project_encoded_name IN ({placeholders})", + list(project_encoded_names), + ) + # Sum across batches (each batch returns its own COUNT) + return sum(r[0] for r in rows) if rows else 0 + + +def query_member_subscription_count( + conn: sqlite3.Connection, member_tag: str +) -> int: + """Count distinct project subscriptions for a member.""" + row = conn.execute( + "SELECT COUNT(DISTINCT project_git_identity) FROM sync_subscriptions " + "WHERE member_tag = ?", + (member_tag,), + ).fetchone() + return row[0] if row else 0 + + +def query_member_last_active( + conn: sqlite3.Connection, member_tag: str +) -> str | None: + """Get the most recent sync event timestamp for a member.""" + row = conn.execute( + "SELECT MAX(created_at) FROM sync_events WHERE member_tag = ?", + (member_tag,), + ).fetchone() + return row[0] if row and row[0] else None + + +def query_member_daily_sync_stats( + conn: sqlite3.Connection, member_tag: str +) -> list: + """Get daily sent/received event counts for a member. + + Returns rows of (date_str, event_type, count). + """ + return conn.execute( + "SELECT date(created_at) as d, event_type, COUNT(*) " + "FROM sync_events " + "WHERE member_tag = ? AND event_type IN ('session_packaged', 'session_received') " + "GROUP BY d, event_type ORDER BY d", + (member_tag,), + ).fetchall() + + +def query_last_packaged_timestamp(conn: sqlite3.Connection) -> str | None: + """Get the most recent 'session_packaged' event timestamp (global).""" + row = conn.execute( + "SELECT MAX(created_at) FROM sync_events WHERE event_type = 'session_packaged'" + ).fetchone() + return row[0] if row and row[0] else None + + +def _normalize_git_identity(raw: str) -> str: + """Normalize a git identity for comparison: strip .git suffix, lowercase.""" + norm = (raw or "").rstrip("/").lower() + if norm.endswith(".git"): + norm = norm[:-4] + return norm + + +def resolve_encoded_name(conn: sqlite3.Connection, git_identity: str) -> str | None: + """Resolve a git_identity to a local encoded_name. + + Single source of truth for mapping machine-independent git_identity + (e.g. ``owner/repo``) to machine-specific encoded_name + (e.g. ``-Users-me-Documents-repo``). + + Strategy: + 1. Check the ``projects`` table (indexed projects with git_identity). + 2. Fallback: check the ``sessions`` table using exact suffix match + on the repo name portion, picking the shortest candidate to avoid + matching subdirectories or worktrees. + + Returns None if no match is found. + """ + norm = _normalize_git_identity(git_identity) + if not norm: + return None + + # Strategy 1: Match against the projects table (fastest, most reliable) + rows = conn.execute( + "SELECT encoded_name, git_identity FROM projects " + "WHERE git_identity IS NOT NULL" + ).fetchall() + for enc, local_git in rows: + lg = _normalize_git_identity(local_git) + if lg and (lg in norm or norm in lg or lg.endswith(norm) or norm.endswith(lg)): + return enc + + # Strategy 2: Fallback to sessions table with exact suffix match. + # Extract repo name from git_identity (e.g. "owner/repo" → "repo") + # and match against project_encoded_name endings. + repo_name = norm.split("/")[-1] + suffix = f"-{repo_name}" + session_rows = conn.execute( + "SELECT DISTINCT project_encoded_name FROM sessions " + "WHERE project_encoded_name LIKE ?", + (f"%{suffix}",), + ).fetchall() + candidates = [r[0] for r in session_rows if r[0] and r[0].endswith(suffix)] + if candidates: + return min(candidates, key=len) + + return None + + +def query_resolve_project( + conn: sqlite3.Connection, git_identity: str +) -> tuple[str | None, str | None]: + """Resolve a sync project's git_identity to (encoded_name, display_name). + + Uses ``resolve_encoded_name`` for the encoded_name lookup, then fetches + display_name from the projects table if found. + """ + enc = resolve_encoded_name(conn, git_identity) + if enc is None: + return None, None + row = conn.execute( + "SELECT display_name FROM projects WHERE encoded_name = ?", (enc,) + ).fetchone() + display = row[0] if row else None + return enc, display diff --git a/api/db/schema.py b/api/db/schema.py index 59c7f0a8..6ec9b93b 100644 --- a/api/db/schema.py +++ b/api/db/schema.py @@ -10,7 +10,7 @@ logger = logging.getLogger(__name__) -SCHEMA_VERSION = 10 +SCHEMA_VERSION = 22 SCHEMA_SQL = """ -- Schema versioning @@ -47,9 +47,14 @@ jsonl_size INTEGER DEFAULT 0, session_source TEXT, source_encoded_name TEXT, + source TEXT DEFAULT 'local', + remote_user_id TEXT, + remote_machine_id TEXT, indexed_at TEXT DEFAULT (datetime('now')) ); +CREATE INDEX IF NOT EXISTS idx_sessions_source ON sessions(source); + CREATE INDEX IF NOT EXISTS idx_sessions_project ON sessions(project_encoded_name); CREATE INDEX IF NOT EXISTS idx_sessions_start ON sessions(start_time DESC); CREATE INDEX IF NOT EXISTS idx_sessions_slug ON sessions(slug); @@ -134,6 +139,7 @@ session_uuid TEXT NOT NULL, agent_id TEXT NOT NULL, subagent_type TEXT, + agent_display_name TEXT, input_tokens INTEGER DEFAULT 0, output_tokens INTEGER DEFAULT 0, cost_usd REAL DEFAULT 0, @@ -208,12 +214,108 @@ project_path TEXT, slug TEXT, display_name TEXT, + git_identity TEXT, session_count INTEGER DEFAULT 0, last_activity TEXT, updated_at TEXT DEFAULT (datetime('now')) ); CREATE UNIQUE INDEX IF NOT EXISTS idx_projects_slug ON projects(slug); + +-- Sync v4 tables (added in schema v19) +CREATE TABLE IF NOT EXISTS sync_teams ( + name TEXT PRIMARY KEY, + leader_device_id TEXT NOT NULL, + leader_member_tag TEXT NOT NULL, + team_id TEXT NOT NULL DEFAULT '', + status TEXT NOT NULL DEFAULT 'active' + CHECK(status IN ('active', 'dissolved')), + created_at TEXT NOT NULL DEFAULT (datetime('now')) +); + +CREATE TABLE IF NOT EXISTS sync_members ( + team_name TEXT NOT NULL REFERENCES sync_teams(name) ON DELETE CASCADE, + member_tag TEXT NOT NULL, + device_id TEXT NOT NULL, + user_id TEXT NOT NULL, + machine_tag TEXT NOT NULL, + status TEXT NOT NULL DEFAULT 'added' + CHECK(status IN ('added', 'active', 'removed')), + added_at TEXT NOT NULL DEFAULT (datetime('now')), + updated_at TEXT NOT NULL DEFAULT (datetime('now')), + PRIMARY KEY (team_name, member_tag) +); + +CREATE TABLE IF NOT EXISTS sync_projects ( + team_name TEXT NOT NULL REFERENCES sync_teams(name) ON DELETE CASCADE, + git_identity TEXT NOT NULL, + encoded_name TEXT, + folder_suffix TEXT NOT NULL, + status TEXT NOT NULL DEFAULT 'shared' + CHECK(status IN ('shared', 'removed')), + shared_at TEXT NOT NULL DEFAULT (datetime('now')), + PRIMARY KEY (team_name, git_identity) +); + +CREATE TABLE IF NOT EXISTS sync_subscriptions ( + member_tag TEXT NOT NULL, + team_name TEXT NOT NULL, + project_git_identity TEXT NOT NULL, + status TEXT NOT NULL DEFAULT 'offered' + CHECK(status IN ('offered', 'accepted', 'paused', 'declined')), + direction TEXT NOT NULL DEFAULT 'both' + CHECK(direction IN ('receive', 'send', 'both')), + updated_at TEXT NOT NULL DEFAULT (datetime('now')), + PRIMARY KEY (member_tag, team_name, project_git_identity), + FOREIGN KEY (team_name, member_tag) + REFERENCES sync_members(team_name, member_tag) ON DELETE CASCADE, + FOREIGN KEY (team_name, project_git_identity) + REFERENCES sync_projects(team_name, git_identity) ON DELETE CASCADE +); + +CREATE TABLE IF NOT EXISTS sync_events ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + event_type TEXT NOT NULL, + team_name TEXT, + member_tag TEXT, + project_git_identity TEXT, + session_uuid TEXT, + detail TEXT, + created_at TEXT NOT NULL DEFAULT (datetime('now')) +); + +CREATE TABLE IF NOT EXISTS sync_removed_members ( + team_name TEXT NOT NULL REFERENCES sync_teams(name) ON DELETE CASCADE, + device_id TEXT NOT NULL, + member_tag TEXT, + removed_at TEXT NOT NULL DEFAULT (datetime('now')), + PRIMARY KEY (team_name, device_id) +); + +CREATE INDEX IF NOT EXISTS idx_members_device ON sync_members(device_id); +CREATE INDEX IF NOT EXISTS idx_members_status ON sync_members(team_name, status); +CREATE INDEX IF NOT EXISTS idx_projects_suffix ON sync_projects(folder_suffix); +CREATE INDEX IF NOT EXISTS idx_projects_git ON sync_projects(git_identity); +CREATE INDEX IF NOT EXISTS idx_subs_member ON sync_subscriptions(member_tag); +CREATE INDEX IF NOT EXISTS idx_subs_status ON sync_subscriptions(status); +CREATE INDEX IF NOT EXISTS idx_subs_project ON sync_subscriptions(project_git_identity); +CREATE INDEX IF NOT EXISTS idx_events_type ON sync_events(event_type); +CREATE INDEX IF NOT EXISTS idx_events_team ON sync_events(team_name); +CREATE INDEX IF NOT EXISTS idx_events_time ON sync_events(created_at); + +-- Skill definitions (custom skills, user commands, remote plugin skills) +CREATE TABLE IF NOT EXISTS skill_definitions ( + skill_name TEXT NOT NULL, + source_user_id TEXT NOT NULL DEFAULT '__local__', + source_machine_id TEXT, + category TEXT, + content TEXT, + base_directory TEXT, + description TEXT, + extracted_from_session TEXT, + updated_at TEXT, + PRIMARY KEY (skill_name, source_user_id) +); """ @@ -426,6 +528,166 @@ def ensure_schema(conn: sqlite3.Connection) -> None: # Nudge mtime to force re-index of all sessions conn.execute("UPDATE sessions SET jsonl_mtime = jsonl_mtime - 1") + # v11-v18: no-op placeholders (schema evolution before sync v4) + + if current_version < 19: + logger.info( + "Migrating → v19: sync v4 — drop all old sync tables, recreate with clean-slate schema" + ) + # Drop all sync tables — both v3 names and v4 names (order matters for FKs) + conn.execute("DROP TABLE IF EXISTS sync_subscriptions") + conn.execute("DROP TABLE IF EXISTS sync_rejected_folders") + conn.execute("DROP TABLE IF EXISTS sync_settings") + conn.execute("DROP TABLE IF EXISTS sync_removed_members") + conn.execute("DROP TABLE IF EXISTS sync_events") + conn.execute("DROP TABLE IF EXISTS sync_team_projects") + conn.execute("DROP TABLE IF EXISTS sync_projects") + conn.execute("DROP TABLE IF EXISTS sync_members") + conn.execute("DROP TABLE IF EXISTS sync_teams") + + # Recreate with v4 schema + conn.execute(""" + CREATE TABLE sync_teams ( + name TEXT PRIMARY KEY, + leader_device_id TEXT NOT NULL, + leader_member_tag TEXT NOT NULL, + team_id TEXT NOT NULL DEFAULT '', + status TEXT NOT NULL DEFAULT 'active' + CHECK(status IN ('active', 'dissolved')), + created_at TEXT NOT NULL DEFAULT (datetime('now')) + ) + """) + conn.execute(""" + CREATE TABLE sync_members ( + team_name TEXT NOT NULL REFERENCES sync_teams(name) ON DELETE CASCADE, + member_tag TEXT NOT NULL, + device_id TEXT NOT NULL, + user_id TEXT NOT NULL, + machine_tag TEXT NOT NULL, + status TEXT NOT NULL DEFAULT 'added' + CHECK(status IN ('added', 'active', 'removed')), + added_at TEXT NOT NULL DEFAULT (datetime('now')), + updated_at TEXT NOT NULL DEFAULT (datetime('now')), + PRIMARY KEY (team_name, member_tag) + ) + """) + conn.execute(""" + CREATE TABLE sync_projects ( + team_name TEXT NOT NULL REFERENCES sync_teams(name) ON DELETE CASCADE, + git_identity TEXT NOT NULL, + encoded_name TEXT, + folder_suffix TEXT NOT NULL, + status TEXT NOT NULL DEFAULT 'shared' + CHECK(status IN ('shared', 'removed')), + shared_at TEXT NOT NULL DEFAULT (datetime('now')), + PRIMARY KEY (team_name, git_identity) + ) + """) + conn.execute(""" + CREATE TABLE sync_subscriptions ( + member_tag TEXT NOT NULL, + team_name TEXT NOT NULL, + project_git_identity TEXT NOT NULL, + status TEXT NOT NULL DEFAULT 'offered' + CHECK(status IN ('offered', 'accepted', 'paused', 'declined')), + direction TEXT NOT NULL DEFAULT 'both' + CHECK(direction IN ('receive', 'send', 'both')), + updated_at TEXT NOT NULL DEFAULT (datetime('now')), + PRIMARY KEY (member_tag, team_name, project_git_identity), + FOREIGN KEY (team_name, member_tag) + REFERENCES sync_members(team_name, member_tag) ON DELETE CASCADE, + FOREIGN KEY (team_name, project_git_identity) + REFERENCES sync_projects(team_name, git_identity) ON DELETE CASCADE + ) + """) + conn.execute(""" + CREATE TABLE sync_events ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + event_type TEXT NOT NULL, + team_name TEXT, + member_tag TEXT, + project_git_identity TEXT, + session_uuid TEXT, + detail TEXT, + created_at TEXT NOT NULL DEFAULT (datetime('now')) + ) + """) + conn.execute(""" + CREATE TABLE sync_removed_members ( + team_name TEXT NOT NULL REFERENCES sync_teams(name) ON DELETE CASCADE, + device_id TEXT NOT NULL, + member_tag TEXT, + removed_at TEXT NOT NULL DEFAULT (datetime('now')), + PRIMARY KEY (team_name, device_id) + ) + """) + # Indexes + conn.execute("CREATE INDEX idx_members_device ON sync_members(device_id)") + conn.execute("CREATE INDEX idx_members_status ON sync_members(team_name, status)") + conn.execute("CREATE INDEX idx_projects_suffix ON sync_projects(folder_suffix)") + conn.execute("CREATE INDEX idx_projects_git ON sync_projects(git_identity)") + conn.execute("CREATE INDEX idx_subs_member ON sync_subscriptions(member_tag)") + conn.execute("CREATE INDEX idx_subs_status ON sync_subscriptions(status)") + conn.execute("CREATE INDEX idx_subs_project ON sync_subscriptions(project_git_identity)") + conn.execute("CREATE INDEX idx_events_type ON sync_events(event_type)") + conn.execute("CREATE INDEX idx_events_team ON sync_events(team_name)") + conn.execute("CREATE INDEX idx_events_time ON sync_events(created_at)") + + if current_version < 20: + logger.info( + "Migrating → v20: normalize remote_user_id from bare user_id to member_tag" + ) + conn.execute(""" + UPDATE sessions SET remote_user_id = ( + SELECT m.member_tag FROM sync_members m + WHERE m.user_id = sessions.remote_user_id + LIMIT 1 + ) WHERE source = 'remote' + AND remote_user_id IS NOT NULL + AND remote_user_id NOT LIKE '%.%' + AND EXISTS ( + SELECT 1 FROM sync_members m + WHERE m.user_id = sessions.remote_user_id + ) + """) + + if current_version < 21: + logger.info( + "Migrating → v21: adding skill_definitions table and projects.git_identity column" + ) + conn.executescript(""" + CREATE TABLE IF NOT EXISTS skill_definitions ( + skill_name TEXT NOT NULL, + source_user_id TEXT NOT NULL DEFAULT '__local__', + source_machine_id TEXT, + category TEXT, + content TEXT, + base_directory TEXT, + description TEXT, + extracted_from_session TEXT, + updated_at TEXT, + PRIMARY KEY (skill_name, source_user_id) + ); + """) + try: + conn.execute("ALTER TABLE projects ADD COLUMN git_identity TEXT") + except sqlite3.OperationalError: + pass # Column already exists + + if current_version < 22: + logger.info("Migrating → v22: adding team_id (incarnation UUID) to sync_teams") + try: + conn.execute("ALTER TABLE sync_teams ADD COLUMN team_id TEXT NOT NULL DEFAULT ''") + except sqlite3.OperationalError: + pass # Column already exists + # Backfill existing teams with a UUID so they participate in incarnation checks + import uuid as _uuid + for row in conn.execute("SELECT name FROM sync_teams WHERE team_id = '' OR team_id IS NULL").fetchall(): + conn.execute( + "UPDATE sync_teams SET team_id = ? WHERE name = ?", + (str(_uuid.uuid4()), row[0]), + ) + # Record version conn.execute( "INSERT OR REPLACE INTO schema_version (version) VALUES (?)", diff --git a/api/domain/__init__.py b/api/domain/__init__.py new file mode 100644 index 00000000..7ceeec69 --- /dev/null +++ b/api/domain/__init__.py @@ -0,0 +1,5 @@ +"""Domain models for the sync system. + +Pure Python value objects with no database or I/O dependencies. +All models are immutable (frozen=True); mutating methods return new instances. +""" diff --git a/api/domain/events.py b/api/domain/events.py new file mode 100644 index 00000000..bb7f45e4 --- /dev/null +++ b/api/domain/events.py @@ -0,0 +1,50 @@ +"""SyncEvent domain model. + +A SyncEvent is an immutable audit record of something that happened within +a sync team. Events are append-only and never mutated after creation. +""" +from __future__ import annotations + +from datetime import datetime, timezone +from enum import Enum +from typing import Any, Dict, Optional + +from pydantic import BaseModel, ConfigDict, Field + + +class SyncEventType(str, Enum): + team_created = "team_created" + team_dissolved = "team_dissolved" + member_added = "member_added" + member_activated = "member_activated" + member_removed = "member_removed" + member_auto_left = "member_auto_left" + member_left = "member_left" + project_shared = "project_shared" + project_removed = "project_removed" + subscription_offered = "subscription_offered" + subscription_accepted = "subscription_accepted" + subscription_paused = "subscription_paused" + subscription_resumed = "subscription_resumed" + subscription_declined = "subscription_declined" + direction_changed = "direction_changed" + session_packaged = "session_packaged" + session_received = "session_received" + device_paired = "device_paired" + device_unpaired = "device_unpaired" + + +class SyncEvent(BaseModel): + """Immutable audit record of a sync system event.""" + + model_config = ConfigDict(frozen=True) + + event_type: SyncEventType + team_name: Optional[str] = None + member_tag: Optional[str] = None + project_git_identity: Optional[str] = None + session_uuid: Optional[str] = None + detail: Optional[Dict[str, Any]] = None + created_at: datetime = Field( + default_factory=lambda: datetime.now(timezone.utc) + ) diff --git a/api/domain/member.py b/api/domain/member.py new file mode 100644 index 00000000..7a1bddc2 --- /dev/null +++ b/api/domain/member.py @@ -0,0 +1,122 @@ +"""Member domain model. + +A Member represents a single device's participation in a Team. +member_tag = "{user_id}.{machine_tag}" uniquely identifies a device within a team. +All state transitions return new immutable instances. +""" +from __future__ import annotations + +from datetime import datetime, timezone +from enum import Enum +from typing import Optional + +from pydantic import BaseModel, ConfigDict, Field + +from domain.team import InvalidTransitionError + + +class MemberStatus(str, Enum): + ADDED = "added" + ACTIVE = "active" + REMOVED = "removed" + + +class Member(BaseModel): + """Immutable domain model representing a team member (device).""" + + model_config = ConfigDict(frozen=True) + + member_tag: str + team_name: str + device_id: str + user_id: str + machine_tag: str + status: MemberStatus = MemberStatus.ADDED + added_at: datetime = Field( + default_factory=lambda: datetime.now(timezone.utc) + ) + updated_at: datetime = Field( + default_factory=lambda: datetime.now(timezone.utc) + ) + + # ------------------------------------------------------------------ + # Derived properties + # ------------------------------------------------------------------ + + @property + def is_active(self) -> bool: + """Return True if the member is in ACTIVE status.""" + return self.status == MemberStatus.ACTIVE + + # ------------------------------------------------------------------ + # Class methods + # ------------------------------------------------------------------ + + @classmethod + def from_member_tag( + cls, + *, + member_tag: str, + team_name: str, + device_id: str, + status: MemberStatus = MemberStatus.ADDED, + added_at: Optional[datetime] = None, + updated_at: Optional[datetime] = None, + ) -> "Member": + """Create a Member by splitting *member_tag* on the first dot. + + Per spec: user_id cannot contain dots; first dot separates user from machine. + """ + if "." not in member_tag: + raise ValueError( + f"member_tag '{member_tag}' must contain a dot separating user_id and machine_tag" + ) + user_id, machine_tag = member_tag.split(".", 1) + kwargs: dict = dict( + member_tag=member_tag, + team_name=team_name, + user_id=user_id, + machine_tag=machine_tag, + device_id=device_id, + status=status, + ) + if added_at is not None: + kwargs["added_at"] = added_at + if updated_at is not None: + kwargs["updated_at"] = updated_at + return cls(**kwargs) + + # ------------------------------------------------------------------ + # State transitions + # ------------------------------------------------------------------ + + def activate(self) -> "Member": + """Transition ADDED → ACTIVE. + + Raises: + InvalidTransitionError: if current status is not ADDED. + """ + if self.status != MemberStatus.ADDED: + raise InvalidTransitionError( + f"Cannot activate member in status '{self.status.value}'. " + "Member must be in ADDED status." + ) + return self.model_copy(update={ + "status": MemberStatus.ACTIVE, + "updated_at": datetime.now(timezone.utc), + }) + + def remove(self) -> "Member": + """Transition ADDED|ACTIVE → REMOVED. + + Raises: + InvalidTransitionError: if current status is REMOVED. + """ + if self.status == MemberStatus.REMOVED: + raise InvalidTransitionError( + "Member is already in REMOVED status." + ) + return self.model_copy(update={ + "status": MemberStatus.REMOVED, + "updated_at": datetime.now(timezone.utc), + }) diff --git a/api/domain/project.py b/api/domain/project.py new file mode 100644 index 00000000..8de81e3c --- /dev/null +++ b/api/domain/project.py @@ -0,0 +1,70 @@ +"""SharedProject domain model. + +A SharedProject represents a git repository that has been shared within a Team +via Syncthing. The folder_suffix is derived from the git_identity and used to +construct Syncthing folder IDs. +""" +from __future__ import annotations + +from datetime import datetime, timezone +from enum import Enum +from typing import Optional + +from pydantic import BaseModel, ConfigDict, Field + +from domain.team import InvalidTransitionError + + +def derive_folder_suffix(git_identity: str) -> str: + """Derive a Syncthing-safe folder suffix from a git identity string. + + Rules: + - Strip trailing ".git" + - Replace all "/" with "-" + + Examples: + "user/repo.git" → "user-repo" + "https://github.com/user/repo.git" → "https:-github.com-user-repo" + "org/team/repo" → "org-team-repo" + """ + suffix = git_identity + if suffix.endswith(".git"): + suffix = suffix[:-4] + suffix = suffix.replace("/", "-") + return suffix + + +class SharedProjectStatus(str, Enum): + SHARED = "shared" + REMOVED = "removed" + + +class SharedProject(BaseModel): + """Immutable domain model representing a project shared within a team.""" + + model_config = ConfigDict(frozen=True) + + team_name: str + git_identity: str + encoded_name: Optional[str] = None + folder_suffix: str + status: SharedProjectStatus = SharedProjectStatus.SHARED + shared_at: datetime = Field( + default_factory=lambda: datetime.now(timezone.utc) + ) + + # ------------------------------------------------------------------ + # State transitions + # ------------------------------------------------------------------ + + def remove(self) -> "SharedProject": + """Transition SHARED → REMOVED. + + Raises: + InvalidTransitionError: if already REMOVED. + """ + if self.status == SharedProjectStatus.REMOVED: + raise InvalidTransitionError( + f"Project '{self.git_identity}' is already removed." + ) + return self.model_copy(update={"status": SharedProjectStatus.REMOVED}) diff --git a/api/domain/subscription.py b/api/domain/subscription.py new file mode 100644 index 00000000..eb826d99 --- /dev/null +++ b/api/domain/subscription.py @@ -0,0 +1,149 @@ +"""Subscription domain model. + +A Subscription represents a member's opt-in/opt-out state for a shared project. +State machine: + OFFERED → ACCEPTED (accept(direction)) + ACCEPTED → PAUSED (pause) + PAUSED → ACCEPTED (resume) + OFFERED|ACCEPTED|PAUSED → DECLINED (decline) + DECLINED → OFFERED (reopen) + change_direction: only allowed when ACCEPTED + +All state transitions return new immutable instances. +""" +from __future__ import annotations + +from datetime import datetime, timezone +from enum import Enum + +from pydantic import BaseModel, ConfigDict, Field + +from domain.team import InvalidTransitionError + + +class SyncDirection(str, Enum): + SEND = "send" + RECEIVE = "receive" + BOTH = "both" + + +class SubscriptionStatus(str, Enum): + OFFERED = "offered" + ACCEPTED = "accepted" + PAUSED = "paused" + DECLINED = "declined" + + +class Subscription(BaseModel): + """Immutable domain model representing a member's subscription to a shared project.""" + + model_config = ConfigDict(frozen=True) + + member_tag: str + team_name: str + project_git_identity: str + status: SubscriptionStatus = SubscriptionStatus.OFFERED + direction: SyncDirection = SyncDirection.BOTH + updated_at: datetime = Field( + default_factory=lambda: datetime.now(timezone.utc) + ) + + # ------------------------------------------------------------------ + # State transitions + # ------------------------------------------------------------------ + + def accept(self, direction: SyncDirection) -> "Subscription": + """Transition OFFERED → ACCEPTED with the given direction. + + Raises: + InvalidTransitionError: if status is not OFFERED. + """ + if self.status != SubscriptionStatus.OFFERED: + raise InvalidTransitionError( + f"Cannot accept subscription in status '{self.status.value}'. " + "Must be in OFFERED status." + ) + return self.model_copy(update={ + "status": SubscriptionStatus.ACCEPTED, + "direction": direction, + "updated_at": datetime.now(timezone.utc), + }) + + def pause(self) -> "Subscription": + """Transition ACCEPTED → PAUSED. + + Raises: + InvalidTransitionError: if status is not ACCEPTED. + """ + if self.status != SubscriptionStatus.ACCEPTED: + raise InvalidTransitionError( + f"Cannot pause subscription in status '{self.status.value}'. " + "Must be in ACCEPTED status." + ) + return self.model_copy(update={ + "status": SubscriptionStatus.PAUSED, + "updated_at": datetime.now(timezone.utc), + }) + + def resume(self) -> "Subscription": + """Transition PAUSED → ACCEPTED. + + Raises: + InvalidTransitionError: if status is not PAUSED. + """ + if self.status != SubscriptionStatus.PAUSED: + raise InvalidTransitionError( + f"Cannot resume subscription in status '{self.status.value}'. " + "Must be in PAUSED status." + ) + return self.model_copy(update={ + "status": SubscriptionStatus.ACCEPTED, + "updated_at": datetime.now(timezone.utc), + }) + + def decline(self) -> "Subscription": + """Transition any status except DECLINED → DECLINED. + + Raises: + InvalidTransitionError: if already DECLINED. + """ + if self.status == SubscriptionStatus.DECLINED: + raise InvalidTransitionError( + "Subscription is already declined." + ) + return self.model_copy(update={ + "status": SubscriptionStatus.DECLINED, + "updated_at": datetime.now(timezone.utc), + }) + + def reopen(self) -> "Subscription": + """Transition DECLINED → OFFERED, allowing the member to reconsider. + + Raises: + InvalidTransitionError: if status is not DECLINED. + """ + if self.status != SubscriptionStatus.DECLINED: + raise InvalidTransitionError( + f"Cannot reopen subscription in status '{self.status.value}'. " + "Must be in DECLINED status." + ) + return self.model_copy(update={ + "status": SubscriptionStatus.OFFERED, + "updated_at": datetime.now(timezone.utc), + }) + + def change_direction(self, direction: SyncDirection) -> "Subscription": + """Change sync direction. Only allowed when ACCEPTED. + + Raises: + InvalidTransitionError: if status is not ACCEPTED. + """ + if self.status != SubscriptionStatus.ACCEPTED: + raise InvalidTransitionError( + f"Cannot change direction of subscription in status '{self.status.value}'. " + "Must be in ACCEPTED status." + ) + return self.model_copy(update={ + "direction": direction, + "updated_at": datetime.now(timezone.utc), + }) diff --git a/api/domain/team.py b/api/domain/team.py new file mode 100644 index 00000000..b98f5ed0 --- /dev/null +++ b/api/domain/team.py @@ -0,0 +1,122 @@ +"""Team domain model. + +A Team is a named group of devices that share Claude Code sessions via Syncthing. +All state transitions return new immutable instances. +""" +from __future__ import annotations + +import uuid +from datetime import datetime, timezone +from enum import Enum +from typing import TYPE_CHECKING + +from pydantic import BaseModel, ConfigDict, Field + +if TYPE_CHECKING: + from domain.member import Member + + +class TeamStatus(str, Enum): + ACTIVE = "active" + DISSOLVED = "dissolved" + + +class AuthorizationError(Exception): + """Raised when a device tries to perform an action it is not authorized for.""" + + +class InvalidTransitionError(ValueError): + """Raised when a state transition is not allowed from the current state.""" + + +class Team(BaseModel): + """Immutable domain model representing a sync team. + + ``team_id`` is a UUID that uniquely identifies a team *incarnation*. + When a team is dissolved and re-created with the same name, the new + team gets a fresh ``team_id``, allowing stale metadata (removal signals, + folder offers) from the old incarnation to be detected and ignored. + """ + + model_config = ConfigDict(frozen=True) + + name: str + leader_device_id: str + leader_member_tag: str + team_id: str = Field(default_factory=lambda: str(uuid.uuid4())) + status: TeamStatus = TeamStatus.ACTIVE + created_at: datetime = Field( + default_factory=lambda: datetime.now(timezone.utc) + ) + + # ------------------------------------------------------------------ + # Queries + # ------------------------------------------------------------------ + + def is_leader(self, device_id: str) -> bool: + """Return True if *device_id* is the current team leader.""" + return self.leader_device_id == device_id + + # ------------------------------------------------------------------ + # State transitions + # ------------------------------------------------------------------ + + def dissolve(self, *, by_device: str) -> "Team": + """Dissolve the team. Only the leader may dissolve. + + Raises: + AuthorizationError: if *by_device* is not the leader. + InvalidTransitionError: if the team is already dissolved. + """ + if not self.is_leader(by_device): + raise AuthorizationError( + f"Device '{by_device}' is not the team leader and cannot dissolve the team." + ) + if self.status == TeamStatus.DISSOLVED: + raise InvalidTransitionError( + f"Team '{self.name}' is already dissolved." + ) + return self.model_copy(update={"status": TeamStatus.DISSOLVED}) + + def _assert_active(self) -> None: + """Raise if the team is not ACTIVE.""" + if self.status != TeamStatus.ACTIVE: + raise InvalidTransitionError( + f"Team '{self.name}' is {self.status.value}; operation requires ACTIVE status." + ) + + def add_member(self, member: "Member", *, by_device: str) -> "Member": + """Add *member* to the team. Only the leader may add members. + + Raises: + InvalidTransitionError: if the team is not ACTIVE. + AuthorizationError: if *by_device* is not the leader. + """ + self._assert_active() + if not self.is_leader(by_device): + raise AuthorizationError( + f"Device '{by_device}' is not the team leader and cannot add members." + ) + return member + + def remove_member(self, member: "Member", *, by_device: str) -> "Member": + """Remove *member* from the team. Only the leader may remove members. + + The leader cannot remove themselves — they must dissolve the team instead. + Calls member.remove() and returns the removed Member. + + Raises: + InvalidTransitionError: if the team is not ACTIVE, or if + trying to remove the leader. + AuthorizationError: if *by_device* is not the leader. + """ + self._assert_active() + if not self.is_leader(by_device): + raise AuthorizationError( + f"Device '{by_device}' is not the team leader and cannot remove members." + ) + if member.member_tag == self.leader_member_tag: + raise InvalidTransitionError( + f"Cannot remove the team leader. Use dissolve_team() instead." + ) + return member.remove() diff --git a/api/main.py b/api/main.py index 693ff51b..52edd4a0 100644 --- a/api/main.py +++ b/api/main.py @@ -32,9 +32,16 @@ plans, plugins, projects, + remote_sessions, sessions, skills, subagent_sessions, + sync_members, + sync_pairing, + sync_pending, + sync_projects, + sync_system, + sync_teams, tools, ) from routers import settings as settings_router # noqa: E402 @@ -93,6 +100,82 @@ async def lifespan(app: FastAPI): except Exception as e: logger.warning(f"SQLite indexing failed to start (non-critical): {e}") + # Start remote session watcher (monitors incoming Syncthing files). + # Watches the karma base dir to catch files in both legacy remote-sessions/ + # and v4 karma-out--* inbox folders. + remote_watcher = None + if settings.use_sqlite: + try: + from services.watcher_manager import RemoteSessionWatcher + + remote_watcher = RemoteSessionWatcher( + watch_dir=settings.karma_base, + ) + remote_watcher.start() + logger.info( + "Remote session watcher started: %s", settings.karma_base + ) + except Exception as e: + logger.warning( + "Remote session watcher failed to start (non-critical): %s", e + ) + + # Start session packager (packages local sessions into Syncthing outbox) + session_watcher_mgr = None + if settings.use_sqlite: + try: + from models.sync_config import SyncConfig + config = SyncConfig.load() + if config and config.member_tag: + from db.connection import get_writer_db + from services.watcher_manager import WatcherManager + + db = get_writer_db() + + from db.queries import resolve_encoded_name + + # Build config_data from sync DB tables + teams_rows = db.execute( + "SELECT name FROM sync_teams WHERE status = 'active'" + ).fetchall() + teams_dict = {} + for (tname,) in teams_rows: + proj_rows = db.execute( + "SELECT git_identity, encoded_name, folder_suffix " + "FROM sync_projects WHERE team_name = ? AND status = 'shared'", + (tname,), + ).fetchall() + projects_dict = {} + for git_id, enc_name, _fsuffix in proj_rows: + local_enc = resolve_encoded_name(db, git_id) or enc_name or git_id + projects_dict[git_id] = { + "encoded_name": local_enc, + "path": "", + } + if projects_dict: + teams_dict[tname] = {"projects": projects_dict} + + if teams_dict: + config_data = { + "teams": teams_dict, + "user_id": config.user_id, + "machine_id": config.machine_id, + "device_id": ( + config.syncthing.device_id if config.syncthing else "" + ), + "member_tag": config.member_tag, + } + session_watcher_mgr = WatcherManager() + session_watcher_mgr.start_all(config_data) + logger.info( + "Session packager started for %d team(s)", + len(teams_dict), + ) + except Exception as e: + logger.warning( + "Session packager failed to start (non-critical): %s", e + ) + # Start live session reconciler reconciler_task = None if settings.reconciler_enabled: @@ -113,6 +196,14 @@ async def lifespan(app: FastAPI): yield # Shutdown + if remote_watcher is not None: + remote_watcher.stop() + logger.info("Remote session watcher stopped") + + if session_watcher_mgr is not None: + session_watcher_mgr.stop() + logger.info("Session packager stopped") + if reconciler_task is not None: reconciler_task.cancel() logger.info("Session reconciler cancelled") @@ -171,6 +262,13 @@ async def lifespan(app: FastAPI): prefix="/agents", tags=["subagent-sessions"], ) +app.include_router(remote_sessions.router, prefix="/remote", tags=["remote"]) +app.include_router(sync_system.router) +app.include_router(sync_members.router) +app.include_router(sync_teams.router) +app.include_router(sync_projects.router) +app.include_router(sync_pairing.router) +app.include_router(sync_pending.router) app.include_router(admin.router) diff --git a/api/models/plugin.py b/api/models/plugin.py index 95daf922..b9fd5c47 100644 --- a/api/models/plugin.py +++ b/api/models/plugin.py @@ -375,6 +375,7 @@ def resolve_manifest_dirs( List of existing directory Paths to scan """ resolved_cache = cache_path.resolve() + plugins_base = (settings.claude_base / "plugins").resolve() dirs: list[Path] = [] seen: set[Path] = set() diff --git a/api/models/sync_config.py b/api/models/sync_config.py new file mode 100644 index 00000000..fb8d132f --- /dev/null +++ b/api/models/sync_config.py @@ -0,0 +1,94 @@ +"""Sync configuration management. + +Identity and credentials only. Teams/members/projects live in SQLite. +""" + +import json +import os +import re +import socket +from pathlib import Path +from typing import Optional + +from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator + + +KARMA_BASE = Path.home() / ".claude_karma" +SYNC_CONFIG_PATH = KARMA_BASE / "sync-config.json" + + +def _sanitize_machine_tag(hostname: str) -> str: + """Derive a safe machine_tag from hostname. + + Rules: lowercase, alphanumeric + hyphens only, collapse multi-hyphens, + strip leading/trailing hyphens, no '--' (folder ID delimiter). + """ + if not hostname: + return "unknown" + tag = hostname.lower() + tag = re.sub(r"[^a-z0-9-]", "-", tag) # non-alphanum -> hyphen + tag = re.sub(r"-{2,}", "-", tag) # collapse multi-hyphens + tag = tag.strip("-") + return tag or "unknown" + + +class SyncthingSettings(BaseModel): + """Syncthing connection settings.""" + + model_config = ConfigDict(frozen=True) + + api_url: str = Field(default="http://127.0.0.1:8384", description="Syncthing REST API URL") + api_key: Optional[str] = Field(default=None, description="Syncthing API key") + device_id: Optional[str] = Field(default=None, description="This device's Syncthing ID") + + +class SyncConfig(BaseModel): + """Identity and credentials. Teams/members/projects live in SQLite.""" + + model_config = ConfigDict(frozen=True) + + user_id: str = Field(..., description="User identity") + machine_id: str = Field( + default_factory=lambda: socket.gethostname(), + description="Machine hostname", + ) + machine_tag: Optional[str] = Field( + default=None, + description="Sanitized machine identifier (auto-derived from machine_id if not set)", + ) + syncthing: SyncthingSettings = Field(default_factory=SyncthingSettings) + + @field_validator("user_id") + @classmethod + def validate_user_id(cls, v: str) -> str: + if not re.match(r"^[a-zA-Z0-9_-]+$", v): + raise ValueError("user_id must be alphanumeric, dash, or underscore (no dots)") + return v + + @model_validator(mode="after") + def _derive_machine_tag(self) -> "SyncConfig": + if self.machine_tag is None: + object.__setattr__(self, "machine_tag", _sanitize_machine_tag(self.machine_id)) + return self + + @property + def member_tag(self) -> str: + """Unique device identity: user_id.machine_tag""" + return f"{self.user_id}.{self.machine_tag}" + + @staticmethod + def load() -> Optional["SyncConfig"]: + """Load config from disk. Returns None if not initialized.""" + if not SYNC_CONFIG_PATH.exists(): + return None + try: + data = json.loads(SYNC_CONFIG_PATH.read_text()) + return SyncConfig(**data) + except (json.JSONDecodeError, ValueError) as e: + raise RuntimeError(f"Corrupt config at {SYNC_CONFIG_PATH}: {e}") from e + + def save(self) -> None: + """Persist config to disk.""" + SYNC_CONFIG_PATH.parent.mkdir(parents=True, exist_ok=True) + SYNC_CONFIG_PATH.write_text(json.dumps(self.model_dump(), indent=2) + "\n") + os.chmod(SYNC_CONFIG_PATH, 0o600) diff --git a/api/models/sync_manifest.py b/api/models/sync_manifest.py new file mode 100644 index 00000000..615b1505 --- /dev/null +++ b/api/models/sync_manifest.py @@ -0,0 +1,85 @@ +"""Sync manifest model — describes what was synced and when.""" + +from datetime import datetime, timezone +from typing import Dict, Optional +from pydantic import BaseModel, ConfigDict, Field + + +class SessionEntry(BaseModel): + """Metadata for a single synced session.""" + + model_config = ConfigDict(frozen=True) + + uuid: str + mtime: str = Field(..., description="ISO timestamp of session file modification time") + size_bytes: int + worktree_name: Optional[str] = Field(default=None, description="Worktree name if session is from a worktree") + git_branch: Optional[str] = Field(default=None, description="Git branch the session was on") + + +class SkillDefinitionEntry(BaseModel): + """Skill definition content from the exporting machine's filesystem.""" + + model_config = ConfigDict(frozen=True) + + content: Optional[str] = Field(default=None, description="SKILL.md body text") + description: Optional[str] = Field( + default=None, description="Description parsed from YAML frontmatter" + ) + category: str = Field( + ..., description="Classification category (e.g., plugin_skill, custom_skill)" + ) + base_directory: Optional[str] = Field( + default=None, description="Parent directory of the skill file on the source machine" + ) + + +class SyncManifest(BaseModel): + """Manifest describing a sync snapshot.""" + + model_config = ConfigDict(frozen=True) + + version: int = Field(default=1) + user_id: str + machine_id: str + member_tag: Optional[str] = Field(default=None, description="Sender identity: user_id.machine_tag") + device_id: Optional[str] = Field(default=None, description="Syncthing device ID of the source machine") + project_path: str = Field(..., description="Original project path on source machine") + project_encoded: str = Field(..., description="Claude-encoded project directory name") + synced_at: str = Field( + default_factory=lambda: datetime.now(timezone.utc).isoformat(), + ) + session_count: int + sessions: list[SessionEntry] + git_identity: Optional[str] = Field( + default=None, description="Normalized git remote identity: owner/repo" + ) + team_name: Optional[str] = Field( + default=None, description="Team this sync belongs to" + ) + proj_suffix: Optional[str] = Field( + default=None, + description="Agreed Syncthing folder ID suffix (e.g., 'acme-org-acme-app' for git, 'experiments' for non-git)", + ) + project_name: Optional[str] = Field( + default=None, + description="Human-readable project name from the CLI 'project add' command. " + "Used by receivers to display meaningful labels for unresolved (especially non-git) projects.", + ) + skill_classifications: Dict[str, str] = Field( + default_factory=dict, + description=( + "Invocation name → category mapping from the exporting machine's filesystem. " + "E.g. {'feature-dev:feature-dev': 'plugin_command', 'superpowers:brainstorming': 'plugin_skill'}. " + "Used by the importing side to classify remote skills/commands correctly " + "without relying on the local plugin cache." + ), + ) + skill_definitions: Dict[str, SkillDefinitionEntry] = Field( + default_factory=dict, + description=( + "skill_name → definition entry with content read from the exporting machine's " + "filesystem. Provides authoritative skill content so the importing machine " + "does not need heuristic JSONL extraction." + ), + ) diff --git a/api/parallel.py b/api/parallel.py index 1247243e..3c24fcee 100644 --- a/api/parallel.py +++ b/api/parallel.py @@ -87,6 +87,7 @@ def process_subagent_data(subagent: Any) -> dict: from collections import Counter from models import AssistantMessage, ToolUseBlock, UserMessage + from utils import extract_prompt_from_content tool_counts: Counter = Counter() initial_prompt = None @@ -95,8 +96,10 @@ def process_subagent_data(subagent: Any) -> dict: for msg in subagent.iter_messages(): message_count += 1 if isinstance(msg, UserMessage): - if initial_prompt is None: - initial_prompt = msg.content[:5000] if msg.content else None + if initial_prompt is None and msg.content: + prompt = extract_prompt_from_content(msg.content) + if prompt: + initial_prompt = prompt[:5000] elif isinstance(msg, AssistantMessage): for block in msg.content_blocks: if isinstance(block, ToolUseBlock): diff --git a/api/repositories/__init__.py b/api/repositories/__init__.py new file mode 100644 index 00000000..177fa0cf --- /dev/null +++ b/api/repositories/__init__.py @@ -0,0 +1 @@ +"""Sync v4 repositories — thin SQLite persistence layer.""" diff --git a/api/repositories/event_repo.py b/api/repositories/event_repo.py new file mode 100644 index 00000000..e8de7cbd --- /dev/null +++ b/api/repositories/event_repo.py @@ -0,0 +1,75 @@ +"""Event repository — SQLite persistence for SyncEvent domain model.""" +from __future__ import annotations + +import json +import sqlite3 +from datetime import datetime, timezone +from typing import Optional + +from domain.events import SyncEvent, SyncEventType + + +class EventRepository: + def log(self, conn: sqlite3.Connection, event: SyncEvent) -> int: + """Persist a SyncEvent and return its auto-generated id.""" + cur = conn.execute( + """INSERT INTO sync_events + (event_type, team_name, member_tag, project_git_identity, + session_uuid, detail, created_at) + VALUES (?, ?, ?, ?, ?, ?, ?)""", + ( + event.event_type.value, + event.team_name, + event.member_tag, + event.project_git_identity, + event.session_uuid, + json.dumps(event.detail) if event.detail is not None else None, + event.created_at.isoformat(), + ), + ) + conn.commit() + return cur.lastrowid + + def query( + self, + conn: sqlite3.Connection, + *, + team: Optional[str] = None, + member_tag: Optional[str] = None, + event_type: Optional[str] = None, + limit: int = 50, + ) -> list[SyncEvent]: + parts = [] + params: list = [] + + if team is not None: + parts.append("team_name = ?") + params.append(team) + if member_tag is not None: + parts.append("member_tag = ?") + params.append(member_tag) + if event_type is not None: + parts.append("event_type = ?") + params.append(event_type) + + where = f"WHERE {' AND '.join(parts)}" if parts else "" + params.append(limit) + + rows = conn.execute( + f"SELECT * FROM sync_events {where} ORDER BY created_at DESC LIMIT ?", + params, + ).fetchall() + return [self._row_to_event(r) for r in rows] + + @staticmethod + def _row_to_event(row: sqlite3.Row) -> SyncEvent: + detail = json.loads(row["detail"]) if row["detail"] is not None else None + return SyncEvent( + event_type=SyncEventType(row["event_type"]), + team_name=row["team_name"], + member_tag=row["member_tag"], + project_git_identity=row["project_git_identity"], + session_uuid=row["session_uuid"], + detail=detail, + created_at=datetime.fromisoformat(row["created_at"]), + ) diff --git a/api/repositories/member_repo.py b/api/repositories/member_repo.py new file mode 100644 index 00000000..ad93f899 --- /dev/null +++ b/api/repositories/member_repo.py @@ -0,0 +1,99 @@ +"""Member repository — SQLite persistence for Member domain model.""" +from __future__ import annotations + +import sqlite3 +from datetime import datetime, timezone + +from domain.member import Member, MemberStatus + + +class MemberRepository: + def get(self, conn: sqlite3.Connection, team_name: str, member_tag: str) -> Member | None: + row = conn.execute( + "SELECT * FROM sync_members WHERE team_name = ? AND member_tag = ?", + (team_name, member_tag), + ).fetchone() + if row is None: + return None + return self._row_to_member(row) + + def get_by_device(self, conn: sqlite3.Connection, device_id: str) -> list[Member]: + rows = conn.execute( + "SELECT * FROM sync_members WHERE device_id = ?", (device_id,) + ).fetchall() + return [self._row_to_member(r) for r in rows] + + def get_all_by_member_tag( + self, conn: sqlite3.Connection, member_tag: str + ) -> list[Member]: + rows = conn.execute( + "SELECT * FROM sync_members WHERE member_tag = ?", (member_tag,) + ).fetchall() + return [self._row_to_member(r) for r in rows] + + def get_by_user_id( + self, conn: sqlite3.Connection, user_id: str + ) -> list[Member]: + rows = conn.execute( + "SELECT * FROM sync_members WHERE user_id = ?", (user_id,) + ).fetchall() + return [self._row_to_member(r) for r in rows] + + def save(self, conn: sqlite3.Connection, member: Member) -> None: + conn.execute( + """INSERT INTO sync_members + (team_name, member_tag, device_id, user_id, machine_tag, status, added_at, updated_at) + VALUES (?, ?, ?, ?, ?, ?, ?, ?) + ON CONFLICT(team_name, member_tag) DO UPDATE SET + device_id = excluded.device_id, + user_id = excluded.user_id, + machine_tag = excluded.machine_tag, + status = excluded.status, + updated_at = excluded.updated_at""", + (member.team_name, member.member_tag, member.device_id, + member.user_id, member.machine_tag, member.status.value, + member.added_at.isoformat(), member.updated_at.isoformat()), + ) + conn.commit() + + def list_for_team(self, conn: sqlite3.Connection, team_name: str) -> list[Member]: + rows = conn.execute( + "SELECT * FROM sync_members WHERE team_name = ?", (team_name,) + ).fetchall() + return [self._row_to_member(r) for r in rows] + + def was_removed(self, conn: sqlite3.Connection, team_name: str, device_id: str) -> bool: + row = conn.execute( + "SELECT 1 FROM sync_removed_members WHERE team_name = ? AND device_id = ?", + (team_name, device_id), + ).fetchone() + return row is not None + + def record_removal( + self, + conn: sqlite3.Connection, + team_name: str, + device_id: str, + member_tag: str | None = None, + ) -> None: + conn.execute( + """INSERT INTO sync_removed_members (team_name, device_id, member_tag) + VALUES (?, ?, ?) + ON CONFLICT(team_name, device_id) DO UPDATE SET + member_tag = excluded.member_tag""", + (team_name, device_id, member_tag), + ) + conn.commit() + + @staticmethod + def _row_to_member(row: sqlite3.Row) -> Member: + return Member( + team_name=row["team_name"], + member_tag=row["member_tag"], + device_id=row["device_id"], + user_id=row["user_id"], + machine_tag=row["machine_tag"], + status=MemberStatus(row["status"]), + added_at=datetime.fromisoformat(row["added_at"]), + updated_at=datetime.fromisoformat(row["updated_at"]), + ) diff --git a/api/repositories/project_repo.py b/api/repositories/project_repo.py new file mode 100644 index 00000000..b982ee56 --- /dev/null +++ b/api/repositories/project_repo.py @@ -0,0 +1,76 @@ +"""Project repository — SQLite persistence for SharedProject domain model.""" +from __future__ import annotations + +import sqlite3 +from datetime import datetime, timezone + +from domain.project import SharedProject, SharedProjectStatus + + +class ProjectRepository: + def get( + self, conn: sqlite3.Connection, team_name: str, git_identity: str + ) -> SharedProject | None: + row = conn.execute( + "SELECT * FROM sync_projects WHERE team_name = ? AND git_identity = ?", + (team_name, git_identity), + ).fetchone() + if row is None: + return None + return self._row_to_project(row) + + def save(self, conn: sqlite3.Connection, project: SharedProject) -> None: + conn.execute( + """INSERT INTO sync_projects + (team_name, git_identity, encoded_name, folder_suffix, status, shared_at) + VALUES (?, ?, ?, ?, ?, ?) + ON CONFLICT(team_name, git_identity) DO UPDATE SET + encoded_name = excluded.encoded_name, + folder_suffix = excluded.folder_suffix, + status = excluded.status""", + (project.team_name, project.git_identity, project.encoded_name, + project.folder_suffix, project.status.value, project.shared_at.isoformat()), + ) + conn.commit() + + def list_for_team( + self, + conn: sqlite3.Connection, + team_name: str, + include_removed: bool = False, + ) -> list[SharedProject]: + if include_removed: + rows = conn.execute( + "SELECT * FROM sync_projects WHERE team_name = ?", (team_name,) + ).fetchall() + else: + rows = conn.execute( + "SELECT * FROM sync_projects WHERE team_name = ? AND status != 'removed'", + (team_name,), + ).fetchall() + return [self._row_to_project(r) for r in rows] + + def find_by_suffix(self, conn: sqlite3.Connection, suffix: str) -> list[SharedProject]: + rows = conn.execute( + "SELECT * FROM sync_projects WHERE folder_suffix = ?", (suffix,) + ).fetchall() + return [self._row_to_project(r) for r in rows] + + def find_by_git_identity( + self, conn: sqlite3.Connection, git_identity: str + ) -> list[SharedProject]: + rows = conn.execute( + "SELECT * FROM sync_projects WHERE git_identity = ?", (git_identity,) + ).fetchall() + return [self._row_to_project(r) for r in rows] + + @staticmethod + def _row_to_project(row: sqlite3.Row) -> SharedProject: + return SharedProject( + team_name=row["team_name"], + git_identity=row["git_identity"], + encoded_name=row["encoded_name"], + folder_suffix=row["folder_suffix"], + status=SharedProjectStatus(row["status"]), + shared_at=datetime.fromisoformat(row["shared_at"]), + ) diff --git a/api/repositories/subscription_repo.py b/api/repositories/subscription_repo.py new file mode 100644 index 00000000..1186d734 --- /dev/null +++ b/api/repositories/subscription_repo.py @@ -0,0 +1,79 @@ +"""Subscription repository — SQLite persistence for Subscription domain model.""" +from __future__ import annotations + +import sqlite3 +from datetime import datetime, timezone + +from domain.subscription import Subscription, SubscriptionStatus, SyncDirection + + +class SubscriptionRepository: + def get( + self, + conn: sqlite3.Connection, + member_tag: str, + team_name: str, + git_identity: str, + ) -> Subscription | None: + row = conn.execute( + """SELECT * FROM sync_subscriptions + WHERE member_tag = ? AND team_name = ? AND project_git_identity = ?""", + (member_tag, team_name, git_identity), + ).fetchone() + if row is None: + return None + return self._row_to_sub(row) + + def save(self, conn: sqlite3.Connection, sub: Subscription) -> None: + conn.execute( + """INSERT INTO sync_subscriptions + (member_tag, team_name, project_git_identity, status, direction, updated_at) + VALUES (?, ?, ?, ?, ?, ?) + ON CONFLICT(member_tag, team_name, project_git_identity) DO UPDATE SET + status = excluded.status, + direction = excluded.direction, + updated_at = excluded.updated_at""", + (sub.member_tag, sub.team_name, sub.project_git_identity, + sub.status.value, sub.direction.value, sub.updated_at.isoformat()), + ) + conn.commit() + + def list_for_member(self, conn: sqlite3.Connection, member_tag: str) -> list[Subscription]: + rows = conn.execute( + "SELECT * FROM sync_subscriptions WHERE member_tag = ?", (member_tag,) + ).fetchall() + return [self._row_to_sub(r) for r in rows] + + def list_for_project( + self, conn: sqlite3.Connection, team_name: str, git_identity: str + ) -> list[Subscription]: + rows = conn.execute( + """SELECT * FROM sync_subscriptions + WHERE team_name = ? AND project_git_identity = ?""", + (team_name, git_identity), + ).fetchall() + return [self._row_to_sub(r) for r in rows] + + def list_accepted_for_suffix( + self, conn: sqlite3.Connection, suffix: str + ) -> list[Subscription]: + rows = conn.execute( + """SELECT ss.* FROM sync_subscriptions ss + JOIN sync_projects sp + ON ss.team_name = sp.team_name + AND ss.project_git_identity = sp.git_identity + WHERE sp.folder_suffix = ? AND ss.status = 'accepted'""", + (suffix,), + ).fetchall() + return [self._row_to_sub(r) for r in rows] + + @staticmethod + def _row_to_sub(row: sqlite3.Row) -> Subscription: + return Subscription( + member_tag=row["member_tag"], + team_name=row["team_name"], + project_git_identity=row["project_git_identity"], + status=SubscriptionStatus(row["status"]), + direction=SyncDirection(row["direction"]), + updated_at=datetime.fromisoformat(row["updated_at"]), + ) diff --git a/api/repositories/team_repo.py b/api/repositories/team_repo.py new file mode 100644 index 00000000..a706d40d --- /dev/null +++ b/api/repositories/team_repo.py @@ -0,0 +1,68 @@ +"""Team repository — SQLite persistence for Team domain model.""" +from __future__ import annotations + +import sqlite3 +from datetime import datetime, timezone + +from domain.team import Team, TeamStatus + + +class TeamRepository: + def get(self, conn: sqlite3.Connection, name: str) -> Team | None: + row = conn.execute( + "SELECT * FROM sync_teams WHERE name = ?", (name,) + ).fetchone() + if row is None: + return None + return self._row_to_team(row) + + def get_by_leader(self, conn: sqlite3.Connection, device_id: str) -> list[Team]: + rows = conn.execute( + "SELECT * FROM sync_teams WHERE leader_device_id = ?", (device_id,) + ).fetchall() + return [self._row_to_team(r) for r in rows] + + def save(self, conn: sqlite3.Connection, team: Team) -> None: + conn.execute( + """INSERT INTO sync_teams (name, leader_device_id, leader_member_tag, team_id, status, created_at) + VALUES (?, ?, ?, ?, ?, ?) + ON CONFLICT(name) DO UPDATE SET + leader_device_id = excluded.leader_device_id, + leader_member_tag = excluded.leader_member_tag, + team_id = excluded.team_id, + status = excluded.status, + created_at = excluded.created_at""", + (team.name, team.leader_device_id, team.leader_member_tag, + team.team_id, team.status.value, team.created_at.isoformat()), + ) + conn.commit() + + def delete(self, conn: sqlite3.Connection, name: str) -> None: + conn.execute("DELETE FROM sync_teams WHERE name = ?", (name,)) + conn.commit() + + def list_all(self, conn: sqlite3.Connection) -> list[Team]: + rows = conn.execute("SELECT * FROM sync_teams").fetchall() + return [self._row_to_team(r) for r in rows] + + def list_active(self, conn: sqlite3.Connection) -> list[Team]: + rows = conn.execute( + "SELECT * FROM sync_teams WHERE status = ?", (TeamStatus.ACTIVE.value,) + ).fetchall() + return [self._row_to_team(r) for r in rows] + + @staticmethod + def _row_to_team(row: sqlite3.Row) -> Team: + # Deterministic fallback: uuid5 from team name so reads are stable + team_id = row["team_id"] + if not team_id: + import uuid + team_id = str(uuid.uuid5(uuid.NAMESPACE_DNS, f"karma-team:{row['name']}")) + return Team( + name=row["name"], + leader_device_id=row["leader_device_id"], + leader_member_tag=row["leader_member_tag"], + team_id=team_id, + status=TeamStatus(row["status"]), + created_at=datetime.fromisoformat(row["created_at"]), + ) diff --git a/api/requirements.txt b/api/requirements.txt index 4d1f8387..5ee8a374 100644 --- a/api/requirements.txt +++ b/api/requirements.txt @@ -4,3 +4,5 @@ pydantic>=2.10.0 pydantic-settings>=2.0.0 aiofiles>=24.1.0 cachetools>=5.0.0 +watchdog>=4.0.0 +requests>=2.31.0 diff --git a/api/routers/agent_analytics.py b/api/routers/agent_analytics.py index d608bf31..198bb512 100644 --- a/api/routers/agent_analytics.py +++ b/api/routers/agent_analytics.py @@ -303,6 +303,7 @@ def _get_agent_history_sqlite( session_uuid=row["session_uuid"], project_encoded_name=row["project_encoded_name"], project_display_name=project_display_name, + display_name=row.get("agent_display_name"), invoked_at=_parse_iso(row["started_at"]), duration_seconds=row["duration_seconds"], input_tokens=row["input_tokens"], diff --git a/api/routers/agents.py b/api/routers/agents.py index decae259..42afef01 100644 --- a/api/routers/agents.py +++ b/api/routers/agents.py @@ -335,6 +335,11 @@ def get_agent_usage_trend( item: [UsageTrendItem(date=t["date"], count=t["count"]) for t in points] for item, points in data.get("trend_by_item", {}).items() }, + trend_by_user={ + user: [UsageTrendItem(date=t["date"], count=t["count"]) for t in points] + for user, points in data.get("trend_by_user", {}).items() + }, + user_names=data.get("user_names", {}), first_used=data.get("first_used"), last_used=data.get("last_used"), ) @@ -377,6 +382,11 @@ def get_single_agent_usage_trend( item: [UsageTrendItem(date=t["date"], count=t["count"]) for t in points] for item, points in data.get("trend_by_item", {}).items() }, + trend_by_user={ + user: [UsageTrendItem(date=t["date"], count=t["count"]) for t in points] + for user, points in data.get("trend_by_user", {}).items() + }, + user_names=data.get("user_names", {}), first_used=data.get("first_used"), last_used=data.get("last_used"), ) @@ -485,6 +495,10 @@ async def get_agent_sessions( session_titles=row.get("session_titles", []) or title_cache.get_titles(row["project_encoded_name"], row["uuid"]) or [], + session_source=row.get("session_source"), + source=row.get("source"), + remote_user_id=row.get("remote_user_id"), + remote_machine_id=row.get("remote_machine_id"), ) ) diff --git a/api/routers/analytics.py b/api/routers/analytics.py index 5756b604..f0eedb85 100644 --- a/api/routers/analytics.py +++ b/api/routers/analytics.py @@ -70,6 +70,18 @@ def _get_analytics_sqlite( except (ValueError, TypeError): continue + # Per-user session counts + sessions_by_date_by_user: dict[str, Counter[str]] = {} + for entry in data.get("start_times_with_user", []): + user_id = entry["user_id"] + try: + ts = datetime.fromisoformat(entry["start_time"]) + local_time = ts.astimezone(local_tz) + date_key = local_time.strftime("%Y-%m-%d") + sessions_by_date_by_user.setdefault(user_id, Counter())[date_key] += 1 + except (ValueError, TypeError): + continue + # Peak hours hour_totals = [(sum(temporal_heatmap[d][h] for d in range(7)), h) for h in range(24)] hour_totals.sort(reverse=True) @@ -104,6 +116,8 @@ def _get_analytics_sqlite( time_distribution=time_distribution, work_mode_distribution=work_mode_distribution, projects_active=totals.get("projects_active", 0), + sessions_by_date_by_user={k: dict(v) for k, v in sessions_by_date_by_user.items()}, + user_names=data.get("user_names", {}), ) except sqlite3.Error as e: logger.warning("SQLite analytics query failed, falling back: %s", e) diff --git a/api/routers/commands.py b/api/routers/commands.py index 49f8119d..244189e6 100644 --- a/api/routers/commands.py +++ b/api/routers/commands.py @@ -11,7 +11,7 @@ import sys from datetime import datetime, timezone from pathlib import Path -from typing import Annotated, Literal +from typing import Annotated, Literal, Optional from fastapi import APIRouter, Depends, HTTPException, Query, Request @@ -214,6 +214,12 @@ def get_command_usage( cmd_name = row["command_name"] is_plugin = ":" in cmd_name plugin_name = cmd_name.split(":")[0] if is_plugin else None + remote_count = row.get("remote_count") or 0 + local_count = row.get("local_count") or 0 + raw_remote_ids = row.get("remote_user_ids") or "" + remote_user_ids = ( + [uid for uid in raw_remote_ids.split(",") if uid] if raw_remote_ids else [] + ) results.append( { "name": cmd_name, @@ -224,6 +230,10 @@ def get_command_usage( "description": get_command_description(cmd_name), "is_plugin": is_plugin, "plugin": plugin_name, + "remote_count": remote_count, + "local_count": local_count, + "remote_user_ids": remote_user_ids, + "is_remote_only": local_count == 0 and remote_count > 0, } ) return results @@ -475,3 +485,59 @@ async def get_command_info( plugin=None, file_path=str(command_file), ) + + +@router.post("/commands/{command_name}/inherit") +async def inherit_command( + command_name: str, + scope: Annotated[str, Query(..., pattern="^(user|project)$")], + project_encoded_name: Annotated[Optional[str], Query()] = None, +) -> dict: + """ + Inherit a remote command by creating the .md file locally. + + scope: "user" -> ~/.claude/commands/{name}.md + scope: "project" -> {project_path}/.claude/commands/{name}.md + """ + _validate_command_name(command_name) + + from db.connection import sqlite_read + + # 1. Get the command content from skill_definitions + with sqlite_read() as conn: + if conn is None: + raise HTTPException(status_code=503, detail="Database unavailable") + row = conn.execute( + "SELECT content, category, description FROM skill_definitions" + " WHERE skill_name = ? AND source_user_id IS NOT NULL" + " ORDER BY updated_at DESC LIMIT 1", + (command_name,), + ).fetchone() + + if not row or not row["content"]: + raise HTTPException(status_code=404, detail="No remote command definition found for this command") + + content = row["content"] + + # 2. Determine target path + if scope == "user": + target_file = settings.commands_dir / f"{command_name}.md" + else: # project + if not project_encoded_name: + raise HTTPException(status_code=400, detail="project_encoded_name required for project scope") + from models.project import Project + + project_path = Project.decode_path(project_encoded_name) + target_file = Path(project_path) / ".claude" / "commands" / f"{command_name}.md" + + # 3. Verify resolved path stays under intended base (defense-in-depth) + target_file = target_file.resolve() + + if target_file.exists(): + raise HTTPException(status_code=409, detail=f"Command file already exists at {target_file}") + + target_file.parent.mkdir(parents=True, exist_ok=True) + target_file.write_text(content) + + logger.info("Inherited remote command %r to %s", command_name, target_file) + return {"status": "created", "path": str(target_file), "command_name": command_name, "scope": scope} diff --git a/api/routers/plans.py b/api/routers/plans.py index 6f7dddcd..bca9149e 100644 --- a/api/routers/plans.py +++ b/api/routers/plans.py @@ -263,6 +263,7 @@ def list_plans_with_context( search: str = Query("", description="Search query for slug, title, preview, project path"), project: str = Query("", description="Filter by project encoded name"), branch: str = Query("", description="Filter by git branch"), + source: str = Query("", description="Filter by source: 'local', 'remote', or '' for all"), ) -> PlanListResponse: """ List all plans with their associated session and project context. @@ -305,19 +306,46 @@ def list_plans_with_context( # Build full list with context all_plans: list[PlanWithContext] = [] - for plan in plans: - all_plans.append( - PlanWithContext( - slug=plan.slug, - title=plan.extract_title(), - preview=plan.content[:500] if plan.content else "", - word_count=plan.word_count, - created=plan.created, - modified=plan.modified, - size_bytes=plan.size_bytes, - session_context=slug_index.get(plan.slug), + + if source != "remote": + for plan in plans: + all_plans.append( + PlanWithContext( + slug=plan.slug, + title=plan.extract_title(), + preview=plan.content[:500] if plan.content else "", + word_count=plan.word_count, + created=plan.created, + modified=plan.modified, + size_bytes=plan.size_bytes, + session_context=slug_index.get(plan.slug), + ) ) - ) + + # Merge remote plans (from all synced users) + if source != "local": + try: + from services.remote_plans import discover_remote_plans + + for rp in discover_remote_plans(): + all_plans.append( + PlanWithContext( + slug=rp.slug, + title=rp.title, + preview=rp.preview, + word_count=rp.word_count, + created=rp.created, + modified=rp.modified, + size_bytes=rp.size_bytes, + remote_user_id=rp.remote_user_id, + linked_sessions=rp.linked_sessions, + ) + ) + except Exception as e: + logger.debug("Remote plan discovery failed: %s", e) + + # Sort merged list by modified time (newest first) + all_plans.sort(key=lambda p: p.modified, reverse=True) # Apply search filter (supports comma-separated tokens with AND logic) if search: @@ -379,23 +407,52 @@ def list_plans_with_context( ) -@router.get("/{slug}", response_model=PlanDetail) +@router.get("/{slug}") @cacheable(max_age=300, stale_while_revalidate=600, private=True) -def get_plan(slug: str, request: Request) -> PlanDetail: +def get_plan( + slug: str, + request: Request, + remote_user: str = Query("", description="Remote user ID (for remote plans)"), +): """ Get a specific plan by slug. - Args: - slug: Plan identifier (filename without .md) - - Returns: - Full plan content and metadata + If remote_user is provided, looks up the plan from that user's synced outbox. + Otherwise looks up from local ~/.claude/plans/. Raises: 404: Plan not found """ - plan = load_plan(slug) + # Remote plan lookup + if remote_user: + try: + from services.remote_plans import get_remote_plan + + rp = get_remote_plan(slug, remote_user) + if rp: + return { + "slug": rp.slug, + "title": rp.title, + "preview": rp.preview, + "word_count": rp.word_count, + "created": rp.created.isoformat(), + "modified": rp.modified.isoformat(), + "size_bytes": rp.size_bytes, + "content": rp.content, + "remote_user_id": rp.remote_user_id, + "project_encoded_name": rp.project_encoded_name, + "linked_sessions": rp.linked_sessions, + } + except Exception as e: + logger.debug("Remote plan lookup failed for %s/%s: %s", remote_user, slug, e) + + raise HTTPException( + status_code=404, + detail=f"Remote plan '{slug}' not found for user '{remote_user}'", + ) + # Local plan lookup + plan = load_plan(slug) if not plan: raise HTTPException( status_code=404, diff --git a/api/routers/plugins.py b/api/routers/plugins.py index 23445ddc..fbd12a30 100644 --- a/api/routers/plugins.py +++ b/api/routers/plugins.py @@ -16,6 +16,8 @@ from typing import Annotated, Optional from urllib.parse import unquote +from utils import utc_to_local_date + from fastapi import APIRouter, HTTPException, Query, Request from command_helpers import is_plugin_skill @@ -45,7 +47,6 @@ SkillContent, SkillItem, ) -from utils import utc_to_local_date logger = logging.getLogger(__name__) @@ -1234,9 +1235,7 @@ def list_plugin_skills(plugin_name: str, request: Request) -> list[SkillItem]: # Scan skills directories for SKILL.md files for skills_dir in resolve_manifest_dirs(install_path, manifest, "skills", ["skills"]): try: - for skill_md in sorted( - skills_dir.rglob("SKILL.md"), key=lambda p: p.parent.name.lower() - ): + for skill_md in sorted(skills_dir.rglob("SKILL.md"), key=lambda p: p.parent.name.lower()): name = skill_md.parent.name if name in seen_names: continue @@ -1282,9 +1281,7 @@ def list_plugin_skills(plugin_name: str, request: Request) -> list[SkillItem]: logger.warning(f"Failed to process skill entry {entry}: {e}") except OSError as e: logger.error(f"Failed to list commands directory {commands_dir}: {e}") - raise HTTPException( - status_code=500, detail="Failed to list plugin skills directory" - ) from e + raise HTTPException(status_code=500, detail="Failed to list plugin skills directory") from e # Sort alphabetically by name return sorted(items, key=lambda x: x.name.lower()) @@ -1397,45 +1394,6 @@ def get_plugin_skill_content( raise HTTPException(status_code=500, detail="Failed to read skill file") from e -@router.get("/installed-skills") -@cacheable(max_age=120, stale_while_revalidate=300, private=True) -def list_installed_skills(request: Request) -> list[dict]: - """ - List all skills across all installed plugins. - - Returns a flat list of skill entries with prefixed names (e.g. "superpowers:brainstorming"), - suitable for merging with usage data to show 0-use plugin skills on the skills page. - - Cache: 2 minutes - """ - installed = load_installed_plugins() - - if not installed: - return [] - - seen: set[str] = set() - result: list[dict] = [] - - for plugin_name in installed.plugins: - full_name = installed.get_plugin_full_name(plugin_name) or plugin_name - short_name = _get_plugin_short_name(full_name) - capabilities = scan_plugin_capabilities(plugin_name) - for skill_name in capabilities.get("skills", []): - prefixed = f"{short_name}:{skill_name}" - if prefixed in seen: - continue - seen.add(prefixed) - result.append( - { - "name": prefixed, - "plugin": full_name, - "category": "plugin_skill", - } - ) - - return result - - @router.get("/{plugin_name:path}", response_model=PluginDetail) @cacheable(max_age=300, stale_while_revalidate=600, private=True) def get_plugin(plugin_name: str, request: Request) -> PluginDetail: diff --git a/api/routers/projects.py b/api/routers/projects.py index c2784c54..55c07eac 100644 --- a/api/routers/projects.py +++ b/api/routers/projects.py @@ -82,9 +82,40 @@ def _enrich_chain_titles(summaries: list[SessionSummary]) -> None: list_all_projects, normalize_timezone, parse_timestamp_range, + resolve_git_remote_url, resolve_git_root, ) +# TTL cache for remote session filesystem scans (avoids walking disk every request). +# Uses cachetools.TTLCache (bounded, auto-evicts) + threading.Lock to prevent +# thundering herd under concurrent FastAPI threadpool requests. +import threading as _threading + +from cachetools import TTLCache as _TTLCache + +_remote_sessions_cache = _TTLCache(maxsize=128, ttl=30.0) +_remote_cache_lock = _threading.Lock() + + +def _get_cached_remote_sessions(encoded_name: str) -> list: + """Return remote sessions for a project, cached for 30s to avoid repeated filesystem walks.""" + cached = _remote_sessions_cache.get(encoded_name) + if cached is not None: + return cached + + with _remote_cache_lock: + # Double-check after acquiring lock (another thread may have populated it) + cached = _remote_sessions_cache.get(encoded_name) + if cached is not None: + return cached + + from services.remote_sessions import list_remote_sessions_for_project + + result = list_remote_sessions_for_project(encoded_name) + _remote_sessions_cache[encoded_name] = result + return result + + router = APIRouter() @@ -255,6 +286,9 @@ def session_to_summary( session: Session, chain_info: Optional[SessionChainInfoSummary] = None, session_source: Optional[str] = None, + source: Optional[str] = None, + remote_user_id: Optional[str] = None, + remote_machine_id: Optional[str] = None, ) -> SessionSummary: """Convert a Session to SessionSummary.""" initial_prompt = get_initial_prompt(session, max_length=500) @@ -275,6 +309,9 @@ def session_to_summary( chain_info=chain_info, session_titles=list(session.session_titles or []), session_source=session_source, + source=source, + remote_user_id=remote_user_id, + remote_machine_id=remote_machine_id, ) @@ -372,6 +409,7 @@ def list_projects(request: Request): encoded_name = row["encoded_name"] is_git = False git_root = None + git_remote = None is_nested = False exists = False if path: @@ -382,6 +420,8 @@ def list_projects(request: Request): git_root = resolve_git_root(path) if git_root is not None: is_nested = p.resolve() != Path(git_root).resolve() + if is_git: + git_remote = resolve_git_remote_url(path) summaries.append( ProjectSummary( path=path, @@ -394,6 +434,7 @@ def list_projects(request: Request): is_git_repository=is_git, git_root_path=git_root, is_nested_project=is_nested, + git_remote_url=git_remote, latest_session_time=row.get("last_activity"), ) ) @@ -415,6 +456,7 @@ def list_projects(request: Request): is_git_repository=p.is_git_repository, git_root_path=p.git_root_path, is_nested_project=p.is_nested_project, + git_remote_url=resolve_git_remote_url(p.path) if p.is_git_repository and p.exists else None, latest_session_time=get_latest_session_time(p), ) for p in projects @@ -453,68 +495,188 @@ def get_project( except Exception as e: raise HTTPException(status_code=404, detail=f"Project not found: {e}") from e + # For remote-only projects, check for synced sessions before returning 404 + # and fetch the display_name already populated by upsert_team_project/indexer. + _remote_display_name: Optional[str] = None if not project.exists: - raise HTTPException(status_code=404, detail="Project directory not found") + has_remote = False + try: + from db.connection import sqlite_read + + with sqlite_read() as conn: + if conn is not None: + row = conn.execute( + "SELECT COUNT(*) FROM sessions WHERE project_encoded_name = ?", + (encoded_name,), + ).fetchone() + if row and row[0] > 0: + has_remote = True + # Fetch display_name from projects table (populated by + # upsert_team_project and the indexer from git_identity). + dn_row = conn.execute( + "SELECT display_name FROM projects" + " WHERE encoded_name = ? AND display_name IS NOT NULL" + " LIMIT 1", + (encoded_name,), + ).fetchone() + if dn_row and dn_row[0]: + _remote_display_name = dn_row[0] + except Exception: + pass + if not has_remote: + try: + remote_metas = _get_cached_remote_sessions(encoded_name) + if remote_metas: + has_remote = True + except Exception: + pass + if not has_remote: + raise HTTPException(status_code=404, detail="Project directory not found") # Compute offset from page/per_page per_page = max(1, min(per_page, 200)) offset = (page - 1) * per_page limit = per_page - # SQLite fast path + # SQLite fast path — isolated try/excepts so enrichment failures + # never trigger the expensive JSONL fallback. + # One connection is reused for both queries; chain info failure is non-fatal. + db_data = None + db_chain_info: dict = {} + all_indexed_uuids: set[str] = set() try: from db.connection import sqlite_read from db.queries import query_chain_info_for_project, query_project_sessions with sqlite_read() as conn: if conn is not None: - # DB now includes worktree sessions under real project, - # so we can paginate directly without post-merge re-sorting. - data = query_project_sessions( + db_data = query_project_sessions( conn, encoded_name, limit=limit, offset=offset, search=search ) + # Chain info — optional enrichment, degrade gracefully + try: + db_chain_info = query_chain_info_for_project(conn, encoded_name) + except Exception as e: + logger.debug("Chain info query failed (non-fatal): %s", e) + # Fetch ALL indexed UUIDs for accurate remote-session dedup + try: + all_indexed_uuids = { + row[0] + for row in conn.execute( + "SELECT uuid FROM sessions WHERE project_encoded_name = ?", + (encoded_name,), + ).fetchall() + } + except Exception as e: + logger.debug("All-UUIDs query failed (non-fatal): %s", e) + except Exception as e: + logger.warning("SQLite project sessions query failed, falling back: %s", e) - # Build chain info from DB (uses leaf_uuid + slug with overlap filtering) - db_chain_info = query_chain_info_for_project(conn, encoded_name) - - # Build session summaries from SQL rows - # (DB now includes worktree sessions under the real project) - session_summaries = [] - for row in data["sessions"]: - chain_info = None - uuid = row["uuid"] - if uuid in db_chain_info: - ci = db_chain_info[uuid] - chain_info = SessionChainInfoSummary( - chain_id=ci["chain_id"], - position=ci["position"], - total=ci["total"], - is_root=ci["is_root"], - is_latest=ci["is_latest"], - ) - titles = row.get("session_titles", []) - if not titles: - titles = title_cache.get_titles(encoded_name, uuid) or [] + if db_data is not None: + + # Build session summaries from SQL rows + session_summaries = [] + for row in db_data["sessions"]: + chain_info = None + uuid = row["uuid"] + if uuid in db_chain_info: + ci = db_chain_info[uuid] + chain_info = SessionChainInfoSummary( + chain_id=ci["chain_id"], + position=ci["position"], + total=ci["total"], + is_root=ci["is_root"], + is_latest=ci["is_latest"], + ) + titles = row.get("session_titles", []) + if not titles: + titles = title_cache.get_titles(encoded_name, uuid) or [] + session_summaries.append( + SessionSummary( + uuid=uuid, + slug=row.get("slug"), + message_count=row["message_count"], + start_time=row.get("start_time"), + end_time=row.get("end_time"), + duration_seconds=row.get("duration_seconds"), + models_used=row.get("models_used", []), + subagent_count=row.get("subagent_count", 0), + has_todos=False, + initial_prompt=row.get("initial_prompt"), + git_branches=row.get("git_branches", []), + session_titles=titles, + chain_info=chain_info, + session_source=row.get("session_source"), + source=row.get("source"), + remote_user_id=row.get("remote_user_id"), + remote_machine_id=row.get("remote_machine_id"), + ) + ) + + total_count = db_data["total"] + + # Merge unindexed remote sessions — optional enrichment + # IMPORTANT: Only add remote sessions on the first page (offset==0) + # to avoid duplicating them across every paginated response. + # Check against ALL indexed UUIDs for this project (not just the + # current page), since a remote session's UUID may exist on a + # different page of DB results. + remote_session_count = 0 + try: + remote_metas = _get_cached_remote_sessions(encoded_name) + remote_session_count = len(remote_metas) + + if remote_metas and offset == 0: + unindexed = [ + m + for m in remote_metas + if m.uuid not in all_indexed_uuids + ] + + for rmeta in unindexed: + titles = rmeta.session_titles or [] + duration = None + if rmeta.start_time and rmeta.end_time: + duration = ( + rmeta.end_time - rmeta.start_time + ).total_seconds() session_summaries.append( SessionSummary( - uuid=uuid, - slug=row.get("slug"), - message_count=row["message_count"], - start_time=row.get("start_time"), - end_time=row.get("end_time"), - duration_seconds=row.get("duration_seconds"), - models_used=row.get("models_used", []), - subagent_count=row.get("subagent_count", 0), + uuid=rmeta.uuid, + slug=rmeta.slug, + message_count=rmeta.message_count, + start_time=rmeta.start_time, + end_time=rmeta.end_time, + duration_seconds=duration, + models_used=[], + subagent_count=0, has_todos=False, - initial_prompt=row.get("initial_prompt"), - git_branches=row.get("git_branches", []), + initial_prompt=rmeta.initial_prompt, + git_branches=( + [rmeta.git_branch] + if rmeta.git_branch + else [] + ), session_titles=titles, - chain_info=chain_info, - session_source=row.get("session_source"), + source=rmeta.source, + remote_user_id=rmeta.remote_user_id, + remote_machine_id=rmeta.remote_machine_id, ) ) - total_count = data["total"] + total_count += len(unindexed) + + # Trigger background reindex so next request + # won't need this disk check + if unindexed: + import threading + + from db.indexer import trigger_remote_reindex + + threading.Thread( + target=trigger_remote_reindex, + daemon=True, + ).start() # Bug fix: If SQLite returns 0 sessions but files exist on disk, fall back to filesystem if total_count == 0: @@ -528,24 +690,25 @@ def get_project( # Fall through to filesystem scan below raise _FallbackToFilesystem() - _enrich_chain_titles(session_summaries) - return ProjectDetail( - path=project.path, - encoded_name=project.encoded_name, - slug=project.slug, - display_name=project.display_name, - session_count=total_count, - agent_count=project.agent_count, - exists=project.exists, - is_git_repository=project.is_git_repository, - git_root_path=project.git_root_path, - is_nested_project=project.is_nested_project, - sessions=session_summaries, - ) - except _FallbackToFilesystem: - logger.info("SQLite/filesystem mismatch, falling back to filesystem scan") - except Exception as e: - logger.warning("SQLite project sessions query failed, falling back: %s", e) + _enrich_chain_titles(session_summaries) + return ProjectDetail( + path=project.path, + encoded_name=project.encoded_name, + slug=project.slug, + display_name=_remote_display_name or project.display_name, + session_count=total_count, + agent_count=project.agent_count, + exists=project.exists, + is_git_repository=project.is_git_repository, + git_root_path=project.git_root_path, + is_nested_project=project.is_nested_project, + sessions=session_summaries, + remote_session_count=remote_session_count, + ) + except _FallbackToFilesystem: + logger.info("SQLite/filesystem mismatch, falling back to filesystem scan") + except Exception as e: + logger.warning("SQLite project sessions query failed, falling back: %s", e) sessions = project.list_sessions() # Filter out empty sessions (no messages = no valid start_time) @@ -561,6 +724,21 @@ def get_project( desktop_uuids.add(s.uuid) sessions.extend(wt_sessions) + # Merge remote sessions from Syncthing sync + remote_metas = _get_cached_remote_sessions(encoded_name) + remote_uuid_map: dict = {} + existing_uuids = {s.uuid for s in sessions} + for rmeta in remote_metas: + remote_uuid_map[rmeta.uuid] = rmeta + if rmeta.uuid in existing_uuids: + continue + try: + remote_session = rmeta.get_session() + sessions.append(remote_session) + existing_uuids.add(rmeta.uuid) + except Exception: + pass + # Apply search filter (JSONL fallback path) if search: search_lower = search.lower() @@ -616,20 +794,25 @@ def _matches_search(s: Session) -> bool: end_idx = offset + limit if limit else None sessions = sessions[offset:end_idx] - fallback_summaries = [ - session_to_summary( - s, - chain_info_map.get(s.uuid), - session_source="desktop" if s.uuid in desktop_uuids else None, + fallback_summaries = [] + for s in sessions: + rmeta = remote_uuid_map.get(s.uuid) + fallback_summaries.append( + session_to_summary( + s, + chain_info_map.get(s.uuid), + session_source="desktop" if s.uuid in desktop_uuids else None, + source=rmeta.source if rmeta else None, + remote_user_id=rmeta.remote_user_id if rmeta else None, + remote_machine_id=rmeta.remote_machine_id if rmeta else None, + ) ) - for s in sessions - ] _enrich_chain_titles(fallback_summaries) return ProjectDetail( path=project.path, encoded_name=project.encoded_name, slug=project.slug, - display_name=project.display_name, + display_name=_remote_display_name or project.display_name, session_count=total_session_count, agent_count=project.agent_count, exists=project.exists, @@ -637,6 +820,7 @@ def _matches_search(s: Session) -> bool: git_root_path=project.git_root_path, is_nested_project=project.is_nested_project, sessions=fallback_summaries, + remote_session_count=len(remote_uuid_map), ) @@ -1051,8 +1235,8 @@ def get_project_branches(encoded_name: str, request: Request): except Exception as e: raise HTTPException(status_code=404, detail=f"Project not found: {e}") from e - if not project.exists: - raise HTTPException(status_code=404, detail="Project directory not found") + # No exists check — remote-only projects serve branches from the DB + # (remote sessions are indexed with git_branch metadata). # SQLite fast path try: @@ -1411,3 +1595,125 @@ async def get_project_memory(encoded_name: str, request: Request): except OSError as e: logger.error(f"Error reading memory file for {encoded_name}: {e}") raise HTTPException(status_code=500, detail="Failed to read memory file") from e + + +# ============================================================================ +# Remote Sessions (Team sync) +# ============================================================================ + + +@router.get("/{encoded_name}/remote-sessions") +async def project_remote_sessions(encoded_name: str): + """Get remote sessions for a project, grouped by remote user. + + Returns full SessionSummary data (including cost, duration, models, tools) + from SQLite for each remote session, grouped by user. + """ + import json + import re + from collections import defaultdict + + ALLOWED_NAME = re.compile(r"^[a-zA-Z0-9_\-]+$") + if not ALLOWED_NAME.match(encoded_name) or len(encoded_name) > 512: + raise HTTPException(400, "Invalid project name") + + # Query SQLite for rich remote session data (cost, duration, models, tools). + try: + from db.connection import sqlite_read + from db.queries import _parse_json_list + + with sqlite_read() as conn: + if conn is None: + return {"users": []} + + rows = conn.execute( + """SELECT + s.uuid, s.slug, s.message_count, s.start_time, s.end_time, + s.duration_seconds, s.models_used, s.subagent_count, + s.initial_prompt, s.git_branch, s.session_titles, + s.input_tokens, s.output_tokens, s.total_cost, + s.session_source, + s.source, s.remote_user_id, s.remote_machine_id + FROM sessions s + WHERE s.project_encoded_name = :project + AND s.source = 'remote' + AND s.message_count > 0 + ORDER BY s.start_time DESC""", + {"project": encoded_name}, + ).fetchall() + + if not rows: + return {"users": []} + + # Bulk-fetch tools_used for all remote sessions in one query + uuids = [r["uuid"] for r in rows] + placeholders = ",".join("?" * len(uuids)) + tool_rows = conn.execute( + f"SELECT session_uuid, tool_name, count FROM session_tools WHERE session_uuid IN ({placeholders})", + uuids, + ).fetchall() + tools_by_session: dict[str, dict[str, int]] = defaultdict(dict) + for tr in tool_rows: + tools_by_session[tr["session_uuid"]][tr["tool_name"]] = tr["count"] + + # Build SessionSummary objects grouped by user + user_sessions: dict[str, list[SessionSummary]] = defaultdict(list) + user_machine: dict[str, str | None] = {} + + for row in rows: + user_id = row["remote_user_id"] or "unknown" + if user_id not in user_machine: + user_machine[user_id] = row["remote_machine_id"] + + uuid = row["uuid"] + user_sessions[user_id].append( + SessionSummary( + uuid=uuid, + slug=row["slug"], + message_count=row["message_count"], + start_time=row["start_time"], + end_time=row["end_time"], + duration_seconds=row["duration_seconds"], + models_used=_parse_json_list(row["models_used"]), + subagent_count=row["subagent_count"] or 0, + has_todos=False, # Remote sessions don't sync todo data + initial_prompt=row["initial_prompt"], + git_branches=[row["git_branch"]] if row["git_branch"] else [], + session_titles=_parse_json_list(row["session_titles"]), + total_input_tokens=row["input_tokens"], + total_output_tokens=row["output_tokens"], + total_cost=row["total_cost"], + tools_used=tools_by_session.get(uuid, {}), + session_source=row["session_source"], + source="remote", + remote_user_id=row["remote_user_id"], + remote_machine_id=row["remote_machine_id"], + ) + ) + + except Exception as e: + logger.warning("SQLite remote sessions query failed: %s", e) + return {"users": []} + + # Load manifest data for synced_at timestamps and build response + remote_base = Path.home() / ".claude_karma" / "remote-sessions" + users = [] + for user_id, sessions in user_sessions.items(): + synced_at = None + manifest_path = remote_base / user_id / encoded_name / "manifest.json" + if manifest_path.exists(): + try: + manifest = json.loads(manifest_path.read_text()) + synced_at = manifest.get("synced_at") + except (json.JSONDecodeError, OSError): + pass + + users.append({ + "user_id": user_id, + "machine_id": user_machine.get(user_id), + "synced_at": synced_at, + "session_count": len(sessions), + "sessions": sessions, + }) + + return {"users": users} diff --git a/api/routers/remote_sessions.py b/api/routers/remote_sessions.py new file mode 100644 index 00000000..41e36444 --- /dev/null +++ b/api/routers/remote_sessions.py @@ -0,0 +1,205 @@ +"""Remote sessions API — serves sessions synced via Syncthing.""" + +import json +import logging +import re +from pathlib import Path +from typing import Optional + +from fastapi import APIRouter, HTTPException +from pydantic import BaseModel, ValidationError + +from config import settings +from services.remote_sessions import _get_local_user_id + +logger = logging.getLogger(__name__) + +router = APIRouter() + +REMOTE_SESSIONS_DIR = settings.karma_base / "remote-sessions" + +_SAFE_NAME = re.compile(r"^[a-zA-Z0-9_.\-]+$") + + +class RemoteUser(BaseModel): + user_id: str + project_count: int + total_sessions: int + + +class RemoteProject(BaseModel): + encoded_name: str + session_count: int + synced_at: Optional[str] = None + machine_id: Optional[str] = None + + +class RemoteSessionSummary(BaseModel): + uuid: str + mtime: str + size_bytes: int + worktree_name: Optional[str] = None + + +class RemoteManifest(BaseModel): + version: int + user_id: str + machine_id: str + project_path: str + project_encoded: str + synced_at: str + session_count: int + sessions: list[RemoteSessionSummary] + + +def _validate_path_segment(value: str, label: str) -> None: + """Reject path segments that could escape the remote-sessions directory.""" + if not _SAFE_NAME.match(value) or value in (".", ".."): + raise HTTPException( + status_code=400, + detail=f"Invalid {label}: must be alphanumeric, dash, underscore, or dot", + ) + + +def _is_safe_dirname(name: str) -> bool: + """Check if a directory name is safe for path construction.""" + return bool(_SAFE_NAME.match(name)) and name not in (".", "..") + + +def _load_manifest_safe(user_id: str, project: str) -> Optional[dict]: + """Load a manifest.json from filesystem-sourced names. Returns None on any error.""" + if not _is_safe_dirname(user_id) or not _is_safe_dirname(project): + return None + manifest_path = REMOTE_SESSIONS_DIR / user_id / project / "manifest.json" + if not manifest_path.exists(): + return None + try: + return json.loads(manifest_path.read_text()) + except (json.JSONDecodeError, OSError): + return None + + +def _resolve_user_dir(user_id: str) -> Optional[Path]: + """Resolve a user_id to the actual filesystem directory. + + Tries direct match first, then uses the cached _resolve_user_id() from + services to find directories where the manifest user_id matches. + """ + _validate_path_segment(user_id, "user_id") + direct = REMOTE_SESSIONS_DIR / user_id + if direct.is_dir(): + return direct + + if not REMOTE_SESSIONS_DIR.is_dir(): + return None + + # Use cached service-layer resolver: scan dirs and check if their + # resolved user_id matches the requested one + from services.remote_sessions import _resolve_user_id as resolve_uid + + for candidate in REMOTE_SESSIONS_DIR.iterdir(): + if not candidate.is_dir() or not _is_safe_dirname(candidate.name): + continue + if resolve_uid(candidate) == user_id: + return candidate + return None + + +def _load_manifest(user_id: str, project: str) -> Optional[dict]: + """Load a manifest.json for a remote user's project (URL param sourced).""" + user_dir = _resolve_user_dir(user_id) + if not user_dir: + return None + _validate_path_segment(project, "project") + manifest_path = user_dir / project / "manifest.json" + if not manifest_path.exists(): + return None + try: + return json.loads(manifest_path.read_text()) + except (json.JSONDecodeError, OSError): + return None + + +@router.get("/users", response_model=list[RemoteUser]) +def list_remote_users() -> list[RemoteUser]: + """List all remote users who have synced sessions.""" + if not REMOTE_SESSIONS_DIR.is_dir(): + return [] + + from services.remote_sessions import _resolve_user_id as resolve_uid + + local_user = _get_local_user_id() + users = [] + for user_dir in sorted(REMOTE_SESSIONS_DIR.iterdir()): + if not user_dir.is_dir() or not _is_safe_dirname(user_dir.name): + continue + resolved_id = resolve_uid(user_dir) + if user_dir.name == local_user or resolved_id == local_user: + continue + project_count = 0 + total_sessions = 0 + for proj_dir in user_dir.iterdir(): + if not proj_dir.is_dir(): + continue + project_count += 1 + manifest = _load_manifest_safe(user_dir.name, proj_dir.name) + if manifest: + total_sessions += manifest.get("session_count", 0) + users.append( + RemoteUser( + user_id=resolved_id, + project_count=project_count, + total_sessions=total_sessions, + ) + ) + return users + + +@router.get("/users/{user_id}/projects", response_model=list[RemoteProject]) +def list_user_projects(user_id: str) -> list[RemoteProject]: + """List projects synced by a remote user.""" + user_dir = _resolve_user_dir(user_id) + if not user_dir: + raise HTTPException(status_code=404, detail=f"User '{user_id}' not found") + + projects = [] + for proj_dir in sorted(user_dir.iterdir()): + if not proj_dir.is_dir(): + continue + manifest = _load_manifest_safe(user_dir.name, proj_dir.name) + projects.append( + RemoteProject( + encoded_name=proj_dir.name, + session_count=manifest.get("session_count", 0) if manifest else 0, + synced_at=manifest.get("synced_at") if manifest else None, + machine_id=manifest.get("machine_id") if manifest else None, + ) + ) + return projects + + +@router.get( + "/users/{user_id}/projects/{project}/sessions", response_model=list[RemoteSessionSummary] +) +def list_user_sessions(user_id: str, project: str) -> list[RemoteSessionSummary]: + """List sessions for a remote user's project.""" + manifest = _load_manifest(user_id, project) + if not manifest: + raise HTTPException(status_code=404, detail="Manifest not found") + + try: + return [RemoteSessionSummary(**s) for s in manifest.get("sessions", [])] + except ValidationError: + raise HTTPException(status_code=422, detail="Malformed session data in manifest") from None + + +@router.get("/users/{user_id}/projects/{project}/manifest", response_model=RemoteManifest) +def get_manifest(user_id: str, project: str) -> RemoteManifest: + """Get the full manifest for a remote user's project.""" + manifest = _load_manifest(user_id, project) + if not manifest: + raise HTTPException(status_code=404, detail="Manifest not found") + try: + return RemoteManifest(**manifest) + except ValidationError: + raise HTTPException(status_code=422, detail="Malformed manifest data") from None diff --git a/api/routers/sessions.py b/api/routers/sessions.py index d93844cd..c6a78897 100644 --- a/api/routers/sessions.py +++ b/api/routers/sessions.py @@ -53,6 +53,7 @@ def _enrich_chain_titles_by_slug(summaries: list[SessionSummary]) -> None: SearchScope, SessionFilter, SessionMetadata, + SessionSource, SessionStatus, determine_session_status, ) @@ -158,6 +159,142 @@ def detect_command_source( return ("unknown", None) +# ============================================================================= +# Parse-once: Direct filesystem helpers (no Session object needed) +# ============================================================================= + + +def _load_todos_direct(uuid: str) -> list[TodoItemSchema]: + """Load todos from filesystem without creating a Session object.""" + from models.todo import load_todos_from_file + + todos_dir = settings.claude_base / "todos" + if not todos_dir.exists(): + return [] + + todos: list[TodoItemSchema] = [] + for todo_file in todos_dir.glob(f"{uuid}-*.json"): + try: + for t in load_todos_from_file(todo_file): + todos.append( + TodoItemSchema( + content=t.content, + status=t.status, + active_form=t.active_form, + ) + ) + except Exception: + continue + return todos + + +def _load_tasks_direct(uuid: str) -> list[TaskSchema]: + """Load tasks from filesystem without creating a Session object.""" + from models.task import load_tasks_from_directory + + tasks_dir = settings.claude_base / "tasks" / uuid + tasks = load_tasks_from_directory(tasks_dir) + return [ + TaskSchema( + id=t.id, + subject=t.subject, + description=t.description, + status=t.status, + active_form=t.active_form, + blocks=t.blocks, + blocked_by=t.blocked_by, + ) + for t in tasks + ] + + +def _build_session_detail_from_db( + detail: dict, + todos: list[TodoItemSchema], + tasks: list[TaskSchema], +) -> SessionDetail: + """Build a SessionDetail schema from DB query result + filesystem data.""" + project_encoded_name = detail.get("project_encoded_name") + uuid = detail["uuid"] + + # Session titles with title_cache fallback + session_titles = detail.get("session_titles") or [] + if not session_titles and project_encoded_name: + session_titles = title_cache.get_titles(project_encoded_name, uuid) or [] + + # Build skill usage list + skills_used = [] + for skill_name, inv_source, count in detail.get("skills_used_raw", []): + skills_used.append( + SkillUsage( + name=skill_name, + count=count, + is_plugin=is_plugin_skill(skill_name), + plugin=_skill_plugin_name(skill_name), + invocation_source=inv_source, + ) + ) + + # Build command usage list + commands_used = [] + for cmd_name, inv_source, count in detail.get("commands_used_raw", []): + source, plugin = detect_command_source(cmd_name, project_encoded_name) + commands_used.append( + CommandUsage( + name=cmd_name, + count=count, + source=source, + plugin=plugin, + invocation_source=inv_source, + ) + ) + + return SessionDetail( + uuid=uuid, + slug=detail.get("slug"), + project_encoded_name=project_encoded_name, + project_display_name=detail.get("project_display_name"), + message_count=detail.get("message_count") or 0, + start_time=detail.get("start_time"), + end_time=detail.get("end_time"), + duration_seconds=detail.get("duration_seconds"), + models_used=detail.get("models_used") or [], + subagent_count=detail.get("subagent_count") or 0, + has_todos=len(todos) > 0, + todo_count=len(todos), + initial_prompt=detail.get("initial_prompt"), + session_source=detail.get("session_source"), + source=detail.get("source"), + remote_user_id=detail.get("remote_user_id"), + remote_machine_id=detail.get("remote_machine_id"), + # SessionDetail-specific fields + initial_prompt_images=[], # Not indexed in DB + tools_used=detail.get("tools_used") or {}, + git_branches=detail.get("git_branches") or [], + working_directories=detail.get("working_directories") or [], + total_input_tokens=detail.get("input_tokens") or 0, + total_output_tokens=detail.get("output_tokens") or 0, + cache_hit_rate=detail.get("cache_hit_rate") or 0.0, + total_cost=detail.get("total_cost") or 0.0, + todos=todos, + tasks=tasks, + has_tasks=len(tasks) > 0, + has_chain=detail.get("has_chain", False), + is_continuation_marker=bool(detail.get("is_continuation_marker")), + file_snapshot_count=detail.get("file_snapshot_count") or 0, + project_context_summaries=[], # Not indexed in DB + project_context_leaf_uuids=detail.get("project_context_leaf_uuids") or [], + session_titles=session_titles, + was_compacted=bool(detail.get("was_compacted")), + compaction_summary_count=detail.get("compaction_count") or 0, + compaction_summaries=[], # Full text not indexed in DB + message_type_breakdown={}, # Not indexed in DB + skills_used=skills_used, + skills_mentioned=[], # DB doesn't distinguish used vs mentioned + commands_used=commands_used, + ) + + # ============================================================================= # All Sessions Listing Endpoint (Global Sessions Page) # ============================================================================= @@ -336,10 +473,12 @@ def get_all_sessions( branch: Optional[str] = None, scope: SearchScope = SearchScope.BOTH, status: SessionStatus = SessionStatus.ALL, + source: str = "all", start_ts: Optional[int] = None, end_ts: Optional[int] = None, page: int = 1, per_page: int = 50, + user: Optional[str] = None, ) -> AllSessionsResponse: """ List all sessions across all projects with optional filtering. @@ -403,12 +542,14 @@ def get_all_sessions( branch=branch, scope=scope, status=status, + source=source, start_dt=start_dt, end_dt=end_dt, start_ts=start_ts, end_ts=end_ts, limit=limit, offset=offset, + user=user, ) except sqlite3.Error as e: logger.warning("SQLite query failed, falling back to JSONL: %s", e) @@ -421,17 +562,19 @@ def get_all_sessions( branch=branch, scope=scope, status=status, + source=source, start_dt=start_dt, end_dt=end_dt, start_ts=start_ts, end_ts=end_ts, limit=limit, offset=offset, + user=user, ) # Cache Control Logic # Disable caching if any filter is active (search results should be fresh) - has_filters = any([search, project, branch, status != SessionStatus.ALL, start_ts, end_ts]) + has_filters = any([search, project, branch, status != SessionStatus.ALL, start_ts, end_ts, user]) if has_filters: # No cache for filtered views @@ -457,12 +600,14 @@ def _get_all_sessions_sqlite( branch, scope, status, - start_dt, - end_dt, - start_ts, - end_ts, - limit, - offset, + source=None, + start_dt=None, + end_dt=None, + start_ts=None, + end_ts=None, + limit=50, + offset=0, + user=None, ) -> AllSessionsResponse: """ SQLite-backed implementation of get_all_sessions. @@ -482,10 +627,12 @@ def _get_all_sessions_sqlite( branch=branch, scope=scope.value if scope else "both", status=status.value if status else "all", + source=source or "all", start_dt=start_dt, end_dt=end_dt, limit=limit, offset=offset, + user=user, ) total = result["total"] @@ -521,6 +668,9 @@ def _get_all_sessions_sqlite( or title_cache.get_titles(row["project_encoded_name"], row["uuid"]) or [], session_source=get_session_source(row["uuid"]), + source=row.get("source"), + remote_user_id=row.get("remote_user_id"), + remote_machine_id=row.get("remote_machine_id"), ) sessions_with_context.append(session_context) @@ -576,12 +726,14 @@ def _get_all_sessions_jsonl( branch, scope, status, - start_dt, - end_dt, - start_ts, - end_ts, - limit, - offset, + source=None, + start_dt=None, + end_dt=None, + start_ts=None, + end_ts=None, + limit=50, + offset=0, + user=None, ) -> AllSessionsResponse: """ Original JSONL-based implementation of get_all_sessions. @@ -589,6 +741,13 @@ def _get_all_sessions_jsonl( Used as fallback when SQLite is unavailable or disabled. """ all_sessions, project_options = _list_all_projects_with_sessions_optimized() + + # Append remote sessions from Syncthing sync + from services.remote_sessions import iter_all_remote_session_metadata + + for remote_meta in iter_all_remote_session_metadata(): + all_sessions.append(remote_meta) + project_options.sort(key=lambda p: p.session_count, reverse=True) search_lower = search.lower() if search else None @@ -599,6 +758,7 @@ def _get_all_sessions_jsonl( search=search_lower, search_scope=scope, status=SessionStatus.ALL, + source=SessionSource(source) if source and source != "all" else SessionSource.ALL, date_from=start_dt, date_to=end_dt, project_encoded_name=project, @@ -607,6 +767,9 @@ def _get_all_sessions_jsonl( filter_without_status._search_lower = search_lower for meta in all_sessions: + # User filter: only include sessions from this remote user + if user and getattr(meta, "remote_user_id", None) != user: + continue if filter_without_status.matches_metadata(meta): session_status = determine_session_status(meta) if session_status in status_counts: @@ -653,8 +816,16 @@ def _get_all_sessions_jsonl( models_used: list[str] = [] subagent_count = 0 - project_dir = settings.projects_dir / meta.encoded_name - subagent_count = _count_subagents_fast(project_dir, meta.uuid) + # For remote sessions, subagents are under the remote-sessions dir; + # for local, under the project dir. Both use {base}/{uuid}/subagents/. + if meta.source == "remote" and meta.remote_user_id: + sessions_dir = ( + settings.karma_base / "remote-sessions" / meta.remote_user_id + / meta.encoded_name / "sessions" + ) + else: + sessions_dir = settings.projects_dir / meta.encoded_name + subagent_count = _count_subagents_fast(sessions_dir, meta.uuid) if meta._session is not None: try: @@ -685,6 +856,9 @@ def _get_all_sessions_jsonl( git_branches=[meta.git_branch] if meta.git_branch else [], session_titles=session_titles, session_source=get_session_source(meta.uuid), + source=meta.source, + remote_user_id=meta.remote_user_id, + remote_machine_id=meta.remote_machine_id, ) sessions_with_context.append(session_context) @@ -827,7 +1001,7 @@ def get_continuation_session(session_uuid: str) -> ContinuationSessionInfo: slug=row["slug"], ) except Exception: - pass + logger.debug("DB fast path failed for continuation lookup", exc_info=True) # JSONL fallback source_result = find_session_with_project(session_uuid) @@ -839,16 +1013,17 @@ def get_continuation_session(session_uuid: str) -> ContinuationSessionInfo: source_slug = source_session.slug source_end_time = source_session.end_time - # Get the project directory - projects_dir = settings.projects_dir - project_dir = projects_dir / project_encoded_name + # Search sibling JSONL files in the same directory as the source session. + # This works for both local (~/.claude/projects/{enc}/) and + # remote (~/.claude_karma/remote-sessions/{user}/{enc}/sessions/) sessions. + sessions_dir = source_session.jsonl_path.parent - if not project_dir.exists(): + if not sessions_dir.exists(): raise HTTPException(status_code=404, detail="Project not found") # Search for continuation session with same slug candidates = [] - for jsonl_path in project_dir.glob("*.jsonl"): + for jsonl_path in sessions_dir.glob("*.jsonl"): if not _is_valid_session_filename(jsonl_path): continue # Skip the source session itself @@ -882,7 +1057,8 @@ def get_continuation_session(session_uuid: str) -> ContinuationSessionInfo: ) # Return the most recent candidate (most likely the actual continuation) - best_candidate = max(candidates, key=lambda s: s.start_time or s.end_time) + _epoch = datetime.min.replace(tzinfo=timezone.utc) + best_candidate = max(candidates, key=lambda s: s.start_time or s.end_time or _epoch) return ContinuationSessionInfo( session_uuid=best_candidate.uuid, @@ -938,14 +1114,62 @@ def get_session(uuid: str, request: Request, fresh: bool = False): """ Get detailed session information. - Phase 3: Supports HTTP caching with ETag and conditional requests. - Returns 304 Not Modified if content hasn't changed. + Parse-once: Uses DB fast path for historical sessions. Falls back to + JSONL when DB unavailable or fresh=True (live polling). Args: uuid: Session UUID fresh: If true, use minimal cache (1s) for live session polling and clear in-memory session cache to get fresh values """ + # DB fast path (skip for fresh=True — live polling needs latest JSONL) + if not fresh: + try: + from db.connection import sqlite_read + from db.queries import query_session_detail + + with sqlite_read() as conn: + if conn is not None: + detail = query_session_detail(conn, uuid) + if detail: + # Supplement truncated initial_prompt from JSONL + # (legacy indexed sessions stored only 500 chars) + db_prompt = detail.get("initial_prompt") + if db_prompt and len(db_prompt) == 500: + try: + result = find_session_with_project(uuid) + if result: + full_prompt = get_initial_prompt(result.session) + if full_prompt: + detail["initial_prompt"] = full_prompt + except Exception: + pass # Keep DB value on failure + + todos = _load_todos_direct(uuid) + tasks = _load_tasks_direct(uuid) + response_data = _build_session_detail_from_db(detail, todos, tasks) + + # ETag from DB jsonl_mtime + jsonl_mtime = detail.get("jsonl_mtime") + etag = f'"{uuid}-{jsonl_mtime}"' if jsonl_mtime else None + conditional_response = check_conditional_request(request, etag, None) + if conditional_response: + return conditional_response + + cache_headers = build_cache_headers( + etag=etag, + max_age=60, + stale_while_revalidate=300, + private=True, + ) + return JSONResponse( + content=response_data.model_dump(mode="json"), + headers=cache_headers, + ) + except Exception: + logger.debug("DB fast path failed for session %s, falling back to JSONL", uuid, exc_info=True) + + # JSONL fallback (also used for fresh=True live polling) result = find_session_with_project(uuid) if not result: raise HTTPException(status_code=404, detail="Session not found") @@ -1147,9 +1371,25 @@ def get_session_todos(uuid: str, request: Request) -> list[TodoItemSchema]: """ Get all todo items for a session. - Returns the current state of todos from ~/.claude/todos/{uuid}-*.json - Phase 3: Cached for 60s with stale-while-revalidate. + Parse-once: Verifies session exists via DB, loads todos directly from + filesystem without parsing JSONL. """ + # DB fast path: verify session exists without JSONL parse + try: + from db.connection import sqlite_read + + with sqlite_read() as conn: + if conn is not None: + row = conn.execute( + "SELECT 1 FROM sessions WHERE uuid = ?", (uuid,) + ).fetchone() + if row: + return _load_todos_direct(uuid) + # Not in DB — might be unindexed, fall through to JSONL + except Exception: + pass + + # JSONL fallback session = find_session(uuid) if session is None: raise HTTPException(status_code=404, detail=f"Session {uuid} not found") @@ -1165,7 +1405,6 @@ def get_session_todos(uuid: str, request: Request) -> list[TodoItemSchema]: for todo in todos ] except Exception as e: - # Log error but return empty list (todos are optional) logger.warning(f"Failed to load todos for session {uuid}: {e}") return [] @@ -1180,8 +1419,8 @@ def get_session_tasks( """ Get task items for a session (new task system with dependency tracking). - Returns the current state of tasks from ~/.claude/tasks/{uuid}/*.json - Tasks have dependency tracking via blocks/blockedBy fields. + Parse-once: Verifies session exists via DB when possible, avoids JSONL parse. + Falls back to JSONL for reconstructed tasks. Args: uuid: Session UUID @@ -1192,9 +1431,26 @@ def get_session_tasks( Returns: List of TaskSchema with updated_at timestamps """ - session = find_session(uuid) - if session is None: - raise HTTPException(status_code=404, detail=f"Session {uuid} not found") + # DB fast path: verify session exists + try filesystem-only task loading + session = None + session_verified = False + try: + from db.connection import sqlite_read + + with sqlite_read() as conn: + if conn is not None: + row = conn.execute( + "SELECT 1 FROM sessions WHERE uuid = ?", (uuid,) + ).fetchone() + if row: + session_verified = True + except Exception: + pass + + if not session_verified: + session = find_session(uuid) + if session is None: + raise HTTPException(status_code=404, detail=f"Session {uuid} not found") # Parse the since parameter if provided since_dt: Optional[datetime] = None @@ -1208,31 +1464,37 @@ def get_session_tasks( # Continue without filtering try: - tasks = session.list_tasks() - tasks_dir = session.tasks_dir + from models.task import load_tasks_from_directory + + tasks_dir = settings.claude_base / "tasks" / uuid + + # Try filesystem first; fall back to JSONL reconstruction if needed + tasks = load_tasks_from_directory(tasks_dir) + if not tasks and session is not None: + # Fallback: reconstruct from JSONL (only if Session was loaded) + tasks = session.list_tasks() task_schemas = [] for task in tasks: - # Determine updated_at from file mtime or session end time + # Determine updated_at from file mtime or fallback updated_at: Optional[datetime] = None task_file = tasks_dir / f"{task.id}.json" if task_file.exists(): - # Use file modification time mtime = task_file.stat().st_mtime updated_at = datetime.fromtimestamp(mtime, tz=timezone.utc) - else: - # For reconstructed tasks, use session end time or current time + elif session is not None: updated_at = session.end_time or datetime.now(timezone.utc) + else: + updated_at = datetime.now(timezone.utc) # Filter by since parameter if provided if since_dt and updated_at: - # Use normalize_timezone for proper timezone comparison normalized_updated = normalize_timezone(updated_at) normalized_since = normalize_timezone(since_dt) if normalized_updated <= normalized_since: - continue # Skip tasks not modified since the given time + continue task_schemas.append( TaskSchema( @@ -1247,7 +1509,6 @@ def get_session_tasks( ) ) - # Add cache headers - minimal cache for live polling response_data = [t.model_dump(mode="json") for t in task_schemas] headers = { "Cache-Control": f"private, max-age={1 if fresh else 60}, stale-while-revalidate={2 if fresh else 300}" @@ -1255,7 +1516,6 @@ def get_session_tasks( return JSONResponse(content=response_data, headers=headers) except Exception as e: - # Log error but return empty list (tasks are optional) logger.warning(f"Failed to load tasks for session {uuid}: {e}") return JSONResponse(content=[], headers={"Cache-Control": "private, max-age=1"}) @@ -1330,6 +1590,7 @@ def get_subagents(uuid: str, request: Request, fresh: bool = False): agent_id=info.agent_id, slug=info.slug, subagent_type=info.subagent_type, + display_name=info.display_name, tools_used=dict(info.tool_counts), message_count=info.message_count, initial_prompt=info.initial_prompt, @@ -1387,6 +1648,7 @@ async def get_subagents_parallel(uuid: str, request: Request): agent_id=info.agent_id, slug=info.slug, subagent_type=info.subagent_type, + display_name=info.display_name, tools_used=dict(info.tool_counts), message_count=info.message_count, initial_prompt=info.initial_prompt, @@ -1418,9 +1680,8 @@ def get_tools(uuid: str, request: Request, fresh: bool = False): """ Get tool usage breakdown for a session. - Phase 2 optimization: Uses single-pass data collection. - Phase 3: Cached for 5min (historical data rarely changes). - Phase 3 DRY: Uses shared conversation_endpoints service. + Parse-once: Uses DB fast path for tool counts. Falls back to JSONL + when DB unavailable or fresh=True (live polling). Args: uuid: Session UUID @@ -1428,20 +1689,40 @@ def get_tools(uuid: str, request: Request, fresh: bool = False): """ from services.conversation_endpoints import build_tool_usage_summaries + # DB fast path + if not fresh: + try: + from db.connection import sqlite_read + from db.queries import query_session_tool_breakdown + + with sqlite_read() as conn: + if conn is not None: + session_counts, subagent_counts = query_session_tool_breakdown(conn, uuid) + if session_counts is not None: + from collections import Counter + summaries = build_tool_usage_summaries( + Counter(session_counts), Counter(subagent_counts) + ) + response_data = [s.model_dump(mode="json") for s in summaries] + headers = { + "Cache-Control": "private, max-age=300, stale-while-revalidate=600" + } + return JSONResponse(content=response_data, headers=headers) + except Exception: + logger.debug("DB fast path failed for tools %s, falling back to JSONL", uuid, exc_info=True) + + # JSONL fallback session = find_session(uuid) if not session: raise HTTPException(status_code=404, detail="Session not found") - # Single-pass collection with subagents data = collect_session_data(session, include_subagents=True) - # Use shared service for building tool summaries summaries = build_tool_usage_summaries( data.session_tool_counts, data.subagent_tool_counts, ) - # Add cache headers - minimal cache for live polling response_data = [s.model_dump(mode="json") for s in summaries] headers = { "Cache-Control": f"private, max-age={1 if fresh else 300}, stale-while-revalidate={2 if fresh else 600}" @@ -1765,6 +2046,21 @@ def set_session_title(uuid: str, request: SetTitleRequest): logger.warning("Failed to update SQLite for session %s: %s", uuid, e) # Don't fail the request if SQLite update fails + # Best-effort write to Syncthing outbox titles.json + try: + sync_config_path = settings.karma_base / "sync-config.json" + if sync_config_path.is_file(): + sync_config = json.loads(sync_config_path.read_text(encoding="utf-8")) + user_id = sync_config.get("user_id") + if user_id: + outbox_dir = settings.karma_base / "remote-sessions" / user_id / encoded_name + if outbox_dir.is_dir(): + from services.titles_io import write_title + + write_title(outbox_dir / "titles.json", uuid, title, "hook") + except Exception as e: + logger.debug("Outbox title write skipped for session %s: %s", uuid, e) + return JSONResponse( content={"status": "ok", "uuid": uuid, "title": title}, status_code=200, diff --git a/api/routers/skills.py b/api/routers/skills.py index cc3296bd..a5aed74a 100644 --- a/api/routers/skills.py +++ b/api/routers/skills.py @@ -13,7 +13,7 @@ import sys from datetime import datetime, timezone from pathlib import Path -from typing import Annotated +from typing import Annotated, Optional from fastapi import APIRouter, Depends, HTTPException, Query, Request @@ -27,6 +27,8 @@ classify_invocation, get_bundled_skill_prompt, get_command_description, + is_custom_skill_local, + is_plugin_installed_locally, is_plugin_skill, ) from config import Settings, settings @@ -421,6 +423,34 @@ def get_skill_usage( if ":" in skill_name else (skill_name if is_plugin else None) ) + remote_count = row.get("remote_count") or 0 + local_count = row.get("local_count") or 0 + raw_remote_ids = row.get("remote_user_ids") or "" + remote_user_ids = ( + [uid for uid in raw_remote_ids.split(",") if uid] + if raw_remote_ids + else [] + ) + category = classify_invocation(skill_name) + # Check if the skill exists locally to avoid tagging + # locally-available skills as "remote-only" when all + # usage happens to come from remote sessions. + # - Plugin skills: check if plugin directory exists + # - Bundled skills/commands: always available locally + # - Custom skills: check if SKILL.md exists on disk + # - User commands: check if .md exists in commands dir + if ":" in skill_name: + exists_locally = is_plugin_installed_locally(skill_name.split(":")[0]) + elif is_plugin: + exists_locally = is_plugin_installed_locally(skill_name) + elif category in ("bundled_skill", "bundled_command"): + exists_locally = True + elif category == "custom_skill": + exists_locally = is_custom_skill_local(skill_name) + elif category == "user_command": + exists_locally = (settings.commands_dir / f"{skill_name}.md").is_file() + else: + exists_locally = False results.append( { "name": skill_name, @@ -429,8 +459,12 @@ def get_skill_usage( "plugin": plugin_name, "last_used": row.get("last_used"), "session_count": row.get("session_count", 0), - "category": classify_invocation(skill_name), + "category": category, "description": get_command_description(skill_name), + "remote_count": remote_count, + "local_count": local_count, + "remote_user_ids": remote_user_ids, + "is_remote_only": local_count == 0 and remote_count > 0 and not exists_locally, } ) return results @@ -535,6 +569,11 @@ def get_skill_usage_trend( item: [UsageTrendItem(date=t["date"], count=t["count"]) for t in points] for item, points in data.get("trend_by_item", {}).items() }, + trend_by_user={ + user: [UsageTrendItem(date=t["date"], count=t["count"]) for t in points] + for user, points in data.get("trend_by_user", {}).items() + }, + user_names=data.get("user_names", {}), first_used=data["first_used"], last_used=data["last_used"], ) @@ -600,7 +639,64 @@ async def get_skill_detail( detail=f"Skill '{skill_name}' not found", ) - # 3. Build sessions list with title enrichment + # 3. Compute remote/local split and optionally fetch remote_definition + remote_count = 0 + local_count = 0 + remote_user_ids: list[str] = [] + is_remote_only = False + remote_definition = None + + if usage_data: + # query_skill_detail does not return these fields directly, so query usage for them + try: + from db.connection import sqlite_read + from db.queries import query_skill_usage + + with sqlite_read() as conn: + if conn is not None: + usage_rows = query_skill_usage(conn, limit=9999) + for urow in usage_rows: + if urow.get("skill_name") == skill_name: + remote_count = urow.get("remote_count") or 0 + local_count = urow.get("local_count") or 0 + raw_ids = urow.get("remote_user_ids") or "" + remote_user_ids = [uid for uid in raw_ids.split(",") if uid] if raw_ids else [] + break + except Exception as e: + logger.warning("Failed to fetch remote/local split for skill %s: %s", skill_name, e) + + # Only mark as remote-only if the skill file doesn't exist locally. + # Without this, locally-installed skills (e.g. superpowers:executing-plans) + # get incorrectly tagged as remote when all usage happens to be from remote sessions. + # Note: `skill_info is None` is used as proxy for "not locally available" — + # _resolve_skill_info succeeds for all locally-present skills (bundled, + # custom, plugin, user commands) and only raises HTTPException (caught + # above) when no local file is found. + is_remote_only = local_count == 0 and remote_count > 0 and skill_info is None + + if is_remote_only: + try: + from db.connection import sqlite_read + + with sqlite_read() as conn: + if conn is not None: + row = conn.execute( + "SELECT content, category, source_user_id, base_directory, description" + " FROM skill_definitions WHERE skill_name = ? AND source_user_id IS NOT NULL LIMIT 1", + (skill_name,), + ).fetchone() + if row: + remote_definition = { + "content": row["content"], + "category": row["category"], + "source_user_id": row["source_user_id"], + "base_directory": row["base_directory"], + "description": row["description"], + } + except Exception as e: + logger.warning("Failed to fetch remote_definition for skill %s: %s", skill_name, e) + + # 4. Build sessions list with title enrichment sessions = [] if usage_data: for row in usage_data["sessions"]: @@ -632,6 +728,10 @@ async def get_skill_detail( tool_source=row.get("tool_source"), subagent_agent_ids=row.get("subagent_agent_ids", []), invocation_sources=row.get("invocation_sources", []), + session_source=row.get("session_source"), + source=row.get("source"), + remote_user_id=row.get("remote_user_id"), + remote_machine_id=row.get("remote_machine_id"), ) ) @@ -641,7 +741,7 @@ async def get_skill_detail( description=skill_info.description if skill_info else None, content=skill_info.content if skill_info else None, is_plugin=skill_info.is_plugin if skill_info else is_plugin_skill(skill_name), - plugin=skill_info.plugin if skill_info else None, + plugin=skill_info.plugin if skill_info else (skill_name.split(":")[0] if ":" in skill_name else None), file_path=skill_info.file_path if skill_info else None, category=classify_invocation(skill_name), calls=usage_data["total_calls"] if usage_data else 0, @@ -661,6 +761,12 @@ async def get_skill_detail( ], sessions=sessions, sessions_total=usage_data["total"] if usage_data else 0, + remote_count=remote_count, + local_count=local_count, + remote_user_ids=remote_user_ids, + is_remote_only=is_remote_only, + remote_definition=remote_definition, + inherited_from=skill_info.inherited_from if skill_info else None, ) @@ -723,6 +829,10 @@ def get_skill_sessions( session_titles=row.get("session_titles", []) or title_cache.get_titles(project_encoded_name, row["uuid"]) or [], + session_source=row.get("session_source"), + source=row.get("source"), + remote_user_id=row.get("remote_user_id"), + remote_machine_id=row.get("remote_machine_id"), ) ) return SkillSessionsResponse( @@ -873,6 +983,35 @@ async def _resolve_skill_info(skill_name: str, config: Settings) -> SkillInfo: skill_file = None + def _find_skill_in_version_dir(version_dir: Path, target_skill: str) -> Path | None: + """Search for a skill file in a plugin version directory. + + Checks default locations (commands/, skills/) and custom paths + from .claude-plugin/plugin.json manifest. + """ + from models.plugin import read_plugin_manifest, _resolve_manifest_dirs + + # Check default locations first + commands_file = version_dir / "commands" / f"{target_skill}.md" + if commands_file.is_file(): + return commands_file + skills_file = version_dir / "skills" / target_skill / "SKILL.md" + if skills_file.is_file(): + return skills_file + + # Check manifest custom paths + manifest = read_plugin_manifest(version_dir) + for skills_dir in _resolve_manifest_dirs(version_dir, manifest, "skills", []): + candidate = skills_dir / target_skill / "SKILL.md" + if candidate.is_file(): + return candidate + for commands_dir in _resolve_manifest_dirs(version_dir, manifest, "commands", []): + candidate = commands_dir / f"{target_skill}.md" + if candidate.is_file(): + return candidate + + return None + if is_plugin: actual_skill_name = skill_name.split(":", 1)[1] if ":" in skill_name else skill_name @@ -898,6 +1037,15 @@ async def _resolve_skill_info(skill_name: str, config: Settings) -> SkillInfo: break if skill_file: break + + # Fallback: check if this plugin skill was inherited locally + # Check both colon-form (legacy) and dash-form (new convention) + if not skill_file: + for candidate_name in (skill_name, skill_name.replace(":", "-")): + inherited_skill = config.claude_base / "skills" / candidate_name / "SKILL.md" + if inherited_skill.is_file(): + skill_file = inherited_skill + break else: # For skills without plugin prefix (e.g., "commit" instead of "commit-commands:commit"), # search in multiple locations: @@ -966,6 +1114,7 @@ async def _resolve_skill_info(skill_name: str, config: Settings) -> SkillInfo: # Parse YAML frontmatter description = None frontmatter_name = skill_name + inherited_from = None if content.startswith("---"): # Split frontmatter from content @@ -977,6 +1126,7 @@ async def _resolve_skill_info(skill_name: str, config: Settings) -> SkillInfo: if isinstance(frontmatter, dict): description = frontmatter.get("description") frontmatter_name = frontmatter.get("name", skill_name) + inherited_from = frontmatter.get("inherited_from") except yaml.YAMLError as e: logger.warning(f"Failed to parse YAML frontmatter for {skill_name}: {e}") @@ -987,6 +1137,7 @@ async def _resolve_skill_info(skill_name: str, config: Settings) -> SkillInfo: is_plugin=is_plugin, plugin=plugin_full_name, file_path=str(skill_file), + inherited_from=inherited_from, ) @@ -999,3 +1150,134 @@ async def get_skill_info( ) -> SkillInfo: """Get detailed information about a skill (cached endpoint wrapper).""" return await _resolve_skill_info(skill_name, config) + + +def _validate_skill_name(skill_name: str) -> None: + """Validate skill_name to prevent path traversal and injection.""" + import re + + if not skill_name or not re.match(r"^[a-zA-Z0-9_\-.:]+$", skill_name): + raise HTTPException(status_code=400, detail="Invalid skill name") + if ".." in skill_name: + raise HTTPException(status_code=400, detail="Path traversal not allowed") + + +@router.post("/skills/{skill_name}/inherit") +async def inherit_skill( + skill_name: str, + scope: Annotated[str, Query(..., pattern="^(user|project)$")], + project_encoded_name: Annotated[Optional[str], Query()] = None, +) -> dict: + """ + Inherit a remote skill by creating the SKILL.md file locally. + + Plugin skill names (with ``:``) are converted to dash-form for the + directory name so Claude Code discovers them as custom skills: + ``oh-my-claudecode:deepsearch`` → ``oh-my-claudecode-deepsearch`` + + scope: "user" -> ~/.claude/skills/{inherited_name}/SKILL.md + scope: "project" -> {project_path}/.claude/skills/{inherited_name}/SKILL.md + """ + _validate_skill_name(skill_name) + + import yaml + + # Convert colon-form to dash-form for filesystem-safe directory name + inherited_name = skill_name.replace(":", "-") + + from db.connection import sqlite_read + + # 1. Get the skill content from skill_definitions + with sqlite_read() as conn: + if conn is None: + raise HTTPException(status_code=503, detail="Database unavailable") + row = conn.execute( + "SELECT content, category, description, source_user_id FROM skill_definitions" + " WHERE skill_name = ? AND source_user_id IS NOT NULL" + " ORDER BY updated_at DESC LIMIT 1", + (skill_name,), + ).fetchone() + + if not row or not row["content"]: + raise HTTPException(status_code=404, detail="No remote skill definition found for this skill") + + content = row["content"] + source_user_id = row["source_user_id"] + description = row["description"] + + # 2. Build frontmatter with provenance tracking + inherit_meta: dict[str, str] = {"inherited_from": skill_name} + if source_user_id: + inherit_meta["source_user_id"] = source_user_id + if description: + inherit_meta["description"] = description + + # Parse existing frontmatter (if any) and merge with inherit metadata + existing_fm: dict = {} + body = content + if content.startswith("---"): + parts = content.split("---", 2) + if len(parts) >= 3: + try: + existing_fm = yaml.safe_load(parts[1]) or {} + except yaml.YAMLError: + existing_fm = {} + body = parts[2].lstrip("\n") + + merged = {**existing_fm, **inherit_meta} + fm_str = yaml.dump(merged, default_flow_style=False, sort_keys=False).strip() + content = f"---\n{fm_str}\n---\n{body}" + + # 3. Determine target path using the dash-form name + if scope == "user": + target_dir = settings.claude_base / "skills" / inherited_name + else: # project + if not project_encoded_name: + raise HTTPException(status_code=400, detail="project_encoded_name required for project scope") + from models.project import Project + + project_path = Project.decode_path(project_encoded_name) + target_dir = Path(project_path) / ".claude" / "skills" / inherited_name + + # 4. Verify resolved path stays under intended base (defense-in-depth) + target_dir = target_dir.resolve() + target_file = target_dir / "SKILL.md" + + # 5. Handle collisions + if target_file.exists(): + # Check if this is an idempotent re-inherit + try: + head = target_file.read_text(encoding="utf-8", errors="ignore")[:512] + if f"inherited_from: {skill_name}" in head: + return { + "status": "already_exists", + "path": str(target_file), + "skill_name": skill_name, + "inherited_name": inherited_name, + "scope": scope, + } + except OSError: + pass + raise HTTPException( + status_code=409, + detail=f"Skill '{inherited_name}' already exists at {target_file}. " + "Delete it first or choose a different name.", + ) + + target_dir.mkdir(parents=True, exist_ok=True) + target_file.write_text(content) + + # Evict classification caches so the new skill is recognized immediately + from command_helpers.plugins import _inherited_skill_cache, _custom_skill_cache + + _inherited_skill_cache.pop(inherited_name, None) + _custom_skill_cache.pop(inherited_name, None) + + logger.info("Inherited remote skill %r as %r to %s", skill_name, inherited_name, target_file) + return { + "status": "created", + "path": str(target_file), + "skill_name": skill_name, + "inherited_name": inherited_name, + "scope": scope, + } diff --git a/api/routers/subagent_sessions.py b/api/routers/subagent_sessions.py index cb8f3e0b..2889fd7c 100644 --- a/api/routers/subagent_sessions.py +++ b/api/routers/subagent_sessions.py @@ -91,19 +91,23 @@ def get_subagent_detail( if isinstance(msg, AssistantMessage) and msg.usage: total_cost += msg.usage.calculate_cost(msg.model) - # Determine subagent type: SQLite fast-path, then JSONL fallback + # Determine subagent type and display name: SQLite fast-path, then JSONL fallback subagent_type = None + display_name = None from db.connection import sqlite_read with sqlite_read() as conn: if conn is not None: row = conn.execute( - "SELECT subagent_type FROM subagent_invocations " + "SELECT subagent_type, agent_display_name FROM subagent_invocations " "WHERE session_uuid = ? AND agent_id = ?", (session_uuid, agent_id), ).fetchone() - if row and row[0]: - subagent_type = row[0] + if row: + if row[0]: + subagent_type = row[0] + if row[1]: + display_name = row[1] if not subagent_type: subagent_type = _determine_subagent_type(parent_session, agent_id) @@ -113,7 +117,7 @@ def get_subagent_detail( slug=agent.slug, is_subagent=True, context=ConversationContext( - project_encoded_name=encoded_name, + project_encoded_name=result.project_encoded_name, parent_session_uuid=session_uuid, parent_session_slug=parent_session.slug, ), @@ -131,7 +135,10 @@ def get_subagent_detail( git_branches=list(agent_data.git_branches), working_directories=list(agent_data.working_directories), subagent_type=subagent_type, + display_name=display_name, initial_prompt=agent_data.initial_prompt, + initial_prompt_images=agent_data.initial_prompt_images, + remote_user_id=result.remote_user_id, ) # Add cache headers diff --git a/api/routers/sync_deps.py b/api/routers/sync_deps.py new file mode 100644 index 00000000..b973228e --- /dev/null +++ b/api/routers/sync_deps.py @@ -0,0 +1,144 @@ +"""Shared dependencies for sync v4 routers. + +Provides connection, config, repo, and service factories used via FastAPI +Depends(). All domain imports are lazy to avoid circular imports and to +survive the deletion of v3 modules in Task 3. +""" +from __future__ import annotations + +import re +import sqlite3 +from pathlib import Path +from typing import Any + +from fastapi import HTTPException + + +# Simple name validation (replaces sync_identity.validate_user_id) +_VALID_NAME = re.compile(r"^[a-zA-Z0-9_-]+$") + + +def validate_name(value: str, label: str = "name") -> None: + """Validate a name is 2-64 chars, alphanumeric + dash/underscore.""" + if not value or not _VALID_NAME.match(value) or len(value) < 2 or len(value) > 64: + raise HTTPException( + 400, f"Invalid {label}: must be 2-64 characters, [a-zA-Z0-9_-]" + ) + + +# --------------------------------------------------------------------------- +# FastAPI dependencies (overridable in tests via app.dependency_overrides) +# --------------------------------------------------------------------------- + + +def get_conn() -> sqlite3.Connection: + """Return the SQLite writer connection.""" + from db.connection import get_writer_db + + conn = get_writer_db() + conn.execute("PRAGMA foreign_keys = ON") + return conn + + +def get_read_conn() -> sqlite3.Connection: + """Read-only connection for sync GET endpoints.""" + from db.connection import create_read_connection + + conn = create_read_connection() + conn.execute("PRAGMA foreign_keys = ON") + return conn + + +async def require_config() -> Any: + """Load SyncConfig from disk. HTTPException 400 if not initialized.""" + from models.sync_config import SyncConfig + + config = SyncConfig.load() + if config is None: + raise HTTPException(400, "Not initialized. Run POST /sync/init first.") + return config + + +async def get_optional_config() -> Any: + """Load SyncConfig, returning None if not initialized (no error).""" + from models.sync_config import SyncConfig + + return SyncConfig.load() + + +# --------------------------------------------------------------------------- +# Factories (called from router endpoints, NOT registered as Depends) +# --------------------------------------------------------------------------- + + +def make_repos() -> dict: + """Instantiate all five v4 repositories (stateless, cheap).""" + from repositories.team_repo import TeamRepository + from repositories.member_repo import MemberRepository + from repositories.project_repo import ProjectRepository + from repositories.subscription_repo import SubscriptionRepository + from repositories.event_repo import EventRepository + + return dict( + teams=TeamRepository(), + members=MemberRepository(), + projects=ProjectRepository(), + subs=SubscriptionRepository(), + events=EventRepository(), + ) + + +def make_managers(config: Any): + """Create (DeviceManager, FolderManager, MetadataService) from config. + + Returns a 3-tuple: (devices, folders, metadata). + """ + from config import settings as app_settings + from services.syncthing.client import SyncthingClient + from services.syncthing.device_manager import DeviceManager + from services.syncthing.folder_manager import FolderManager + from services.sync.metadata_service import MetadataService + + api_key = config.syncthing.api_key if config.syncthing else "" + client = SyncthingClient(api_url="http://localhost:8384", api_key=api_key) + devices = DeviceManager(client) + folders = FolderManager(client, karma_base=app_settings.karma_base) + metadata = MetadataService( + meta_base=app_settings.karma_base / "metadata-folders" + ) + return devices, folders, metadata + + +def make_team_service(config: Any): + """Build TeamService from runtime config.""" + from services.sync.team_service import TeamService + + repos = make_repos() + devices, folders, metadata = make_managers(config) + return TeamService(**repos, devices=devices, metadata=metadata, folders=folders) + + +def make_project_service(config: Any): + """Build ProjectService from runtime config.""" + from services.sync.project_service import ProjectService + + repos = make_repos() + _, folders, metadata = make_managers(config) + return ProjectService(**repos, folders=folders, metadata=metadata) + + +def make_reconciliation_service(config: Any): + """Build ReconciliationService from runtime config.""" + from services.sync.reconciliation_service import ReconciliationService + + repos = make_repos() + devices, folders, metadata = make_managers(config) + device_id = config.syncthing.device_id if config.syncthing else "" + return ReconciliationService( + **repos, + devices=devices, + folders=folders, + metadata=metadata, + my_member_tag=config.member_tag, + my_device_id=device_id, + ) diff --git a/api/routers/sync_members.py b/api/routers/sync_members.py new file mode 100644 index 00000000..5f8f7957 --- /dev/null +++ b/api/routers/sync_members.py @@ -0,0 +1,390 @@ +"""Sync Members router — cross-team member listing and member profiles.""" +from __future__ import annotations + +import asyncio +import logging +import re +import sqlite3 +from typing import Any + +from fastapi import APIRouter, Depends, HTTPException + +from db.queries import ( + query_last_packaged_timestamp, + query_member_daily_sync_stats, + query_member_last_active, + query_member_local_session_count, + query_member_received_count, + query_member_remote_sessions_count, + query_member_sent_count, + query_member_session_count, + query_member_subscription_count, + query_member_total_sessions, + query_resolve_project, +) +from routers.sync_deps import get_optional_config, get_read_conn, make_repos + +logger = logging.getLogger(__name__) + +router = APIRouter(prefix="/sync", tags=["sync-members"]) + +DEVICE_ID_RE = re.compile(r"^[A-Z2-7]{7}(-[A-Z2-7]{7}){7}$") + + +# --------------------------------------------------------------------------- +# Helpers +# --------------------------------------------------------------------------- + +def _get_connections(config: Any) -> dict: + """Fetch Syncthing connections once. Returns {} on any error.""" + if config is None or not getattr(config, "syncthing", None): + return {} + try: + import httpx + api_key = config.syncthing.api_key or "" + resp = httpx.get( + "http://localhost:8384/rest/system/connections", + headers={"X-API-Key": api_key}, + timeout=5.0, + ) + resp.raise_for_status() + return resp.json().get("connections", {}) + except Exception: + return {} + + +def _event_dict(e, idx: int = 0) -> dict: + return { + "id": idx, + "event_type": e.event_type.value, + "team_name": e.team_name, + "member_tag": e.member_tag, + "detail": e.detail, + "created_at": e.created_at.isoformat(), + } + + +# --------------------------------------------------------------------------- +# GET /sync/members — cross-team member list +# --------------------------------------------------------------------------- + +@router.get("/members") +async def list_members( + conn: sqlite3.Connection = Depends(get_read_conn), + config=Depends(get_optional_config), +): + """List all members across all teams, deduplicated by device_id.""" + repos = make_repos() + teams = [t for t in repos["teams"].list_all(conn) if t.status.value != "dissolved"] + + # Aggregate members across teams, dedup by device_id (fallback to member_tag when empty) + my_device_id = ( + config.syncthing.device_id + if config and getattr(config, "syncthing", None) + else None + ) + my_member_tag = config.member_tag if config else None + + members_by_device: dict[str, dict] = {} + for t in teams: + for m in repos["members"].list_for_team(conn, t.name): + # Use device_id as dedup key; fall back to member_tag when device_id is empty + did = m.device_id or "" + dedup_key = did if did else f"tag:{m.member_tag}" + if dedup_key in members_by_device: + entry = members_by_device[dedup_key] + if t.name not in entry["teams"]: + entry["teams"].append(t.name) + # Use the most recent member_tag (latest added_at) + if m.added_at > entry["_added_at"]: + entry["_added_at"] = m.added_at + entry["_member_tag"] = m.member_tag + # Prefer non-empty device_id + if not entry["device_id"] and m.device_id: + entry["device_id"] = m.device_id + # Fallback to config device_id for self + if not entry["device_id"] and m.member_tag == my_member_tag and my_device_id: + entry["device_id"] = my_device_id + else: + members_by_device[dedup_key] = { + "name": m.user_id, + "device_id": m.device_id or my_device_id if m.member_tag == my_member_tag else m.device_id, + "teams": [t.name], + "_added_at": m.added_at, + "_member_tag": m.member_tag, + "_machine_tag": m.machine_tag, + } + + # Fetch connection status once + connections = await asyncio.to_thread(_get_connections, config) + + result = [] + for entry in members_by_device.values(): + tag = entry["_member_tag"] + did = entry["device_id"] + is_you = tag == my_member_tag + connected = is_you or bool(connections.get(did, {}).get("connected", False)) + result.append({ + "name": entry["name"], + "device_id": did or "", + "member_tag": tag, + "machine_tag": entry.get("_machine_tag", ""), + "connected": connected, + "is_you": is_you, + "team_count": len(entry["teams"]), + "teams": entry["teams"], + "added_at": entry["_added_at"].isoformat(), + }) + + result.sort(key=lambda x: (not x["is_you"], x["name"].lower())) + return {"members": result, "total": len(result)} + + +# --------------------------------------------------------------------------- +# GET /sync/members/{identifier} — full member profile +# --------------------------------------------------------------------------- + +@router.get("/members/{identifier}") +async def get_member_profile( + identifier: str, + conn: sqlite3.Connection = Depends(get_read_conn), + config=Depends(get_optional_config), +): + """Full member profile. Accepts member_tag or device_id (auto-detected).""" + if not identifier or not identifier.strip(): + raise HTTPException(400, "identifier must not be empty") + repos = make_repos() + + # Detect format: Syncthing device_id vs member_tag + if DEVICE_ID_RE.match(identifier): + memberships = repos["members"].get_by_device(conn, identifier) + else: + memberships = repos["members"].get_all_by_member_tag(conn, identifier) + + # Fallback for self: config device_id or member_tag + if not memberships and config: + my_did = ( + config.syncthing.device_id + if getattr(config, "syncthing", None) + else None + ) + if config.member_tag: + if identifier == my_did or identifier == config.member_tag: + teams = repos["teams"].list_all(conn) + for t in teams: + m = repos["members"].get(conn, t.name, config.member_tag) + if m: + memberships.append(m) + + if not memberships: + raise HTTPException(404, f"Member '{identifier}' not found") + + member_tag = memberships[0].member_tag + user_id = memberships[0].user_id + device_id = memberships[0].device_id or "" + + # Syncthing connection info (single HTTP call) + my_device_id = ( + config.syncthing.device_id + if config and getattr(config, "syncthing", None) + else None + ) + my_member_tag = config.member_tag if config else None + connections = await asyncio.to_thread(_get_connections, config) + conn_entry = connections.get(device_id, {}) if device_id else {} + is_you = member_tag == my_member_tag if my_member_tag else False + connected = is_you or bool(conn_entry.get("connected", False)) + in_bytes = conn_entry.get("inBytesTotal", 0) + out_bytes = conn_entry.get("outBytesTotal", 0) + + # Build teams list with projects and online counts + teams_data = [] + all_project_encoded = set() + for m in memberships: + team_members = repos["members"].list_for_team(conn, m.team_name) + team_projects = repos["projects"].list_for_team(conn, m.team_name) + + # Count online members using already-fetched connections + online_count = 0 + for tm in team_members: + if tm.member_tag == my_member_tag: + online_count += 1 # self is always online + elif tm.device_id and connections.get(tm.device_id, {}).get("connected", False): + online_count += 1 + + # Build project list with session counts + proj_list = [] + for p in team_projects: + if p.status.value != "shared": + continue + enc, display = query_resolve_project(conn, p.git_identity) + display = display or p.git_identity + sess_count = 0 + if enc: + all_project_encoded.add(enc) + sess_count = query_member_session_count(conn, enc) + proj_list.append({ + "encoded_name": enc or p.git_identity, + "name": display, + "session_count": sess_count, + }) + + teams_data.append({ + "name": m.team_name, + "member_count": len(team_members), + "project_count": len([p for p in team_projects if p.status.value == "shared"]), + "online_count": online_count, + "projects": proj_list, + }) + + # Stats: sessions sent/received, total projects, last active + sent_count = 0 + received_count = 0 + total_sessions = 0 + + sent_count = query_member_sent_count(conn, member_tag) + + # Fallback: if no packaged events logged yet, count outbox files on disk + if sent_count == 0 and is_you: + from config import settings as app_settings + # Count across ALL outbox folders matching this member's tag pattern, + # regardless of folder naming convention (handles legacy folder names) + outbox_prefix = f"karma-out--{member_tag}--" + seen_files: set[str] = set() + if app_settings.karma_base.is_dir(): + for folder in app_settings.karma_base.iterdir(): + if not folder.is_dir() or not folder.name.startswith(outbox_prefix): + continue + sessions_dir = folder / "sessions" + if sessions_dir.is_dir(): + for f in sessions_dir.glob("*.jsonl"): + if f.name not in seen_files: + seen_files.add(f.name) + sent_count += 1 + + received_count = query_member_received_count(conn, member_tag) + + # Fallback: if no received events but we have remote sessions in DB + if received_count == 0 and not is_you: + if all_project_encoded: + received_count = query_member_remote_sessions_count( + conn, member_tag, list(all_project_encoded) + ) + + if all_project_encoded: + total_sessions = query_member_total_sessions( + conn, list(all_project_encoded) + ) + + # Total distinct projects across subscriptions + total_projects = query_member_subscription_count(conn, member_tag) + + last_active = query_member_last_active(conn, member_tag) + + stats = { + "total_sessions": total_sessions, + "sessions_sent": sent_count, + "sessions_received": received_count, + "total_projects": total_projects, + "last_active": last_active, + } + + # Session stats: daily sent/received aggregation + session_stats_rows = query_member_daily_sync_stats(conn, member_tag) + + daily: dict[str, dict] = {} + for date_str, etype, cnt in session_stats_rows: + if date_str not in daily: + daily[date_str] = {"date": date_str, "member_name": user_id, "out": 0, "packaged": 0, "received": 0} + if etype == "session_packaged": + daily[date_str]["packaged"] = cnt + daily[date_str]["out"] = cnt + elif etype == "session_received": + daily[date_str]["received"] = cnt + + session_stats = list(daily.values()) + + # Incoming stats: daily received + incoming_stats = [ + {"date": d["date"], "incoming": d["received"]} + for d in daily.values() + if d["received"] > 0 + ] + + # --- New fields: sync health --- + from routers.sync_teams import _get_active_counts, _count_packaged + + unsynced_count = None + last_packaged_at = None + project_sync = None + sync_direction_val = None + + if is_you: + active_counts = _get_active_counts() + project_sync_list = [] + total_gap = 0 + for m_item in memberships: + team_projects = repos["projects"].list_for_team(conn, m_item.team_name) + for p in team_projects: + if p.status.value != "shared": + continue + enc, display = query_resolve_project(conn, p.git_identity) + local_count = 0 + if enc: + local_count = query_member_local_session_count(conn, enc) + packaged_count = _count_packaged(member_tag, p.folder_suffix) + active_count = active_counts.get(enc, 0) if enc else 0 + gap = max(0, local_count - packaged_count - active_count) + total_gap += gap + project_sync_list.append({ + "team_name": m_item.team_name, + "git_identity": p.git_identity, + "encoded_name": enc, + "name": display or p.git_identity, + "local_count": local_count, + "packaged_count": packaged_count, + "active_count": active_count, + "gap": gap, + }) + unsynced_count = total_gap + project_sync = project_sync_list + + last_packaged_at = query_last_packaged_timestamp(conn) + + # sync_direction: aggregate from accepted subscriptions + subs = repos["subs"].list_for_member(conn, member_tag) + accepted_dirs = {s.direction.value for s in subs if s.status.value == "accepted"} + if len(accepted_dirs) == 0: + sync_direction_val = None + elif len(accepted_dirs) == 1: + sync_direction_val = next(iter(accepted_dirs)) + else: + sync_direction_val = "mixed" + + # Activity feed + events = repos["events"].query(conn, member_tag=member_tag, limit=50) + activity = [_event_dict(e, idx=i) for i, e in enumerate(events)] + + return { + "user_id": user_id, + "device_id": device_id, + "member_tag": member_tag, + "machine_tag": memberships[0].machine_tag, + "connected": connected, + "is_you": is_you, + "in_bytes_total": in_bytes, + "out_bytes_total": out_bytes, + "teams": teams_data, + "stats": stats, + "session_stats": session_stats, + "incoming_stats": incoming_stats, + "activity": activity, + "unsynced_count": unsynced_count, + "last_packaged_at": last_packaged_at, + "sync_direction": sync_direction_val, + "project_sync": project_sync, + } + + + +# _resolve_project has been moved to db.queries.query_resolve_project diff --git a/api/routers/sync_pairing.py b/api/routers/sync_pairing.py new file mode 100644 index 00000000..6efe8d1a --- /dev/null +++ b/api/routers/sync_pairing.py @@ -0,0 +1,77 @@ +"""Sync Pairing + Devices router — pairing codes and device status.""" +from __future__ import annotations + +import logging + +from fastapi import APIRouter, Depends, HTTPException +from pydantic import BaseModel + +from routers.sync_deps import make_managers, require_config + +logger = logging.getLogger(__name__) + +router = APIRouter(prefix="/sync", tags=["sync-pairing"]) + + +# --- Schemas --------------------------------------------------------------- + +class ValidateCodeRequest(BaseModel): + code: str + + +# --- Dependencies ---------------------------------------------------------- + +def get_pairing_svc(): + from services.sync.pairing_service import PairingService + + return PairingService() + + +async def get_device_mgr(config=Depends(require_config)): + devices, _, _ = make_managers(config) + return devices + + +# --- Endpoints ------------------------------------------------------------- + +@router.get("/pairing/code") +async def generate_pairing_code( + config=Depends(require_config), + pairing=Depends(get_pairing_svc), +): + """Generate a permanent pairing code for this device.""" + device_id = config.syncthing.device_id if config.syncthing else "" + if not device_id: + raise HTTPException(400, "No Syncthing device ID configured") + code = pairing.generate_code(config.member_tag, device_id) + return {"code": code, "member_tag": config.member_tag} + + +@router.post("/pairing/validate") +async def validate_pairing_code( + req: ValidateCodeRequest, + pairing=Depends(get_pairing_svc), +): + """Validate and decode a pairing code (preview, does not add member).""" + try: + info = pairing.validate_code(req.code) + except ValueError as e: + raise HTTPException(400, str(e)) + return {"member_tag": info.member_tag, "device_id": info.device_id} + + +@router.get("/devices") +async def list_devices( + config=Depends(require_config), + devices=Depends(get_device_mgr), +): + """List connected Syncthing devices.""" + try: + connected = await devices.list_connected() + except Exception: + connected = [] + device_id = config.syncthing.device_id if config.syncthing else "" + return { + "my_device_id": device_id, + "connected_devices": connected, + } diff --git a/api/routers/sync_pending.py b/api/routers/sync_pending.py new file mode 100644 index 00000000..4d34d39b --- /dev/null +++ b/api/routers/sync_pending.py @@ -0,0 +1,241 @@ +"""Sync Pending Devices + Folders router — v4, Syncthing cluster pending API.""" +from __future__ import annotations + +import logging +import re +from typing import Optional + +from fastapi import APIRouter, Depends, HTTPException +from pydantic import BaseModel + +from routers.sync_deps import make_managers, require_config + +logger = logging.getLogger(__name__) + +router = APIRouter(prefix="/sync", tags=["sync-pending"]) + + +# --- Request schemas ------------------------------------------------------- + +class AcceptDeviceRequest(BaseModel): + name: Optional[str] = None + + +class RejectFolderRequest(BaseModel): + device_id: str + + +# --- Dependencies ---------------------------------------------------------- + +async def get_syncthing_client(config=Depends(require_config)): + """Build a raw SyncthingClient from config.""" + from services.syncthing.client import SyncthingClient + + api_key = config.syncthing.api_key if config.syncthing else "" + return SyncthingClient(api_url="http://localhost:8384", api_key=api_key) + + +async def get_folder_mgr(config=Depends(require_config)): + """Return the FolderManager from make_managers.""" + _, folders, _ = make_managers(config) + return folders + + +# --- Pending devices ------------------------------------------------------- + +@router.get("/pending-devices") +async def list_pending_devices(client=Depends(get_syncthing_client)): + """List devices requesting to connect (Syncthing pending devices).""" + try: + raw = await client.get_pending_devices() + except Exception as e: + logger.warning("Failed to fetch pending devices: %s", e) + return {"devices": []} + + devices = [] + for device_id, info in raw.items(): + devices.append({ + "device_id": device_id, + "name": info.get("name", ""), + "address": info.get("address", ""), + "time": info.get("time", ""), + }) + return {"devices": devices} + + +@router.post("/pending-devices/{device_id}/accept") +async def accept_pending_device( + device_id: str, + req: AcceptDeviceRequest, + client=Depends(get_syncthing_client), + config=Depends(require_config), +): + """Accept a pending device and auto-accept any karma-meta--* folders from it.""" + device_config = { + "deviceID": device_id, + "name": req.name or "", + "addresses": ["dynamic"], + "autoAcceptFolders": False, + } + try: + await client.put_config_device(device_config) + except Exception as e: + raise HTTPException(500, f"Failed to accept device: {e}") + + # Auto-accept karma-meta--* folders offered by the same device + discovered_teams: list[str] = [] + try: + from config import settings as app_settings + karma_base = app_settings.karma_base + raw = await client.get_pending_folders() + + _meta_re = re.compile(r"^karma-meta--(.+)$") + + for folder_id, folder_data in raw.items(): + m = _meta_re.match(folder_id) + if not m: + continue + # Syncthing nests under "offeredBy": {device_id: {...}} + offered_by = folder_data.get("offeredBy", folder_data) + # Check if this folder is offered by the device we just accepted + if device_id not in offered_by: + continue + + team_name = m.group(1) + + try: + from services.syncthing.folder_manager import build_folder_config + + devices = [{"deviceID": device_id, "encryptionPassword": ""}] + local_id = config.syncthing.device_id if config.syncthing else None + if local_id: + devices.append({"deviceID": local_id, "encryptionPassword": ""}) + + folder_config = build_folder_config( + karma_base, folder_id, "sendreceive", devices, + ) + await client.put_config_folder(folder_config) + await client.dismiss_pending_folder(folder_id, device_id) + discovered_teams.append(team_name) + except Exception as folder_exc: + logger.warning( + "Failed to auto-accept metadata folder %s: %s", + folder_id, + folder_exc, + ) + except Exception as e: + logger.warning("Failed to auto-accept metadata folders: %s", e) + + return {"ok": True, "device_id": device_id, "teams": discovered_teams} + + +@router.delete("/pending-devices/{device_id}") +async def dismiss_pending_device( + device_id: str, + client=Depends(get_syncthing_client), +): + """Dismiss/reject a pending device.""" + try: + await client.dismiss_pending_device(device_id) + except Exception as e: + raise HTTPException(500, f"Failed to dismiss device: {e}") + return {"ok": True, "device_id": device_id} + + +# --- Pending folders ------------------------------------------------------- + +# Pattern: karma-out--{member_tag}--{suffix} +_KARMA_FOLDER_RE = re.compile(r"^karma-(out|meta)--(.+?)(?:--(.+))?$") + + +def _parse_folder_id(folder_id: str) -> dict: + """Extract folder_type, member_tag, suffix from a karma folder ID.""" + m = _KARMA_FOLDER_RE.match(folder_id) + if m: + return { + "folder_type": m.group(1), + "from_member": m.group(2), + "suffix": m.group(3), + } + return {"folder_type": "unknown", "from_member": None, "suffix": None} + + +@router.get("/pending") +async def list_pending_folders(client=Depends(get_syncthing_client)): + """List folders offered by peers (Syncthing pending folders).""" + try: + raw = await client.get_pending_folders() + except Exception as e: + logger.warning("Failed to fetch pending folders: %s", e) + return {"folders": []} + + folders = [] + for folder_id, folder_data in raw.items(): + parsed = _parse_folder_id(folder_id) + # Syncthing nests under "offeredBy": {device_id: {time, label, ...}} + device_map = folder_data.get("offeredBy", folder_data) + for dev_id, info in device_map.items(): + folders.append({ + "folder_id": folder_id, + "label": info.get("label", folder_id), + "from_device": dev_id, + "from_member": parsed["from_member"], + "offered_at": info.get("time", ""), + "folder_type": parsed["folder_type"], + }) + return {"folders": folders} + + +@router.post("/pending/accept/{folder_id:path}") +async def accept_pending_folder( + folder_id: str, + config=Depends(require_config), + client=Depends(get_syncthing_client), + folder_mgr=Depends(get_folder_mgr), +): + """Accept a pending folder by creating it in Syncthing config.""" + # Determine which device offered the folder + try: + raw = await client.get_pending_folders() + except Exception as e: + raise HTTPException(500, f"Failed to fetch pending folders: {e}") + + folder_data = raw.get(folder_id) + if not folder_data: + raise HTTPException(404, f"Pending folder '{folder_id}' not found") + + # Syncthing nests under "offeredBy": {device_id: {...}} + offered_by = folder_data.get("offeredBy", folder_data) + device_ids = list(offered_by.keys()) + if not device_ids: + raise HTTPException(404, f"No offering device found for folder '{folder_id}'") + + # Parse folder_id to determine type and create appropriate config + parsed = _parse_folder_id(folder_id) + devices = [{"deviceID": did, "encryptionPassword": ""} for did in device_ids] + + from config import settings as app_settings + from services.syncthing.folder_manager import build_folder_config, resolve_folder_type + + folder_config = build_folder_config( + app_settings.karma_base, folder_id, resolve_folder_type(folder_id), devices, + ) + try: + await client.put_config_folder(folder_config) + except Exception as e: + raise HTTPException(500, f"Failed to accept folder: {e}") + return {"ok": True, "folder_id": folder_id} + + +@router.post("/pending/reject/{folder_id:path}") +async def reject_pending_folder( + folder_id: str, + req: RejectFolderRequest, + client=Depends(get_syncthing_client), +): + """Reject/dismiss a pending folder.""" + try: + await client.dismiss_pending_folder(folder_id, req.device_id) + except Exception as e: + raise HTTPException(500, f"Failed to reject folder: {e}") + return {"ok": True, "folder_id": folder_id} diff --git a/api/routers/sync_projects.py b/api/routers/sync_projects.py new file mode 100644 index 00000000..b52d8d8e --- /dev/null +++ b/api/routers/sync_projects.py @@ -0,0 +1,298 @@ +"""Sync Projects + Subscriptions router — v4, delegates to ProjectService.""" +from __future__ import annotations + +import logging +import sqlite3 +from typing import Optional + +from fastapi import APIRouter, Depends, HTTPException +from pydantic import BaseModel + +from domain.subscription import SyncDirection +from domain.team import AuthorizationError, InvalidTransitionError +from domain.project import SharedProjectStatus +from routers.sync_deps import ( + get_conn, + get_read_conn, + make_project_service, + make_repos, + require_config, +) + +logger = logging.getLogger(__name__) + +router = APIRouter(prefix="/sync", tags=["sync-projects"]) + + +# --- Request schemas ------------------------------------------------------- + +class ShareProjectRequest(BaseModel): + git_identity: str + encoded_name: Optional[str] = None + + +class AcceptRequest(BaseModel): + direction: str = "both" + + +class DirectionRequest(BaseModel): + direction: str + + +# --- Dependencies ---------------------------------------------------------- + +async def get_project_svc(config=Depends(require_config)): + return make_project_service(config) + + +# --- Project endpoints ----------------------------------------------------- + +@router.post("/teams/{name}/projects", status_code=201) +async def share_project( + name: str, + req: ShareProjectRequest, + conn: sqlite3.Connection = Depends(get_conn), + config=Depends(require_config), + svc=Depends(get_project_svc), +): + """Share a project with the team. Leader only.""" + device_id = config.syncthing.device_id if config.syncthing else "" + + # Auto-resolve encoded_name from git_identity if not provided. + encoded_name = req.encoded_name + if not encoded_name: + from db.queries import resolve_encoded_name + encoded_name = resolve_encoded_name(conn, req.git_identity) + + try: + project = await svc.share_project( + conn, + team_name=name, + by_device=device_id, + git_identity=req.git_identity, + encoded_name=encoded_name, + ) + except AuthorizationError: + raise HTTPException(403, "Only the team leader can share projects") + except ValueError as e: + raise HTTPException(400, str(e)) + return _project_dict(project) + + +@router.delete("/teams/{name}/projects/{git_identity:path}") +async def remove_project( + name: str, + git_identity: str, + conn: sqlite3.Connection = Depends(get_conn), + config=Depends(require_config), + svc=Depends(get_project_svc), +): + """Remove a project from the team. Leader only.""" + device_id = config.syncthing.device_id if config.syncthing else "" + try: + project = await svc.remove_project( + conn, team_name=name, by_device=device_id, git_identity=git_identity, + ) + except AuthorizationError: + raise HTTPException(403, "Only the team leader can remove projects") + except InvalidTransitionError as e: + raise HTTPException(409, str(e)) + except ValueError as e: + raise HTTPException(404, str(e)) + return {"ok": True, **_project_dict(project)} + + +@router.get("/teams/{name}/projects") +async def list_projects(name: str, conn: sqlite3.Connection = Depends(get_read_conn)): + """List projects shared in the team.""" + repos = make_repos() + team = repos["teams"].get(conn, name) + if team is None: + raise HTTPException(404, f"Team '{name}' not found") + projects = repos["projects"].list_for_team(conn, name) + return {"projects": [_project_dict(p) for p in projects]} + + +# --- Subscription endpoints ------------------------------------------------ + +@router.post("/subscriptions/{team}/{git_identity:path}/accept") +async def accept_subscription( + team: str, + git_identity: str, + req: AcceptRequest, + conn: sqlite3.Connection = Depends(get_conn), + config=Depends(require_config), + svc=Depends(get_project_svc), +): + """Accept a subscription with the given sync direction.""" + direction = _parse_direction(req.direction) + try: + sub = await svc.accept_subscription( + conn, + member_tag=config.member_tag, + team_name=team, + git_identity=git_identity, + direction=direction, + ) + except InvalidTransitionError as e: + raise HTTPException(409, str(e)) + except ValueError as e: + raise HTTPException(404, str(e)) + return _sub_dict(sub) + + +@router.post("/subscriptions/{team}/{git_identity:path}/pause") +async def pause_subscription( + team: str, + git_identity: str, + conn: sqlite3.Connection = Depends(get_conn), + config=Depends(require_config), + svc=Depends(get_project_svc), +): + """Pause an accepted subscription.""" + try: + sub = await svc.pause_subscription( + conn, + member_tag=config.member_tag, + team_name=team, + git_identity=git_identity, + ) + except InvalidTransitionError as e: + raise HTTPException(409, str(e)) + except ValueError as e: + raise HTTPException(404, str(e)) + return _sub_dict(sub) + + +@router.post("/subscriptions/{team}/{git_identity:path}/resume") +async def resume_subscription( + team: str, + git_identity: str, + conn: sqlite3.Connection = Depends(get_conn), + config=Depends(require_config), + svc=Depends(get_project_svc), +): + """Resume a paused subscription.""" + try: + sub = await svc.resume_subscription( + conn, + member_tag=config.member_tag, + team_name=team, + git_identity=git_identity, + ) + except InvalidTransitionError as e: + raise HTTPException(409, str(e)) + except ValueError as e: + raise HTTPException(404, str(e)) + return _sub_dict(sub) + + +@router.post("/subscriptions/{team}/{git_identity:path}/decline") +async def decline_subscription( + team: str, + git_identity: str, + conn: sqlite3.Connection = Depends(get_conn), + config=Depends(require_config), + svc=Depends(get_project_svc), +): + """Decline a subscription.""" + try: + sub = await svc.decline_subscription( + conn, + member_tag=config.member_tag, + team_name=team, + git_identity=git_identity, + ) + except InvalidTransitionError as e: + raise HTTPException(409, str(e)) + except ValueError as e: + raise HTTPException(404, str(e)) + return _sub_dict(sub) + + +@router.post("/subscriptions/{team}/{git_identity:path}/reopen") +async def reopen_subscription( + team: str, + git_identity: str, + conn: sqlite3.Connection = Depends(get_conn), + config=Depends(require_config), + svc=Depends(get_project_svc), +): + """Reopen a declined subscription, returning it to OFFERED status.""" + try: + sub = await svc.reopen_subscription( + conn, + member_tag=config.member_tag, + team_name=team, + git_identity=git_identity, + ) + except InvalidTransitionError as e: + raise HTTPException(409, str(e)) + except ValueError as e: + raise HTTPException(404, str(e)) + return _sub_dict(sub) + + +@router.patch("/subscriptions/{team}/{git_identity:path}/direction") +async def change_direction( + team: str, + git_identity: str, + req: DirectionRequest, + conn: sqlite3.Connection = Depends(get_conn), + config=Depends(require_config), + svc=Depends(get_project_svc), +): + """Change sync direction of an accepted subscription.""" + direction = _parse_direction(req.direction) + try: + sub = await svc.change_direction( + conn, + member_tag=config.member_tag, + team_name=team, + git_identity=git_identity, + direction=direction, + ) + except InvalidTransitionError as e: + raise HTTPException(409, str(e)) + except ValueError as e: + raise HTTPException(404, str(e)) + return _sub_dict(sub) + + +@router.get("/subscriptions") +async def list_subscriptions( + conn: sqlite3.Connection = Depends(get_read_conn), + config=Depends(require_config), +): + """List all subscriptions for the current member.""" + repos = make_repos() + subs = repos["subs"].list_for_member(conn, config.member_tag) + return {"subscriptions": [_sub_dict(s) for s in subs]} + + +# --- Helpers --------------------------------------------------------------- + +def _parse_direction(value: str) -> SyncDirection: + try: + return SyncDirection(value) + except ValueError: + raise HTTPException(400, f"Invalid direction '{value}'. Use: send, receive, both") + + +def _project_dict(p) -> dict: + return { + "git_identity": p.git_identity, + "folder_suffix": p.folder_suffix, + "encoded_name": p.encoded_name, + "status": p.status.value, + } + + +def _sub_dict(s) -> dict: + return { + "member_tag": s.member_tag, + "team_name": s.team_name, + "project_git_identity": s.project_git_identity, + "status": s.status.value, + "direction": s.direction.value, + } diff --git a/api/routers/sync_system.py b/api/routers/sync_system.py new file mode 100644 index 00000000..afc8516a --- /dev/null +++ b/api/routers/sync_system.py @@ -0,0 +1,358 @@ +"""Sync system endpoints — status, initialization, reconciliation, reset.""" +from __future__ import annotations + +import logging +import shutil +import sqlite3 +import subprocess +from typing import Any, Optional + +from fastapi import APIRouter, Depends, HTTPException +from pydantic import BaseModel + +from routers.sync_deps import ( + get_conn, + get_optional_config, + get_read_conn, + make_reconciliation_service, + make_repos, + require_config, + validate_name, +) + +logger = logging.getLogger(__name__) + +router = APIRouter(prefix="/sync", tags=["sync-system"]) + + +# --- Request schemas ------------------------------------------------------- + +class InitRequest(BaseModel): + user_id: str + backend: str = "syncthing" + + +class ResetOptions(BaseModel): + uninstall_syncthing: bool = False + + +# --- Dependencies ---------------------------------------------------------- + +async def get_recon_svc(config=Depends(require_config)): + return make_reconciliation_service(config) + + +# --- Endpoints ------------------------------------------------------------- + +@router.get("/status") +async def sync_status( + conn: sqlite3.Connection = Depends(get_read_conn), + config=Depends(get_optional_config), +): + """Sync configuration and team summary.""" + if config is None: + return {"configured": False} + + repos = make_repos() + teams = repos["teams"].list_all(conn) + + return { + "configured": True, + "user_id": config.user_id, + "machine_id": config.machine_id, + "machine_tag": config.machine_tag, + "member_tag": config.member_tag, + "device_id": config.syncthing.device_id if config.syncthing else None, + "teams": [ + { + "name": t.name, + "status": t.status.value, + "leader_member_tag": t.leader_member_tag, + "member_count": len(repos["members"].list_for_team(conn, t.name)), + } + for t in teams + ], + } + + +@router.post("/init") +async def sync_init(req: InitRequest): + """Initialize Karma sync — detects Syncthing and saves config.""" + validate_name(req.user_id, "user_id") + if req.backend != "syncthing": + raise HTTPException(400, "Only 'syncthing' backend is supported") + + from models.sync_config import SyncConfig, SyncthingSettings + from services.syncthing.key_reader import read_local_api_key + from services.syncthing.client import SyncthingClient + + api_key = read_local_api_key() + if not api_key: + raise HTTPException( + 503, "Cannot read Syncthing API key. Is Syncthing installed?" + ) + + client = SyncthingClient(api_url="http://localhost:8384", api_key=api_key) + try: + status = await client.get_system_status() + except Exception: + raise HTTPException(503, "Syncthing is not running or unreachable") + + device_id = status.get("myID") + syncthing_settings = SyncthingSettings(api_key=api_key, device_id=device_id) + config = SyncConfig(user_id=req.user_id, syncthing=syncthing_settings) + config.save() + + return { + "ok": True, + "user_id": config.user_id, + "machine_id": config.machine_id, + "member_tag": config.member_tag, + "device_id": device_id, + } + + +@router.post("/package") +async def trigger_package( + team_name: Optional[str] = None, + git_identity: Optional[str] = None, + conn: sqlite3.Connection = Depends(get_conn), + config=Depends(require_config), +): + """Trigger on-demand session packaging. + + Scope: + - No params: all projects across all teams + - team_name: all projects in that team + - team_name + git_identity: single project + """ + from services.sync.packaging_service import PackagingService + + svc = PackagingService( + member_tag=config.member_tag, + user_id=config.user_id, + machine_id=config.machine_id, + device_id=config.syncthing.device_id if config.syncthing else "", + ) + + projects = svc.resolve_packagable_projects( + conn, team_name=team_name, git_identity=git_identity, + ) + + results = [] + for proj in projects: + result = svc.package_project( + conn, + team_name=proj["team_name"], + git_identity=proj["git_identity"], + encoded_name=proj["encoded_name"], + folder_suffix=proj["folder_suffix"], + ) + entry = { + "team_name": result.team_name, + "git_identity": result.git_identity, + "sessions_packaged": result.sessions_packaged, + } + if result.error: + entry["error"] = result.error + results.append(entry) + + return {"ok": True, "packaged": results} + + +@router.post("/reconcile") +async def trigger_reconciliation( + conn: sqlite3.Connection = Depends(get_conn), + svc=Depends(get_recon_svc), +): + """Trigger a manual 3-phase reconciliation cycle.""" + try: + await svc.run_cycle(conn) + except Exception as e: + logger.warning("Manual reconciliation failed: %s", e) + raise HTTPException(500, f"Reconciliation failed: {e}") + return {"ok": True} + + +@router.get("/detect") +async def sync_detect(): + """Detect whether Syncthing is installed and running.""" + import shutil + + syncthing_installed = shutil.which("syncthing") is not None + + try: + from services.syncthing.key_reader import read_local_api_key + from services.syncthing.client import SyncthingClient + + api_key = read_local_api_key() + if not api_key: + return { + "syncthing_installed": syncthing_installed, + "syncthing_running": False, + "api_key_found": False, + "device_id": None, + "running": False, + "version": None, + } + + client = SyncthingClient(api_url="http://localhost:8384", api_key=api_key) + status = await client.get_system_status() + return { + "syncthing_installed": syncthing_installed, + "syncthing_running": True, + "api_key_found": True, + "device_id": status.get("myID"), + "running": True, + "version": status.get("version"), + } + except Exception: + return { + "syncthing_installed": syncthing_installed, + "syncthing_running": False, + "api_key_found": False, + "device_id": None, + "running": False, + "version": None, + } + + +@router.post("/reset") +async def sync_reset(options: Optional[ResetOptions] = None): + """Full sync teardown — clean Syncthing, delete files, clear DB.""" + from models.sync_config import SYNC_CONFIG_PATH, KARMA_BASE + + if options is None: + options = ResetOptions() + + steps: dict[str, Any] = {} + + # 1. Clean Syncthing config (best-effort) + try: + from services.syncthing.key_reader import read_local_api_key + from services.syncthing.client import SyncthingClient + + api_key = read_local_api_key() + if api_key: + client = SyncthingClient( + api_url="http://localhost:8384", api_key=api_key + ) + # Remove all karma-* folders + try: + folders = await client.get_config_folders() + removed = [] + for f in folders: + if f.get("id", "").startswith("karma-"): + await client.delete_config_folder(f["id"]) + removed.append(f["id"]) + steps["folders_removed"] = removed + except Exception as e: + steps["folders_removed"] = f"error: {e}" + + # Remove all non-self devices + try: + sys_status = await client.get_system_status() + my_id = sys_status.get("myID", "") + devices = await client.get_config_devices() + removed_devs = [] + for d in devices: + if d.get("deviceID") != my_id: + await client.delete_config_device(d["deviceID"]) + removed_devs.append(d["deviceID"]) + steps["devices_removed"] = removed_devs + except Exception as e: + steps["devices_removed"] = f"error: {e}" + except Exception: + steps["syncthing_cleanup"] = "skipped" + + # 2. Delete filesystem dirs (named subdirectories) + for dir_name in ["remote-sessions", "handshakes", "metadata-folders", "quarantine"]: + d = KARMA_BASE / dir_name + if d.exists(): + shutil.rmtree(d, ignore_errors=True) + steps[f"{dir_name.replace('-', '_')}_deleted"] = True + + # 2b. Delete karma-out--* outbox/inbox directories (live flat under KARMA_BASE) + outbox_removed = [] + if KARMA_BASE.exists(): + for entry in KARMA_BASE.iterdir(): + if entry.is_dir() and entry.name.startswith("karma-out--"): + shutil.rmtree(entry, ignore_errors=True) + outbox_removed.append(entry.name) + if outbox_removed: + steps["outbox_dirs_removed"] = outbox_removed + + # 3. Delete sync config + if SYNC_CONFIG_PATH.exists(): + SYNC_CONFIG_PATH.unlink() + steps["config_deleted"] = True + + # 4. Clear v4 sync tables + related sync data + from db.connection import get_writer_db + + conn = get_writer_db() + tables_cleared = [] + for table in [ + "sync_subscriptions", + "sync_projects", + "sync_removed_members", + "sync_events", + "sync_members", + "sync_teams", + "skill_definitions", + ]: + try: + conn.execute(f"DELETE FROM {table}") # noqa: S608 + tables_cleared.append(table) + except sqlite3.OperationalError: + pass + + # 4b. Remove remote session rows from sessions table + remote_deleted = 0 + try: + cur = conn.execute("DELETE FROM sessions WHERE source = 'remote'") + remote_deleted = cur.rowcount + except sqlite3.OperationalError: + pass + conn.commit() + steps["tables_cleared"] = tables_cleared + if remote_deleted: + steps["remote_sessions_deleted"] = remote_deleted + + # 5. Stop Syncthing service (best-effort) + try: + subprocess.run( + ["brew", "services", "stop", "syncthing"], + capture_output=True, + timeout=15, + ) + steps["service_stopped"] = True + except Exception: + steps["service_stopped"] = False + + # 6. Optionally uninstall Syncthing + if options.uninstall_syncthing: + try: + r = subprocess.run( + ["brew", "uninstall", "syncthing"], + capture_output=True, + text=True, + timeout=30, + ) + steps["brew_uninstalled"] = r.returncode == 0 + except Exception: + steps["brew_uninstalled"] = False + + # 6b. Clean Syncthing's own data directory (certs, config, index DB) + from pathlib import Path + import platform + + if platform.system() == "Darwin": + st_data = Path.home() / "Library" / "Application Support" / "Syncthing" + else: + st_data = Path.home() / ".local" / "share" / "syncthing" + if st_data.exists(): + shutil.rmtree(st_data, ignore_errors=True) + steps["syncthing_data_cleaned"] = True + + return {"ok": True, "steps": steps} diff --git a/api/routers/sync_teams.py b/api/routers/sync_teams.py new file mode 100644 index 00000000..1bb4172f --- /dev/null +++ b/api/routers/sync_teams.py @@ -0,0 +1,678 @@ +"""Sync Teams + Members router — v4, thin delegation to TeamService.""" +from __future__ import annotations + +import logging +import sqlite3 +from datetime import datetime, timezone +from pathlib import Path +from typing import Optional + +from fastapi import APIRouter, Depends, HTTPException, Query +from pydantic import BaseModel + +from domain.team import AuthorizationError, InvalidTransitionError +from routers.sync_deps import ( + get_conn, + get_optional_config, + get_read_conn, + make_managers, + make_repos, + make_team_service, + require_config, + validate_name, +) + +logger = logging.getLogger(__name__) + +router = APIRouter(prefix="/sync", tags=["sync-teams"]) + + +# --- Request schemas ------------------------------------------------------- + +class CreateTeamRequest(BaseModel): + name: str + + +class AddMemberRequest(BaseModel): + pairing_code: str + + +# --- Dependencies (overridable in tests) ----------------------------------- + +async def get_team_svc(config=Depends(require_config)): + return make_team_service(config) + + +def get_pairing_svc(): + from services.sync.pairing_service import PairingService + + return PairingService() + + +# --- Team endpoints -------------------------------------------------------- + +@router.post("/teams", status_code=201) +async def create_team( + req: CreateTeamRequest, + conn: sqlite3.Connection = Depends(get_conn), + config=Depends(require_config), + svc=Depends(get_team_svc), +): + """Create a new team. Caller becomes the leader.""" + validate_name(req.name, "team name") + device_id = config.syncthing.device_id if config.syncthing else "" + try: + team = await svc.create_team( + conn, + name=req.name, + leader_member_tag=config.member_tag, + leader_device_id=device_id, + ) + except ValueError as e: + raise HTTPException(400, str(e)) + return _team_dict(team) + + +@router.get("/teams") +async def list_teams( + conn: sqlite3.Connection = Depends(get_read_conn), + include_dissolved: bool = Query(False, description="Include dissolved teams"), +): + """List all teams with member/project counts.""" + repos = make_repos() + teams = repos["teams"].list_all(conn) if include_dissolved else repos["teams"].list_active(conn) + result = [] + for t in teams: + members = repos["members"].list_for_team(conn, t.name) + projects = repos["projects"].list_for_team(conn, t.name) + result.append({ + **_team_dict(t), + "member_count": len(members), + "project_count": len(projects), + "members": [_member_dict(m) for m in members], + "projects": [ + { + "git_identity": p.git_identity, + "encoded_name": p.encoded_name, + "folder_suffix": p.folder_suffix, + "status": p.status.value, + } + for p in projects + ], + }) + return {"teams": result} + + +@router.get("/teams/{name}") +async def get_team(name: str, conn: sqlite3.Connection = Depends(get_read_conn)): + """Team detail with members, projects, and subscriptions.""" + repos = make_repos() + team = repos["teams"].get(conn, name) + if team is None: + raise HTTPException(404, f"Team '{name}' not found") + members = repos["members"].list_for_team(conn, name) + projects = repos["projects"].list_for_team(conn, name) + subs_list = [] + for m in members: + subs_list.extend(repos["subs"].list_for_member(conn, m.member_tag)) + return { + **_team_dict(team), + "members": [_member_dict(m) for m in members], + "projects": [ + { + "git_identity": p.git_identity, + "encoded_name": p.encoded_name, + "folder_suffix": p.folder_suffix, + "status": p.status.value, + } + for p in projects + ], + "subscriptions": [ + { + "member_tag": s.member_tag, + "team_name": s.team_name, + "project_git_identity": s.project_git_identity, + "status": s.status.value, + "direction": s.direction.value, + } + for s in subs_list + ], + } + + +@router.delete("/teams/{name}") +async def dissolve_team( + name: str, + conn: sqlite3.Connection = Depends(get_conn), + config=Depends(require_config), + svc=Depends(get_team_svc), +): + """Dissolve a team. Leader only.""" + device_id = config.syncthing.device_id if config.syncthing else "" + try: + team = await svc.dissolve_team(conn, team_name=name, by_device=device_id) + except AuthorizationError: + raise HTTPException(403, "Only the team leader can dissolve the team") + except InvalidTransitionError as e: + raise HTTPException(409, str(e)) + except ValueError as e: + raise HTTPException(404, str(e)) + return {"ok": True, "name": team.name, "status": team.status.value} + + +@router.post("/teams/{name}/leave") +async def leave_team( + name: str, + conn: sqlite3.Connection = Depends(get_conn), + config=Depends(require_config), + svc=Depends(get_team_svc), +): + """Leave a team. Non-leaders use this to self-remove.""" + member_tag = config.member_tag if config else "" + try: + await svc.leave_team(conn, team_name=name, member_tag=member_tag) + except ValueError as e: + raise HTTPException(400, str(e)) + return {"ok": True, "name": name} + + +# --- Member endpoints ------------------------------------------------------ + +@router.post("/teams/{name}/members", status_code=201) +async def add_member( + name: str, + req: AddMemberRequest, + conn: sqlite3.Connection = Depends(get_conn), + config=Depends(require_config), + svc=Depends(get_team_svc), + pairing=Depends(get_pairing_svc), +): + """Add member via pairing code. Leader only.""" + try: + info = pairing.validate_code(req.pairing_code) + except ValueError as e: + raise HTTPException(400, f"Invalid pairing code: {e}") + device_id = config.syncthing.device_id if config.syncthing else "" + try: + member = await svc.add_member( + conn, + team_name=name, + by_device=device_id, + new_member_tag=info.member_tag, + new_device_id=info.device_id, + ) + except AuthorizationError: + raise HTTPException(403, "Only the team leader can add members") + except InvalidTransitionError as e: + raise HTTPException(409, str(e)) + except ValueError as e: + raise HTTPException(404, str(e)) + return _member_dict(member) + + +@router.delete("/teams/{name}/members/{tag}") +async def remove_member( + name: str, + tag: str, + conn: sqlite3.Connection = Depends(get_conn), + config=Depends(require_config), + svc=Depends(get_team_svc), +): + """Remove a member. Leader only.""" + device_id = config.syncthing.device_id if config.syncthing else "" + try: + member = await svc.remove_member( + conn, team_name=name, by_device=device_id, member_tag=tag, + ) + except AuthorizationError: + raise HTTPException(403, "Only the team leader can remove members") + except InvalidTransitionError as e: + raise HTTPException(409, str(e)) + except ValueError as e: + raise HTTPException(404, str(e)) + + # Check if the removed member's device is connected — if not, + # the removal signal can't propagate via Syncthing metadata sync. + delivery_pending = True + try: + devices, _, _ = make_managers(config) + connected = await devices.is_connected(member.device_id) + delivery_pending = not connected + except Exception: + pass # Assume pending if we can't check + + result = _member_dict(member) + result["delivery_pending"] = delivery_pending + return result + + +@router.get("/teams/{name}/members") +async def list_members( + name: str, + conn: sqlite3.Connection = Depends(get_read_conn), + config=Depends(get_optional_config), +): + """List team members with delivery status for removed members.""" + repos = make_repos() + team = repos["teams"].get(conn, name) + if team is None: + raise HTTPException(404, f"Team '{name}' not found") + members = repos["members"].list_for_team(conn, name) + + # Check connectivity for removed members to surface delivery_pending + connections: dict | None = None + removed = [m for m in members if m.status.value == "removed"] + if removed and config and config.syncthing: + try: + devices, _, _ = make_managers(config) + connections = await devices._client.get_connections() + except Exception: + pass + + result = [] + for m in members: + d = _member_dict(m) + if m.status.value == "removed": + connected = False + if connections and m.device_id in connections: + connected = connections[m.device_id].get("connected", False) + d["delivery_pending"] = not connected + result.append(d) + + return {"members": result} + + +# --- Join code endpoint ---------------------------------------------------- + +@router.get("/teams/{name}/join-code") +async def get_join_code( + name: str, + conn: sqlite3.Connection = Depends(get_read_conn), + config=Depends(require_config), + pairing=Depends(get_pairing_svc), +): + """Generate a join code for this team's device.""" + repos = make_repos() + team = repos["teams"].get(conn, name) + if team is None: + raise HTTPException(404, f"Team '{name}' not found") + device_id = config.syncthing.device_id if config.syncthing else "" + if not device_id: + raise HTTPException(400, "No Syncthing device ID configured") + code = pairing.generate_code(config.member_tag, device_id) + return {"code": code, "member_tag": config.member_tag, "device_id": device_id} + + +# --- Activity endpoint ----------------------------------------------------- + +@router.get("/teams/{name}/activity") +async def get_team_activity( + name: str, + limit: int = Query(default=20, ge=1, le=200), + conn: sqlite3.Connection = Depends(get_read_conn), +): + """Return recent activity events for a team.""" + repos = make_repos() + team = repos["teams"].get(conn, name) + if team is None: + raise HTTPException(404, f"Team '{name}' not found") + events = repos["events"].query(conn, team=name, limit=limit) + return { + "events": [ + { + "event_type": e.event_type.value, + "team_name": e.team_name, + "member_tag": e.member_tag, + "detail": e.detail, + "created_at": e.created_at.isoformat(), + } + for e in events + ] + } + + +# --- Project status endpoint ----------------------------------------------- + +@router.get("/teams/{name}/project-status") +async def get_project_status( + name: str, + conn: sqlite3.Connection = Depends(get_read_conn), + config=Depends(get_optional_config), +): + """Per-project sync status: subscriptions, session counts, sync gap.""" + repos = make_repos() + team = repos["teams"].get(conn, name) + if team is None: + raise HTTPException(404, f"Team '{name}' not found") + projects = repos["projects"].list_for_team(conn, name) + + # Resolve local encoded_name and display_name for each project + encoded_map, name_map = _resolve_project_names(conn, projects) + relevant_encoded = {v for v in encoded_map.values() if v is not None} + + # Batch query: local session counts + local_counts: dict[str, int] = {} + if relevant_encoded: + placeholders = ",".join("?" * len(relevant_encoded)) + rows = conn.execute( + f"SELECT project_encoded_name, COUNT(*) FROM sessions " + f"WHERE (source IS NULL OR source != 'remote') " + f"AND project_encoded_name IN ({placeholders}) " + f"GROUP BY project_encoded_name", + list(relevant_encoded), + ).fetchall() + local_counts = {r[0]: r[1] for r in rows} + + # Batch query: received session counts per project + remote member + received_by_encoded: dict[str, dict[str, int]] = {} + if relevant_encoded: + placeholders = ",".join("?" * len(relevant_encoded)) + rows = conn.execute( + f"SELECT project_encoded_name, remote_user_id, COUNT(*) FROM sessions " + f"WHERE source = 'remote' AND remote_user_id IS NOT NULL " + f"AND project_encoded_name IN ({placeholders}) " + f"GROUP BY project_encoded_name, remote_user_id", + list(relevant_encoded), + ).fetchall() + for enc, uid, cnt in rows: + received_by_encoded.setdefault(enc, {})[uid] = cnt + + # Local member_tag for outbox counting + member_tag = config.member_tag if config else None + + # Get active session counts to exclude from gap + active_counts = _get_active_counts() + + result = [] + for p in projects: + subs = repos["subs"].list_for_project(conn, name, p.git_identity) + sub_counts = {"offered": 0, "accepted": 0, "paused": 0, "declined": 0} + for s in subs: + if s.status.value in sub_counts: + sub_counts[s.status.value] += 1 + + encoded = encoded_map.get(p.git_identity) + display = name_map.get(p.git_identity) + local_count = local_counts.get(encoded, 0) if encoded else 0 + received = received_by_encoded.get(encoded, {}) if encoded else {} + packaged_count = ( + _count_packaged(member_tag, p.folder_suffix) if member_tag else 0 + ) + active_count = active_counts.get(encoded, 0) if encoded else 0 + + result.append({ + "git_identity": p.git_identity, + "folder_suffix": p.folder_suffix, + "status": p.status.value, + "encoded_name": encoded, + "name": display, + "subscription_counts": sub_counts, + "local_count": local_count, + "packaged_count": packaged_count, + "active_count": active_count, + "received_counts": received, + "gap": max(0, local_count - packaged_count - active_count) if member_tag else None, + }) + return {"projects": result} + + +# --- Session stats endpoint ------------------------------------------------ + +@router.get("/teams/{name}/session-stats") +async def get_session_stats( + name: str, + days: int = Query(default=30, ge=1, le=365), + conn: sqlite3.Connection = Depends(get_read_conn), +): + """Per-member stats for a team: status and subscription count.""" + repos = make_repos() + team = repos["teams"].get(conn, name) + if team is None: + raise HTTPException(404, f"Team '{name}' not found") + members = repos["members"].list_for_team(conn, name) + result = [] + for m in members: + subs = repos["subs"].list_for_member(conn, m.member_tag) + # Filter to this team's subscriptions + team_subs = [s for s in subs if s.team_name == name] + result.append({ + "member_tag": m.member_tag, + "user_id": m.user_id, + "status": m.status.value, + "subscription_count": len(team_subs), + }) + return {"members": result} + + +# --- Helpers --------------------------------------------------------------- + +def _team_dict(team) -> dict: + return { + "name": team.name, + "leader_member_tag": team.leader_member_tag, + "status": team.status.value, + "created_at": team.created_at.isoformat(), + } + + +def _member_dict(member) -> dict: + return { + "member_tag": member.member_tag, + "device_id": member.device_id, + "user_id": member.user_id, + "machine_tag": member.machine_tag, + "status": member.status.value, + } + + +def _resolve_project_names( + conn: sqlite3.Connection, projects, +) -> tuple[dict[str, str | None], dict[str, str | None]]: + """Resolve local encoded_name and display_name for sync projects. + + Uses git_identity substring matching (same pattern as indexer.py). + Returns (encoded_by_git, name_by_git). + """ + local_rows = conn.execute( + "SELECT encoded_name, git_identity, display_name FROM projects " + "WHERE git_identity IS NOT NULL" + ).fetchall() + + encoded_by_git: dict[str, str | None] = {} + name_by_git: dict[str, str | None] = {} + + for p in projects: + sync_git = (p.git_identity or "").rstrip("/").lower() + if sync_git.endswith(".git"): + sync_git = sync_git[:-4] + + matched_enc = None + matched_name = None + for enc, local_git, display_name in local_rows: + lg = (local_git or "").rstrip("/").lower() + if lg.endswith(".git"): + lg = lg[:-4] + if lg and ( + lg in sync_git or sync_git in lg + or lg.endswith(sync_git) or sync_git.endswith(lg) + ): + matched_enc = enc + matched_name = display_name + break + + encoded_by_git[p.git_identity] = matched_enc + name_by_git[p.git_identity] = matched_name + + return encoded_by_git, name_by_git + + +def _count_packaged(member_tag: str, folder_suffix: str) -> int: + """Count *.jsonl files in the local Syncthing outbox for a project.""" + from config import settings as app_settings + from services.syncthing.folder_manager import build_outbox_folder_id + + folder_id = build_outbox_folder_id(member_tag, folder_suffix) + sessions_dir = app_settings.karma_base / folder_id / "sessions" + if not sessions_dir.is_dir(): + return 0 + return sum(1 for _ in sessions_dir.glob("*.jsonl")) + + +def _get_active_counts(live_sessions_dir: Path | None = None) -> dict[str, int]: + """Count active (non-ended, non-stale) sessions per project encoded_name. + + Reads ~/.claude_karma/live-sessions/*.json. Returns {encoded_name: count}. + Uses worktree-to-parent resolution so worktree sessions roll up to + the real project. + """ + from services.sync.session_packager import STALE_LIVE_SESSION_SECONDS + + if live_sessions_dir is None: + from config import settings as app_settings + live_sessions_dir = app_settings.karma_base / "live-sessions" + + if not live_sessions_dir.is_dir(): + return {} + + import json as _json + now = datetime.now(timezone.utc) + counts: dict[str, int] = {} + + for json_file in live_sessions_dir.glob("*.json"): + try: + data = _json.loads(json_file.read_text(encoding="utf-8")) + if data.get("state") == "ENDED": + continue + + # Check staleness + updated_str = data.get("updated_at") + if updated_str: + updated = datetime.fromisoformat(updated_str.replace("Z", "+00:00")) + if updated.tzinfo is None: + updated = updated.replace(tzinfo=timezone.utc) + if (now - updated).total_seconds() > STALE_LIVE_SESSION_SECONDS: + continue + + # Extract encoded_name from transcript_path + tp = data.get("transcript_path", "") + if "/projects/" not in tp: + continue + parts = tp.split("/projects/", 1)[1].split("/") + if not parts: + continue + enc = parts[0] + + # Worktree resolution: if encoded name is a worktree path, resolve + # to real project via git_root if available + git_root = data.get("git_root") + if git_root and (".claude-worktrees" in enc or "-worktrees-" in enc): + enc = "-" + git_root.lstrip("/").replace("/", "-") + + counts[enc] = counts.get(enc, 0) + 1 + except (ValueError, OSError): + continue + return counts + + +# --- Member settings endpoint ------------------------------------------------ + +@router.get("/teams/{name}/members/{device_id}/settings") +async def get_member_settings( + name: str, + device_id: str, + conn: sqlite3.Connection = Depends(get_read_conn), +): + """Get sync direction settings for a member in a team.""" + repos = make_repos() + team = repos["teams"].get(conn, name) + if team is None: + raise HTTPException(404, f"Team '{name}' not found") + + # Find member by device_id in this team + members = repos["members"].get_by_device(conn, device_id) + member = next((m for m in members if m.team_name == name), None) + if member is None: + raise HTTPException(404, f"No member with device '{device_id}' in team '{name}'") + + # Get accepted subscriptions for this member in this team + subs = repos["subs"].list_for_member(conn, member.member_tag) + team_subs = [s for s in subs if s.team_name == name and s.status.value == "accepted"] + + # Determine effective direction from subscriptions + # Map API values to frontend format: send→send_only, receive→receive_only + api_to_frontend = {"send": "send_only", "receive": "receive_only", "both": "both"} + + if team_subs: + directions = {s.direction.value for s in team_subs} + if len(directions) == 1: + raw = directions.pop() + direction_value = api_to_frontend.get(raw, raw) + else: + direction_value = "mixed" + # Source: "default" if direction is "both" (the default), "member" otherwise + source = "default" if direction_value == "both" else "member" + else: + direction_value = "both" + source = "default" + + return { + "settings": { + "sync_direction": { + "value": direction_value, + "source": source, + } + } + } + + +@router.patch("/teams/{name}/members/{device_id}/settings") +async def update_member_settings( + name: str, + device_id: str, + body: dict, + conn: sqlite3.Connection = Depends(get_conn), +): + """Update sync direction for a member in a team.""" + repos = make_repos() + team = repos["teams"].get(conn, name) + if team is None: + raise HTTPException(404, f"Team '{name}' not found") + + members = repos["members"].get_by_device(conn, device_id) + member = next((m for m in members if m.team_name == name), None) + if member is None: + raise HTTPException(404, f"No member with device '{device_id}' in team '{name}'") + + new_direction = body.get("sync_direction") + + # Accept frontend aliases: send_only→send, receive_only→receive, none→both + # null means "reset to default (both)" + from domain.subscription import SyncDirection + if new_direction is None: + new_direction = "both" + direction_aliases = {"send_only": "send", "receive_only": "receive", "none": "both"} + normalized = direction_aliases.get(new_direction, new_direction) + try: + direction_enum = SyncDirection(normalized) + except ValueError: + raise HTTPException(400, f"Invalid direction: {new_direction}. Use: both, send, receive") + + # Update all accepted subscriptions for this member in this team + subs = repos["subs"].list_for_member(conn, member.member_tag) + team_subs = [s for s in subs if s.team_name == name and s.status.value == "accepted"] + + for sub in team_subs: + updated = sub.change_direction(direction_enum) + repos["subs"].save(conn, updated) + + source = "default" if normalized == "both" else "member" + # Return frontend-compatible value + api_to_frontend = {"send": "send_only", "receive": "receive_only", "both": "both"} + return { + "settings": { + "sync_direction": { + "value": api_to_frontend.get(normalized, new_direction), + "source": source, + } + } + } diff --git a/api/routers/tools.py b/api/routers/tools.py index 6ff77468..4d53a0b9 100644 --- a/api/routers/tools.py +++ b/api/routers/tools.py @@ -7,6 +7,7 @@ import logging import sqlite3 +from collections import defaultdict from typing import Optional from fastapi import APIRouter, HTTPException, Query, Request @@ -147,6 +148,10 @@ def _build_session_summary(session_data: dict) -> SessionSummary: session_titles=session_data.get("session_titles", []), tool_source=session_data.get("tool_source"), subagent_agent_ids=session_data.get("subagent_agent_ids", []), + session_source=session_data.get("session_source"), + source=session_data.get("source"), + remote_user_id=session_data.get("remote_user_id"), + remote_machine_id=session_data.get("remote_machine_id"), ) @@ -280,11 +285,28 @@ def get_mcp_tool_usage_trend( ] # No limit — frontend handles top-N display + # Merge trend_by_user: sum counts per date across both sources + merged_by_user: dict[str, dict[str, int]] = defaultdict(lambda: defaultdict(int)) + for source in (mcp_data, builtin_data): + for user_id, points in source.get("trend_by_user", {}).items(): + for pt in points: + merged_by_user[user_id][pt["date"]] += pt["count"] + merged_trend_by_user = { + uid: [{"date": d, "count": c} for d, c in sorted(date_counts.items())] + for uid, date_counts in merged_by_user.items() + } + merged_user_names = { + **mcp_data.get("user_names", {}), + **builtin_data.get("user_names", {}), + } + return UsageTrendResponse( total=mcp_data["total"] + builtin_data["total"], by_item=merged_by_item, trend=[UsageTrendItem(**t) for t in merged_trend], trend_by_item=merged_trend_by_item, + trend_by_user=merged_trend_by_user, + user_names=merged_user_names, first_used=min(firsts) if firsts else None, last_used=max(lasts) if lasts else None, ) diff --git a/api/schemas.py b/api/schemas.py index e4917efd..f6782016 100644 --- a/api/schemas.py +++ b/api/schemas.py @@ -78,6 +78,9 @@ class SubagentSummary(BaseModel): subagent_type: Optional[str] = Field( None, description="Type of subagent: Explore, Plan, Bash, or custom agent name" ) + display_name: Optional[str] = Field( + None, description="Human-readable display name from Agent tool input (e.g., 'security-fixes')" + ) tools_used: dict[str, int] = Field(default_factory=dict, description="Tool name -> usage count") message_count: int = Field(0, description="Total messages in subagent conversation") initial_prompt: Optional[str] = Field(None, description="First user message to subagent") @@ -178,6 +181,13 @@ class SessionSummary(BaseModel): git_branches: list[str] = Field( default_factory=list, description="Git branches touched during this session" ) + # Token and cost fields + total_input_tokens: Optional[int] = Field(None, description="Total input tokens") + total_output_tokens: Optional[int] = Field(None, description="Total output tokens") + total_cost: Optional[float] = Field(None, description="Total estimated cost in USD") + tools_used: Optional[dict[str, int]] = Field( + None, description="Tool name → invocation count map" + ) # Chain info for list view badges chain_info: Optional[SessionChainInfoSummary] = Field( None, description="Chain context if session is part of a resumed chain" @@ -207,6 +217,19 @@ class SessionSummary(BaseModel): None, description="Session origin: 'desktop' for Claude Desktop, None for CLI", ) + # Remote sync fields + source: Optional[str] = Field( + None, + description="Session source: 'local' or 'remote' (None defaults to local)", + ) + remote_user_id: Optional[str] = Field( + None, + description="User ID of the remote machine that produced this session", + ) + remote_machine_id: Optional[str] = Field( + None, + description="Machine ID of the remote machine that produced this session", + ) class CompactionSummary(BaseModel): @@ -349,6 +372,9 @@ class ProjectSummary(BaseModel): is_nested_project: bool = Field( default=False, description="True if project is inside a git repo but not at the root" ) + git_remote_url: Optional[str] = Field( + default=None, description="Git remote 'origin' URL — machine-independent project identity" + ) latest_session_time: Optional[datetime] = Field( default=None, description="Start time of the most recent session" ) @@ -358,6 +384,9 @@ class ProjectDetail(ProjectSummary): """Detailed project info with sessions list.""" sessions: list[SessionSummary] = Field(default_factory=list) + remote_session_count: int = Field( + 0, description="Number of remote sessions from team members" + ) class TimeDistribution(BaseModel): @@ -419,6 +448,14 @@ class ProjectAnalytics(BaseModel): default_factory=WorkModeDistribution, description="Work mode distribution based on tool usage", ) + sessions_by_date_by_user: dict[str, dict[str, int]] = Field( + default_factory=dict, + description="Per-user session counts: user_id -> {date -> count}. '_local' = local user.", + ) + user_names: dict[str, str] = Field( + default_factory=dict, + description="user_id -> display name from sync_members", + ) class DashboardStats(BaseModel): @@ -557,9 +594,20 @@ class SubagentSessionDetail(BaseModel): subagent_type: Optional[str] = Field( None, description="Type of subagent: Explore, Plan, Bash, or custom" ) + display_name: Optional[str] = Field( + None, description="Human-readable name given when spawning the agent (e.g., 'security-fixes')" + ) initial_prompt: Optional[str] = Field( None, description="First user message to subagent (truncated)" ) + initial_prompt_images: list[dict[str, str]] = Field( + default_factory=list, description="Image attachments from subagent's first user message" + ) + + # Remote session metadata + remote_user_id: Optional[str] = Field( + None, description="User ID of the remote machine that produced the parent session" + ) # ============================================================================= @@ -683,6 +731,7 @@ class SkillInfo(BaseModel): is_plugin: bool = Field(..., description="True if this is a plugin skill") plugin: Optional[str] = Field(None, description="Plugin name if is_plugin") file_path: Optional[str] = Field(None, description="Path to the skill file") + inherited_from: Optional[str] = Field(None, description="Original plugin skill name this was inherited from") class SkillSessionsResponse(BaseModel): @@ -712,7 +761,10 @@ class SkillDetailResponse(BaseModel): is_plugin: bool = Field(False, description="True if this is a plugin skill") plugin: Optional[str] = Field(None, description="Plugin name if is_plugin") file_path: Optional[str] = Field(None, description="Path to the skill file") - category: Optional[str] = Field(None, description="Invocation category (builtin_command, bundled_skill, plugin_skill, user_skill, unknown)") + category: Optional[str] = Field( + None, + description="Invocation category (builtin_command, bundled_skill, plugin_skill, user_skill, unknown)", + ) calls: int = Field(0, description="Total invocations") main_calls: int = Field(0, description="Calls from main sessions") subagent_calls: int = Field(0, description="Calls from subagents") @@ -731,6 +783,22 @@ class SkillDetailResponse(BaseModel): default_factory=list, description="Sessions using this skill" ) sessions_total: int = Field(0, description="Total session count (before pagination)") + remote_count: int = Field(0, description="Invocations from remote sessions") + local_count: int = Field(0, description="Invocations from local sessions") + remote_user_ids: list[str] = Field( + default_factory=list, description="Distinct remote user IDs that used this skill" + ) + is_remote_only: bool = Field( + False, description="True when skill has only been used in remote sessions" + ) + remote_definition: Optional[Dict[str, Any]] = Field( + None, + description="Skill definition from skill_definitions table (populated for remote-only skills)", + ) + inherited_from: Optional[str] = Field( + None, + description="Original plugin skill name this was inherited from (e.g. 'oh-my-claudecode:deepsearch')", + ) class AgentSessionsResponse(BaseModel): @@ -868,6 +936,12 @@ class PlanWithContext(PlanSummary): session_context: Optional[PlanSessionContext] = Field( None, description="Session context if plan can be linked to a session" ) + remote_user_id: Optional[str] = Field( + None, description="Remote user ID if this plan was synced from another user" + ) + linked_sessions: Optional[list[dict]] = Field( + None, description="Sessions linked to this plan via plans-index.json (remote plans)" + ) class PlanListResponse(PaginationMeta): @@ -1179,6 +1253,9 @@ class AgentInvocation(BaseModel): project_encoded_name: str = Field(..., description="Project where invocation occurred") project_slug: Optional[str] = Field(None, description="URL-friendly project slug") project_display_name: Optional[str] = Field(None, description="Human-readable project name") + display_name: Optional[str] = Field( + None, description="Human-readable display name from Agent tool input (e.g., 'security-fixes')" + ) invoked_at: Optional[datetime] = Field(None, description="When the agent was invoked") duration_seconds: Optional[float] = Field(None, description="Invocation duration") input_tokens: int = Field(0, description="Input tokens used") @@ -1453,6 +1530,14 @@ class UsageTrendResponse(BaseModel): default_factory=dict, description="Per-item daily trend for top items (item name -> daily counts)", ) + trend_by_user: dict[str, list[UsageTrendItem]] = Field( + default_factory=dict, + description="Per-user daily trend (user_id -> daily counts)", + ) + user_names: dict[str, str] = Field( + default_factory=dict, + description="user_id -> display name mapping for sync members", + ) first_used: Optional[datetime] = Field(None, description="First usage timestamp") last_used: Optional[datetime] = Field(None, description="Most recent usage timestamp") @@ -1525,3 +1610,57 @@ class AllSessionsResponse(PaginationMeta): default_factory=list, description="Status filter options with counts" ) applied_filters: dict = Field(default_factory=dict, description="Echo of applied filter values") + +# ============================================================================= +# Sync Request Models (used by routers/sync_status.py) +# ============================================================================= + + +class AddDeviceRequest(BaseModel): + device_id: str + name: str + + +class InitRequest(BaseModel): + user_id: str + backend: str = "syncthing" + + +class CreateTeamRequest(BaseModel): + name: str + backend: str = "syncthing" + + +class AddMemberRequest(BaseModel): + name: str + device_id: str + + +class AddTeamProjectRequest(BaseModel): + name: str + path: str + + +class JoinTeamRequest(BaseModel): + join_code: str + team_name: Optional[str] = None + + +class UpdateTeamSettingsRequest(BaseModel): + sync_session_limit: Optional[str] = None # 'all', 'recent_100', 'recent_10' + auto_accept_members: Optional[str] = None # 'true', 'false' + sync_direction: Optional[str] = None # 'both', 'send_only', 'receive_only', 'none' + + +class UpdateMemberSettingsRequest(BaseModel): + sync_direction: Optional[str] = None # 'both', 'send_only', 'receive_only', 'none', or null to clear + + +class ResetOptions(BaseModel): + """Options for sync reset.""" + uninstall_syncthing: bool = False # Remove Syncthing config directory + + +class AcceptPendingDeviceRequest(BaseModel): + team_name: str + member_name: Optional[str] = None # Optional — falls back to device hostname diff --git a/api/services/file_validator.py b/api/services/file_validator.py new file mode 100644 index 00000000..d2f4e6e9 --- /dev/null +++ b/api/services/file_validator.py @@ -0,0 +1,215 @@ +"""File validation for received sync files. + +Validates extension, size, content format, and paths before indexing. +Quarantines rejected files with audit logging. +""" + +import json +import logging +import re +import shutil +from datetime import datetime, timezone +from pathlib import Path +from typing import Optional + +from pydantic import BaseModel, field_validator + +logger = logging.getLogger(__name__) + +# ── Size limits ────────────────────────────────────────────────────── + +ALLOWED_EXTENSIONS = {".jsonl", ".json", ".txt"} +MAX_JSONL_SIZE = 200 * 1024 * 1024 # 200 MB per session file +MAX_JSON_SIZE = 10 * 1024 * 1024 # 10 MB per manifest/todo +MAX_TXT_SIZE = 50 * 1024 * 1024 # 50 MB per tool result +MAX_FILES_PER_SESSION = 500 # subagents + tool results +MAX_TOTAL_SIZE_PER_PROJECT = 2 * 1024 * 1024 * 1024 # 2 GB + +_SIZE_LIMITS = { + ".jsonl": MAX_JSONL_SIZE, + ".json": MAX_JSON_SIZE, + ".txt": MAX_TXT_SIZE, +} + +SAFE_PATH_PART = re.compile(r'^[a-zA-Z0-9_\-\.]+$') + +# ── Manifest validation ────────────────────────────────────────────── + +# Same pattern as SAFE_PATH_PART — reuse for identifiers +SAFE_IDENTIFIER = SAFE_PATH_PART +from command_helpers.categories import InvocationCategory +import typing as _typing + +# Derive valid categories from the canonical type, excluding "agent" (not a manifest category) +VALID_SKILL_CATEGORIES: frozenset[str] = frozenset(_typing.get_args(InvocationCategory)) - {"agent"} + + +class ManifestSession(BaseModel): + uuid: str + mtime: str + size_bytes: int = 0 + worktree_name: Optional[str] = None + git_branch: Optional[str] = None + + +class SyncManifest(BaseModel): + """Validated manifest for remote session packages.""" + version: int = 1 + user_id: str + machine_id: str + device_id: Optional[str] = None + project_path: str = "" + project_encoded: str = "" + synced_at: str = "" + session_count: int = 0 + sessions: list[ManifestSession] = [] + sync_backend: str = "syncthing" + skill_classifications: dict[str, str] = {} + # Allow extra fields from older/newer manifests + model_config = {"extra": "ignore"} + + @field_validator("user_id", "machine_id") + @classmethod + def validate_identifiers(cls, v: str) -> str: + if not SAFE_IDENTIFIER.match(v): + raise ValueError(f"Unsafe identifier: {v!r}") + if len(v) > 128: + raise ValueError(f"Identifier too long: {len(v)} chars") + return v + + @field_validator("skill_classifications") + @classmethod + def validate_classifications(cls, v: dict) -> dict: + return {k: cat for k, cat in v.items() if isinstance(cat, str) and cat in VALID_SKILL_CATEGORIES} + + +# ── Path validation ────────────────────────────────────────────────── + + +def validate_remote_path(base_dir: Path, relative_parts: list[str]) -> Path: + """Construct and validate a path from remote-derived components. + + Ensures the resolved path is strictly under base_dir. + Rejects: .., symlinks, non-alphanumeric chars (except - _ .). + """ + for part in relative_parts: + if not SAFE_PATH_PART.match(part): + raise ValueError(f"Unsafe path component: {part!r}") + if part in (".", ".."): + raise ValueError(f"Path traversal attempt: {part!r}") + + constructed = base_dir.joinpath(*relative_parts).resolve() + base_resolved = base_dir.resolve() + + if not str(constructed).startswith(str(base_resolved) + "/") and constructed != base_resolved: + raise ValueError(f"Path escapes base directory: {constructed}") + + return constructed + + +# ── File validation ────────────────────────────────────────────────── + + +def validate_received_file(path: Path) -> tuple[bool, str]: + """Validate a received file. Returns (valid, reason).""" + if not path.is_file(): + return False, "Not a file" + + ext = path.suffix.lower() + if ext not in ALLOWED_EXTENSIONS: + return False, f"Disallowed extension: {ext}" + + size = path.stat().st_size + max_size = _SIZE_LIMITS.get(ext, MAX_TXT_SIZE) + if size > max_size: + return False, f"File too large: {size} bytes (max {max_size})" + + if size == 0: + return True, "ok" # Empty files are valid (new sessions) + + # Content validation for JSONL + if ext == ".jsonl": + return validate_jsonl_file(path) + + # Content validation for JSON + if ext == ".json": + return validate_json_file(path) + + return True, "ok" + + +def validate_jsonl_file(path: Path) -> tuple[bool, str]: + """Validate JSONL: check first line is valid JSON with expected keys.""" + try: + with open(path) as f: + first_line = f.readline(2_000_000) # Cap line read to 2MB + if not first_line.strip(): + return False, "Empty JSONL file" + obj = json.loads(first_line) + if not isinstance(obj, dict): + return False, "First line is not a JSON object" + # Claude Code JSONL lines have 'type' or 'role' at top level + if "type" not in obj and "role" not in obj: + return False, "Missing 'type' or 'role' key in first line" + except json.JSONDecodeError as e: + return False, f"Invalid JSON on first line: {e}" + except Exception as e: + return False, f"Read error: {e}" + + return True, "ok" + + +def validate_json_file(path: Path) -> tuple[bool, str]: + """Validate JSON file: must be parseable. + + Size is already checked by validate_received_file() via stat(). + """ + try: + with open(path) as f: + json.load(f) + except json.JSONDecodeError as e: + return False, f"Invalid JSON: {e}" + except Exception as e: + return False, f"Read error: {e}" + + return True, "ok" + + +def validate_manifest(path: Path) -> tuple[Optional[SyncManifest], str]: + """Parse and validate a manifest.json file. Returns (manifest, reason).""" + try: + if path.stat().st_size > MAX_JSON_SIZE: + return None, "Manifest too large" + data = json.loads(path.read_text()) + manifest = SyncManifest.model_validate(data) + return manifest, "ok" + except json.JSONDecodeError as e: + return None, f"Invalid JSON: {e}" + except Exception as e: + return None, f"Validation failed: {e}" + + +# ── Quarantine ─────────────────────────────────────────────────────── + +QUARANTINE_DIR = Path.home() / ".claude_karma" / "quarantine" + + +def quarantine_file(path: Path, reason: str, member_name: str = "unknown") -> Path: + """Move a rejected file to quarantine directory. + + Returns the quarantine path. + """ + QUARANTINE_DIR.mkdir(parents=True, exist_ok=True) + + timestamp = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H%M%S") + quarantine_name = f"{timestamp}_{member_name}_{path.name}" + dest = QUARANTINE_DIR / quarantine_name + + try: + shutil.move(str(path), str(dest)) + logger.warning("Quarantined %s → %s (reason: %s)", path.name, dest, reason) + except Exception as e: + logger.error("Failed to quarantine %s: %s", path, e) + dest = path # Return original path if move fails + + return dest diff --git a/api/services/remote_plans.py b/api/services/remote_plans.py new file mode 100644 index 00000000..78365583 --- /dev/null +++ b/api/services/remote_plans.py @@ -0,0 +1,285 @@ +""" +Remote plans service for Syncthing-synced plan files. + +Directory structure (written by CLI packager, synced by Syncthing): + ~/.claude_karma/remote-sessions/{user_id}/{encoded_name}/ + plans/{slug}.md + plans-index.json + +Discovers plans from all remote users and provides plan-to-session linkage +via the plans-index.json sidecar written by the sender's packager. +""" + +import json +import logging +import time +from dataclasses import dataclass +from datetime import datetime, timezone +from pathlib import Path +from typing import Optional + +from config import settings +from services.syncthing.folder_manager import parse_member_tag + +logger = logging.getLogger(__name__) + +# Cache for plans-index.json (keyed by (user_id, encoded_name)) +_plans_index_cache: dict[tuple[str, str], tuple[float, dict]] = {} +_PLANS_INDEX_TTL = 30.0 # seconds + + +def _get_remote_sessions_dir() -> Path: + """Get the remote-sessions base directory.""" + return settings.karma_base / "remote-sessions" + + +def _get_local_user_id() -> Optional[str]: + """Get local user_id from sync-config.json (cached).""" + config_path = settings.karma_base / "sync-config.json" + if not config_path.is_file(): + return None + try: + data = json.loads(config_path.read_text(encoding="utf-8")) + return data.get("user_id") + except (json.JSONDecodeError, OSError): + return None + + +def _is_local_user(dir_name: str, local_user_id: Optional[str]) -> bool: + """Check if a remote-sessions directory belongs to the local user. + + Handles both bare user_id ("jayant") and member_tag ("jayant.mac-mini"). + """ + if not local_user_id: + return False + if dir_name == local_user_id: + return True + parsed_uid, _ = parse_member_tag(dir_name) + return parsed_uid == local_user_id + + +def _load_plans_index(user_id: str, encoded_name: str) -> dict: + """ + Load plans-index.json for a (user_id, encoded_name) pair. + + Returns the "plans" dict: {slug: {"sessions": {uuid: operation}}}. + Cached with TTL. + """ + cache_key = (user_id, encoded_name) + now = time.monotonic() + + cached = _plans_index_cache.get(cache_key) + if cached is not None: + cache_time, cache_data = cached + if (now - cache_time) < _PLANS_INDEX_TTL: + return cache_data + + result: dict = {} + index_path = ( + _get_remote_sessions_dir() / user_id / encoded_name / "plans-index.json" + ) + if index_path.is_file(): + try: + data = json.loads(index_path.read_text(encoding="utf-8")) + if data.get("version") == 1: + result = data.get("plans", {}) + except (json.JSONDecodeError, OSError) as e: + logger.debug( + "Failed to load plans-index for %s/%s: %s", + user_id, encoded_name, e, + ) + + _plans_index_cache[cache_key] = (now, result) + return result + + +@dataclass +class RemotePlan: + """A plan file discovered from a remote user's synced outbox.""" + slug: str + title: Optional[str] + content: str + preview: str + word_count: int + size_bytes: int + created: datetime + modified: datetime + remote_user_id: str + project_encoded_name: str + linked_sessions: list[dict] # [{uuid, operation}, ...] + + +def discover_remote_plans() -> list[RemotePlan]: + """ + Discover all plan files from remote users' synced outboxes. + + Walks ~/.claude_karma/remote-sessions/{user_id}/{encoded}/plans/*.md + Skips the local user's directory (that's our outbox). + Returns plans from all remote users, supporting multi-user scenarios. + """ + remote_dir = _get_remote_sessions_dir() + if not remote_dir.is_dir(): + return [] + + local_user = _get_local_user_id() + plans: list[RemotePlan] = [] + + for user_dir in remote_dir.iterdir(): + if not user_dir.is_dir(): + continue + dir_name = user_dir.name + + # Skip our own outbox (handles both bare user_id and member_tag) + if _is_local_user(dir_name, local_user): + continue + + # Resolve to clean user_id (strip machine_tag if present) + remote_user_id = parse_member_tag(dir_name)[0] + + for encoded_dir in user_dir.iterdir(): + if not encoded_dir.is_dir(): + continue + encoded_name = encoded_dir.name + + plans_dir = encoded_dir / "plans" + if not plans_dir.is_dir(): + continue + + # Load the plans-index for session linkage + plans_index = _load_plans_index(dir_name, encoded_name) + + for plan_file in plans_dir.glob("*.md"): + try: + slug = plan_file.stem + stat = plan_file.stat() + content = plan_file.read_text(encoding="utf-8") + + # Extract title (first h1 heading) + title = None + for line in content.split("\n"): + stripped = line.strip() + if stripped.startswith("# "): + title = stripped[2:].strip() + break + + # Build linked sessions from plans-index + linked_sessions = [] + if slug in plans_index: + sessions_map = plans_index[slug].get("sessions", {}) + for session_uuid, operation in sessions_map.items(): + linked_sessions.append({ + "uuid": session_uuid, + "operation": operation, + "remote_user_id": remote_user_id, + }) + + plans.append(RemotePlan( + slug=slug, + title=title, + content=content, + preview=content[:500] if content else "", + word_count=len(content.split()) if content else 0, + size_bytes=stat.st_size, + created=datetime.fromtimestamp(stat.st_mtime, tz=timezone.utc), + modified=datetime.fromtimestamp(stat.st_mtime, tz=timezone.utc), + remote_user_id=remote_user_id, + project_encoded_name=encoded_name, + linked_sessions=linked_sessions, + )) + except (PermissionError, OSError, UnicodeDecodeError) as e: + logger.debug("Failed to read remote plan %s: %s", plan_file, e) + continue + + # Sort by modified time (newest first) + plans.sort(key=lambda p: p.modified, reverse=True) + return plans + + +def _find_user_dir(remote_dir: Path, user_id: str) -> Optional[Path]: + """Find the remote-sessions directory for a user_id. + + Handles both bare user_id dirs (``jayant``) and member_tag dirs + (``jayant.mac-mini``) by matching the user_id portion. + """ + # Direct match first (fast path) + direct = remote_dir / user_id + if direct.is_dir(): + return direct + # Search for member_tag dirs where user_id matches + if not remote_dir.is_dir(): + return None + for candidate in remote_dir.iterdir(): + if not candidate.is_dir(): + continue + parsed_uid, _ = parse_member_tag(candidate.name) + if parsed_uid == user_id: + return candidate + return None + + +def get_remote_plan(slug: str, user_id: str) -> Optional[RemotePlan]: + """ + Get a specific remote plan by slug and user_id. + + Searches all encoded directories for the user to find the plan. + Handles both bare user_id and member_tag directory names. + """ + remote_dir = _get_remote_sessions_dir() + user_dir = _find_user_dir(remote_dir, user_id) + if user_dir is None: + return None + + # Use actual dir name for filesystem ops, clean user_id for display + dir_name = user_dir.name + clean_user_id = parse_member_tag(dir_name)[0] + + for encoded_dir in user_dir.iterdir(): + if not encoded_dir.is_dir(): + continue + plan_file = encoded_dir / "plans" / f"{slug}.md" + if plan_file.is_file(): + try: + stat = plan_file.stat() + content = plan_file.read_text(encoding="utf-8") + encoded_name = encoded_dir.name + + title = None + for line in content.split("\n"): + stripped = line.strip() + if stripped.startswith("# "): + title = stripped[2:].strip() + break + + plans_index = _load_plans_index(dir_name, encoded_name) + linked_sessions = [] + if slug in plans_index: + sessions_map = plans_index[slug].get("sessions", {}) + for session_uuid, operation in sessions_map.items(): + linked_sessions.append({ + "uuid": session_uuid, + "operation": operation, + "remote_user_id": clean_user_id, + }) + + return RemotePlan( + slug=slug, + title=title, + content=content, + preview=content[:500] if content else "", + word_count=len(content.split()) if content else 0, + size_bytes=stat.st_size, + created=datetime.fromtimestamp(stat.st_mtime, tz=timezone.utc), + modified=datetime.fromtimestamp(stat.st_mtime, tz=timezone.utc), + remote_user_id=clean_user_id, + project_encoded_name=encoded_name, + linked_sessions=linked_sessions, + ) + except (PermissionError, OSError, UnicodeDecodeError) as e: + logger.debug("Failed to read remote plan %s/%s: %s", user_id, slug, e) + + return None + + +def clear_caches() -> None: + """Clear all remote plan caches. Used during testing.""" + _plans_index_cache.clear() diff --git a/api/services/remote_sessions.py b/api/services/remote_sessions.py new file mode 100644 index 00000000..9348b03c --- /dev/null +++ b/api/services/remote_sessions.py @@ -0,0 +1,773 @@ +""" +Remote sessions service for Syncthing-synced session data. + +Directory structure (written by CLI packager, synced by Syncthing): + ~/.claude_karma/remote-sessions/{member_tag}/{encoded_name}/ + sessions/{uuid}.jsonl + sessions/{uuid}/subagents/... + todos/{uuid}-*.json + manifest.json + +The top-level directory under remote-sessions/ may be a bare ``user_id`` +(legacy) or a ``member_tag`` in ``{user_id}.{machine_tag}`` format. +Both formats are supported; ``parse_member_tag()`` extracts the user_id. + +The inbox path on the receiving machine uses the LOCAL encoded name, +so no path mapping is needed — the encoded_name in the directory IS +the local project's encoded name. + +The local user's directory is the outbox (sendonly) and should be skipped. +""" + +import json +import logging +import re +import time +from dataclasses import dataclass +from datetime import datetime +from pathlib import Path +from typing import Iterator, Optional + +from config import settings +from models import Session +from services.syncthing.folder_manager import parse_member_tag +from services.session_filter import SessionMetadata + +logger = logging.getLogger(__name__) + +# Cache for local user_id (TTL-based) +_local_user_cache: Optional[str] = None +_local_user_cache_time: float = 0.0 +_LOCAL_USER_TTL = 30.0 # seconds + +# Cache for project mapping (TTL-based) +_project_mapping_cache: Optional[dict] = None +_project_mapping_cache_time: float = 0.0 +_PROJECT_MAPPING_TTL = 30.0 # seconds + +# Cache for manifest worktree lookups (keyed by (user_id, encoded_name)) +_manifest_worktree_cache: dict[tuple[str, str], tuple[float, dict[str, Optional[str]]]] = {} +_MANIFEST_WORKTREE_TTL = 30.0 # seconds + +# Cache for remote titles (keyed by (user_id, encoded_name)) +_titles_cache: dict[tuple[str, str], tuple[float, dict[str, str]]] = {} +_TITLES_TTL = 30.0 # seconds + +# Cache for resolved user_id from manifest (keyed by dir_name) +_resolved_user_cache: dict[str, tuple[float, str]] = {} +_RESOLVED_USER_TTL = 60.0 # seconds + + +def invalidate_caches() -> None: + """Clear all in-memory caches. Called on sync reset.""" + global _local_user_cache, _local_user_cache_time + global _project_mapping_cache, _project_mapping_cache_time + global _manifest_worktree_cache, _titles_cache, _resolved_user_cache + _local_user_cache = None + _local_user_cache_time = 0.0 + _project_mapping_cache = None + _project_mapping_cache_time = 0.0 + _manifest_worktree_cache.clear() + _titles_cache.clear() + _resolved_user_cache.clear() + + +@dataclass +class RemoteSessionResult: + """Result of finding a remote session.""" + + session: Session + user_id: str + machine_id: str + local_encoded_name: str + + +def _read_sync_config() -> Optional[dict]: + """Read sync-config.json from karma base directory.""" + config_path = settings.karma_base / "sync-config.json" + if not config_path.exists(): + return None + try: + with open(config_path) as f: + return json.load(f) + except (json.JSONDecodeError, OSError) as e: + logger.warning("Failed to read sync-config.json: %s", e) + return None + + +def _get_local_user_id() -> Optional[str]: + """Get local user_id from sync-config.json (cached with TTL).""" + global _local_user_cache, _local_user_cache_time + + now = time.monotonic() + if _local_user_cache is not None and (now - _local_user_cache_time) < _LOCAL_USER_TTL: + return _local_user_cache + + config = _read_sync_config() + _local_user_cache = config.get("user_id") if config else None + _local_user_cache_time = now + return _local_user_cache + + +def _is_local_user(dir_name: str, local_user_id: Optional[str]) -> bool: + """Check if a directory name belongs to the local user. + + Handles both bare user_id directories (e.g. ``jayant``) and + member_tag directories (e.g. ``jayant.mac-mini``) by extracting + the user_id portion via :func:`parse_member_tag`. + """ + if not local_user_id: + return False + if dir_name == local_user_id: + return True + # member_tag format: user_id.machine_tag + parsed_uid, _ = parse_member_tag(dir_name) + return parsed_uid == local_user_id + + +def get_project_mapping() -> dict[tuple[str, str], str]: + """ + Build mapping from (user_id, remote_encoded) -> local_encoded_name. + + Supports two config formats: + + 1. Legacy "paths" format (used in tests): + teams.{team}.projects.{name}.paths = {user_id: encoded_name} + + 2. Syncthing format (real config): + teams.{team}.projects.{name}.encoded_name = local_encoded + teams.{team}.syncthing_members = {member_name: {...}} + Inbox directories already use local encoded name, so mapping is identity. + + Returns: + Dict mapping (user_id, encoded_name) to local_encoded_name. + """ + global _project_mapping_cache, _project_mapping_cache_time + + now = time.monotonic() + if ( + _project_mapping_cache is not None + and (now - _project_mapping_cache_time) < _PROJECT_MAPPING_TTL + ): + return _project_mapping_cache + + config = _read_sync_config() + if not config: + _project_mapping_cache = {} + _project_mapping_cache_time = now + return _project_mapping_cache + + mapping: dict[tuple[str, str], str] = {} + local_user_id = config.get("user_id", config.get("local_user_id", "")) + + teams = config.get("teams", {}) + for _team_name, team_config in teams.items(): + projects = team_config.get("projects", {}) + for _project_name, project_config in projects.items(): + # Legacy format: paths dict mapping user_id -> encoded_name + paths = project_config.get("paths", {}) + if paths: + local_encoded = paths.get(local_user_id) + if not local_encoded: + continue + for user_id, encoded_path in paths.items(): + if user_id != local_user_id: + mapping[(user_id, encoded_path)] = local_encoded + continue + + # Syncthing format: encoded_name is the local encoded name + local_encoded = project_config.get("encoded_name", "") + if not local_encoded: + continue + + # Map each syncthing member to this project + syncthing_members = team_config.get("syncthing_members", {}) + for member_name in syncthing_members: + if member_name != local_user_id: + mapping[(member_name, local_encoded)] = local_encoded + + # Augment mapping with git_identity-based matching from SQLite + manifests + try: + from db.connection import create_read_connection + + db_conn = create_read_connection() + try: + rows = db_conn.execute( + "SELECT encoded_name, git_identity FROM projects" + " WHERE git_identity IS NOT NULL ORDER BY encoded_name" + ).fetchall() + # When multiple projects share the same git_identity (e.g. monorepo + # and old submodule dirs), prefer the one registered in sync_team_projects. + # Secondary tiebreaker: shorter encoded_name (typically the monorepo root). + team_projects = { + r[0] + for r in db_conn.execute( + "SELECT project_encoded_name FROM sync_team_projects" + ).fetchall() + } + git_lookup: dict[str, str] = {} + for row in rows: + encoded, git_id = row[0], row[1] + existing = git_lookup.get(git_id) + if existing is None: + git_lookup[git_id] = encoded + elif encoded in team_projects and existing not in team_projects: + git_lookup[git_id] = encoded + elif encoded in team_projects and existing in team_projects: + # Both in team — prefer shorter name (monorepo root) + if len(encoded) < len(existing): + git_lookup[git_id] = encoded + finally: + db_conn.close() + + if git_lookup: + remote_base = _get_remote_sessions_dir() + if remote_base.exists(): + for user_dir in remote_base.iterdir(): + if not user_dir.is_dir(): + continue + dir_name = user_dir.name + if _is_local_user(dir_name, local_user_id): + continue + for encoded_dir in user_dir.iterdir(): + if not encoded_dir.is_dir(): + continue + manifest_path = encoded_dir / "manifest.json" + if not manifest_path.exists(): + continue + try: + with open(manifest_path) as f: + manifest = json.load(f) + remote_git_id = manifest.get("git_identity") + if remote_git_id and remote_git_id in git_lookup: + remote_encoded = encoded_dir.name + local_encoded = git_lookup[remote_git_id] + if (dir_name, remote_encoded) not in mapping: + mapping[(dir_name, remote_encoded)] = local_encoded + except (json.JSONDecodeError, OSError): + continue + + # Also scan v4 karma-out--* inbox directories for manifests + karma_base = settings.karma_base + local_member_tag = None + machine_tag = config.get("machine_tag", "") + if local_user_id and machine_tag: + local_member_tag = f"{local_user_id}.{machine_tag}" + + for inbox_dir in karma_base.iterdir(): + if not inbox_dir.is_dir(): + continue + dname = inbox_dir.name + if not dname.startswith("karma-out--"): + continue + rest = dname[len("karma-out--"):] + parts = rest.split("--", 1) + if len(parts) != 2: + continue + inbox_tag, _suffix = parts + # Skip our own outbox + if local_member_tag and inbox_tag == local_member_tag: + continue + manifest_path = inbox_dir / "manifest.json" + if not manifest_path.exists(): + continue + try: + with open(manifest_path) as f: + manifest = json.load(f) + remote_git_id = manifest.get("git_identity") + remote_encoded = manifest.get("project_encoded_name", "") + if remote_git_id and remote_git_id in git_lookup: + local_enc = git_lookup[remote_git_id] + if remote_encoded and (inbox_tag, remote_encoded) not in mapping: + mapping[(inbox_tag, remote_encoded)] = local_enc + except (json.JSONDecodeError, OSError): + continue + except Exception as e: + logger.debug("git_identity augmentation failed: %s", e) + + _project_mapping_cache = mapping + _project_mapping_cache_time = now + return mapping + + +def _get_remote_sessions_dir() -> Path: + """Get the remote-sessions base directory.""" + return settings.karma_base / "remote-sessions" + + +def _resolve_user_id(user_dir: Path, conn=None) -> str: + """ + Resolve a clean user_id for a remote-sessions user directory. + + # NOTE: remote_user_id should always be member_tag format (e.g., "jay.mac"), not bare user_id. + + The directory name may be a machine hostname (e.g. 'Jayants-Mac-mini.local') + when Syncthing creates the folder. The manifest.json inside each project + subdirectory contains the canonical user_id set by the sender. + + Resolution order (most reliable first): + 1. manifest.device_id → sync_members DB lookup (DB is authoritative — + handshake healing keeps it current, while manifest may be stale) + 2. manifest.user_id (canonical sender identity, fallback when no DB match) + 3. directory name (last resort) + + Reads the first manifest.json found under the user_dir, caches the result. + Falls back to directory name if no manifest is available. + + Args: + user_dir: Path to a user directory under remote-sessions/. + conn: Optional SQLite connection for device_id → member lookup. + """ + dir_name = user_dir.name + now = time.monotonic() + + cached = _resolved_user_cache.get(dir_name) + if cached is not None: + cache_time, cached_id = cached + if (now - cache_time) < _RESOLVED_USER_TTL: + return cached_id + + # Scan project subdirs for a manifest + resolved = dir_name + try: + for project_dir in user_dir.iterdir(): + if not project_dir.is_dir(): + continue + manifest_path = project_dir / "manifest.json" + if manifest_path.exists(): + with open(manifest_path) as f: + manifest = json.load(f) + + manifest_uid = manifest.get("user_id") + device_id = manifest.get("device_id") + + # Priority 1: DB lookup via device_id — DB is authoritative + # because handshake healing keeps member names current, + # while manifest user_id may be stale (written at package time). + if device_id and conn is not None: + try: + from repositories.member_repo import MemberRepository + members = MemberRepository().get_by_device(conn, device_id) + if members: + db_name = members[0].member_tag + if manifest_uid and db_name != manifest_uid: + logger.debug( + "DB name '%s' differs from manifest '%s' for device %s " + "— trusting DB (handshake-healed)", + db_name, manifest_uid, device_id[:20], + ) + resolved = db_name + break + except Exception: + pass + + # Priority 2: manifest user_id (no DB match by device_id) + if manifest_uid: + resolved = manifest_uid + # Normalize bare user_id to full member_tag via DB + if conn is not None and "." not in manifest_uid: + try: + from repositories.member_repo import MemberRepository + members = MemberRepository().get_by_user_id(conn, manifest_uid) + if members: + resolved = members[0].member_tag + except Exception: + pass + break + except (json.JSONDecodeError, OSError) as e: + logger.debug("Failed to resolve user_id from manifest in %s: %s", dir_name, e) + + # If still unresolved (equals dir_name) and dir_name looks like a + # member_tag (contains a dot), extract the user_id portion. + # Guard: only treat as member_tag if the machine_tag part is a valid + # sanitized tag ([a-z0-9-]+). Hostname suffixes like ".local" contain + # no uppercase or special chars but ARE valid — so also check that the + # user_id part looks like a karma username (no dots, no uppercase). + if resolved == dir_name and "." in dir_name: + parsed_uid, machine_part = parse_member_tag(dir_name) + # Valid member_tag: user_id has no dots AND machine_tag matches [a-z0-9-]+ + # Hostnames like "Bobs-Mac.local" fail because the user_id part has uppercase + # or the machine_tag is a known hostname suffix. + _HOSTNAME_SUFFIXES = ("local", "lan", "home", "internal", "localdomain") + if (parsed_uid and machine_part + and machine_part not in _HOSTNAME_SUFFIXES + and re.match(r"^[a-z0-9][a-z0-9-]*$", machine_part)): + resolved = parsed_uid + + # Final normalization: if resolved is a bare user_id (no dot), + # attempt to resolve to full member_tag via DB lookup. + if conn is not None and "." not in resolved: + try: + from repositories.member_repo import MemberRepository + members = MemberRepository().get_by_user_id(conn, resolved) + if members: + resolved = members[0].member_tag + except Exception: + pass + + _resolved_user_cache[dir_name] = (now, resolved) + return resolved + + +def _load_manifest_worktree_map( + user_id: str, encoded_name: str +) -> dict[str, Optional[str]]: + """ + Load manifest.json for a (user_id, encoded_name) pair and return + a mapping of uuid -> worktree_name. + + Results are cached with a TTL to avoid re-reading the manifest + for every session in the same project. + + Args: + user_id: Remote user identifier. + encoded_name: Encoded project directory name. + + Returns: + Dict mapping session UUID to worktree_name (may be None per session). + """ + cache_key = (user_id, encoded_name) + now = time.monotonic() + + cached = _manifest_worktree_cache.get(cache_key) + if cached is not None: + cache_time, cache_data = cached + if (now - cache_time) < _MANIFEST_WORKTREE_TTL: + return cache_data + + result: dict[str, Optional[str]] = {} + manifest_path = ( + _get_remote_sessions_dir() / user_id / encoded_name / "manifest.json" + ) + if manifest_path.exists(): + try: + with open(manifest_path) as f: + manifest = json.load(f) + for entry in manifest.get("sessions", []): + uuid = entry.get("uuid") + if uuid: + result[uuid] = entry.get("worktree_name") + except (json.JSONDecodeError, OSError) as e: + logger.debug( + "Failed to load manifest for %s/%s: %s", + user_id, + encoded_name, + e, + ) + + _manifest_worktree_cache[cache_key] = (now, result) + return result + + +def _load_remote_titles( + user_id: str, encoded_name: str +) -> dict[str, str]: + """ + Load titles.json for a (user_id, encoded_name) pair and return + a mapping of uuid -> title_string. + + Results are cached with a TTL to avoid re-reading the file + for every session in the same project. + + Args: + user_id: Remote user identifier. + encoded_name: Encoded project directory name. + + Returns: + Dict mapping session UUID to title string. + """ + cache_key = (user_id, encoded_name) + now = time.monotonic() + + cached = _titles_cache.get(cache_key) + if cached is not None: + cache_time, cache_data = cached + if (now - cache_time) < _TITLES_TTL: + return cache_data + + result: dict[str, str] = {} + titles_path = ( + _get_remote_sessions_dir() / user_id / encoded_name / "titles.json" + ) + if titles_path.exists(): + try: + with open(titles_path) as f: + data = json.load(f) + if data.get("version") == 1: + titles = data.get("titles", {}) + for uuid, entry in titles.items(): + if isinstance(entry, dict): + title_str = entry.get("title") + if title_str: + result[uuid] = title_str + elif isinstance(entry, str): + result[uuid] = entry + except (json.JSONDecodeError, OSError) as e: + logger.debug( + "Failed to load titles for %s/%s: %s", + user_id, + encoded_name, + e, + ) + + _titles_cache[cache_key] = (now, result) + return result + + +def find_remote_session(uuid: str) -> Optional[RemoteSessionResult]: + """ + Search for a session UUID in remote-sessions directories. + + Searches: remote-sessions/{user_id}/{encoded_name}/sessions/{uuid}.jsonl + + Skips the local user's outbox directory. + + Args: + uuid: Session UUID to find. + + Returns: + RemoteSessionResult if found, None otherwise. + """ + remote_base = _get_remote_sessions_dir() + if not remote_base.exists(): + return None + + local_user = _get_local_user_id() + + for user_dir in remote_base.iterdir(): + if not user_dir.is_dir(): + continue + dir_name = user_dir.name + user_id = _resolve_user_id(user_dir) + + # Skip local user's outbox (check dir name, resolved id, and member_tag) + if _is_local_user(dir_name, local_user) or user_id == local_user: + continue + + for encoded_dir in user_dir.iterdir(): + if not encoded_dir.is_dir(): + continue + encoded_name = encoded_dir.name + + sessions_dir = encoded_dir / "sessions" + if not sessions_dir.exists(): + continue + + jsonl_path = sessions_dir / f"{uuid}.jsonl" + if not jsonl_path.exists(): + continue + + try: + session = Session.from_path( + jsonl_path, + claude_base_dir=encoded_dir, + ) + return RemoteSessionResult( + session=session, + user_id=user_id, + machine_id=dir_name, + local_encoded_name=encoded_name, + ) + except Exception as e: + logger.warning( + "Failed to load remote session %s from %s: %s", + uuid, + jsonl_path, + e, + ) + continue + + return None + + +def list_remote_sessions_for_project(local_encoded: str) -> list[SessionMetadata]: + """ + Find remote sessions that map to a local project. + + Walks remote-sessions/{user_id}/{local_encoded}/sessions/ for all + remote users (skipping local user's outbox). + + Args: + local_encoded: Local project encoded name. + + Returns: + List of SessionMetadata with source="remote". + """ + remote_base = _get_remote_sessions_dir() + if not remote_base.exists(): + return [] + + local_user = _get_local_user_id() + results: list[SessionMetadata] = [] + + for user_dir in remote_base.iterdir(): + if not user_dir.is_dir(): + continue + dir_name = user_dir.name + user_id = _resolve_user_id(user_dir) + + # Skip local user's outbox (check dir name, resolved id, and member_tag) + if _is_local_user(dir_name, local_user) or user_id == local_user: + continue + + sessions_dir = user_dir / local_encoded / "sessions" + if not sessions_dir.exists(): + continue + + # Load manifest once per (dir_name, project) for worktree attribution + wt_map = _load_manifest_worktree_map(dir_name, local_encoded) + # Load titles once per (dir_name, project) + titles_map = _load_remote_titles(dir_name, local_encoded) + + for jsonl_path in sessions_dir.glob("*.jsonl"): + uuid = jsonl_path.stem + if uuid.startswith("agent-"): + continue + + meta = _build_remote_metadata( + jsonl_path=jsonl_path, + uuid=uuid, + local_encoded=local_encoded, + project_dir=sessions_dir, + user_id=user_id, + machine_id=dir_name, + worktree_name=wt_map.get(uuid), + title=titles_map.get(uuid), + ) + if meta: + results.append(meta) + + return results + + +def iter_all_remote_session_metadata() -> Iterator[SessionMetadata]: + """ + Iterate over all remote session metadata. + + Walks remote-sessions/{user_id}/{encoded_name}/sessions/ for all + remote users. Used for global /sessions/all endpoint. + + Yields: + SessionMetadata with source="remote" for each remote session. + """ + remote_base = _get_remote_sessions_dir() + if not remote_base.exists(): + return + + local_user = _get_local_user_id() + + for user_dir in remote_base.iterdir(): + if not user_dir.is_dir(): + continue + dir_name = user_dir.name + user_id = _resolve_user_id(user_dir) + + # Skip local user's outbox (check dir name, resolved id, and member_tag) + if _is_local_user(dir_name, local_user) or user_id == local_user: + continue + + for encoded_dir in user_dir.iterdir(): + if not encoded_dir.is_dir(): + continue + encoded_name = encoded_dir.name + + sessions_dir = encoded_dir / "sessions" + if not sessions_dir.exists(): + continue + + # Load manifest once per (dir_name, project) for worktree attribution + wt_map = _load_manifest_worktree_map(dir_name, encoded_name) + # Load titles once per (dir_name, project) + titles_map = _load_remote_titles(dir_name, encoded_name) + + for jsonl_path in sessions_dir.glob("*.jsonl"): + uuid = jsonl_path.stem + if uuid.startswith("agent-"): + continue + + meta = _build_remote_metadata( + jsonl_path=jsonl_path, + uuid=uuid, + local_encoded=encoded_name, + project_dir=sessions_dir, + user_id=user_id, + machine_id=dir_name, + worktree_name=wt_map.get(uuid), + title=titles_map.get(uuid), + ) + if meta: + yield meta + + +def _parse_timestamp(ts: Optional[str]) -> Optional[datetime]: + """Parse an ISO timestamp string to datetime.""" + if not ts: + return None + try: + from utils import normalize_timezone + + dt = datetime.fromisoformat(ts) + return normalize_timezone(dt) + except (ValueError, TypeError): + return None + + +def _build_remote_metadata( + *, + jsonl_path: Path, + uuid: str, + local_encoded: str, + project_dir: Path, + user_id: str, + machine_id: str, + worktree_name: Optional[str] = None, + title: Optional[str] = None, +) -> Optional[SessionMetadata]: + """ + Build SessionMetadata from a remote JSONL file. + + Reads only the first and last lines of the JSONL for timestamps, + avoiding full session parsing for performance (lazy loading pattern). + """ + try: + # Read first and last lines only — avoid full parse + with open(jsonl_path) as f: + first_line = f.readline().strip() + if not first_line: + return None + + # Count lines and find last + message_count = 1 + last_line = first_line + for line in f: + stripped = line.strip() + if stripped: + last_line = stripped + message_count += 1 + + first = json.loads(first_line) + last = json.loads(last_line) + + start_time = _parse_timestamp(first.get("timestamp")) + end_time = _parse_timestamp(last.get("timestamp")) + slug = first.get("sessionId") + + return SessionMetadata( + uuid=uuid, + encoded_name=local_encoded, + project_path=str(project_dir), + message_count=message_count, + start_time=start_time, + end_time=end_time, + slug=slug, + initial_prompt=None, # Skip for performance + git_branch=None, + session_titles=[title] if title else None, + worktree_name=worktree_name, + source="remote", + remote_user_id=user_id, + remote_machine_id=machine_id, + ) + except Exception as e: + logger.warning("Failed to build metadata for remote session %s: %s", uuid, e) + return None diff --git a/api/services/session_filter.py b/api/services/session_filter.py index 10e1ae11..4601fff5 100644 --- a/api/services/session_filter.py +++ b/api/services/session_filter.py @@ -38,6 +38,14 @@ class SessionStatus(str, Enum): ERROR = "error" +class SessionSource(str, Enum): + """Source filter for session search.""" + + ALL = "all" + LOCAL = "local" + REMOTE = "remote" + + @dataclass class SessionMetadata: """ @@ -59,6 +67,12 @@ class SessionMetadata: # Session title/summary for display (from sessions-index.json summary field) title: Optional[str] = None session_titles: Optional[list] = None # All session titles (from title cache) + # Worktree attribution + worktree_name: Optional[str] = None + # Remote sync fields + source: Optional[str] = None # "local" or "remote" (None = local) + remote_user_id: Optional[str] = None + remote_machine_id: Optional[str] = None # Lazy session loader - only called when we need the full Session _session: Optional["Session"] = None @@ -145,6 +159,7 @@ class SessionFilter: search: Optional[str] = None search_scope: SearchScope = SearchScope.BOTH status: SessionStatus = SessionStatus.ALL + source: SessionSource = SessionSource.ALL date_from: Optional[datetime] = None date_to: Optional[datetime] = None project_encoded_name: Optional[str] = None @@ -254,6 +269,12 @@ def matches_metadata(self, meta: SessionMetadata) -> bool: if self.branch not in branches: return False + # Source filter (local/remote) + if self.source != SessionSource.ALL: + meta_source = meta.source or "local" + if meta_source != self.source.value: + return False + # Search filter with token-based AND logic if self._search_tokens: # Build combined searchable text based on scope diff --git a/api/services/session_lookup.py b/api/services/session_lookup.py index cb78a75f..3a18f742 100644 --- a/api/services/session_lookup.py +++ b/api/services/session_lookup.py @@ -6,6 +6,7 @@ service with consistent error handling and return types. """ +import logging from dataclasses import dataclass from pathlib import Path from typing import Optional @@ -14,6 +15,8 @@ from models import Agent, Session from utils import is_encoded_project_dir +logger = logging.getLogger(__name__) + @dataclass class SessionLookupResult: @@ -30,6 +33,16 @@ class SubagentLookupResult: agent: Agent parent_session: Session project_encoded_name: str + remote_user_id: Optional[str] = None + + +@dataclass +class _ResolvedPath: + """Resolved JSONL path with source metadata.""" + + jsonl_path: Path + project_encoded_name: str + remote_user_id: Optional[str] = None def _is_valid_session_filename(path: Path) -> bool: @@ -38,62 +51,151 @@ def _is_valid_session_filename(path: Path) -> bool: Valid session files have UUID-like stems with dashes and alphanumeric characters. This filters out non-session files like sessions-index.json. - - Args: - path: Path to check - - Returns: - True if the filename looks like a valid session file """ stem = path.stem - # Must contain dashes (UUID format) if "-" not in stem: return False - # After removing dashes/underscores, should be alphanumeric if not stem.replace("-", "").replace("_", "").isalnum(): return False return True -def find_session_with_project(uuid: str) -> Optional[SessionLookupResult]: +def _resolve_from_db(uuid: str) -> Optional[_ResolvedPath]: """ - Find a session by UUID and return both session and project encoded name. + Resolve a session's JSONL path using the DB. - Searches all projects in ~/.claude/projects/ for a session with the given UUID. + The DB stores `source` ('local' or 'remote') and `remote_user_id`, + so we can construct the correct path directly without scanning. + """ + try: + from db.connection import sqlite_read + + with sqlite_read() as conn: + if conn is None: + return None + row = conn.execute( + "SELECT project_encoded_name, source_encoded_name, " + "source, remote_user_id FROM sessions WHERE uuid = ?", + (uuid,), + ).fetchone() + if not row: + return None + + project_enc = row["project_encoded_name"] + source = row["source"] or "local" + + if source == "remote": + remote_uid = row["remote_user_id"] + if not remote_uid: + logger.warning( + "Session %s has source=remote but no remote_user_id", uuid + ) + return None + jsonl_path = ( + settings.karma_base + / "remote-sessions" + / remote_uid + / project_enc + / "sessions" + / f"{uuid}.jsonl" + ) + if jsonl_path.exists(): + return _ResolvedPath(jsonl_path, project_enc, remote_uid) + else: + source_enc = row["source_encoded_name"] or project_enc + jsonl_path = settings.projects_dir / source_enc / f"{uuid}.jsonl" + if jsonl_path.exists(): + return _ResolvedPath(jsonl_path, project_enc) + except Exception: + logger.debug( + "DB path resolution failed for session %s", uuid, exc_info=True + ) - Args: - uuid: Session UUID to find + return None - Returns: - SessionLookupResult with session and project info, or None if not found. + +def _resolve_from_filesystem( + uuid: str, encoded_name: Optional[str] = None +) -> Optional[_ResolvedPath]: + """ + Fallback: find a session JSONL by scanning the filesystem. + + Used when DB is unavailable or session isn't indexed yet. + Searches the specific project dir first (with worktree fallback), + then all project dirs, then remote-sessions. """ projects_dir = settings.projects_dir - if not projects_dir.exists(): - return None - for encoded_dir in projects_dir.iterdir(): - if encoded_dir.is_dir() and is_encoded_project_dir(encoded_dir.name): - jsonl_path = encoded_dir / f"{uuid}.jsonl" - if jsonl_path.exists(): - return SessionLookupResult( - session=Session.from_path(jsonl_path), - project_encoded_name=encoded_dir.name, - ) + # If we have a hint, check that project dir first (+ worktrees) + if encoded_name: + path = _find_session_jsonl(projects_dir, encoded_name, uuid) + if path: + return _ResolvedPath(path, encoded_name) + + # Scan all project dirs + if projects_dir.exists(): + for encoded_dir in projects_dir.iterdir(): + if encoded_dir.is_dir() and encoded_dir.name.startswith("-"): + jsonl_path = encoded_dir / f"{uuid}.jsonl" + if jsonl_path.exists(): + return _ResolvedPath(jsonl_path, encoded_dir.name) + + # Scan remote-sessions dirs + from services.remote_sessions import find_remote_session + + remote = find_remote_session(uuid) + if remote: + return _ResolvedPath( + remote.session.jsonl_path, + remote.local_encoded_name, + remote.user_id, + ) + return None +def _resolve_session( + uuid: str, encoded_name: Optional[str] = None +) -> Optional[_ResolvedPath]: + """ + Resolve a session's JSONL path. DB first, filesystem fallback. + + This is the single entry point for all session path resolution. + """ + return _resolve_from_db(uuid) or _resolve_from_filesystem(uuid, encoded_name) + + +def find_session_with_project(uuid: str) -> Optional[SessionLookupResult]: + """ + Find a session by UUID and return both session and project encoded name. + + Uses DB for O(1) lookup, falls back to filesystem scan. + """ + resolved = _resolve_session(uuid) + if not resolved: + return None + + # For remote sessions, set claude_base_dir to the project-level dir + # so that todos_dir, tasks_dir, debug_log, etc. resolve correctly. + # Path layout: .../remote-sessions/{user}/{encoded}/sessions/{uuid}.jsonl + # claude_base_dir should be: .../remote-sessions/{user}/{encoded}/ + claude_base = None + if resolved.remote_user_id: + claude_base = resolved.jsonl_path.parent.parent + + session = Session.from_path(resolved.jsonl_path, claude_base_dir=claude_base) + return SessionLookupResult( + session=session, + project_encoded_name=resolved.project_encoded_name, + ) + + def find_session(uuid: str) -> Optional[Session]: """ Find a session by UUID across all projects. Convenience wrapper around find_session_with_project() that returns just the Session object. - - Args: - uuid: Session UUID to find - - Returns: - Session if found, None otherwise. """ result = find_session_with_project(uuid) return result.session if result else None @@ -103,18 +205,35 @@ def find_session_by_message_uuid(message_uuid: str) -> Optional[SessionLookupRes """ Find a session that contains a message with the given UUID. - Searches all sessions across all projects for a message with matching UUID. - Used to link continuation marker sessions to their continuation sessions. - - Note: This is an expensive operation that may scan many JSONL files. - - Args: - message_uuid: The UUID of a message to search for - - Returns: - SessionLookupResult with session and project info, or None if not found. + Uses DB message_uuids table for O(1) lookup when available, + falls back to O(n*m) JSONL scan. """ projects_dir = settings.projects_dir + + # DB fast path: O(1) lookup via message_uuids table + try: + from db.connection import sqlite_read + from db.queries import query_session_by_message_uuid as db_lookup + + with sqlite_read() as conn: + if conn is not None: + row = db_lookup(conn, message_uuid) + if row: + session_uuid = row["session_uuid"] + resolved = _resolve_session(session_uuid) + if resolved: + return SessionLookupResult( + session=Session.from_path(resolved.jsonl_path), + project_encoded_name=resolved.project_encoded_name, + ) + except Exception: + logger.debug( + "DB fast path failed for message UUID %s, falling back to scan", + message_uuid, + exc_info=True, + ) + + # JSONL fallback: O(n*m) scan of all sessions if not projects_dir.exists(): return None @@ -122,14 +241,12 @@ def find_session_by_message_uuid(message_uuid: str) -> Optional[SessionLookupRes if not encoded_dir.is_dir() or not is_encoded_project_dir(encoded_dir.name): continue - # Search all session JSONL files in this project for jsonl_path in encoded_dir.glob("*.jsonl"): if not _is_valid_session_filename(jsonl_path): continue try: session = Session.from_path(jsonl_path) - # Search messages for matching UUID for msg in session.iter_messages(): if hasattr(msg, "uuid") and msg.uuid == message_uuid: return SessionLookupResult( @@ -137,7 +254,6 @@ def find_session_by_message_uuid(message_uuid: str) -> Optional[SessionLookupRes project_encoded_name=encoded_dir.name, ) except Exception: - # Skip invalid session files continue return None @@ -153,14 +269,6 @@ def _find_session_jsonl( directory (e.g., -Users-...-worktrees-karma-focused-jepsen/) but the UI routes through the real project's encoded_name. This function handles the fallback transparently. - - Args: - projects_dir: Root ~/.claude/projects/ directory - encoded_name: Encoded project directory name (may be the real project) - session_uuid: Session UUID to find - - Returns: - Path to the session JSONL file, or None if not found. """ # Primary: check the project directory itself session_jsonl = projects_dir / encoded_name / f"{session_uuid}.jsonl" @@ -184,29 +292,17 @@ def find_subagent( """ Find a subagent by project, session, and agent ID. - Supports worktree-grouped sessions: when the UI navigates via the real - project's encoded_name but the session JSONL lives in a worktree directory, - this function searches worktree dirs as a fallback. - - Args: - encoded_name: Encoded project directory name - session_uuid: Parent session UUID - agent_id: Short hex agent ID - - Returns: - SubagentLookupResult with agent, parent session, and project info, - or None if not found. + Uses DB to determine session source (local vs remote) and resolve + the correct JSONL path directly. Falls back to filesystem scan + when DB is unavailable. """ - projects_dir = settings.projects_dir - - # Find parent session (searches worktree dirs if needed) - session_jsonl = _find_session_jsonl(projects_dir, encoded_name, session_uuid) - if not session_jsonl: + resolved = _resolve_session(session_uuid, encoded_name) + if not resolved: return None - parent_session = Session.from_path(session_jsonl) + parent_session = Session.from_path(resolved.jsonl_path) - # Find subagent + # Find subagent in the parent session's subagents dir subagents_dir = parent_session.subagents_dir agent_jsonl = subagents_dir / f"agent-{agent_id}.jsonl" @@ -218,5 +314,6 @@ def find_subagent( return SubagentLookupResult( agent=agent, parent_session=parent_session, - project_encoded_name=encoded_name, + project_encoded_name=resolved.project_encoded_name, + remote_user_id=resolved.remote_user_id, ) diff --git a/api/services/session_relationships.py b/api/services/session_relationships.py index 378d0324..1e52237b 100644 --- a/api/services/session_relationships.py +++ b/api/services/session_relationships.py @@ -364,8 +364,12 @@ def build_chain(self, session_uuid: str) -> SessionChain: # Get initial prompt from first user message initial_prompt = None for msg in session.iter_user_messages(): - initial_prompt = msg.content[:200] if msg.content else None - break + if msg.content: + from utils import extract_prompt_from_content + prompt = extract_prompt_from_content(msg.content) + if prompt: + initial_prompt = prompt[:200] + break node = SessionChainNode( uuid=session.uuid, diff --git a/api/services/subagent_types.py b/api/services/subagent_types.py index 10efc081..6de60446 100644 --- a/api/services/subagent_types.py +++ b/api/services/subagent_types.py @@ -25,11 +25,15 @@ AGENT_ID_PATTERN = re.compile(r"agentId:\s*([a-fA-F0-9]+)") -def get_all_subagent_types(jsonl_path: Path, subagents_dir: Path | None = None) -> dict[str, str]: +def get_all_subagent_metadata( + jsonl_path: Path, subagents_dir: Path | None = None +) -> tuple[dict[str, str], dict[str, str]]: """ - Extract agent_id -> subagent_type mapping from a session and its subagents. + Extract agent_id -> subagent_type AND agent_id -> display_name mappings + from a session and its subagents in a single pass over all files. - Four-phase approach: + Five-phase approach: + 0. Read .meta.json sidecar files (most reliable — written by Claude Code) 1. Scan parent session JSONL for Task tool_use / tool_result pairs 2. Scan ALL subagent JSONLs (catches nested agent spawns) 3. Classify remaining agents by ID prefix (system agents) @@ -40,56 +44,112 @@ def get_all_subagent_types(jsonl_path: Path, subagents_dir: Path | None = None) subagents_dir: Path to the subagents/ directory (may not exist) Returns: - Dict mapping agent_id -> subagent_type + Tuple of (types_dict, names_dict) where: + - types_dict maps agent_id -> subagent_type + - names_dict maps agent_id -> display_name (only agents that have a name) """ - result: dict[str, str] = {} - - # Phase 1: Scan parent session JSONL - result.update(_extract_types_from_raw_jsonl(jsonl_path)) + types: dict[str, str] = {} + names: dict[str, str] = {} # Collect agent files once if subagents_dir exists agent_files = [] if subagents_dir and subagents_dir.exists(): agent_files = list(subagents_dir.glob("agent-*.jsonl")) - # Phase 2: Scan ALL subagent JSONLs (catches nested agents) + # Phase 0: Read .meta.json sidecar files (highest priority) + for agent_file in agent_files: + meta_path = agent_file.with_suffix(".meta.json") + if not meta_path.exists(): + continue + try: + with open(meta_path, "r") as f: + meta = json.loads(f.read()) + agent_id = agent_file.stem.removeprefix("agent-") + agent_type = meta.get("agentType") + if agent_type: + types[agent_id] = agent_type + name = meta.get("name") + if name: + names[agent_id] = name + except (OSError, IOError, json.JSONDecodeError) as e: + logger.debug("Error reading meta.json %s: %s", meta_path, e) + + # Phase 1: Scan parent session JSONL (don't overwrite Phase 0 results) + phase1_types, phase1_names = _extract_metadata_from_raw_jsonl(jsonl_path) + for agent_id, agent_type in phase1_types.items(): + if agent_id not in types: + types[agent_id] = agent_type + for agent_id, name in phase1_names.items(): + if agent_id not in names: + names[agent_id] = name + + # Phase 2: Scan ALL subagent JSONLs (catches nested agents, don't overwrite earlier phases) for agent_file in agent_files: - result.update(_extract_types_from_raw_jsonl(agent_file)) + file_types, file_names = _extract_metadata_from_raw_jsonl(agent_file) + for agent_id, agent_type in file_types.items(): + if agent_id not in types: + types[agent_id] = agent_type + for agent_id, name in file_names.items(): + if agent_id not in names: + names[agent_id] = name # Phase 3: Classify remaining by ID prefix for agent_file in agent_files: agent_id = agent_file.stem.removeprefix("agent-") - if agent_id not in result: - result[agent_id] = _classify_by_prefix(agent_id) + if agent_id not in types: + types[agent_id] = _classify_by_prefix(agent_id) # Phase 4: Classify remaining _unknown agents by first message content for agent_file in agent_files: agent_id = agent_file.stem.removeprefix("agent-") - if result.get(agent_id) == "_unknown": + if types.get(agent_id) == "_unknown": classified = _classify_by_first_message(agent_file) if classified: - result[agent_id] = classified + types[agent_id] = classified - return result + return types, names -def _extract_types_from_raw_jsonl(path: Path) -> dict[str, str]: +def get_all_subagent_types(jsonl_path: Path, subagents_dir: Path | None = None) -> dict[str, str]: """ - Parse a JSONL file line-by-line to extract Task tool call -> agent ID mappings. + Extract agent_id -> subagent_type mapping from a session and its subagents. + + Thin wrapper around get_all_subagent_metadata() for backward compatibility. - For assistant messages: finds Task tool_use blocks -> collects {tool_use_id: subagent_type} + Args: + jsonl_path: Path to the parent session's JSONL file + subagents_dir: Path to the subagents/ directory (may not exist) + + Returns: + Dict mapping agent_id -> subagent_type + """ + types, _names = get_all_subagent_metadata(jsonl_path, subagents_dir) + return types + + +def _extract_metadata_from_raw_jsonl(path: Path) -> tuple[dict[str, str], dict[str, str]]: + """ + Parse a JSONL file line-by-line to extract Task tool call -> agent ID mappings + for both subagent_type and display_name in a single pass. + + For assistant messages: finds Task tool_use blocks -> collects + {tool_use_id: (subagent_type, display_name)} For user messages: finds tool_result entries whose tool_use_id matches a known Task call - -> extracts agentId from the result text content + -> extracts agentId from the result text content Key invariant: Only extracts agentId from tool_result entries whose tool_use_id matches a known Task tool call. This prevents double-counting from Bash output or other incidental mentions of agent IDs. Returns: - Dict mapping agent_id -> subagent_type + Tuple of (types_dict, names_dict) where: + - types_dict maps agent_id -> subagent_type + - names_dict maps agent_id -> display_name (only agents that have a name) """ - task_tools: dict[str, str] = {} # tool_use_id -> subagent_type + # tool_use_id -> (subagent_type, display_name_or_None) + task_tools: dict[str, tuple[str, str | None]] = {} agent_id_to_type: dict[str, str] = {} + agent_id_to_name: dict[str, str] = {} try: with open(path, "r", encoding="utf-8", errors="replace") as f: @@ -106,20 +166,20 @@ def _extract_types_from_raw_jsonl(path: Path) -> dict[str, str]: if msg_type == "assistant": _collect_task_tools(msg, task_tools) elif msg_type == "user": - _match_tool_results(msg, task_tools, agent_id_to_type) + _match_tool_results(msg, task_tools, agent_id_to_type, agent_id_to_name) except (OSError, IOError) as e: logger.debug("Error reading JSONL %s: %s", path, e) - return agent_id_to_type + return agent_id_to_type, agent_id_to_name -def _collect_task_tools(msg: dict, task_tools: dict[str, str]) -> None: +def _collect_task_tools(msg: dict, task_tools: dict[str, tuple[str, str | None]]) -> None: """ Extract Task tool_use blocks from an assistant message. - Looks for content blocks with type="tool_use" and name="Task", - then stores tool_use_id -> subagent_type from the input. + Looks for content blocks with type="tool_use" and name="Task" or "Agent", + then stores tool_use_id -> (subagent_type, display_name) from the input. """ content = msg.get("message", {}).get("content", []) if isinstance(content, str): @@ -130,15 +190,18 @@ def _collect_task_tools(msg: dict, task_tools: dict[str, str]) -> None: continue if block.get("type") == "tool_use" and block.get("name") in ("Task", "Agent"): tool_use_id = block.get("id") - subagent_type = (block.get("input") or {}).get("subagent_type") - if tool_use_id and subagent_type: - task_tools[tool_use_id] = subagent_type + tool_input = block.get("input") or {} + subagent_type = tool_input.get("subagent_type") or "general-purpose" + display_name = tool_input.get("name") # May be None + if tool_use_id: + task_tools[tool_use_id] = (subagent_type, display_name) def _match_tool_results( msg: dict, - task_tools: dict[str, str], + task_tools: dict[str, tuple[str, str | None]], agent_id_to_type: dict[str, str], + agent_id_to_name: dict[str, str], ) -> None: """ Match tool_result entries in a user message to known Task tool calls. @@ -146,17 +209,19 @@ def _match_tool_results( User messages have a "content" field that is either a string or a list of content blocks. Each block may be a tool_result with a tool_use_id. If that tool_use_id matches a known Task call, extract agentId from the - text content of the result. + text content of the result and map it to both type and name. """ content = msg.get("message", {}).get("content", []) if isinstance(content, str): # Simple string content — check if any task tool_use_id appears # (fallback for flattened content) - for tid, subagent_type in task_tools.items(): + for tid, (subagent_type, display_name) in task_tools.items(): if tid in content: match = AGENT_ID_PATTERN.search(content) if match: agent_id_to_type[match.group(1)] = subagent_type + if display_name: + agent_id_to_name[match.group(1)] = display_name return for block in content: @@ -185,7 +250,10 @@ def _match_tool_results( match = AGENT_ID_PATTERN.search(text) if match: - agent_id_to_type[match.group(1)] = task_tools[tool_use_id] + subagent_type, display_name = task_tools[tool_use_id] + agent_id_to_type[match.group(1)] = subagent_type + if display_name: + agent_id_to_name[match.group(1)] = display_name def _classify_by_prefix(agent_id: str) -> str: diff --git a/api/services/sync/__init__.py b/api/services/sync/__init__.py new file mode 100644 index 00000000..a61d4d07 --- /dev/null +++ b/api/services/sync/__init__.py @@ -0,0 +1,8 @@ +"""Sync service layer — pairing, reconciliation, and metadata helpers.""" + +from services.sync.pairing_service import PairingInfo, PairingService + +__all__ = [ + "PairingInfo", + "PairingService", +] diff --git a/api/services/sync/metadata_service.py b/api/services/sync/metadata_service.py new file mode 100644 index 00000000..472f653c --- /dev/null +++ b/api/services/sync/metadata_service.py @@ -0,0 +1,214 @@ +"""Metadata folder read/write for P2P team state synchronization. + +Each team has a metadata folder (karma-meta--{team}). Members write their +own state files. Leader writes team.json and removal signals. + +Member state files use a unified schema — all fields coexist: + {member_tag, device_id, user_id, machine_tag, status, projects, subscriptions, updated_at} +write_member_state() uses read-merge-write to preserve fields across callers. +""" +from __future__ import annotations + +import json +import os +from datetime import datetime, timezone +from pathlib import Path +from typing import TYPE_CHECKING + +if TYPE_CHECKING: + from domain.member import Member + from domain.team import Team + + +import re + +_SAFE_PATH_COMPONENT = re.compile(r"^[a-zA-Z0-9._-]+$") + + +def _validate_path_component(value: str, label: str) -> None: + """Reject values that could escape their intended directory.""" + if not value or ".." in value or not _SAFE_PATH_COMPONENT.match(value): + raise ValueError(f"Unsafe {label}: {value!r}") + + +class MetadataService: + def __init__(self, meta_base: Path): + self.meta_base = meta_base + + def _team_dir(self, team_name: str) -> Path: + _validate_path_component(team_name, "team_name") + return self.meta_base / f"karma-meta--{team_name}" + + # ------------------------------------------------------------------ + # Read + # ------------------------------------------------------------------ + + def read_team_json(self, team_name: str) -> dict | None: + """Read team.json from the metadata folder. Returns None if not found.""" + team_dir = self._team_dir(team_name) + team_json_path = team_dir / "team.json" + if not team_json_path.exists(): + return None + try: + return json.loads(team_json_path.read_text()) + except (json.JSONDecodeError, OSError): + return None + + def read_team_metadata(self, team_name: str) -> dict[str, dict]: + """Read all member states and removal signals from metadata folder. + + Returns dict keyed by member_tag. Special key '__removals' contains removal signals. + """ + team_dir = self._team_dir(team_name) + if not team_dir.exists(): + return {} + + result: dict[str, dict] = {} + + # Read member states + members_dir = team_dir / "members" + if members_dir.exists(): + for f in members_dir.glob("*.json"): + try: + data = json.loads(f.read_text()) + tag = data.get("member_tag", f.stem) + result[tag] = data + except (json.JSONDecodeError, KeyError): + continue + + # Read removal signals + removed_dir = team_dir / "removed" + if removed_dir.exists(): + removals = {} + for f in removed_dir.glob("*.json"): + try: + data = json.loads(f.read_text()) + tag = data.get("member_tag", f.stem) + removals[tag] = data + except (json.JSONDecodeError, KeyError): + continue + if removals: + result["__removals"] = removals + + return result + + # ------------------------------------------------------------------ + # Write — team.json + # ------------------------------------------------------------------ + + def _write_team_json(self, team: "Team") -> None: + """Write team.json only. Creates dirs if needed.""" + team_dir = self._team_dir(team.name) + team_dir.mkdir(parents=True, exist_ok=True) + (team_dir / "members").mkdir(exist_ok=True) + (team_dir / "removed").mkdir(exist_ok=True) + + team_data = { + "name": team.name, + "team_id": team.team_id, + "created_by": team.leader_member_tag, + "leader_device_id": team.leader_device_id, + "created_at": team.created_at.isoformat(), + } + (team_dir / "team.json").write_text(json.dumps(team_data, indent=2)) + + def purge_stale_removals(self, team_name: str) -> None: + """Delete all removal signal files from a team's metadata folder. + + Called during team creation to prevent stale signals from a previous + team incarnation with the same name from triggering auto-leave. + """ + _validate_path_component(team_name, "team_name") + removed_dir = self._team_dir(team_name) / "removed" + if not removed_dir.exists(): + return + for f in removed_dir.glob("*.json"): + try: + f.unlink() + except OSError: + pass + + # ------------------------------------------------------------------ + # Write — unified member state (read-merge-write) + # ------------------------------------------------------------------ + + def write_member_state(self, team_name: str, member_tag: str, **fields) -> None: + """Write or update a member's state file using read-merge-write. + + Reads the existing file (if any), merges in the provided fields, + and writes back. Fields not provided are preserved from the existing + file, eliminating the schema collision between basic info writes + (device_id, status) and enriched writes (projects, subscriptions). + + Always sets updated_at to now. + """ + _validate_path_component(member_tag, "member_tag") + team_dir = self._team_dir(team_name) + (team_dir / "members").mkdir(parents=True, exist_ok=True) + + member_file = team_dir / "members" / f"{member_tag}.json" + + # Read existing state + existing: dict = {} + if member_file.exists(): + try: + existing = json.loads(member_file.read_text()) + except (json.JSONDecodeError, OSError): + existing = {} + + # Merge: provided fields overwrite, unset fields preserved + existing["member_tag"] = member_tag + existing.update(fields) + existing["updated_at"] = datetime.now(timezone.utc).isoformat() + + # Atomic write via temp file + os.replace (POSIX-atomic) + tmp_file = member_file.with_suffix(".tmp") + tmp_file.write_text(json.dumps(existing, indent=2)) + os.replace(tmp_file, member_file) + + # ------------------------------------------------------------------ + # Write — convenience: team.json + member basic info + # ------------------------------------------------------------------ + + def write_team_state(self, team: "Team", members: list["Member"]) -> None: + """Write team.json + member state files (basic info, preserving enriched fields). + + Uses write_member_state() for each member, so existing projects/subscriptions + fields are preserved via read-merge-write. + """ + self._write_team_json(team) + + for member in members: + self.write_member_state( + team.name, + member.member_tag, + device_id=member.device_id, + user_id=member.user_id, + machine_tag=member.machine_tag, + status=member.status.value, + ) + + # ------------------------------------------------------------------ + # Write — removal signals + # ------------------------------------------------------------------ + + def write_removal_signal( + self, team_name: str, member_tag: str, *, removed_by: str, team_id: str = "" + ) -> None: + """Write removal signal to metadata folder. + + Includes ``team_id`` so the reconciler can ignore stale signals + from a previous team incarnation with the same name. + """ + _validate_path_component(member_tag, "member_tag") + team_dir = self._team_dir(team_name) + (team_dir / "removed").mkdir(parents=True, exist_ok=True) + + removal_data = { + "member_tag": member_tag, + "removed_by": removed_by, + "removed_at": datetime.now(timezone.utc).isoformat(), + "team_id": team_id, + } + removal_file = team_dir / "removed" / f"{member_tag}.json" + removal_file.write_text(json.dumps(removal_data, indent=2)) diff --git a/api/services/sync/packaging_service.py b/api/services/sync/packaging_service.py new file mode 100644 index 00000000..186e922b --- /dev/null +++ b/api/services/sync/packaging_service.py @@ -0,0 +1,191 @@ +"""Shared packaging service — used by both watcher and on-demand endpoint.""" +from __future__ import annotations + +import logging +import sqlite3 +import threading +from dataclasses import dataclass +from pathlib import Path +from typing import Any, Optional + +logger = logging.getLogger(__name__) + +_project_locks: dict[str, threading.Lock] = {} +_locks_lock = threading.Lock() + + +def _get_project_lock(encoded_name: str) -> threading.Lock: + with _locks_lock: + if encoded_name not in _project_locks: + _project_locks[encoded_name] = threading.Lock() + return _project_locks[encoded_name] + + +@dataclass +class PackageResult: + team_name: str + git_identity: str + sessions_packaged: int = 0 + error: Optional[str] = None + + +class PackagingService: + def __init__( + self, + member_tag: str, + user_id: str = "unknown", + machine_id: str = "unknown", + device_id: str = "", + ): + self.member_tag = member_tag + self.user_id = user_id + self.machine_id = machine_id + self.device_id = device_id + + def resolve_packagable_projects( + self, + conn: sqlite3.Connection, + *, + team_name: Optional[str] = None, + git_identity: Optional[str] = None, + ) -> list[dict[str, Any]]: + """Return projects that this member should package sessions for. + + Filters: + - Only ACCEPTED subscriptions with direction send or both + - Only SHARED projects + - Optional team_name / git_identity narrowing + - Dedup key: (encoded_name, team_name) + """ + from repositories.subscription_repo import SubscriptionRepository + from repositories.project_repo import ProjectRepository + + subs = SubscriptionRepository().list_for_member(conn, self.member_tag) + results: list[dict[str, Any]] = [] + seen: set[tuple[str, str]] = set() # (encoded_name, team_name) + + for s in subs: + if s.status.value != "accepted" or s.direction.value not in ( + "send", + "both", + ): + continue + if team_name and s.team_name != team_name: + continue + + project = ProjectRepository().get( + conn, s.team_name, s.project_git_identity + ) + if not project or project.status.value != "shared": + continue + if git_identity and project.git_identity != git_identity: + continue + + enc = project.encoded_name or "" + key = (enc, s.team_name) + if key in seen: + continue + seen.add(key) + + results.append( + { + "team_name": s.team_name, + "git_identity": project.git_identity, + "encoded_name": enc, + "folder_suffix": project.folder_suffix, + } + ) + + return results + + def package_project( + self, + conn: sqlite3.Connection, + *, + team_name: str, + git_identity: str, + encoded_name: str, + folder_suffix: str, + ) -> PackageResult: + """Package sessions for a single project into the Syncthing outbox. + + Thread-safe: uses a per-project lock so concurrent calls for the + same encoded_name are serialized (non-blocking — returns immediately + if another thread is already packaging). + """ + from services.sync.session_packager import SessionPackager + from services.sync.worktree_discovery import find_worktree_dirs + from models.sync_config import KARMA_BASE + from services.syncthing.folder_manager import build_outbox_folder_id + + lock = _get_project_lock(encoded_name) + if not lock.acquire(blocking=False): + return PackageResult( + team_name=team_name, + git_identity=git_identity, + error="Packaging already in progress", + ) + try: + projects_dir = Path.home() / ".claude" / "projects" + claude_dir = projects_dir / encoded_name + if not claude_dir.is_dir(): + return PackageResult( + team_name=team_name, + git_identity=git_identity, + error=f"Project dir not found: {encoded_name}", + ) + + folder_id = build_outbox_folder_id(self.member_tag, folder_suffix) + outbox = KARMA_BASE / folder_id + outbox.mkdir(parents=True, exist_ok=True) + + wt_dirs = find_worktree_dirs(encoded_name, projects_dir) + packager = SessionPackager( + project_dir=claude_dir, + user_id=self.user_id, + machine_id=self.machine_id, + device_id=self.device_id, + project_path="", + extra_dirs=wt_dirs, + member_tag=self.member_tag, + ) + manifest = packager.package(staging_dir=outbox) + count = len(manifest.sessions) if manifest else 0 + self._log_events(conn, team_name, git_identity, manifest) + return PackageResult( + team_name=team_name, + git_identity=git_identity, + sessions_packaged=count, + ) + except Exception as e: + logger.warning("Packaging failed for %s: %s", encoded_name, e) + return PackageResult( + team_name=team_name, + git_identity=git_identity, + error=str(e), + ) + finally: + lock.release() + + def _log_events(self, conn, team_name, git_identity, manifest): + if not manifest or not manifest.sessions: + return + try: + from repositories.event_repo import EventRepository + from domain.events import SyncEvent, SyncEventType + + repo = EventRepository() + for session_uuid in manifest.sessions: + repo.log( + conn, + SyncEvent( + event_type=SyncEventType.session_packaged, + team_name=team_name, + project_git_identity=git_identity, + session_uuid=session_uuid, + ), + ) + except Exception: + logger.debug( + "Failed to log session_packaged events", exc_info=True + ) diff --git a/api/services/sync/pairing_service.py b/api/services/sync/pairing_service.py new file mode 100644 index 00000000..272146bc --- /dev/null +++ b/api/services/sync/pairing_service.py @@ -0,0 +1,102 @@ +""" +PairingService — permanent, deterministic pairing codes using base64url. + +Codes encode "{member_tag}:{device_id}" via base64url, strip padding, and +group the result into 6-character blocks separated by dashes. + +Example output: amF5LW-1hY2Jv-b2suam-... + +Backwards-compatible: validate_code() auto-detects old base32 codes (all +uppercase + digits) vs new base64url codes (mixed case). +""" + +import base64 + +from pydantic import BaseModel + + +class PairingInfo(BaseModel): + """Decoded pairing information extracted from a pairing code.""" + + model_config = {"frozen": True} + + member_tag: str + device_id: str + + +class PairingService: + """Generates and validates permanent, deterministic pairing codes.""" + + BLOCK_SIZE = 6 + + # ------------------------------------------------------------------ + # Public API + # ------------------------------------------------------------------ + + def generate_code(self, member_tag: str, device_id: str) -> str: + """Return a deterministic pairing code for (member_tag, device_id). + + The code is a sequence of 6-character blocks separated by dashes, + using base64url encoding for ~22% shorter codes than base32. + """ + payload = f"{member_tag}:{device_id}" + encoded = base64.urlsafe_b64encode(payload.encode()).decode() + encoded = encoded.rstrip("=") + blocks = [encoded[i : i + self.BLOCK_SIZE] for i in range(0, len(encoded), self.BLOCK_SIZE)] + return "-".join(blocks) + + def validate_code(self, code: str) -> PairingInfo: + """Decode a pairing code and return PairingInfo. + + Auto-detects encoding format: + - base64url (v2): contains lowercase letters + - base32 (v1, legacy): all uppercase + digits + + Raises ValueError if the code is invalid or cannot be decoded. + """ + if not code: + raise ValueError("Pairing code must not be empty") + + normalized = code.replace("-", "").replace(" ", "").replace("\n", "").replace("\r", "").strip() + if not normalized: + raise ValueError("Pairing code contains no data") + + # Auto-detect: base64url uses lowercase; base32 is all uppercase + digits + is_base64 = any(c.islower() or c in ("_",) for c in normalized) + + if is_base64: + decoded = self._decode_base64url(normalized) + else: + decoded = self._decode_base32(normalized) + + if ":" not in decoded: + raise ValueError("Pairing code does not contain expected separator") + + member_tag, device_id = decoded.split(":", 1) + return PairingInfo(member_tag=member_tag, device_id=device_id) + + # ------------------------------------------------------------------ + # Private decoders + # ------------------------------------------------------------------ + + @staticmethod + def _decode_base64url(normalized: str) -> str: + """Decode a base64url-encoded pairing code (v2).""" + pad = (4 - len(normalized) % 4) % 4 + padded = normalized + "=" * pad + try: + return base64.urlsafe_b64decode(padded).decode() + except Exception as exc: + raise ValueError(f"Invalid pairing code (base64url): {exc}") from exc + + @staticmethod + def _decode_base32(normalized: str) -> str: + """Decode a legacy base32-encoded pairing code (v1).""" + normalized = normalized.upper() + remainder = len(normalized) % 8 + if remainder: + normalized += "=" * (8 - remainder) + try: + return base64.b32decode(normalized).decode() + except Exception as exc: + raise ValueError(f"Invalid pairing code (base32): {exc}") from exc diff --git a/api/services/sync/project_service.py b/api/services/sync/project_service.py new file mode 100644 index 00000000..7d24d447 --- /dev/null +++ b/api/services/sync/project_service.py @@ -0,0 +1,416 @@ +"""ProjectService — project sharing + subscription management orchestration.""" +from __future__ import annotations + +import logging +import sqlite3 +from typing import TYPE_CHECKING + +logger = logging.getLogger(__name__) + +from domain.member import MemberStatus +from domain.project import SharedProject, derive_folder_suffix +from domain.subscription import Subscription, SubscriptionStatus, SyncDirection +from domain.events import SyncEvent, SyncEventType +from domain.team import AuthorizationError + +if TYPE_CHECKING: + from repositories.project_repo import ProjectRepository + from repositories.subscription_repo import SubscriptionRepository + from repositories.member_repo import MemberRepository + from repositories.team_repo import TeamRepository + from repositories.event_repo import EventRepository + from services.syncthing.folder_manager import FolderManager + from services.sync.metadata_service import MetadataService + + +class ProjectService: + def __init__( + self, + projects: "ProjectRepository", + subs: "SubscriptionRepository", + members: "MemberRepository", + teams: "TeamRepository", + folders: "FolderManager", + metadata: "MetadataService", + events: "EventRepository", + ): + self.projects = projects + self.subs = subs + self.members = members + self.teams = teams + self.folders = folders + self.metadata = metadata + self.events = events + + async def share_project( + self, + conn: sqlite3.Connection, + *, + team_name: str, + by_device: str, + git_identity: str, + encoded_name: str | None = None, + ) -> SharedProject: + """Share a project with the team. Only the leader may share. + + Creates OFFERED subscriptions for each non-removed, non-leader member + (including ADDED members so subscriptions are ready when they activate). + If `encoded_name` is provided, creates the leader's outbox folder. + """ + team = self.teams.get(conn, team_name) + if not team or not team.is_leader(by_device): + raise AuthorizationError("Only leader can share projects") + if not git_identity: + raise ValueError("git_identity is required (git-only projects)") + + project = SharedProject( + team_name=team_name, + git_identity=git_identity, + encoded_name=encoded_name, + folder_suffix=derive_folder_suffix(git_identity), + ) + self.projects.save(conn, project) + + # Create ACCEPTED subscription for the leader (direction=BOTH) so they + # participate in Phase 3 device lists and get inbox folders for members. + leader_sub = Subscription( + member_tag=team.leader_member_tag, + team_name=team_name, + project_git_identity=git_identity, + status=SubscriptionStatus.ACCEPTED, + direction=SyncDirection.BOTH, + ) + self.subs.save(conn, leader_sub) + + # Create OFFERED subscription for each non-removed, non-leader member. + # Include ADDED members so subscriptions are waiting when they activate. + for member in self.members.list_for_team(conn, team_name): + if member.status != MemberStatus.REMOVED and not team.is_leader(member.device_id): + sub = Subscription( + member_tag=member.member_tag, + team_name=team_name, + project_git_identity=git_identity, + ) + self.subs.save(conn, sub) + + # Create leader's outbox if they have the repo locally + if encoded_name: + await self.folders.ensure_outbox_folder( + team.leader_member_tag, project.folder_suffix, + ) + + # Publish leader's updated project list to metadata folder + self._publish_member_metadata(conn, team_name, team.leader_member_tag) + + self.events.log(conn, SyncEvent( + event_type=SyncEventType.project_shared, + team_name=team_name, + project_git_identity=git_identity, + )) + return project + + async def remove_project( + self, + conn: sqlite3.Connection, + *, + team_name: str, + by_device: str, + git_identity: str, + ) -> SharedProject: + """Remove a project from the team. Only the leader may remove. + + Declines all subscriptions and cleans up Syncthing folders. + """ + team = self.teams.get(conn, team_name) + if not team or not team.is_leader(by_device): + raise AuthorizationError("Only leader can remove projects") + + project = self.projects.get(conn, team_name, git_identity) + if not project: + raise ValueError(f"Project '{git_identity}' not found in team '{team_name}'") + + removed = project.remove() + self.projects.save(conn, removed) + + # Decline all subscriptions for this project + for sub in self.subs.list_for_project(conn, team_name, git_identity): + if sub.status.value != "declined": + self.subs.save(conn, sub.decline()) + + # Cleanup Syncthing folders for all members + members = self.members.list_for_team(conn, team_name) + tags = [m.member_tag for m in members] + await self.folders.cleanup_project_folders(removed.folder_suffix, tags, conn=conn, team_name=team_name) + + # Publish leader's updated project list to metadata folder + self._publish_member_metadata(conn, team_name, team.leader_member_tag) + + self.events.log(conn, SyncEvent( + event_type=SyncEventType.project_removed, + team_name=team_name, + project_git_identity=git_identity, + )) + return removed + + async def accept_subscription( + self, + conn: sqlite3.Connection, + *, + member_tag: str, + team_name: str, + git_identity: str, + direction: SyncDirection = SyncDirection.BOTH, + ) -> Subscription: + """Accept a subscription with the given sync direction. + + Applies the direction by creating outbox and/or inbox folders as needed. + """ + sub = self.subs.get(conn, member_tag, team_name, git_identity) + if sub is None: + raise ValueError( + f"Subscription not found for member '{member_tag}' " + f"on project '{git_identity}' in team '{team_name}'" + ) + + # Auto-reopen declined subscriptions so the frontend can call + # accept directly without needing to know the state machine. + if sub.status == SubscriptionStatus.DECLINED: + sub = sub.reopen() + self.subs.save(conn, sub) + + accepted = sub.accept(direction) + self.subs.save(conn, accepted) + await self._apply_sync_direction(conn, accepted) + + self._publish_member_metadata(conn, team_name, member_tag) + + self.events.log(conn, SyncEvent( + event_type=SyncEventType.subscription_accepted, + team_name=team_name, + member_tag=member_tag, + project_git_identity=git_identity, + detail={"direction": direction.value}, + )) + return accepted + + async def pause_subscription( + self, + conn: sqlite3.Connection, + *, + member_tag: str, + team_name: str, + git_identity: str, + ) -> Subscription: + """Pause an accepted subscription.""" + sub = self.subs.get(conn, member_tag, team_name, git_identity) + if sub is None: + raise ValueError("Subscription not found") + + paused = sub.pause() + self.subs.save(conn, paused) + self._publish_member_metadata(conn, team_name, member_tag) + + self.events.log(conn, SyncEvent( + event_type=SyncEventType.subscription_paused, + team_name=team_name, + member_tag=member_tag, + project_git_identity=git_identity, + )) + return paused + + async def resume_subscription( + self, + conn: sqlite3.Connection, + *, + member_tag: str, + team_name: str, + git_identity: str, + ) -> Subscription: + """Resume a paused subscription, re-applying sync direction.""" + sub = self.subs.get(conn, member_tag, team_name, git_identity) + if sub is None: + raise ValueError("Subscription not found") + + resumed = sub.resume() + self.subs.save(conn, resumed) + await self._apply_sync_direction(conn, resumed) + self._publish_member_metadata(conn, team_name, member_tag) + + self.events.log(conn, SyncEvent( + event_type=SyncEventType.subscription_resumed, + team_name=team_name, + member_tag=member_tag, + project_git_identity=git_identity, + )) + return resumed + + async def decline_subscription( + self, + conn: sqlite3.Connection, + *, + member_tag: str, + team_name: str, + git_identity: str, + ) -> Subscription: + """Decline a subscription.""" + sub = self.subs.get(conn, member_tag, team_name, git_identity) + if sub is None: + raise ValueError("Subscription not found") + + declined = sub.decline() + self.subs.save(conn, declined) + self._publish_member_metadata(conn, team_name, member_tag) + + self.events.log(conn, SyncEvent( + event_type=SyncEventType.subscription_declined, + team_name=team_name, + member_tag=member_tag, + project_git_identity=git_identity, + )) + return declined + + async def change_direction( + self, + conn: sqlite3.Connection, + *, + member_tag: str, + team_name: str, + git_identity: str, + direction: SyncDirection, + ) -> Subscription: + """Change the sync direction of an accepted subscription. + + Removes outbox if switching away from send/both — but only if no + other team's subscription for the same member+suffix still needs it. + Creates outbox if switching to send/both from receive. + """ + sub = self.subs.get(conn, member_tag, team_name, git_identity) + if sub is None: + raise ValueError("Subscription not found") + + old_direction = sub.direction + changed = sub.change_direction(direction) + self.subs.save(conn, changed) + + project = self.projects.get(conn, team_name, git_identity) + + # Remove outbox if no longer sending + was_sending = old_direction in (SyncDirection.SEND, SyncDirection.BOTH) + now_sending = direction in (SyncDirection.SEND, SyncDirection.BOTH) + + if project: + if was_sending and not now_sending: + # Check if another team's subscription still needs this outbox + other_subs = self.subs.list_accepted_for_suffix(conn, project.folder_suffix) + other_team_needs = any( + s.member_tag == member_tag + and s.team_name != team_name + and s.direction in (SyncDirection.SEND, SyncDirection.BOTH) + for s in other_subs + ) + if not other_team_needs: + await self.folders.remove_outbox_folder(member_tag, project.folder_suffix) + elif not was_sending and now_sending: + await self.folders.ensure_outbox_folder(member_tag, project.folder_suffix) + + self._publish_member_metadata(conn, team_name, member_tag) + + self.events.log(conn, SyncEvent( + event_type=SyncEventType.direction_changed, + team_name=team_name, + member_tag=member_tag, + project_git_identity=git_identity, + detail={"old_direction": old_direction.value, "new_direction": direction.value}, + )) + return changed + + async def reopen_subscription( + self, + conn: sqlite3.Connection, + *, + member_tag: str, + team_name: str, + git_identity: str, + ) -> Subscription: + """Reopen a declined subscription, returning it to OFFERED status. + + The member can then accept it again with a new direction choice. + """ + sub = self.subs.get(conn, member_tag, team_name, git_identity) + if sub is None: + raise ValueError("Subscription not found") + + reopened = sub.reopen() + self.subs.save(conn, reopened) + self._publish_member_metadata(conn, team_name, member_tag) + + self.events.log(conn, SyncEvent( + event_type=SyncEventType.subscription_offered, + team_name=team_name, + member_tag=member_tag, + project_git_identity=git_identity, + detail={"reopened": True}, + )) + return reopened + + # ------------------------------------------------------------------ + # Internal helpers + # ------------------------------------------------------------------ + + def _publish_member_metadata( + self, conn: sqlite3.Connection, team_name: str, member_tag: str, + ) -> None: + """Publish a member's project list and subscriptions to the metadata folder. + + Queries current projects and subscriptions from DB, then writes them + to the member's state file via read-merge-write (preserving basic fields). + Best-effort: filesystem errors are logged but do not abort the caller. + """ + try: + projects = self.projects.list_for_team(conn, team_name) + projects_data = [ + { + "git_identity": p.git_identity, + "folder_suffix": p.folder_suffix, + "encoded_name": p.encoded_name, + } + for p in projects + if p.status.value == "shared" + ] + subs = self.subs.list_for_member(conn, member_tag) + subs_data = { + s.project_git_identity: { + "status": s.status.value, + "direction": s.direction.value, + } + for s in subs + if s.team_name == team_name + } + self.metadata.write_member_state( + team_name, member_tag, + projects=projects_data, + subscriptions=subs_data, + ) + except Exception as e: + logger.warning( + "Failed to publish metadata for member '%s' in team '%s': %s", + member_tag, team_name, e, + ) + + async def _apply_sync_direction(self, conn: sqlite3.Connection, sub: Subscription) -> None: + """Create Syncthing folders based on subscription direction.""" + project = self.projects.get(conn, sub.team_name, sub.project_git_identity) + if not project: + return + + if sub.direction in (SyncDirection.SEND, SyncDirection.BOTH): + await self.folders.ensure_outbox_folder(sub.member_tag, project.folder_suffix) + + if sub.direction in (SyncDirection.RECEIVE, SyncDirection.BOTH): + # Create inbox folders for each active teammate (they are senders) + members = self.members.list_for_team(conn, sub.team_name) + for m in members: + if m.member_tag != sub.member_tag and m.is_active: + await self.folders.ensure_inbox_folder( + m.member_tag, project.folder_suffix, m.device_id, + ) diff --git a/api/services/sync/reconciliation_service.py b/api/services/sync/reconciliation_service.py new file mode 100644 index 00000000..4a806380 --- /dev/null +++ b/api/services/sync/reconciliation_service.py @@ -0,0 +1,512 @@ +"""Reconciliation pipeline. Runs every 60s.""" +from __future__ import annotations + +import logging +import re +import sqlite3 +from typing import TYPE_CHECKING + +from domain.member import Member, MemberStatus +from domain.project import SharedProject, SharedProjectStatus, derive_folder_suffix +from domain.subscription import Subscription, SubscriptionStatus, SyncDirection +from domain.team import Team +from domain.events import SyncEvent, SyncEventType + +if TYPE_CHECKING: + from repositories.team_repo import TeamRepository + from repositories.member_repo import MemberRepository + from repositories.project_repo import ProjectRepository + from repositories.subscription_repo import SubscriptionRepository + from repositories.event_repo import EventRepository + from services.syncthing.device_manager import DeviceManager + from services.syncthing.folder_manager import FolderManager + from services.sync.metadata_service import MetadataService + +logger = logging.getLogger(__name__) + +_META_FOLDER_RE = re.compile(r"^karma-meta--(.+)$") + + +class ReconciliationService: + """Orchestrates 4-phase reconciliation for all teams. + + Phase 0 (team discovery): Scan Syncthing config for karma-meta--* + folders that have no local Team row. Bootstrap Team + self-Member + from the metadata folder's team.json so joiners can participate + in reconciliation immediately after accepting a device. + + Phase 1 (metadata): Read metadata folder. Detect removal signals + (auto-leave if own tag removed). Discover new members. Detect + removed projects (decline subs). + + Phase 2 (mesh pair): For each active member, ensure Syncthing device + is paired. Skip self. + + Phase 3 (device lists): For each shared project, query accepted + subscriptions with send|both direction. Compute desired device + set. Apply declaratively via set_folder_devices. + """ + + def __init__( + self, + teams: "TeamRepository", + members: "MemberRepository", + projects: "ProjectRepository", + subs: "SubscriptionRepository", + events: "EventRepository", + devices: "DeviceManager", + folders: "FolderManager", + metadata: "MetadataService", + my_member_tag: str, + my_device_id: str = "", + ): + self.teams = teams + self.members = members + self.projects = projects + self.subs = subs + self.events = events + self.devices = devices + self.folders = folders + self.metadata = metadata + self.my_member_tag = my_member_tag + self.my_device_id = my_device_id + + async def run_cycle(self, conn: sqlite3.Connection) -> None: + """Run full reconciliation for all teams.""" + # Phase 0: discover teams from Syncthing metadata folders + try: + await self.phase_team_discovery(conn) + except Exception as exc: + logger.warning("phase_team_discovery failed (non-fatal): %s", exc) + + for team in self.teams.list_active(conn): + await self.phase_metadata(conn, team) + await self.phase_mesh_pair(conn, team) + await self.phase_device_lists(conn, team) + + async def phase_team_discovery(self, conn: sqlite3.Connection) -> None: + """Phase 0: Discover teams from karma-meta--* folders in Syncthing config. + + When a joiner accepts a device, Syncthing may already have metadata + folders configured but no local team record. This phase reads those + folders, parses team.json, and bootstraps the local Team + Member rows + so subsequent phases have something to iterate over. + """ + try: + configured_folders = await self.folders.get_configured_folders() + except Exception as exc: + logger.debug("phase_team_discovery: cannot query folders: %s", exc) + return + + for folder_cfg in configured_folders: + folder_id = folder_cfg.get("id", "") + m = _META_FOLDER_RE.match(folder_id) + if not m: + continue + + team_name = m.group(1) + + # Skip if team already exists locally + existing = self.teams.get(conn, team_name) + if existing is not None: + continue + + # Read team.json from the metadata folder on disk + try: + team_data = self.metadata.read_team_json(team_name) + if team_data is None: + logger.debug( + "phase_team_discovery: no team.json yet for %s", team_name + ) + continue + + leader_member_tag = team_data.get("created_by", "") + leader_device_id = team_data.get("leader_device_id", "") + + if not leader_member_tag or not leader_device_id: + logger.warning( + "phase_team_discovery: incomplete team.json for %s", team_name + ) + continue + + # Create team (use team_id from metadata if available, + # otherwise generate a new one) + remote_team_id = team_data.get("team_id", "") + team_kwargs = dict( + name=team_name, + leader_device_id=leader_device_id, + leader_member_tag=leader_member_tag, + ) + if remote_team_id: + team_kwargs["team_id"] = remote_team_id + team = Team(**team_kwargs) + self.teams.save(conn, team) + + # Create self as an ACTIVE member + member = Member.from_member_tag( + member_tag=self.my_member_tag, + team_name=team_name, + device_id=self.my_device_id, + status=MemberStatus.ACTIVE, + ) + self.members.save(conn, member) + + logger.info( + "phase_team_discovery: bootstrapped team '%s' (leader=%s)", + team_name, + leader_member_tag, + ) + except Exception as exc: + logger.warning( + "phase_team_discovery: failed to bootstrap team '%s': %s", + team_name, + exc, + ) + + # Also scan PENDING folders for karma-meta--* that haven't been accepted yet. + # This closes the timing race where Accept & Pair fires before Syncthing + # propagates the folder offer. + try: + client = self.folders._client + pending_raw = await client.get_pending_folders() + except Exception as exc: + logger.debug("phase_team_discovery: cannot query pending folders: %s", exc) + return + + configured_ids = {f.get("id", "") for f in configured_folders} + + for folder_id, folder_data in pending_raw.items(): + m = _META_FOLDER_RE.match(folder_id) + if not m: + continue + + # Skip if already configured (handled above) + if folder_id in configured_ids: + continue + + # Auto-accept the pending metadata folder + offered_by = folder_data.get("offeredBy", folder_data) + device_ids = list(offered_by.keys()) + if not device_ids: + continue + + try: + from config import settings as app_settings + from services.syncthing.folder_manager import build_folder_config + + devices = [{"deviceID": did, "encryptionPassword": ""} for did in device_ids] + if self.my_device_id: + devices.append({"deviceID": self.my_device_id, "encryptionPassword": ""}) + + folder_config = build_folder_config( + app_settings.karma_base, folder_id, "sendreceive", devices, + ) + await client.put_config_folder(folder_config) + for did in device_ids: + await client.dismiss_pending_folder(folder_id, did) + logger.info( + "phase_team_discovery: auto-accepted pending metadata folder '%s'", + folder_id, + ) + except Exception as exc: + logger.warning( + "phase_team_discovery: failed to auto-accept pending folder '%s': %s", + folder_id, exc, + ) + + async def phase_metadata(self, conn: sqlite3.Connection, team) -> None: + """Phase 1: Read metadata, detect removals, discover members/projects.""" + states = self.metadata.read_team_metadata(team.name) + if not states: + return + + # Check removal signals — auto-leave if own tag is in removals + # BUT skip stale signals from a previous team incarnation. + # Uses team_id (incarnation UUID) for reliable detection. + # Falls back to timestamp comparison for legacy signals without team_id. + removals = states.pop("__removals", {}) + if self.my_member_tag in removals: + removal = removals[self.my_member_tag] + signal_team_id = removal.get("team_id", "") + + if signal_team_id and team.team_id and signal_team_id != team.team_id: + # Signal is from a different incarnation — ignore it + logger.info( + "phase_metadata: ignoring stale removal signal for '%s' in team '%s' " + "(signal team_id=%s != current team_id=%s)", + self.my_member_tag, team.name, signal_team_id, team.team_id, + ) + elif signal_team_id and team.team_id and signal_team_id == team.team_id: + # Signal matches current incarnation — definitely valid + await self._auto_leave(conn, team) + return + else: + # Legacy signal without team_id — fall back to timestamp check + removed_at_str = removal.get("removed_at", "") + try: + from datetime import datetime, timezone, timedelta + removed_at = datetime.fromisoformat(removed_at_str) + if team.created_at and removed_at < (team.created_at - timedelta(seconds=60)): + logger.info( + "phase_metadata: ignoring stale removal signal for '%s' in team '%s' " + "(removed_at=%s < created_at=%s, no team_id)", + self.my_member_tag, team.name, removed_at_str, team.created_at.isoformat(), + ) + else: + await self._auto_leave(conn, team) + return + except (ValueError, TypeError): + await self._auto_leave(conn, team) + return + + # Discover new members from peer state files + for tag, state in states.items(): + if tag == self.my_member_tag: + continue + existing = self.members.get(conn, team.name, tag) + if existing is None: + device_id = state.get("device_id") + if device_id and not self.members.was_removed(conn, team.name, device_id): + new_member = Member.from_member_tag( + member_tag=tag, + team_name=team.name, + device_id=device_id, + ) + # Register as ADDED then immediately activate (they've published state) + activated = new_member.activate() + self.members.save(conn, activated) + elif existing.status == MemberStatus.ADDED: + # Activate if we can see them in metadata (they've acknowledged) + self.members.save(conn, existing.activate()) + # Backfill OFFERED subscriptions for shared projects the member missed + # (they were ADDED when share_project ran, so no sub was created) + for proj in self.projects.list_for_team(conn, team.name): + if proj.status != SharedProjectStatus.SHARED: + continue + existing_sub = self.subs.get(conn, tag, team.name, proj.git_identity) + if existing_sub is None: + sub = Subscription( + member_tag=tag, + team_name=team.name, + project_git_identity=proj.git_identity, + ) + self.subs.save(conn, sub) + logger.info( + "phase_metadata: backfilled OFFERED subscription for member '%s' on project '%s'", + tag, proj.git_identity, + ) + + # Sync subscription status + direction from peer metadata to local DB. + # When a member changes state on their machine (accept, pause, resume, + # decline, reopen, direction change), they publish to their metadata + # state file. We read it and update our local record so Phase 3 device + # lists reflect the actual subscription state. + for tag, state in states.items(): + if tag == self.my_member_tag: + continue + peer_subs = state.get("subscriptions", {}) + for git_id, sub_info in peer_subs.items(): + peer_status = sub_info.get("status") + peer_direction = sub_info.get("direction") + if not peer_status: + continue + local_sub = self.subs.get(conn, tag, team.name, git_id) + if local_sub is None: + continue + try: + updated = self._sync_peer_subscription( + local_sub, peer_status, peer_direction, + ) + if updated is not None: + self.subs.save(conn, updated) + logger.info( + "phase_metadata: synced subscription %s/%s → %s/%s (from peer metadata)", + tag, git_id, updated.status.value, updated.direction.value, + ) + except Exception as e: + logger.debug("phase_metadata: subscription sync skip %s/%s: %s", tag, git_id, e) + + # Discover/remove projects from leader's metadata state + leader_state = states.get(team.leader_member_tag, {}) + + # Guard: skip project sync if leader hasn't published projects yet. + # Distinguishes "no projects key" (not synced) from "projects: []" (no projects). + if "projects" not in leader_state: + logger.debug( + "phase_metadata: skipping project sync for team '%s' — " + "leader '%s' has not yet published projects key", + team.name, team.leader_member_tag, + ) + return + + leader_projects_raw = leader_state["projects"] + leader_projects = {p["git_identity"] for p in leader_projects_raw} + local_projects = self.projects.list_for_team(conn, team.name) + local_git_identities = {lp.git_identity for lp in local_projects} + + # Remove projects no longer in leader's list + for lp in local_projects: + if lp.git_identity not in leader_projects and lp.status == SharedProjectStatus.SHARED: + removed = lp.remove() + self.projects.save(conn, removed) + for sub in self.subs.list_for_project(conn, team.name, lp.git_identity): + if sub.status != SubscriptionStatus.DECLINED: + self.subs.save(conn, sub.decline()) + + # Discover new projects from leader's metadata + for proj_data in leader_projects_raw: + git_id = proj_data.get("git_identity") + if not git_id: + logger.warning( + "phase_metadata: skipping malformed project entry (no git_identity) in team '%s'", + team.name, + ) + continue + if git_id in local_git_identities: + continue + # Create SharedProject locally + project = SharedProject( + team_name=team.name, + git_identity=git_id, + encoded_name=proj_data.get("encoded_name"), + folder_suffix=proj_data.get("folder_suffix", derive_folder_suffix(git_id)), + ) + self.projects.save(conn, project) + # Create OFFERED subscription for self + sub = Subscription( + member_tag=self.my_member_tag, + team_name=team.name, + project_git_identity=git_id, + ) + self.subs.save(conn, sub) + logger.info( + "phase_metadata: discovered project '%s' in team '%s' — created OFFERED subscription", + git_id, team.name, + ) + + @staticmethod + def _sync_peer_subscription( + local_sub, peer_status: str, peer_direction: str | None, + ): + """Compute the updated subscription by mirroring peer state, or None if no change needed. + + Handles all state transitions: + offered → accepted (accept) + accepted → paused (pause) + paused → accepted (resume) + * → declined (decline) + declined → offered (reopen) + accepted == accepted with different direction (direction change) + """ + local_status = local_sub.status.value + + # --- Status differs: apply the appropriate transition --- + if local_status != peer_status: + if peer_status == "accepted" and local_status == "offered": + direction = SyncDirection(peer_direction) if peer_direction else SyncDirection.BOTH + return local_sub.accept(direction) + + if peer_status == "accepted" and local_status == "paused": + # Resume: paused → accepted + return local_sub.resume() + + if peer_status == "paused" and local_status == "accepted": + return local_sub.pause() + + if peer_status == "declined" and local_status in ("offered", "accepted", "paused"): + return local_sub.decline() + + if peer_status == "offered" and local_status == "declined": + return local_sub.reopen() + + # Unknown transition — skip + return None + + # --- Status matches: check direction drift --- + if ( + local_status == "accepted" + and peer_direction + and local_sub.direction.value != peer_direction + ): + return local_sub.change_direction(SyncDirection(peer_direction)) + + # Nothing to sync + return None + + async def phase_mesh_pair(self, conn: sqlite3.Connection, team) -> None: + """Phase 2: Pair with undiscovered active team members.""" + members = self.members.list_for_team(conn, team.name) + for member in members: + if member.is_active and member.member_tag != self.my_member_tag: + await self.devices.ensure_paired(member.device_id) + + async def phase_device_lists(self, conn: sqlite3.Connection, team) -> None: + """Phase 3: Declarative device list sync for all project folders.""" + from services.syncthing.folder_manager import build_outbox_folder_id + + projects = self.projects.list_for_team(conn, team.name) + team_members = self.members.list_for_team(conn, team.name) + + for project in projects: + if project.status.value != "shared": + continue + + accepted = self.subs.list_accepted_for_suffix(conn, project.folder_suffix) + + # Ensure outbox folders exist for members with send|both subs + # in THIS team (recovery from accidental deletion) + for sub in accepted: + if sub.team_name != team.name: + continue + if sub.direction in (SyncDirection.SEND, SyncDirection.BOTH): + member = self.members.get(conn, sub.team_name, sub.member_tag) + if member and member.is_active: + await self.folders.ensure_outbox_folder( + sub.member_tag, project.folder_suffix, + ) + + # Compute desired device set: members with send|both direction + # IMPORTANT: filter by current team to prevent cross-team data leaks. + # list_accepted_for_suffix() returns subs from ALL teams sharing + # the same folder_suffix — we must only include THIS team's members. + desired: set[str] = set() + for sub in accepted: + if sub.team_name != team.name: + continue + if sub.direction in (SyncDirection.SEND, SyncDirection.BOTH): + member = self.members.get(conn, sub.team_name, sub.member_tag) + if member and member.is_active: + desired.add(member.device_id) + + # Apply declaratively to all outbox folders with this suffix + for m in team_members: + folder_id = build_outbox_folder_id(m.member_tag, project.folder_suffix) + await self.folders.set_folder_devices(folder_id, desired) + + async def _auto_leave(self, conn: sqlite3.Connection, team) -> None: + """Clean up everything for this team on the local machine.""" + projects = self.projects.list_for_team(conn, team.name) + members = self.members.list_for_team(conn, team.name) + suffixes = [p.folder_suffix for p in projects] + tags = [m.member_tag for m in members] + + await self.folders.cleanup_team_folders(suffixes, tags, team.name, conn=conn) + + # Unpair devices not shared with other teams + for member in members: + if member.member_tag == self.my_member_tag: + continue + others = self.members.get_by_device(conn, member.device_id) + if len([o for o in others if o.team_name != team.name]) == 0: + await self.devices.unpair(member.device_id) + + conn.execute("DELETE FROM sync_events WHERE team_name = ?", (team.name,)) + self.teams.delete(conn, team.name) + self.events.log( + conn, + SyncEvent( + event_type=SyncEventType.member_auto_left, + team_name=team.name, + member_tag=self.my_member_tag, + ), + ) diff --git a/api/services/sync/session_packager.py b/api/services/sync/session_packager.py new file mode 100644 index 00000000..7228e325 --- /dev/null +++ b/api/services/sync/session_packager.py @@ -0,0 +1,769 @@ +"""Session packager — collects project sessions into a staging directory.""" + +import json +import logging +import re +import shutil +import subprocess +from datetime import datetime, timezone +from pathlib import Path +from typing import Optional + +from config import settings +from models.sync_manifest import SessionEntry, SkillDefinitionEntry, SyncManifest + +logger = logging.getLogger(__name__) + +MIN_FREE_BYTES = 10 * 1024 * 1024 * 1024 # 10 GiB +MAX_SKILL_SIZE = 1_000_000 # 1 MB, mirrors api/config.py + + +STALE_LIVE_SESSION_SECONDS = 30 * 60 # 30 minutes + + +def _get_live_session_uuids() -> set[str]: + """Return UUIDs of sessions that are currently live (not yet ended). + + Reads ``~/.claude_karma/live-sessions/*.json`` written by Claude Code hooks. + If hooks aren't configured (directory missing/empty), returns an empty set + so all sessions pass through — backward compatible. + + Sessions idle for more than 30 minutes are considered stale (likely crashed + without a SessionEnd hook) and are NOT excluded — their JSONL is stable + enough to package. + """ + live_dir = settings.karma_base / "live-sessions" + if not live_dir.is_dir(): + return set() + + now = datetime.now(timezone.utc) + live_uuids: set[str] = set() + for json_file in live_dir.glob("*.json"): + try: + data = json.loads(json_file.read_text(encoding="utf-8")) + state = data.get("state", "") + if state == "ENDED": + continue + + # Skip sessions idle longer than the staleness threshold — + # likely crashed without SessionEnd, safe to package. + updated_at_str = data.get("updated_at") + if updated_at_str: + updated_at = datetime.fromisoformat( + updated_at_str.replace("Z", "+00:00") + ) + if updated_at.tzinfo is None: + updated_at = updated_at.replace(tzinfo=timezone.utc) + idle_seconds = (now - updated_at).total_seconds() + if idle_seconds > STALE_LIVE_SESSION_SECONDS: + logger.debug( + "Live session %s idle %.0fs > %ds, treating as stale", + data.get("session_id", "?"), + idle_seconds, + STALE_LIVE_SESSION_SECONDS, + ) + continue + + # Current active session UUID + sid = data.get("session_id") + if sid: + live_uuids.add(sid) + # All historical UUIDs for this slug (resumed sessions) + for sid in data.get("session_ids", []): + live_uuids.add(sid) + except (json.JSONDecodeError, OSError): + continue + return live_uuids + + +def get_session_limit( + team_session_limit: str, + dest_path: Path, + *, + team_name: Optional[str] = None, + member_tag: Optional[str] = None, +) -> int | None: + """Return max sessions to package, or None for unlimited. + + Checks for per-device override in metadata file before using team setting. + If disk has < 10 GiB free, force recent 100 regardless of setting. + """ + try: + free = shutil.disk_usage(dest_path).free + except OSError: + return 100 # Can't check disk → be conservative + if free < MIN_FREE_BYTES: + return 100 # safety cap + + # Check per-device override from metadata file + effective_limit = team_session_limit + if team_name and member_tag: + try: + meta_file = settings.karma_base / "metadata-folders" / team_name / "members" / f"{member_tag}.json" + if meta_file.exists(): + state = json.loads(meta_file.read_text(encoding="utf-8")) + device_limit = state.get("session_limit") + if device_limit and device_limit in ("all", "recent_100", "recent_10"): + effective_limit = device_limit + except (json.JSONDecodeError, OSError): + pass + + limits = {"all": None, "recent_100": 100, "recent_10": 10} + return limits.get(effective_limit, None) + + +# Regex to extract plan slugs from JSONL bytes: matches plans/{slug}.md +_PLAN_SLUG_RE = re.compile(rb'plans/([\w][\w.-]*?)\.md') + + +def _discover_plan_references( + session_jsonl_paths: list[tuple[str, Path]], +) -> dict[str, dict]: + """Scan session JONLs for plan file references. + + Returns: + {slug: {"sessions": {uuid: operation, ...}}} where operation is + "created" (Write), "edited" (Edit/StrReplace), or "read" (Read). + """ + # Operation priority: created > edited > read + op_priority = {"created": 3, "edited": 2, "read": 1} + plans: dict[str, dict[str, str]] = {} # slug -> {uuid -> operation} + + for uuid, jsonl_path in session_jsonl_paths: + if not jsonl_path.is_file(): + continue + try: + raw = jsonl_path.read_bytes() + except (PermissionError, OSError): + continue + + # Fast check: any plan reference at all? + if b"plans/" not in raw or b".md" not in raw: + continue + + # Extract all plan slugs referenced in this JSONL + slugs_found = set(_PLAN_SLUG_RE.findall(raw)) + if not slugs_found: + continue + + # Determine operation type per slug by scanning for tool use patterns + for slug_bytes in slugs_found: + slug = slug_bytes.decode("utf-8", errors="replace") + needle = f"plans/{slug}.md".encode() + + # Determine best operation: scan for Write/Edit/StrReplace/Read near the slug + operation = "read" # default + for line in raw.split(b"\n"): + if needle not in line: + continue + if b'"Write"' in line or b'"name": "Write"' in line: + operation = "created" + break # highest priority, stop + elif b'"Edit"' in line or b'"StrReplace"' in line: + if op_priority.get(operation, 0) < op_priority["edited"]: + operation = "edited" + + if slug not in plans: + plans[slug] = {} + # Keep highest-priority operation per session + existing = plans[slug].get(uuid, "") + if op_priority.get(operation, 0) > op_priority.get(existing, 0): + plans[slug][uuid] = operation + + return plans + + +def _build_titles_from_db(session_uuids: list[str]) -> dict[str, dict]: + """Query the metadata DB for session titles of given sessions. + + Returns dict suitable for write_titles_bulk(): + {uuid: {"title": str, "source": str}} for sessions that have titles. + """ + if not session_uuids: + return {} + + try: + from db.connection import create_writer_connection + + conn = create_writer_connection() + except Exception: + return {} + + titles: dict[str, dict] = {} + placeholders = ",".join("?" * len(session_uuids)) + + try: + rows = conn.execute( + f"SELECT uuid, session_titles FROM sessions WHERE uuid IN ({placeholders}) AND session_titles IS NOT NULL", + session_uuids, + ).fetchall() + for row in rows: + try: + parsed = json.loads(row[1]) if isinstance(row[1], str) else row[1] + if isinstance(parsed, list) and parsed: + titles[row[0]] = {"title": parsed[0], "source": "db"} + except (json.JSONDecodeError, TypeError, IndexError): + continue + except Exception as e: + logger.debug("Failed to query session titles from DB: %s", e) + finally: + conn.close() + + return titles + + +def _resolve_skill_file(skill_name: str, claude_base: Path) -> Optional[Path]: + """Resolve a skill name to its definition file path on disk. + + Synchronous, no HTTP dependencies. Checks global commands/skills, + plugin cache (with manifest custom paths), and inherited skills. + Returns None if no file is found. + """ + is_plugin = ":" in skill_name + + if not is_plugin: + # Non-plugin: check global commands and skills directories + for candidate in ( + claude_base / "commands" / f"{skill_name}.md", + claude_base / "skills" / skill_name / "SKILL.md", + ): + if candidate.is_file(): + return candidate + + # Extract plugin/skill parts for cache walk + if is_plugin: + plugin_short_name = skill_name.split(":")[0].split("@")[0] + actual_skill = skill_name.split(":", 1)[1] + else: + plugin_short_name = None + actual_skill = skill_name + + # Try to import read_plugin_manifest for custom path support + try: + from models.plugin import read_plugin_manifest + except ImportError: + read_plugin_manifest = None # type: ignore[assignment] + + plugins_cache = claude_base / "plugins" / "cache" + if plugins_cache.is_dir(): + for registry_dir in plugins_cache.iterdir(): + if not registry_dir.is_dir(): + continue + for plugin_dir in registry_dir.iterdir(): + if not plugin_dir.is_dir(): + continue + if plugin_short_name and plugin_dir.name != plugin_short_name: + continue + for version_dir in plugin_dir.iterdir(): + if not version_dir.is_dir(): + continue + + # Check default locations + for candidate in ( + version_dir / "commands" / f"{actual_skill}.md", + version_dir / "skills" / actual_skill / "SKILL.md", + ): + if candidate.is_file(): + return candidate + + # Check manifest custom paths + if read_plugin_manifest: + manifest = read_plugin_manifest(version_dir) + if manifest: + for key, filename in [ + ("skills", f"{actual_skill}/SKILL.md"), + ("commands", f"{actual_skill}.md"), + ]: + custom = manifest.get(key) + if not custom: + continue + for cp in ( + [custom] if isinstance(custom, str) else custom + ): + d = version_dir / cp.removeprefix("./") + candidate = d / filename + if candidate.is_file(): + return candidate + + # Fallback: check inherited skills (colon-form and dash-form) + if is_plugin: + for candidate_name in (skill_name, skill_name.replace(":", "-")): + inherited = claude_base / "skills" / candidate_name / "SKILL.md" + if inherited.is_file(): + return inherited + + return None + + +def _build_skill_definitions( + skill_classifications: dict[str, str], + claude_base: Path, +) -> dict[str, SkillDefinitionEntry]: + """Resolve skill definition files and build content entries for the manifest. + + Iterates skill_classifications keys, resolves each to its SKILL.md file, + reads content (capped at MAX_SKILL_SIZE), and builds SkillDefinitionEntry + objects. Only includes skills where a file was found and readable. + Skips bundled/builtin categories (they ship with Claude Code). + """ + definitions: dict[str, SkillDefinitionEntry] = {} + skip_categories = {"bundled_skill", "builtin_command"} + + for name, category in skill_classifications.items(): + if category in skip_categories: + continue + try: + skill_file = _resolve_skill_file(name, claude_base) + if not skill_file: + continue + if skill_file.stat().st_size > MAX_SKILL_SIZE: + continue + + content = skill_file.read_text(encoding="utf-8", errors="replace") + + # Parse description from YAML frontmatter + description = None + if content.startswith("---"): + parts = content.split("---", 2) + if len(parts) >= 3: + try: + import yaml + + frontmatter = yaml.safe_load(parts[1]) + if isinstance(frontmatter, dict): + description = frontmatter.get("description") + except Exception: + pass # Best-effort: skip unparseable frontmatter + + definitions[name] = SkillDefinitionEntry( + content=content, + description=description, + category=category, + base_directory=str(skill_file.parent), + ) + except Exception as e: + logger.debug("Skipping skill definition for %s: %s", name, e) + + return definitions + + +def _build_skill_classifications_from_db( + session_uuids: list[str], +) -> dict[str, str]: + """Query the metadata DB for skill/command classifications of given sessions. + + The DB already has correctly classified invocations (session_skills and + session_commands tables). We extract all plugin colon-format names and + their categories so the importing machine can use them as ground truth. + + Returns: + Dict mapping invocation name → InvocationCategory string. + E.g. {'feature-dev:feature-dev': 'plugin_command', + 'superpowers:brainstorming': 'plugin_skill'} + """ + if not session_uuids: + return {} + + try: + from db.connection import create_writer_connection + + conn = create_writer_connection() + except Exception: + return {} + + classifications: dict[str, str] = {} + placeholders = ",".join("?" * len(session_uuids)) + + try: + # Import classify_invocation from API (already on sys.path) + try: + from command_helpers import classify_invocation + _classify = classify_invocation + except ImportError: + # Fallback: colon-format → plugin, otherwise unknown (will be reclassified on import) + def _classify(name, source="skill_tool"): # type: ignore[misc] + return "plugin_skill" if ":" in name else "custom_skill" + + # Skills from session_skills table (all names, not just colon-format) + rows = conn.execute( + f"SELECT DISTINCT skill_name FROM session_skills WHERE session_uuid IN ({placeholders})", + session_uuids, + ).fetchall() + for row in rows: + classifications[row[0]] = _classify(row[0], source="skill_tool") + + # Commands from session_commands table (all names, not just colon-format) + rows = conn.execute( + f"SELECT DISTINCT command_name FROM session_commands WHERE session_uuid IN ({placeholders})", + session_uuids, + ).fetchall() + for row in rows: + classifications[row[0]] = _classify(row[0], source="slash_command") + + # Subagent skills + rows = conn.execute( + f"""SELECT DISTINCT ss.skill_name FROM subagent_skills ss + JOIN subagent_invocations si ON ss.invocation_id = si.id + WHERE si.session_uuid IN ({placeholders})""", + session_uuids, + ).fetchall() + for row in rows: + if row[0] not in classifications: + classifications[row[0]] = _classify(row[0], source="skill_tool") + + # Subagent commands + rows = conn.execute( + f"""SELECT DISTINCT sc.command_name FROM subagent_commands sc + JOIN subagent_invocations si ON sc.invocation_id = si.id + WHERE si.session_uuid IN ({placeholders})""", + session_uuids, + ).fetchall() + for row in rows: + if row[0] not in classifications: + classifications[row[0]] = _classify(row[0], source="slash_command") + + except Exception as e: + logger.warning("Failed to extract skill classifications from DB: %s", e) + finally: + conn.close() + + return classifications + + +def _detect_git_branch(project_path: str) -> Optional[str]: + """Detect the current git branch for a project/worktree path. + + Tries ``git rev-parse --abbrev-ref HEAD`` in the given directory. + Returns None if git is not available, the path doesn't exist, or + the repo is in detached-HEAD state. + """ + try: + result = subprocess.run( + ["git", "rev-parse", "--abbrev-ref", "HEAD"], + cwd=project_path, + capture_output=True, + text=True, + timeout=5, + ) + if result.returncode != 0: + return None + branch = result.stdout.strip() + if not branch or branch == "HEAD": + return None + return branch + except (subprocess.SubprocessError, OSError): + return None + + +def _extract_worktree_name(dir_name: str, main_dir_name: str) -> Optional[str]: + """Extract human-readable worktree name from encoded dir name. + + Given main="-Users-jay-GitHub-karma" and + dir="-Users-jay-GitHub-karma--claude-worktrees-feat-a", + returns "feat-a". + """ + markers = ["--claude-worktrees-", "-.claude-worktrees-", "--worktrees-", "-.worktrees-"] + for marker in markers: + idx = dir_name.find(marker) + if idx > 0: + return dir_name[idx + len(marker):] + return None + + +class SessionPackager: + """Discovers and packages Claude Code sessions for a project.""" + + def __init__( + self, + project_dir: Path, + user_id: str, + machine_id: str, + device_id: Optional[str] = None, + project_path: str = "", + extra_dirs: Optional[list[Path]] = None, + team_name: Optional[str] = None, + proj_suffix: Optional[str] = None, + member_tag: Optional[str] = None, + ): + self.project_dir = Path(project_dir) + self.user_id = user_id + self.machine_id = machine_id + self.member_tag = member_tag + self.device_id = device_id + self.project_path = project_path or str(self.project_dir) + + self.extra_dirs = [Path(d) for d in (extra_dirs or [])] + self.team_name = team_name + self.proj_suffix = proj_suffix + # ~/.claude/ base directory (parent of projects/{encoded}/) + self._claude_base = self.project_dir.parent.parent + + def _discover_from_dir( + self, + directory: Path, + worktree_name: Optional[str] = None, + git_branch: Optional[str] = None, + ) -> list[SessionEntry]: + """Find session JSONL files in a single directory.""" + entries = [] + for jsonl_path in sorted(directory.glob("*.jsonl")): + if jsonl_path.name.startswith("agent-"): + continue + try: + stat = jsonl_path.stat() + except (PermissionError, OSError) as e: + logger.debug("Skipping unreadable file %s: %s", jsonl_path, e) + continue + if stat.st_size == 0: + continue + entries.append( + SessionEntry( + uuid=jsonl_path.stem, + mtime=datetime.fromtimestamp(stat.st_mtime, tz=timezone.utc).isoformat(), + size_bytes=stat.st_size, + worktree_name=worktree_name, + git_branch=git_branch, + ) + ) + return entries + + def discover_sessions(self, exclude_live: bool = True) -> list[SessionEntry]: + """Find all session JSONL files in the project and worktree directories. + + Args: + exclude_live: If True (default), skip sessions that are currently + live according to ``~/.claude_karma/live-sessions/``. When hooks + aren't configured the live-sessions dir won't exist, so no + sessions are excluded — backward compatible. + """ + live_uuids = _get_live_session_uuids() if exclude_live else set() + + # Detect git branch for the main project directory + main_branch = _detect_git_branch(self.project_path) + entries = self._discover_from_dir(self.project_dir, git_branch=main_branch) + + for extra_dir in self.extra_dirs: + if not extra_dir.is_dir(): + continue + wt_name = _extract_worktree_name(extra_dir.name, self.project_dir.name) + + # For worktrees, construct the real worktree path from the project path + wt_branch: Optional[str] = None + if wt_name: + wt_path = Path(self.project_path) / ".claude" / "worktrees" / wt_name + if wt_path.is_dir(): + wt_branch = _detect_git_branch(str(wt_path)) + if wt_branch is None: + # Fallback: try .worktrees/ (alternate location) + wt_path_alt = Path(self.project_path) / ".worktrees" / wt_name + if wt_path_alt.is_dir(): + wt_branch = _detect_git_branch(str(wt_path_alt)) + + entries.extend( + self._discover_from_dir(extra_dir, worktree_name=wt_name, git_branch=wt_branch) + ) + + if live_uuids: + before = len(entries) + entries = [e for e in entries if e.uuid not in live_uuids] + skipped = before - len(entries) + if skipped: + logger.info("Excluded %d live session(s) from packaging", skipped) + + return entries + + def _source_dir_for_session(self, entry: SessionEntry) -> Path: + """Find the directory containing the session's JSONL file.""" + if (self.project_dir / f"{entry.uuid}.jsonl").exists(): + return self.project_dir + for extra_dir in self.extra_dirs: + if (extra_dir / f"{entry.uuid}.jsonl").exists(): + return extra_dir + return self.project_dir # fallback + + def package(self, staging_dir: Path, session_limit: str = "all") -> SyncManifest: + """Copy session files into staging directory and create manifest.""" + sessions = self.discover_sessions() + + # Apply session limit (disk space aware, with per-device metadata override) + limit = get_session_limit( + session_limit, staging_dir, + team_name=self.team_name, member_tag=self.member_tag, + ) + if limit is not None and len(sessions) > limit: + # Sort by mtime descending (most recent first), take top N + sessions.sort(key=lambda s: s.mtime, reverse=True) + sessions = sessions[:limit] + + sessions_dir = staging_dir / "sessions" + sessions_dir.mkdir(parents=True, exist_ok=True) + + for entry in sessions: + source_dir = self._source_dir_for_session(entry) + + # Copy JSONL file (skip if unchanged) + src_jsonl = source_dir / f"{entry.uuid}.jsonl" + dst_jsonl = sessions_dir / src_jsonl.name + if not dst_jsonl.exists() or src_jsonl.stat().st_mtime > dst_jsonl.stat().st_mtime: + try: + shutil.copy2(src_jsonl, dst_jsonl) + except (PermissionError, OSError) as e: + logger.warning("Failed to copy %s: %s", src_jsonl, e) + continue + + # Copy associated directories (subagents, tool-results) + assoc_dir = source_dir / entry.uuid + if assoc_dir.is_dir(): + try: + shutil.copytree( + assoc_dir, + sessions_dir / entry.uuid, + dirs_exist_ok=True, + ) + except (PermissionError, OSError) as e: + logger.warning("Failed to copy directory %s: %s", assoc_dir, e) + + # Copy todos (glob pattern: {uuid}-*.json) + todos_base = self._claude_base / "todos" + if todos_base.is_dir(): + todos_staging = staging_dir / "todos" + for session_entry in sessions: + for todo_file in todos_base.glob(f"{session_entry.uuid}-*.json"): + todos_staging.mkdir(exist_ok=True) + try: + shutil.copy2(todo_file, todos_staging / todo_file.name) + except (PermissionError, OSError) as e: + logger.warning("Failed to copy %s: %s", todo_file, e) + + # Copy per-session directories (tasks, file-history) + for resource_name in ("tasks", "file-history"): + resource_base = self._claude_base / resource_name + if resource_base.is_dir(): + resource_staging = staging_dir / resource_name + for session_entry in sessions: + src_dir = resource_base / session_entry.uuid + if src_dir.is_dir(): + resource_staging.mkdir(exist_ok=True) + try: + shutil.copytree( + src_dir, + resource_staging / session_entry.uuid, + dirs_exist_ok=True, + ) + except (PermissionError, OSError) as e: + logger.warning("Failed to copy directory %s: %s", src_dir, e) + + # Copy debug logs (single file: {uuid}.txt) + debug_base = self._claude_base / "debug" + if debug_base.is_dir(): + debug_staging = staging_dir / "debug" + for session_entry in sessions: + debug_file = debug_base / f"{session_entry.uuid}.txt" + if debug_file.is_file(): + debug_staging.mkdir(exist_ok=True) + try: + shutil.copy2(debug_file, debug_staging / debug_file.name) + except (PermissionError, OSError) as e: + logger.warning("Failed to copy %s: %s", debug_file, e) + + # Discover and copy referenced plans (best-effort) + try: + session_jsonls = [ + (entry.uuid, self._source_dir_for_session(entry) / f"{entry.uuid}.jsonl") + for entry in sessions + ] + plan_refs = _discover_plan_references(session_jsonls) + + if plan_refs: + plans_base = self._claude_base / "plans" + plans_staging = staging_dir / "plans" + copied_slugs = [] + + for slug in plan_refs: + src_plan = plans_base / f"{slug}.md" + if src_plan.is_file(): + plans_staging.mkdir(exist_ok=True) + dst_plan = plans_staging / f"{slug}.md" + if not dst_plan.exists() or src_plan.stat().st_mtime > dst_plan.stat().st_mtime: + shutil.copy2(src_plan, dst_plan) + copied_slugs.append(slug) + + # Write plans-index.json sidecar + if copied_slugs: + plans_index = { + "version": 1, + "updated_at": datetime.now(timezone.utc).isoformat(), + "plans": { + slug: {"sessions": plan_refs[slug]} + for slug in copied_slugs + }, + } + index_path = staging_dir / "plans-index.json" + index_path.write_text( + json.dumps(plans_index, indent=2, ensure_ascii=False) + "\n", + encoding="utf-8", + ) + logger.debug("Packaged %d plans for sync", len(copied_slugs)) + except Exception as e: + logger.debug("Plan packaging failed (best-effort): %s", e) + + # Detect git identity for cross-machine project matching + from utils.git import detect_git_identity + + git_id = detect_git_identity(self.project_path) + + # Build skill classifications from the metadata DB. + # The exporting machine has already indexed sessions with correct + # classifications — reuse that instead of re-scanning JSONL files. + skill_classifications = _build_skill_classifications_from_db( + [entry.uuid for entry in sessions] + ) + + # Build skill definitions from the local filesystem (best-effort). + # Resolves each skill in skill_classifications to its SKILL.md file + # and includes the content in the manifest for reliable remote import. + try: + skill_definitions = _build_skill_definitions( + skill_classifications, self._claude_base + ) + except Exception as e: + logger.debug("Skill definitions packaging failed (best-effort): %s", e) + skill_definitions = {} + + # Derive human-readable project name for manifest + # Prefer: directory name from project path > proj_suffix > encoded name + _project_name = Path(self.project_path).name if self.project_path else self.proj_suffix + + # Build manifest + manifest = SyncManifest( + user_id=self.user_id, + machine_id=self.machine_id, + member_tag=self.member_tag, + device_id=self.device_id, + project_path=self.project_path, + project_encoded=self.project_dir.name, + session_count=len(sessions), + sessions=sessions, + + git_identity=git_id, + team_name=self.team_name, + proj_suffix=self.proj_suffix, + project_name=_project_name, + skill_classifications=skill_classifications, + skill_definitions=skill_definitions, + ) + + manifest_path = staging_dir / "manifest.json" + manifest_path.write_text(json.dumps(manifest.model_dump(), indent=2) + "\n") + + # Backfill titles.json from DB (merges with any existing hook-written titles) + try: + from services.titles_io import write_titles_bulk + + titles_path = staging_dir / "titles.json" + db_titles = _build_titles_from_db([entry.uuid for entry in sessions]) + write_titles_bulk(titles_path, db_titles) + except Exception as e: + logger.debug("titles.json backfill failed (best-effort): %s", e) + + return manifest diff --git a/api/services/sync/session_watcher.py b/api/services/sync/session_watcher.py new file mode 100644 index 00000000..e2508bae --- /dev/null +++ b/api/services/sync/session_watcher.py @@ -0,0 +1,79 @@ +"""Filesystem watcher for automatic session packaging.""" + +import logging +import threading +from pathlib import Path +from typing import Callable, Optional + +from watchdog.events import FileSystemEventHandler +from watchdog.observers import Observer + +logger = logging.getLogger(__name__) + + +class SessionWatcher(FileSystemEventHandler): + """Watches Claude project dirs for JSONL changes and triggers packaging.""" + + def __init__( + self, + watch_dir: Path, + package_fn: Callable[[], None], + debounce_seconds: float = 5.0, + ): + self.watch_dir = Path(watch_dir) + self.package_fn = package_fn + self.debounce_seconds = debounce_seconds + self._timer: Optional[threading.Timer] = None + self._observer: Optional[Observer] = None + self._lock = threading.Lock() + + @property + def is_running(self) -> bool: + return self._observer is not None and self._observer.is_alive() + + def _should_process(self, path: str) -> bool: + """Only process session JSONL files (not agent files).""" + p = Path(path) + return p.suffix == ".jsonl" and not p.name.startswith("agent-") + + def on_modified(self, event): + if self._should_process(event.src_path): + self._schedule_package() + + def on_created(self, event): + if self._should_process(event.src_path): + self._schedule_package() + + def _schedule_package(self): + """Debounced packaging — waits for quiet period before running.""" + with self._lock: + if self._timer is not None: + self._timer.cancel() + self._timer = threading.Timer(self.debounce_seconds, self._do_package) + self._timer.daemon = True + self._timer.start() + + def _do_package(self): + """Execute the packaging function.""" + try: + self.package_fn() + except Exception: + logger.exception("Packaging error during watch") + + def start(self): + """Start watching the directory.""" + self._observer = Observer() + self._observer.schedule(self, str(self.watch_dir), recursive=True) + self._observer.daemon = True + self._observer.start() + + def stop(self): + """Stop watching.""" + with self._lock: + if self._timer is not None: + self._timer.cancel() + self._timer = None + if self._observer is not None: + self._observer.stop() + self._observer.join(timeout=5) + self._observer = None diff --git a/api/services/sync/team_service.py b/api/services/sync/team_service.py new file mode 100644 index 00000000..5f163fa2 --- /dev/null +++ b/api/services/sync/team_service.py @@ -0,0 +1,321 @@ +"""TeamService — team lifecycle + member management orchestration.""" +from __future__ import annotations + +import logging +import sqlite3 +from typing import TYPE_CHECKING + +from domain.team import Team +from domain.member import Member, MemberStatus +from domain.subscription import Subscription +from domain.events import SyncEvent, SyncEventType +from services.syncthing.folder_manager import build_outbox_folder_id, build_metadata_folder_id + +logger = logging.getLogger(__name__) + +if TYPE_CHECKING: + from repositories.team_repo import TeamRepository + from repositories.member_repo import MemberRepository + from repositories.project_repo import ProjectRepository + from repositories.subscription_repo import SubscriptionRepository + from repositories.event_repo import EventRepository + from services.syncthing.device_manager import DeviceManager + from services.syncthing.folder_manager import FolderManager + from services.sync.metadata_service import MetadataService + + +class TeamService: + def __init__( + self, + teams: "TeamRepository", + members: "MemberRepository", + projects: "ProjectRepository", + subs: "SubscriptionRepository", + events: "EventRepository", + devices: "DeviceManager", + metadata: "MetadataService", + folders: "FolderManager", + ): + self.teams = teams + self.members = members + self.projects = projects + self.subs = subs + self.events = events + self.devices = devices + self.metadata = metadata + self.folders = folders + + async def create_team( + self, + conn: sqlite3.Connection, + *, + name: str, + leader_member_tag: str, + leader_device_id: str, + ) -> Team: + """Create a new team with the given leader as an immediately ACTIVE member.""" + team = Team( + name=name, + leader_device_id=leader_device_id, + leader_member_tag=leader_member_tag, + ) + leader = Member.from_member_tag( + member_tag=leader_member_tag, + team_name=name, + device_id=leader_device_id, + status=MemberStatus.ACTIVE, + ) + self.teams.save(conn, team) + self.members.save(conn, leader) + self.metadata.write_team_state(team, [leader]) + self.metadata.purge_stale_removals(name) + await self.folders.ensure_metadata_folder(name) + self.events.log(conn, SyncEvent( + event_type=SyncEventType.team_created, + team_name=name, + )) + return team + + async def add_member( + self, + conn: sqlite3.Connection, + *, + team_name: str, + by_device: str, + new_member_tag: str, + new_device_id: str, + ) -> Member: + """Add a new member to the team. Only the leader may add members. + + Creates OFFERED subscriptions for all currently shared projects. + Pairs the new device via Syncthing. + """ + team = self.teams.get(conn, team_name) + if team is None: + raise ValueError(f"Team '{team_name}' not found") + + member = Member.from_member_tag( + member_tag=new_member_tag, + team_name=team_name, + device_id=new_device_id, + ) + added = team.add_member(member, by_device=by_device) # auth check + self.members.save(conn, added) + + # Syncthing operations are best-effort — failures must not block + # DB operations (subscriptions, metadata, events) below. + try: + await self.devices.pair(new_device_id) + await self.folders.ensure_metadata_folder(team_name) + + all_folders = await self.folders.get_configured_folders() + + # Share metadata folder + meta_folder_id = build_metadata_folder_id(team_name) + meta_folder = next((f for f in all_folders if f["id"] == meta_folder_id), None) + if meta_folder: + existing_device_ids = {d["deviceID"] for d in meta_folder.get("devices", [])} + existing_device_ids.add(new_device_id) + await self.folders.set_folder_devices(meta_folder_id, existing_device_ids) + + # Share all project outbox folders + shared_projects = self.projects.list_for_team(conn, team_name) + for project in shared_projects: + if project.status.value == "shared": + folder_id = build_outbox_folder_id(team.leader_member_tag, project.folder_suffix) + folder = next((f for f in all_folders if f["id"] == folder_id), None) + if folder: + existing = {d["deviceID"] for d in folder.get("devices", [])} + existing.add(new_device_id) + await self.folders.set_folder_devices(folder_id, existing) + except Exception as e: + logger.warning("Syncthing setup failed for new member %s (reconciliation will retry): %s", new_member_tag, e) + + # Update metadata with all current members + all_members = self.members.list_for_team(conn, team_name) + self.metadata.write_team_state(team, all_members) + + # Create OFFERED subscriptions for all currently shared projects + projects = self.projects.list_for_team(conn, team_name) + for project in projects: + if project.status.value == "shared": + sub = Subscription( + member_tag=new_member_tag, + team_name=team_name, + project_git_identity=project.git_identity, + ) + self.subs.save(conn, sub) + + self.events.log(conn, SyncEvent( + event_type=SyncEventType.member_added, + team_name=team_name, + member_tag=new_member_tag, + detail={"device_id": new_device_id, "added_by": team.leader_member_tag}, + )) + return added + + async def remove_member( + self, + conn: sqlite3.Connection, + *, + team_name: str, + by_device: str, + member_tag: str, + ) -> Member: + """Remove a member from the team. Only the leader may remove members. + + Records the removal to prevent re-add from stale metadata. + Writes a removal signal to the metadata folder. + Unpairing happens only if the device is not in any other team. + """ + team = self.teams.get(conn, team_name) + if team is None: + raise ValueError(f"Team '{team_name}' not found") + + member = self.members.get(conn, team_name, member_tag) + if member is None: + raise ValueError(f"Member '{member_tag}' not found in team '{team_name}'") + + removed = team.remove_member(member, by_device=by_device) # auth check + self.members.save(conn, removed) + self.members.record_removal(conn, team_name, removed.device_id, member_tag=member_tag) + + # Write removal signal to metadata folder (includes team_id for incarnation check) + self.metadata.write_removal_signal( + team_name, member_tag, removed_by=team.leader_member_tag, team_id=team.team_id, + ) + + # Remove device from all team folder device lists + projects = self.projects.list_for_team(conn, team_name) + suffixes = [p.folder_suffix for p in projects if p.status.value == "shared"] + all_members = self.members.list_for_team(conn, team_name) + tags = [m.member_tag for m in all_members] + await self.folders.remove_device_from_team_folders(suffixes, tags, removed.device_id) + + # Unpair only if device not in any other team (ADDED or ACTIVE) + other_memberships = self.members.get_by_device(conn, removed.device_id) + alive_others = [ + m for m in other_memberships + if m.team_name != team_name and m.status != MemberStatus.REMOVED + ] + if not alive_others: + await self.devices.unpair(removed.device_id) + + self.events.log(conn, SyncEvent( + event_type=SyncEventType.member_removed, + team_name=team_name, + member_tag=member_tag, + detail={"device_id": removed.device_id, "removed_by": team.leader_member_tag}, + )) + return removed + + async def leave_team( + self, + conn: sqlite3.Connection, + *, + team_name: str, + member_tag: str, + ) -> None: + """Leave a team voluntarily. Non-leaders only. + + Runs the same cleanup as reconciliation auto-leave: + removes folders, unpairs devices not shared with other teams, deletes team locally. + """ + team = self.teams.get(conn, team_name) + if team is None: + raise ValueError(f"Team '{team_name}' not found") + + if team.leader_member_tag == member_tag: + raise ValueError("Team leaders must dissolve the team, not leave it") + + # Same cleanup as _auto_leave in ReconciliationService + projects = self.projects.list_for_team(conn, team_name) + members = self.members.list_for_team(conn, team_name) + suffixes = [p.folder_suffix for p in projects] + tags = [m.member_tag for m in members] + + await self.folders.cleanup_team_folders(suffixes, tags, team_name, conn=conn) + + # Unpair devices not shared with other teams + for member in members: + if member.member_tag == member_tag: + continue + others = self.members.get_by_device(conn, member.device_id) + if len([o for o in others if o.team_name != team_name]) == 0: + await self.devices.unpair(member.device_id) + + conn.execute("DELETE FROM sync_events WHERE team_name = ?", (team_name,)) + self.teams.delete(conn, team_name) + self.events.log(conn, SyncEvent( + event_type=SyncEventType.member_left, + team_name=team_name, + member_tag=member_tag, + )) + + async def dissolve_team( + self, + conn: sqlite3.Connection, + *, + team_name: str, + by_device: str, + ) -> Team: + """Dissolve the team. Only the leader may dissolve. + + Writes removal signals for all non-leader members so their + reconciliation auto-leaves. Then cleans up Syncthing folders + and deletes the team from DB (CASCADE handles members, projects, + subscriptions). + """ + team = self.teams.get(conn, team_name) + if team is None: + raise ValueError(f"Team '{team_name}' not found") + + dissolved = team.dissolve(by_device=by_device) # auth check + + # Write removal signals for all non-leader members so their + # reconciliation Phase 1 detects dissolution and auto-leaves. + members = self.members.list_for_team(conn, team_name) + for member in members: + if member.member_tag != team.leader_member_tag: + try: + self.metadata.write_removal_signal( + team_name, member.member_tag, + removed_by=team.leader_member_tag, team_id=team.team_id, + ) + except Exception as e: + logger.warning( + "Failed to write dissolution removal signal for %s: %s", + member.member_tag, e, + ) + + # Cleanup Syncthing folders for all projects + members + projects = self.projects.list_for_team(conn, team_name) + suffixes = [p.folder_suffix for p in projects] + tags = [m.member_tag for m in members] + await self.folders.cleanup_team_folders(suffixes, tags, team_name, conn=conn) + + # Unpair devices for non-leader members not shared with other teams + for member in members: + if member.member_tag != team.leader_member_tag: + others = self.members.get_by_device(conn, member.device_id) + if len([o for o in others if o.team_name != team_name]) == 0: + await self.devices.unpair(member.device_id) + + # Soft-delete: persist dissolved status for audit trail + self.teams.save(conn, dissolved) + + # Explicitly clean up child records (CASCADE doesn't fire on UPDATE). + # Members, subscriptions, projects, events, and removal records + # are no longer relevant — clean slate for potential team name reuse. + conn.execute("DELETE FROM sync_subscriptions WHERE team_name = ?", (team_name,)) + conn.execute("DELETE FROM sync_projects WHERE team_name = ?", (team_name,)) + conn.execute("DELETE FROM sync_members WHERE team_name = ?", (team_name,)) + conn.execute("DELETE FROM sync_events WHERE team_name = ?", (team_name,)) + conn.execute("DELETE FROM sync_removed_members WHERE team_name = ?", (team_name,)) + + self.events.log(conn, SyncEvent( + event_type=SyncEventType.team_dissolved, + team_name=team_name, + )) + conn.commit() + return dissolved diff --git a/api/services/sync/worktree_discovery.py b/api/services/sync/worktree_discovery.py new file mode 100644 index 00000000..e5af83f1 --- /dev/null +++ b/api/services/sync/worktree_discovery.py @@ -0,0 +1,157 @@ +"""Worktree directory discovery for CLI packager. + +Detects worktree project directories that belong to a given main project. +This is a lightweight port of the logic in api/services/desktop_sessions.py, +without any API dependencies. + +Worktree patterns (all encoded by Claude Code): + 1. CLI worktrees: {project}/.claude/worktrees/{name} + Encoded: {project_encoded}--claude-worktrees-{name} + 2. Superpowers: {project}/.worktrees/{name} + Encoded: {project_encoded}--worktrees-{name} + 3. Desktop worktrees: ~/.claude-worktrees/{project}/{name} + Encoded: -Users-{user}--claude-worktrees-{project}-{name} + (These DON'T share a prefix with the main project -- handled separately) +""" + +from pathlib import Path + +_WORKTREE_MARKERS = [ + "--claude-worktrees-", + "-.claude-worktrees-", + "--worktrees-", + "-.worktrees-", +] + + +def is_worktree_dir(encoded_name: str) -> bool: + """Check if an encoded project directory name is a worktree.""" + if not encoded_name: + return False + if "-claude-worktrees-" in encoded_name: + return True + if "--worktrees-" in encoded_name or "-.worktrees-" in encoded_name: + return True + return False + + +def _get_worktree_prefix(encoded_name: str) -> str | None: + """Extract the main project prefix from a worktree encoded name. + + Returns the prefix before the worktree marker, or None if not a + prefix-style worktree (e.g., Desktop worktrees don't share a prefix). + """ + for marker in _WORKTREE_MARKERS: + idx = encoded_name.find(marker) + if idx > 0: + prefix = encoded_name[:idx] + if prefix.startswith("-") and len(prefix) > 1: + return prefix + return None + + +def find_worktree_dirs( + main_encoded_name: str, projects_dir: Path +) -> list[Path]: + """Find all worktree directories that belong to a main project. + + Scans projects_dir for directories whose encoded name starts with + the main project's encoded name followed by a worktree marker. + + Args: + main_encoded_name: The main project's encoded directory name + (e.g., "-Users-jay-GitHub-karma"). + projects_dir: Path to ~/.claude/projects/ + + Returns: + List of Path objects for matching worktree directories. + """ + if not projects_dir.is_dir(): + return [] + + matches = [] + for entry in projects_dir.iterdir(): + if not entry.is_dir(): + continue + if entry.name == main_encoded_name: + continue # skip the main project itself + if not is_worktree_dir(entry.name): + continue + # Check if this worktree's prefix matches the main project + prefix = _get_worktree_prefix(entry.name) + if prefix == main_encoded_name: + matches.append(entry) + + return sorted(matches) + + +def project_name_from_path(project_path: str) -> str: + """Extract the directory name from a full project path. + + Examples: + /Users/jay/GitHub/claude-karma -> claude-karma + C:\\Users\\jay\\repos\\karma -> karma + /Users/jay/repo/ -> repo (trailing slash) + myproject -> myproject + """ + p = project_path.replace("\\", "/").rstrip("/") + return p.rsplit("/", 1)[-1] if "/" in p else p + + +def find_desktop_worktree_dirs( + project_name: str, + projects_dir: Path, + worktree_base: Path | None = None, +) -> list[Path]: + """Find Desktop worktree directories for a project. + + Desktop worktrees (created by Claude Desktop) live in + ~/.claude-worktrees/{project_name}/{random_name}/ and get encoded as: + -Users-{user}--claude-worktrees-{project}-{name} + + These DON'T share a prefix with the main project, so we scan for + the marker pattern instead. + """ + if worktree_base is None: + worktree_base = Path.home() / ".claude-worktrees" + + if not projects_dir.is_dir(): + return [] + + marker = f"-claude-worktrees-{project_name}-" + + matches = [] + for entry in projects_dir.iterdir(): + if not entry.is_dir(): + continue + if marker not in entry.name: + continue + matches.append(entry) + + return sorted(matches) + + +def find_all_worktree_dirs( + main_encoded_name: str, + project_path: str, + projects_dir: Path, + worktree_base: Path | None = None, +) -> list[Path]: + """Find ALL worktree directories for a project (CLI + Desktop). + + Combines find_worktree_dirs() (prefix match) and + find_desktop_worktree_dirs() (project name match), deduplicating results. + """ + cli_dirs = find_worktree_dirs(main_encoded_name, projects_dir) + proj_name = project_name_from_path(project_path) + desktop_dirs = find_desktop_worktree_dirs(proj_name, projects_dir, worktree_base) + + seen: set[Path] = set() + result: list[Path] = [] + for d in cli_dirs + desktop_dirs: + resolved = d.resolve() + if resolved not in seen: + seen.add(resolved) + result.append(d) + + return sorted(result) diff --git a/api/services/syncthing/__init__.py b/api/services/syncthing/__init__.py new file mode 100644 index 00000000..de6062a8 --- /dev/null +++ b/api/services/syncthing/__init__.py @@ -0,0 +1,21 @@ +"""Syncthing abstraction layer — pure HTTP wrappers and domain managers.""" + +from services.syncthing.client import SyncthingClient +from services.syncthing.device_manager import DeviceManager +from services.syncthing.folder_manager import ( + FolderManager, + build_metadata_folder_id, + build_outbox_folder_id, + parse_member_tag, + parse_outbox_id, +) + +__all__ = [ + "SyncthingClient", + "DeviceManager", + "FolderManager", + "build_outbox_folder_id", + "build_metadata_folder_id", + "parse_member_tag", + "parse_outbox_id", +] diff --git a/api/services/syncthing/client.py b/api/services/syncthing/client.py new file mode 100644 index 00000000..250774b7 --- /dev/null +++ b/api/services/syncthing/client.py @@ -0,0 +1,167 @@ +""" +SyncthingClient — pure HTTP wrapper for the Syncthing REST API. + +No business logic lives here. Each method maps 1-to-1 to a Syncthing +REST endpoint. Callers (DeviceManager, FolderManager, etc.) add logic. +""" + +from typing import Any, Dict, List, Optional + +import httpx + + +class SyncthingClient: + """Thin async HTTP client for the Syncthing REST API.""" + + def __init__(self, api_url: str, api_key: str, timeout: float = 30.0) -> None: + self.api_url = api_url.rstrip("/") + self.api_key = api_key + self.timeout = timeout + + # ------------------------------------------------------------------ + # Internal helpers + # ------------------------------------------------------------------ + + def _headers(self) -> Dict[str, str]: + return { + "X-API-Key": self.api_key, + "Content-Type": "application/json", + } + + async def _get(self, path: str, params: Optional[Dict[str, str]] = None) -> Any: + async with httpx.AsyncClient(timeout=self.timeout) as http: + resp = await http.get( + self.api_url + path, + headers=self._headers(), + params=params, + ) + resp.raise_for_status() + return resp.json() + + async def _post( + self, + path: str, + json: Optional[Any] = None, + params: Optional[Dict[str, str]] = None, + ) -> None: + async with httpx.AsyncClient(timeout=self.timeout) as http: + resp = await http.post( + self.api_url + path, + headers=self._headers(), + json=json, + params=params, + ) + resp.raise_for_status() + + async def _put(self, path: str, json: Optional[Any] = None) -> None: + async with httpx.AsyncClient(timeout=self.timeout) as http: + resp = await http.put( + self.api_url + path, + headers=self._headers(), + json=json, + ) + resp.raise_for_status() + + async def _delete( + self, path: str, params: Optional[Dict[str, str]] = None + ) -> None: + async with httpx.AsyncClient(timeout=self.timeout) as http: + resp = await http.delete( + self.api_url + path, + headers=self._headers(), + params=params, + ) + resp.raise_for_status() + + # ------------------------------------------------------------------ + # System + # ------------------------------------------------------------------ + + async def get_system_status(self) -> Dict[str, Any]: + """GET /rest/system/status — returns myID, uptime, etc.""" + return await self._get("/rest/system/status") + + async def get_connections(self) -> Dict[str, Any]: + """GET /rest/system/connections — returns connected device map.""" + return await self._get("/rest/system/connections") + + # ------------------------------------------------------------------ + # Config (whole config) + # ------------------------------------------------------------------ + + async def get_config(self) -> Dict[str, Any]: + """GET /rest/config — full Syncthing config.""" + return await self._get("/rest/config") + + async def post_config(self, config: Dict[str, Any]) -> None: + """POST /rest/config — replace full config.""" + await self._post("/rest/config", json=config) + + # ------------------------------------------------------------------ + # Config — devices + # ------------------------------------------------------------------ + + async def get_config_devices(self) -> List[Dict[str, Any]]: + """GET /rest/config/devices — list of configured devices.""" + return await self._get("/rest/config/devices") + + async def put_config_device(self, device: Dict[str, Any]) -> None: + """PUT /rest/config/devices/{id} — add or update a single device.""" + device_id = device["deviceID"] + await self._put(f"/rest/config/devices/{device_id}", json=device) + + async def delete_config_device(self, device_id: str) -> None: + """DELETE /rest/config/devices/{device_id} — remove a device.""" + await self._delete(f"/rest/config/devices/{device_id}") + + # ------------------------------------------------------------------ + # Config — folders + # ------------------------------------------------------------------ + + async def get_config_folders(self) -> List[Dict[str, Any]]: + """GET /rest/config/folders — list of configured folders.""" + return await self._get("/rest/config/folders") + + async def put_config_folder(self, folder: Dict[str, Any]) -> None: + """PUT /rest/config/folders/{id} — add or update a single folder.""" + folder_id = folder["id"] + await self._put(f"/rest/config/folders/{folder_id}", json=folder) + + async def delete_config_folder(self, folder_id: str) -> None: + """DELETE /rest/config/folders/{folder_id} — remove a folder.""" + await self._delete(f"/rest/config/folders/{folder_id}") + + # ------------------------------------------------------------------ + # Pending (cluster) + # ------------------------------------------------------------------ + + async def get_pending_devices(self) -> Dict[str, Any]: + """GET /rest/cluster/pending/devices — devices requesting connection.""" + return await self._get("/rest/cluster/pending/devices") + + async def dismiss_pending_device(self, device_id: str) -> None: + """DELETE /rest/cluster/pending/devices?device={device_id} — dismiss a pending device.""" + await self._delete("/rest/cluster/pending/devices", params={"device": device_id}) + + async def get_pending_folders(self) -> Dict[str, Any]: + """GET /rest/cluster/pending/folders — folders offered by peers.""" + return await self._get("/rest/cluster/pending/folders") + + async def dismiss_pending_folder(self, folder_id: str, device_id: str) -> None: + """DELETE /rest/cluster/pending/folders?folder={id}&device={id} — dismiss a pending folder.""" + await self._delete( + "/rest/cluster/pending/folders", + params={"folder": folder_id, "device": device_id}, + ) + + # ------------------------------------------------------------------ + # Database / folder ops + # ------------------------------------------------------------------ + + async def get_folder_status(self, folder_id: str) -> Dict[str, Any]: + """GET /rest/db/status?folder={folder_id} — folder sync status.""" + return await self._get("/rest/db/status", params={"folder": folder_id}) + + async def post_folder_rescan(self, folder_id: str) -> None: + """POST /rest/db/scan?folder={folder_id} — trigger rescan.""" + await self._post("/rest/db/scan", params={"folder": folder_id}) diff --git a/api/services/syncthing/device_manager.py b/api/services/syncthing/device_manager.py new file mode 100644 index 00000000..3173a76f --- /dev/null +++ b/api/services/syncthing/device_manager.py @@ -0,0 +1,76 @@ +""" +DeviceManager — high-level operations on Syncthing device configuration. + +Wraps SyncthingClient to provide idempotent pair/unpair operations and +connection status queries. +""" + +from typing import List + +from services.syncthing.client import SyncthingClient + + +class DeviceManager: + """Manages Syncthing device pairing and connection status.""" + + def __init__(self, client: SyncthingClient) -> None: + self._client = client + + # ------------------------------------------------------------------ + # Pairing + # ------------------------------------------------------------------ + + async def pair(self, device_id: str) -> None: + """Add device to Syncthing config. Overwrites if already present.""" + device = { + "deviceID": device_id, + "name": device_id[:8], + "addresses": ["dynamic"], + "compression": "metadata", + "certName": "", + "introducer": False, + "skipIntroductionRemovals": False, + "introducedBy": "", + "paused": False, + "allowedNetworks": [], + "autoAcceptFolders": False, + "maxSendKbps": 0, + "maxRecvKbps": 0, + "ignoredFolders": [], + "encryptionPassword": "", + } + await self._client.put_config_device(device) + + async def unpair(self, device_id: str) -> None: + """Remove device from Syncthing config.""" + await self._client.delete_config_device(device_id) + + async def ensure_paired(self, device_id: str) -> None: + """Pair the device only if it is not already in the config (idempotent).""" + existing = await self._client.get_config_devices() + existing_ids = {d["deviceID"] for d in existing} + if device_id not in existing_ids: + await self.pair(device_id) + + # ------------------------------------------------------------------ + # Connection status + # ------------------------------------------------------------------ + + async def is_connected(self, device_id: str) -> bool: + """Return True if the device is currently connected.""" + data = await self._client.get_connections() + connections = data.get("connections", {}) + entry = connections.get(device_id) + if entry is None: + return False + return bool(entry.get("connected", False)) + + async def list_connected(self) -> List[str]: + """Return list of device IDs that are currently connected.""" + data = await self._client.get_connections() + connections = data.get("connections", {}) + return [ + device_id + for device_id, info in connections.items() + if info.get("connected", False) + ] diff --git a/api/services/syncthing/folder_manager.py b/api/services/syncthing/folder_manager.py new file mode 100644 index 00000000..50be7ee3 --- /dev/null +++ b/api/services/syncthing/folder_manager.py @@ -0,0 +1,357 @@ +""" +FolderManager — high-level operations on Syncthing folder configuration. + +Wraps SyncthingClient to provide idempotent folder creation/deletion and +declarative device-list management for karma outbox/inbox/metadata folders. + +Also provides folder-ID parsing utilities (``parse_member_tag``, +``parse_outbox_id``) that were previously in ``services.folder_id``. +""" + +import logging +import sqlite3 +from pathlib import Path +from typing import List, Optional, Set + +from services.syncthing.client import SyncthingClient + +logger = logging.getLogger(__name__) + + +# --------------------------------------------------------------------------- +# Constants +# --------------------------------------------------------------------------- + +OUTBOX_PREFIX = "karma-out--" + + +# --------------------------------------------------------------------------- +# Helper functions (importable independently) +# --------------------------------------------------------------------------- + + +def build_outbox_folder_id(member_tag: str, suffix: str) -> str: + """Return the Syncthing folder ID for an outbox folder.""" + return f"karma-out--{member_tag}--{suffix}" + + +def build_metadata_folder_id(team_name: str) -> str: + """Return the Syncthing folder ID for a team metadata folder.""" + return f"karma-meta--{team_name}" + + +def resolve_folder_path(karma_base: Path, folder_id: str) -> Path: + """Return the filesystem path for a Syncthing folder. + + Metadata folders (karma-meta--*) live under metadata-folders/ subdirectory. + All other folders (karma-out--*) live flat under karma_base. + """ + if folder_id.startswith("karma-meta--"): + return karma_base / "metadata-folders" / folder_id + return karma_base / folder_id + + +def resolve_folder_type(folder_id: str) -> str: + """Return the Syncthing folder type for a given folder ID. + + Metadata folders are sendreceive; outbox folders are sendonly by default. + """ + if folder_id.startswith("karma-meta--"): + return "sendreceive" + return "receiveonly" + + +def build_folder_config( + karma_base: Path, + folder_id: str, + folder_type: str, + devices: List[dict] | None = None, +) -> dict: + """Build a Syncthing folder configuration dict. + + Single source of truth for the 10-key config dict used when creating + or accepting Syncthing folders. All call sites (FolderManager, reconciler, + pending-folder router) should use this instead of constructing dicts inline. + """ + return { + "id": folder_id, + "label": folder_id, + "path": str(resolve_folder_path(karma_base, folder_id)), + "type": folder_type, + "devices": devices or [], + "rescanIntervalS": 3600, + "fsWatcherEnabled": True, + "fsWatcherDelayS": 10, + "ignorePerms": False, + "autoNormalize": True, + } + + +def parse_outbox_id(folder_id: str) -> Optional[tuple[str, str]]: + """Parse ``karma-out--{username}--{suffix}`` into ``(username, suffix)``. + + Returns ``None`` if the folder ID does not match the expected format. + """ + if not folder_id.startswith(OUTBOX_PREFIX): + return None + rest = folder_id[len(OUTBOX_PREFIX):] + parts = rest.split("--") + if len(parts) != 2 or not parts[0] or not parts[1]: + return None + return parts[0], parts[1] + + +def parse_member_tag(member_tag: str) -> tuple[str, Optional[str]]: + """Parse member_tag into (user_id, machine_tag). + + Format: ``{user_id}.{machine_tag}`` or bare ``{user_id}`` (legacy). + Splits on the FIRST dot only. + + Returns: + (user_id, machine_tag) -- machine_tag is None if no dot present. + """ + if "." in member_tag: + user_id, machine_tag_part = member_tag.split(".", 1) + return user_id, machine_tag_part + return member_tag, None + + +# --------------------------------------------------------------------------- +# FolderManager +# --------------------------------------------------------------------------- + + +class FolderManager: + """Manages Syncthing folder configuration for karma sync folders.""" + + def __init__(self, client: SyncthingClient, karma_base: Path) -> None: + self._client = client + self._karma_base = karma_base + + # ------------------------------------------------------------------ + # Public accessors + # ------------------------------------------------------------------ + + async def get_configured_folders(self) -> list[dict]: + """Return all configured Syncthing folders.""" + return await self._client.get_config_folders() + + # ------------------------------------------------------------------ + # Internal helpers + # ------------------------------------------------------------------ + + async def _get_folder_ids(self) -> Set[str]: + folders = await self._client.get_config_folders() + return {f["id"] for f in folders} + + def _folder_path(self, folder_id: str) -> str: + return str(resolve_folder_path(self._karma_base, folder_id)) + + def _make_folder_config( + self, + folder_id: str, + folder_type: str, + devices: List[dict] = None, + ) -> dict: + return build_folder_config(self._karma_base, folder_id, folder_type, devices) + + # ------------------------------------------------------------------ + # Outbox / Inbox + # ------------------------------------------------------------------ + + async def ensure_metadata_folder(self, team_name: str) -> None: + """Create a sendreceive metadata folder if it does not already exist.""" + folder_id = build_metadata_folder_id(team_name) + existing_ids = await self._get_folder_ids() + if folder_id in existing_ids: + return + folder = self._make_folder_config(folder_id, "sendreceive") + await self._client.put_config_folder(folder) + + async def ensure_outbox_folder(self, member_tag: str, folder_suffix: str) -> None: + """Create a sendonly outbox folder if it does not already exist.""" + folder_id = build_outbox_folder_id(member_tag, folder_suffix) + existing_ids = await self._get_folder_ids() + if folder_id in existing_ids: + return + folder = self._make_folder_config(folder_id, "sendonly") + await self._client.put_config_folder(folder) + + async def ensure_inbox_folder( + self, + remote_member_tag: str, + folder_suffix: str, + remote_device_id: str, + ) -> None: + """Create a receiveonly inbox folder mirroring the remote's outbox. + + The folder ID is identical to the remote's outbox ID so Syncthing + can match them automatically. + """ + folder_id = build_outbox_folder_id(remote_member_tag, folder_suffix) + existing_ids = await self._get_folder_ids() + if folder_id in existing_ids: + return + devices = [{"deviceID": remote_device_id, "encryptionPassword": ""}] + folder = self._make_folder_config(folder_id, "receiveonly", devices=devices) + await self._client.put_config_folder(folder) + + async def remove_outbox_folder(self, member_tag: str, folder_suffix: str) -> None: + """Delete an outbox folder from Syncthing config.""" + folder_id = build_outbox_folder_id(member_tag, folder_suffix) + await self._client.delete_config_folder(folder_id) + + # ------------------------------------------------------------------ + # Declarative device-list management + # ------------------------------------------------------------------ + + async def set_folder_devices(self, folder_id: str, device_ids: Set[str]) -> None: + """Replace the device list on a folder declaratively. + + If the folder is not found, this is a no-op. + """ + all_folders = await self._client.get_config_folders() + folder = next((f for f in all_folders if f["id"] == folder_id), None) + if folder is None: + return + updated = dict(folder) + updated["devices"] = [{"deviceID": did, "encryptionPassword": ""} for did in device_ids] + await self._client.put_config_folder(updated) + + async def remove_device_from_team_folders( + self, + folder_suffixes: List[str], + member_tags: List[str], + device_id: str, + ) -> None: + """Remove a device from all team folders matching the given suffixes/member_tags.""" + target_ids = { + build_outbox_folder_id(mt, suffix) + for mt in member_tags + for suffix in folder_suffixes + } + all_folders = await self._client.get_config_folders() + for folder in all_folders: + if folder["id"] not in target_ids: + continue + existing_devices = folder.get("devices", []) + updated_devices = [d for d in existing_devices if d["deviceID"] != device_id] + if len(updated_devices) == len(existing_devices): + # device was not present — skip unnecessary write + continue + updated = dict(folder) + updated["devices"] = updated_devices + await self._client.put_config_folder(updated) + + # ------------------------------------------------------------------ + # Cleanup helpers + # ------------------------------------------------------------------ + + def _is_folder_needed_by_other_team( + self, + conn: sqlite3.Connection, + folder_suffix: str, + member_tag: str, + team_name: str, + ) -> bool: + """Check if another team still needs a folder with this suffix for this member. + + Returns True if at least one other team has an active subscription + (offered/accepted/paused) for a project with the same folder_suffix. + """ + row = conn.execute( + """ + SELECT COUNT(*) FROM sync_subscriptions s + JOIN sync_projects p + ON s.team_name = p.team_name + AND s.project_git_identity = p.git_identity + WHERE p.folder_suffix = ? + AND s.member_tag = ? + AND s.status IN ('offered', 'accepted', 'paused') + AND s.team_name != ? + """, + (folder_suffix, member_tag, team_name), + ).fetchone() + return row[0] > 0 + + async def cleanup_team_folders( + self, + folder_suffixes: List[str], + member_tags: List[str], + team_name: str, + conn: Optional[sqlite3.Connection] = None, + ) -> None: + """Delete all outbox folders for this team plus the metadata folder. + + If ``conn`` is provided, each outbox folder is checked against other + teams' subscriptions before deletion. Folders still needed by another + team are skipped. The metadata folder (team-scoped) is always deleted. + + When ``conn`` is None the legacy behaviour is preserved: all matching + folders are deleted unconditionally. + """ + meta_id = build_metadata_folder_id(team_name) + + all_folders = await self._client.get_config_folders() + for folder in all_folders: + fid = folder["id"] + + # Metadata folder is always team-scoped — safe to delete + if fid == meta_id: + await self._client.delete_config_folder(fid) + continue + + # Check each outbox folder + for mt in member_tags: + for suffix in folder_suffixes: + if fid != build_outbox_folder_id(mt, suffix): + continue + if conn is not None and self._is_folder_needed_by_other_team( + conn, suffix, mt, team_name, + ): + logger.info( + "cleanup_team_folders: skipping folder %s " + "(still needed by another team)", + fid, + ) + continue + await self._client.delete_config_folder(fid) + + async def cleanup_project_folders( + self, + folder_suffix: str, + member_tags: List[str], + conn: Optional[sqlite3.Connection] = None, + team_name: Optional[str] = None, + ) -> None: + """Delete all outbox/inbox folders for a specific project suffix. + + If ``conn`` and ``team_name`` are provided, each folder is checked + against other teams' subscriptions before deletion. Folders still + needed by another team are skipped. + + When ``conn`` is None the legacy behaviour is preserved. + """ + # Build a map from folder_id → member_tag for cross-team lookups + folder_to_member: dict[str, str] = { + build_outbox_folder_id(mt, folder_suffix): mt for mt in member_tags + } + all_folders = await self._client.get_config_folders() + for folder in all_folders: + fid = folder["id"] + mt = folder_to_member.get(fid) + if mt is None: + continue + + if conn is not None and team_name is not None: + if self._is_folder_needed_by_other_team( + conn, folder_suffix, mt, team_name, + ): + logger.info( + "cleanup_project_folders: skipping folder %s " + "(still needed by another team)", + fid, + ) + continue + + await self._client.delete_config_folder(fid) diff --git a/api/services/syncthing/key_reader.py b/api/services/syncthing/key_reader.py new file mode 100644 index 00000000..a8bb41d1 --- /dev/null +++ b/api/services/syncthing/key_reader.py @@ -0,0 +1,42 @@ +"""Read Syncthing API key from local config file.""" + +import subprocess +import xml.etree.ElementTree as ET +from pathlib import Path +from typing import Optional + + +def read_local_api_key() -> Optional[str]: + """Auto-detect the Syncthing API key from the local config file.""" + # Ask Syncthing itself where its config lives + try: + result = subprocess.run( + ["syncthing", "paths"], + capture_output=True, text=True, timeout=5, + ) + for line in result.stdout.splitlines(): + line = line.strip() + if line.endswith("config.xml"): + config_path = Path(line) + if config_path.exists(): + tree = ET.parse(config_path) + key = tree.getroot().findtext(".//apikey") + return key or None + except (subprocess.SubprocessError, FileNotFoundError, ET.ParseError): + pass + + # Fallback: try known platform locations + candidates = [ + Path.home() / "Library" / "Application Support" / "Syncthing" / "config.xml", + Path.home() / ".local" / "share" / "syncthing" / "config.xml", + Path.home() / ".config" / "syncthing" / "config.xml", + ] + for path in candidates: + if path.exists(): + try: + tree = ET.parse(path) + key = tree.getroot().findtext(".//apikey") + return key or None + except ET.ParseError: + continue + return None diff --git a/api/services/titles_io.py b/api/services/titles_io.py new file mode 100644 index 00000000..273ad5f1 --- /dev/null +++ b/api/services/titles_io.py @@ -0,0 +1,84 @@ +"""Atomic read/write/merge for titles.json sidecar files. + +Used by both the session packager (bulk dump of cached titles) and the +POST /sessions/{uuid}/title handler (single title write on generation). + +File format: +{ + "version": 1, + "updated_at": "2026-03-08T14:30:00Z", + "titles": { + "uuid": {"title": "...", "source": "git|haiku|fallback", "generated_at": "..."} + } +} +""" + +import json +import os +from datetime import datetime, timezone +from pathlib import Path +from typing import Optional + + +_VERSION = 1 + + +def read_titles(path: Path) -> dict[str, dict]: + """Read titles.json. Returns {uuid: {title, source, generated_at}} or empty dict.""" + if not path.is_file(): + return {} + try: + data = json.loads(path.read_text(encoding="utf-8")) + if data.get("version") != _VERSION: + return {} + return data.get("titles", {}) + except (json.JSONDecodeError, OSError, TypeError): + return {} + + +def write_title( + path: Path, + uuid: str, + title: str, + source: str, + generated_at: Optional[str] = None, +) -> None: + """Write or merge a single title into titles.json. Atomic (tmp+rename).""" + existing = read_titles(path) + existing[uuid] = { + "title": title, + "source": source, + "generated_at": generated_at or datetime.now(timezone.utc).isoformat(), + } + _write_file(path, existing) + + +def write_titles_bulk(path: Path, entries: dict[str, dict]) -> None: + """Bulk write/merge titles into titles.json. Atomic (tmp+rename). + + Args: + path: Path to titles.json + entries: {uuid: {"title": str, "source": str}} — generated_at added if missing + """ + existing = read_titles(path) + now = datetime.now(timezone.utc).isoformat() + for uuid, entry in entries.items(): + existing[uuid] = { + "title": entry["title"], + "source": entry.get("source", "unknown"), + "generated_at": entry.get("generated_at", now), + } + _write_file(path, existing) + + +def _write_file(path: Path, titles: dict[str, dict]) -> None: + """Atomically write titles dict to path.""" + path.parent.mkdir(parents=True, exist_ok=True) + payload = { + "version": _VERSION, + "updated_at": datetime.now(timezone.utc).isoformat(), + "titles": titles, + } + tmp_path = path.with_name(f".titles-{os.getpid()}.tmp") + tmp_path.write_text(json.dumps(payload, indent=2, ensure_ascii=False) + "\n", encoding="utf-8") + tmp_path.replace(path) diff --git a/api/services/watcher_manager.py b/api/services/watcher_manager.py new file mode 100644 index 00000000..d8e1614a --- /dev/null +++ b/api/services/watcher_manager.py @@ -0,0 +1,477 @@ +"""In-process session watcher manager. + +Runs the same SessionWatcher + SessionPackager logic as `karma watch`, +but as a background service managed by the API process. + +Also provides RemoteSessionWatcher for monitoring incoming Syncthing files +in ~/.claude_karma/remote-sessions/ and triggering remote reindex. +""" +from __future__ import annotations + +import asyncio +import logging +import sqlite3 +import threading +from datetime import datetime, timezone +from pathlib import Path +from typing import Any, Optional + +from watchdog.events import FileSystemEventHandler +from watchdog.observers import Observer + +logger = logging.getLogger(__name__) + + + +class RemoteSessionWatcher(FileSystemEventHandler): + """Watches ~/.claude_karma/remote-sessions/ for incoming Syncthing files. + + When JSONL session files are created or modified (by Syncthing syncing from + a teammate's outbox), debounces and then calls trigger_remote_reindex() to + import the new sessions into the local SQLite database. + + Uses the same debounce pattern as cli/karma/watcher.py SessionWatcher. + """ + + def __init__(self, watch_dir: Path, debounce_seconds: float = 5.0): + self.watch_dir = Path(watch_dir) + self.debounce_seconds = debounce_seconds + self._timer: Optional[threading.Timer] = None + self._observer: Optional[Observer] = None + self._lock = threading.Lock() + + @property + def is_running(self) -> bool: + return self._observer is not None and self._observer.is_alive() + + def _should_process(self, path: str) -> bool: + """Only process session JSONL files in remote-sessions/ or karma-out-- inbox dirs. + + Skips agent files, Syncthing temp files, and our own sendonly outbox + files (those are outgoing, not incoming). + """ + p = Path(path) + if ".stversions" in p.parts or ".stfolder" in p.parts: + return False + if p.name.startswith(".syncthing."): + return False + if ".sync-conflict-" in p.name: + return False + if p.suffix != ".jsonl" or p.name.startswith("agent-"): + return False + # Only trigger on files inside remote-sessions/ or karma-out-- dirs + parts_str = str(p) + if "remote-sessions" in parts_str: + return True + if "karma-out--" in parts_str: + return True + return False + + def on_created(self, event): + if self._should_process(event.src_path): + self._schedule_reindex() + + def on_modified(self, event): + if self._should_process(event.src_path): + self._schedule_reindex() + + def _schedule_reindex(self): + """Debounced reindex -- waits for quiet period before running.""" + with self._lock: + if self._timer is not None: + self._timer.cancel() + self._timer = threading.Timer( + self.debounce_seconds, self._do_reindex + ) + self._timer.daemon = True + self._timer.start() + + def _do_reindex(self): + """Execute trigger_remote_reindex().""" + try: + from db.indexer import trigger_remote_reindex + + result = trigger_remote_reindex() + logger.info("Remote session watcher triggered reindex: %s", result) + except Exception as e: + logger.warning("Remote session watcher reindex error: %s", e) + + def start(self): + """Start watching the remote-sessions directory. + + Creates the watch directory if it doesn't exist yet (it may be + created later when Syncthing sync is first configured). + """ + self.watch_dir.mkdir(parents=True, exist_ok=True) + self._observer = Observer() + self._observer.schedule(self, str(self.watch_dir), recursive=True) + self._observer.daemon = True + self._observer.start() + logger.info( + "Remote session watcher started: %s", self.watch_dir + ) + + def stop(self): + """Stop watching.""" + with self._lock: + if self._timer is not None: + self._timer.cancel() + self._timer = None + if self._observer is not None: + self._observer.stop() + self._observer.join(timeout=5) + self._observer = None + logger.info("Remote session watcher stopped") + + +class ReconciliationTimer: + """Periodic timer that runs v4 3-phase reconciliation every N seconds. + + Uses ReconciliationService.run_cycle() which handles: + Phase 1 (metadata): member/project discovery, removal signals, auto-leave + Phase 2 (mesh pair): ensure Syncthing devices are paired + Phase 3 (device lists): declarative folder device-list sync + + H1 fix preserved: dedicated SQLite connection per timer thread. + """ + + def __init__(self, config_data: dict, interval: float = 60.0): + self._config_data = config_data + self._interval = interval + self._timer: Optional[threading.Timer] = None + self._running = False + + def start(self): + self._running = True + self._schedule() + logger.info("Reconciliation timer started (interval=%ds)", self._interval) + + def _schedule(self): + if not self._running: + return + self._timer = threading.Timer(self._interval, self._run) + self._timer.daemon = True + self._timer.start() + + def _run(self): + try: + self._reconcile() + except Exception as e: + logger.warning("Reconciliation cycle failed: %s", e) + finally: + self._schedule() + + def _reconcile(self): + """Run ReconciliationService.run_cycle() with a dedicated connection.""" + from models.sync_config import SyncConfig + + config = SyncConfig.load() + if config is None: + logger.debug("Reconciliation skipped: not initialized") + return + + # H1 fix: dedicated connection per timer thread + from db.connection import get_db_path, _apply_pragmas + + db_path = get_db_path() + conn = sqlite3.connect(str(db_path), timeout=10.0) + conn.row_factory = sqlite3.Row + _apply_pragmas(conn, readonly=False) + + try: + # Build v4 service stack + from config import settings as app_settings + from repositories.team_repo import TeamRepository + from repositories.member_repo import MemberRepository + from repositories.project_repo import ProjectRepository + from repositories.subscription_repo import SubscriptionRepository + from repositories.event_repo import EventRepository + from services.syncthing.client import SyncthingClient + from services.syncthing.device_manager import DeviceManager + from services.syncthing.folder_manager import FolderManager + from services.sync.metadata_service import MetadataService + from services.sync.reconciliation_service import ReconciliationService + + api_key = config.syncthing.api_key if config.syncthing else "" + client = SyncthingClient( + api_url="http://localhost:8384", api_key=api_key, + ) + devices = DeviceManager(client) + folders = FolderManager(client, karma_base=app_settings.karma_base) + metadata = MetadataService( + meta_base=app_settings.karma_base / "metadata-folders", + ) + repos = dict( + teams=TeamRepository(), + members=MemberRepository(), + projects=ProjectRepository(), + subs=SubscriptionRepository(), + events=EventRepository(), + ) + recon = ReconciliationService( + **repos, + devices=devices, + folders=folders, + metadata=metadata, + my_member_tag=config.member_tag, + my_device_id=config.syncthing.device_id if config.syncthing else "", + ) + + # Run the async 3-phase pipeline with 120s timeout + loop = asyncio.new_event_loop() + try: + loop.run_until_complete( + asyncio.wait_for(recon.run_cycle(conn), timeout=120) + ) + except asyncio.TimeoutError: + logger.warning("Reconciliation timed out after 120s") + finally: + loop.close() + finally: + conn.close() + + def stop(self): + self._running = False + if self._timer is not None: + self._timer.cancel() + self._timer = None + logger.info("Reconciliation timer stopped") + + +class WatcherManager: + """Manages SessionWatcher instances across one or more teams.""" + + def __init__(self) -> None: + self._running = False + self._teams: list[str] = [] + self._watchers: list = [] + self._started_at: Optional[str] = None + self._last_packaged_at: Optional[str] = None + self._projects_watched: list[str] = [] + self._remote_watcher: Optional[RemoteSessionWatcher] = None + self._metadata_timer: Optional[ReconciliationTimer] = None + + @property + def is_running(self) -> bool: + return self._running + + def status(self) -> dict[str, Any]: + return { + "running": self._running, + "teams": self._teams, + "started_at": self._started_at, + "last_packaged_at": self._last_packaged_at, + "projects_watched": self._projects_watched, + "remote_watcher_running": ( + self._remote_watcher is not None + and self._remote_watcher.is_running + ), + } + + def start_all(self, config_data: dict) -> dict[str, Any]: + """Start watchers for all projects across all teams. + + Deduplicates projects by encoded_name so each directory is watched + only once, even if the same project appears in multiple teams. + + Args: + config_data: Full config dict with "teams", "user_id", "machine_id". + + Returns: + Current status dict. + """ + if self._running: + raise ValueError( + f"Watcher already running for team(s) {self._teams!r}" + ) + + from services.sync.session_watcher import SessionWatcher + from services.sync.worktree_discovery import find_worktree_dirs + + all_teams = config_data.get("teams", {}) + user_id = config_data.get("user_id", "unknown") + machine_id = config_data.get("machine_id", "unknown") + device_id = config_data.get("device_id") + member_tag = config_data.get("member_tag") + projects_dir = Path.home() / ".claude" / "projects" + + # Collect unique projects across all teams, tracking which teams each belongs to + # Key: encoded_name -> {"proj": proj_dict, "teams": [team_names]} + unique_projects: dict[str, dict[str, Any]] = {} + team_names: list[str] = [] + + for team_name, team_cfg in all_teams.items(): + team_names.append(team_name) + projects = team_cfg.get("projects", {}) + for proj_name, proj in projects.items(): + encoded = proj.get("encoded_name", proj_name) + if encoded not in unique_projects: + unique_projects[encoded] = { + "proj": proj, + "proj_name": proj_name, + "teams": [team_name], + } + else: + if team_name not in unique_projects[encoded]["teams"]: + unique_projects[encoded]["teams"].append(team_name) + + watchers = [] + watched = [] + initial_package_fns = [] + + for encoded, info in unique_projects.items(): + proj = info["proj"] + proj_name = info["proj_name"] + proj_teams = info["teams"] + claude_dir = projects_dir / encoded + + if not claude_dir.is_dir(): + logger.warning("Skipping %s: dir not found %s", proj_name, claude_dir) + continue + + def make_package_fn( + en=encoded, pt=proj_teams, + ps=proj.get("folder_suffix", encoded), + gi=proj.get("git_identity", encoded), + ): + def package(): + from db.connection import get_writer_db + from services.sync.packaging_service import PackagingService + + db = get_writer_db() + svc = PackagingService( + member_tag=member_tag or user_id, + user_id=user_id, + machine_id=machine_id, + device_id=device_id, + ) + for tn in pt: + svc.package_project( + db, + team_name=tn, + git_identity=gi, + encoded_name=en, + folder_suffix=ps, + ) + self._last_packaged_at = ( + datetime.now(timezone.utc).isoformat() + ) + return package + + pkg_fn = make_package_fn() + watcher = SessionWatcher( + watch_dir=claude_dir, + package_fn=pkg_fn, + ) + watcher.start() + watchers.append(watcher) + watched.append(proj_name) + initial_package_fns.append((proj_name, pkg_fn)) + + # Also watch worktree dirs + wt_dirs = find_worktree_dirs(encoded, projects_dir) + for wt_dir in wt_dirs: + wt_watcher = SessionWatcher( + watch_dir=wt_dir, + package_fn=make_package_fn(), + ) + wt_watcher.start() + watchers.append(wt_watcher) + + self._watchers = watchers + self._running = True + self._teams = team_names + self._started_at = datetime.now(timezone.utc).isoformat() + self._projects_watched = watched + + # Initial sync: package all existing sessions in a background thread + # so pre-existing and missed sessions are staged for sending immediately. + if initial_package_fns: + def _initial_sync(): + for proj_name, pkg_fn in initial_package_fns: + try: + pkg_fn() + except Exception as e: + logger.warning("Initial package failed for %s: %s", proj_name, e) + logger.info("Initial sync complete: packaged %d project(s)", len(initial_package_fns)) + + t = threading.Thread(target=_initial_sync, daemon=True, name="initial-sync") + t.start() + + # Start metadata reconciliation timer (~60s periodic) + if self._metadata_timer is None: + try: + self._metadata_timer = ReconciliationTimer(config_data) + self._metadata_timer.start() + except Exception as e: + logger.warning("Failed to start metadata reconciliation timer: %s", e) + + # Start remote session watcher (for incoming Syncthing files) + if self._remote_watcher is None or not self._remote_watcher.is_running: + try: + from config import settings + + remote_dir = settings.karma_base / "remote-sessions" + self._remote_watcher = RemoteSessionWatcher( + watch_dir=remote_dir + ) + self._remote_watcher.start() + except Exception as e: + logger.warning( + "Failed to start remote session watcher: %s", e + ) + + logger.info( + "Watcher started: teams=%s, projects=%d, watchers=%d", + team_names, len(watched), len(watchers), + ) + return self.status() + + def start(self, team_name: str, config_data: dict) -> dict[str, Any]: + """Start watchers for all projects in the given team. + + Backward-compatible wrapper around start_all(). Filters config_data + to only the specified team, then delegates to start_all(). + """ + # Filter config_data to only the specified team + all_teams = config_data.get("teams", {}) + if team_name not in all_teams: + raise ValueError(f"Team '{team_name}' not found in config_data") + + filtered_config = { + **config_data, + "teams": {team_name: all_teams[team_name]}, + } + return self.start_all(filtered_config) + + def stop(self) -> dict[str, Any]: + """Stop all watchers (including remote session watcher).""" + for w in self._watchers: + try: + w.stop() + except Exception as e: + logger.warning("Error stopping watcher: %s", e) + + if self._metadata_timer is not None: + try: + self._metadata_timer.stop() + except Exception as e: + logger.warning("Error stopping metadata timer: %s", e) + self._metadata_timer = None + + if self._remote_watcher is not None: + try: + self._remote_watcher.stop() + except Exception as e: + logger.warning("Error stopping remote watcher: %s", e) + self._remote_watcher = None + + self._watchers = [] + self._running = False + teams = self._teams + self._teams = [] + self._started_at = None + self._projects_watched = [] + + logger.info("Watcher stopped (was teams=%s)", teams) + return self.status() diff --git a/api/tests/api/test_remote_sessions.py b/api/tests/api/test_remote_sessions.py new file mode 100644 index 00000000..4542100d --- /dev/null +++ b/api/tests/api/test_remote_sessions.py @@ -0,0 +1,277 @@ +"""Tests for remote sessions API router (requires fastapi).""" + +import json +from pathlib import Path +from unittest.mock import patch + +import pytest +from fastapi.testclient import TestClient + +from main import app + +client = TestClient(app) + + +@pytest.fixture +def remote_sessions_dir(tmp_path: Path) -> Path: + """Create fake remote sessions directory.""" + remote = tmp_path / "remote-sessions" + + # Alice's sessions + alice_proj = remote / "alice" / "-Users-alice-acme" + alice_proj.mkdir(parents=True) + + manifest = { + "version": 1, + "user_id": "alice", + "machine_id": "alice-mbp", + "project_path": "/Users/alice/acme", + "project_encoded": "-Users-alice-acme", + "synced_at": "2026-03-03T14:00:00Z", + "session_count": 2, + "sessions": [ + {"uuid": "sess-001", "mtime": "2026-03-03T12:00:00Z", "size_bytes": 1000}, + {"uuid": "sess-002", "mtime": "2026-03-03T13:00:00Z", "size_bytes": 2000}, + ], + } + (alice_proj / "manifest.json").write_text(json.dumps(manifest)) + + sessions_dir = alice_proj / "sessions" + sessions_dir.mkdir() + (sessions_dir / "sess-001.jsonl").write_text( + '{"type":"user","uuid":"msg-1","message":{"role":"user","content":"hello"}}\n' + ) + (sessions_dir / "sess-002.jsonl").write_text( + '{"type":"user","uuid":"msg-2","message":{"role":"user","content":"build X"}}\n' + ) + + return remote + + +class TestRemoteSessionsRouter: + def test_load_manifest_helper(self, remote_sessions_dir): + """Test the _load_manifest helper directly.""" + from routers.remote_sessions import _load_manifest + + with patch("routers.remote_sessions.REMOTE_SESSIONS_DIR", remote_sessions_dir): + manifest = _load_manifest("alice", "-Users-alice-acme") + assert manifest is not None + assert manifest["user_id"] == "alice" + assert manifest["session_count"] == 2 + + def test_load_manifest_returns_none_for_missing(self, remote_sessions_dir): + from routers.remote_sessions import _load_manifest + + with patch("routers.remote_sessions.REMOTE_SESSIONS_DIR", remote_sessions_dir): + assert _load_manifest("nonexistent", "nope") is None + + +# ============================================================================ +# Integration tests: session detail endpoints via remote fallback +# ============================================================================ + + +def _make_session_jsonl(uuid: str, prompt: str = "hello") -> str: + """Build minimal valid JSONL for a session.""" + lines = [ + json.dumps({ + "type": "user", + "uuid": f"msg-{uuid}", + "message": {"role": "user", "content": prompt}, + "timestamp": "2026-03-03T12:00:00.000Z", + }), + json.dumps({ + "type": "assistant", + "uuid": f"resp-{uuid}", + "message": { + "role": "assistant", + "content": [{"type": "text", "text": "ok"}], + "model": "claude-sonnet-4-20250514", + "usage": {"input_tokens": 100, "output_tokens": 50}, + }, + "timestamp": "2026-03-03T12:00:01.000Z", + }), + ] + return "\n".join(lines) + "\n" + + +@pytest.fixture +def karma_base_with_resources(tmp_path: Path) -> Path: + """Create a complete remote session environment with all resource types.""" + karma = tmp_path / ".claude_karma" + karma.mkdir() + + encoded = "-Users-jayant-acme" + alice_dir = karma / "remote-sessions" / "alice" / encoded + + # Session JSONL + sessions_dir = alice_dir / "sessions" + sessions_dir.mkdir(parents=True) + (sessions_dir / "sess-integration.jsonl").write_text( + _make_session_jsonl("integration", "Build a CLI tool") + ) + + # Subagent + sub_dir = sessions_dir / "sess-integration" / "subagents" + sub_dir.mkdir(parents=True) + (sub_dir / "agent-abc.jsonl").write_text( + json.dumps({ + "type": "user", + "message": {"role": "user", "content": "sub task"}, + "timestamp": "2026-03-03T12:01:00Z", + }) + "\n" + ) + + # Tool result + tr_dir = sessions_dir / "sess-integration" / "tool-results" + tr_dir.mkdir(parents=True) + (tr_dir / "toolu_xyz.txt").write_text("tool output") + + # Todos (claude_base_dir = alice_dir, so todos_dir = alice_dir / "todos") + todos_dir = alice_dir / "todos" + todos_dir.mkdir() + (todos_dir / "sess-integration-item.json").write_text( + json.dumps([{"content": "Remote todo", "status": "pending"}]) + ) + + # Tasks (tasks_dir = alice_dir / "tasks" / "sess-integration") + task_dir = alice_dir / "tasks" / "sess-integration" + task_dir.mkdir(parents=True) + (task_dir / "1.json").write_text( + json.dumps({"id": "1", "subject": "Parse CLI args", "description": "Implement argument parsing for the CLI tool", "status": "in_progress"}) + ) + + # Sync config (needed so local user != "alice", preventing outbox skip) + (karma / "sync-config.json").write_text( + json.dumps({"user_id": "local-me", "machine_id": "my-mac"}) + ) + + return karma + + +@pytest.fixture(autouse=True) +def _clear_remote_cache(): + """Clear caches before each test.""" + import services.remote_sessions as mod + + mod._local_user_cache = None + mod._local_user_cache_time = 0.0 + mod._project_mapping_cache = None + mod._project_mapping_cache_time = 0.0 + yield + mod._local_user_cache = None + mod._local_user_cache_time = 0.0 + mod._project_mapping_cache = None + mod._project_mapping_cache_time = 0.0 + + +class TestRemoteSessionEndpoints: + """Integration tests: session endpoints work for remote sessions via fallback. + + Strategy: patch the internal functions in services.remote_sessions to point + at the test data, and patch config.settings.claude_base to a nonexistent + dir so the local project scan in find_session_with_project() misses, + triggering the remote fallback path. + """ + + @staticmethod + def _patches(karma_base): + """Return an ExitStack with patches for remote session fallback. + + Patches Settings class properties so all code paths that access + settings.projects_dir and settings.karma_base get test values. + """ + from contextlib import ExitStack + from unittest.mock import PropertyMock + + from config import Settings + + stack = ExitStack() + # Make local project scan miss (nonexistent projects_dir) + stack.enter_context( + patch.object( + Settings, + "projects_dir", + new_callable=PropertyMock, + return_value=karma_base / "nonexistent" / "projects", + ) + ) + # Route karma_base to test data (used by remote session lookup) + stack.enter_context( + patch.object( + Settings, + "karma_base", + new_callable=PropertyMock, + return_value=karma_base, + ) + ) + return stack + + def test_session_detail_endpoint(self, karma_base_with_resources): + """GET /sessions/{uuid} should return full detail for remote sessions.""" + with self._patches(karma_base_with_resources): + response = client.get("/sessions/sess-integration") + + assert response.status_code == 200 + data = response.json() + assert data["uuid"] == "sess-integration" + assert data["message_count"] >= 2 + + def test_todos_endpoint(self, karma_base_with_resources): + """GET /sessions/{uuid}/todos should return remote session todos.""" + with self._patches(karma_base_with_resources): + response = client.get("/sessions/sess-integration/todos") + + assert response.status_code == 200 + todos = response.json() + assert len(todos) >= 1 + assert todos[0]["content"] == "Remote todo" + + def test_tasks_endpoint(self, karma_base_with_resources): + """GET /sessions/{uuid}/tasks should return remote session tasks.""" + with self._patches(karma_base_with_resources): + response = client.get("/sessions/sess-integration/tasks") + + assert response.status_code == 200 + tasks = response.json() + assert len(tasks) >= 1 + + def test_subagents_endpoint(self, karma_base_with_resources): + """GET /sessions/{uuid}/subagents should work for remote sessions.""" + with self._patches(karma_base_with_resources): + response = client.get("/sessions/sess-integration/subagents") + + assert response.status_code == 200 + data = response.json() + assert len(data) >= 1 + + def test_timeline_endpoint(self, karma_base_with_resources): + """GET /sessions/{uuid}/timeline should work for remote sessions.""" + with self._patches(karma_base_with_resources): + response = client.get("/sessions/sess-integration/timeline") + + assert response.status_code == 200 + events = response.json() + assert len(events) >= 1 + + def test_file_activity_endpoint(self, karma_base_with_resources): + """GET /sessions/{uuid}/file-activity should work for remote sessions.""" + with self._patches(karma_base_with_resources): + response = client.get("/sessions/sess-integration/file-activity") + + # Should return 200 even if no file activity in the JSONL + assert response.status_code == 200 + + def test_tools_endpoint(self, karma_base_with_resources): + """GET /sessions/{uuid}/tools should work for remote sessions.""" + with self._patches(karma_base_with_resources): + response = client.get("/sessions/sess-integration/tools") + + assert response.status_code == 200 + + def test_nonexistent_session_returns_404(self, karma_base_with_resources): + """GET /sessions/{uuid} should return 404 for nonexistent remote sessions.""" + with self._patches(karma_base_with_resources): + response = client.get("/sessions/nonexistent-uuid") + + assert response.status_code == 404 diff --git a/api/tests/api/test_set_session_title.py b/api/tests/api/test_set_session_title.py index 96be8646..6dba0fb1 100644 --- a/api/tests/api/test_set_session_title.py +++ b/api/tests/api/test_set_session_title.py @@ -3,6 +3,8 @@ """ import json +from pathlib import Path +from unittest.mock import patch import pytest from fastapi.testclient import TestClient @@ -167,3 +169,110 @@ def test_set_title_long_title(self, client, sample_session_for_title): assert response.status_code == 200 cached_titles = title_cache.get_titles(encoded_name, session_uuid) assert long_title in cached_titles + + +class TestSetSessionTitleOutbox: + """Tests for Syncthing outbox write in POST /sessions/{uuid}/title.""" + + @pytest.fixture + def mock_karma_base(self, tmp_path): + """Create a fake karma_base directory with sync-config.json.""" + karma_dir = tmp_path / ".claude_karma" + karma_dir.mkdir() + return karma_dir + + @pytest.fixture + def setup_sync_config(self, mock_karma_base): + """Write a sync-config.json with a test user_id.""" + config = {"user_id": "test-user-123", "device_name": "test-device"} + (mock_karma_base / "sync-config.json").write_text( + json.dumps(config), encoding="utf-8" + ) + return "test-user-123" + + @pytest.fixture + def setup_outbox(self, mock_karma_base, setup_sync_config): + """Create the outbox directory for a test project.""" + user_id = setup_sync_config + encoded_name = "-Users-test-myproject" + outbox_dir = mock_karma_base / "remote-sessions" / user_id / encoded_name + outbox_dir.mkdir(parents=True) + return outbox_dir + + def test_writes_to_outbox_titles_json( + self, client, sample_session_for_title, mock_karma_base, setup_outbox + ): + """When sync-config exists and outbox dir exists, title is written to outbox titles.json.""" + session_uuid, encoded_name = sample_session_for_title + outbox_dir = setup_outbox + new_title = "Outbox Title Test" + + from config import Settings + + with patch.object( + Settings, "karma_base", new_callable=lambda: property(lambda self: mock_karma_base) + ): + response = client.post( + f"/sessions/{session_uuid}/title", + json={"title": new_title}, + ) + + assert response.status_code == 200 + + # Verify titles.json was written in the outbox + titles_path = outbox_dir / "titles.json" + assert titles_path.is_file(), "titles.json should have been created in outbox" + + data = json.loads(titles_path.read_text(encoding="utf-8")) + assert data["version"] == 1 + assert session_uuid in data["titles"] + assert data["titles"][session_uuid]["title"] == new_title + assert data["titles"][session_uuid]["source"] == "hook" + + def test_skips_when_no_sync_config( + self, client, sample_session_for_title, mock_karma_base + ): + """No error when sync-config.json doesn't exist.""" + session_uuid, _encoded_name = sample_session_for_title + + # mock_karma_base exists but has no sync-config.json + from config import Settings + + with patch.object( + Settings, "karma_base", new_callable=lambda: property(lambda self: mock_karma_base) + ): + response = client.post( + f"/sessions/{session_uuid}/title", + json={"title": "No Config Title"}, + ) + + assert response.status_code == 200 + data = response.json() + assert data["status"] == "ok" + + def test_skips_when_outbox_missing( + self, client, sample_session_for_title, mock_karma_base, setup_sync_config + ): + """No error when outbox directory doesn't exist (sync-config exists but no outbox dir).""" + session_uuid, _encoded_name = sample_session_for_title + + # sync-config.json exists but no remote-sessions dir + from config import Settings + + with patch.object( + Settings, "karma_base", new_callable=lambda: property(lambda self: mock_karma_base) + ): + response = client.post( + f"/sessions/{session_uuid}/title", + json={"title": "No Outbox Title"}, + ) + + assert response.status_code == 200 + data = response.json() + assert data["status"] == "ok" + + # Verify no titles.json was created anywhere + remote_dir = mock_karma_base / "remote-sessions" + if remote_dir.exists(): + titles_files = list(remote_dir.rglob("titles.json")) + assert len(titles_files) == 0, "No titles.json should be created when outbox is missing" diff --git a/api/tests/api/test_sync_pairing_router.py b/api/tests/api/test_sync_pairing_router.py new file mode 100644 index 00000000..bff6685a --- /dev/null +++ b/api/tests/api/test_sync_pairing_router.py @@ -0,0 +1,111 @@ +"""Tests for sync_pairing v4 router.""" +import sys +from pathlib import Path + +sys.path.insert(0, str(Path(__file__).parent.parent.parent)) + +from unittest.mock import MagicMock, AsyncMock + +import pytest +from fastapi import FastAPI +from fastapi.testclient import TestClient + +from services.sync.pairing_service import PairingInfo + + +@pytest.fixture +def mock_config(): + config = MagicMock() + config.user_id = "jayant" + config.member_tag = "jayant.macbook" + config.syncthing = MagicMock() + config.syncthing.device_id = "DEV-SELF" + config.syncthing.api_key = "test-key" + return config + + +@pytest.fixture +def mock_pairing_svc(): + svc = MagicMock() + svc.generate_code = MagicMock(return_value="ABCD-1234-EFGH") + svc.validate_code = MagicMock() + return svc + + +@pytest.fixture +def mock_device_mgr(): + mgr = MagicMock() + mgr.list_connected = AsyncMock(return_value=["DEV-A", "DEV-B"]) + return mgr + + +@pytest.fixture +def client(mock_config, mock_pairing_svc, mock_device_mgr): + from routers.sync_pairing import router, get_pairing_svc, get_device_mgr + from routers.sync_deps import require_config + + app = FastAPI() + app.include_router(router) + app.dependency_overrides[require_config] = lambda: mock_config + app.dependency_overrides[get_pairing_svc] = lambda: mock_pairing_svc + app.dependency_overrides[get_device_mgr] = lambda: mock_device_mgr + return TestClient(app) + + +class TestGenerateCode: + def test_returns_code(self, client, mock_pairing_svc): + resp = client.get("/sync/pairing/code") + assert resp.status_code == 200 + data = resp.json() + assert data["code"] == "ABCD-1234-EFGH" + assert data["member_tag"] == "jayant.macbook" + mock_pairing_svc.generate_code.assert_called_once_with( + "jayant.macbook", "DEV-SELF" + ) + + def test_no_device_id_returns_400(self, client, mock_config): + mock_config.syncthing.device_id = "" + resp = client.get("/sync/pairing/code") + assert resp.status_code == 400 + + +class TestValidateCode: + def test_valid_code(self, client, mock_pairing_svc): + mock_pairing_svc.validate_code.return_value = PairingInfo( + member_tag="ayush.laptop", + device_id="DEV-A", + ) + resp = client.post( + "/sync/pairing/validate", + json={"code": "ABCD-1234"}, + ) + assert resp.status_code == 200 + assert resp.json()["member_tag"] == "ayush.laptop" + assert resp.json()["device_id"] == "DEV-A" + + def test_invalid_code_returns_400(self, client, mock_pairing_svc): + mock_pairing_svc.validate_code.side_effect = ValueError("bad code") + resp = client.post( + "/sync/pairing/validate", + json={"code": "BAD"}, + ) + assert resp.status_code == 400 + + def test_missing_code_returns_422(self, client): + resp = client.post("/sync/pairing/validate", json={}) + assert resp.status_code == 422 + + +class TestListDevices: + def test_returns_devices(self, client): + resp = client.get("/sync/devices") + assert resp.status_code == 200 + data = resp.json() + assert data["my_device_id"] == "DEV-SELF" + assert data["connected_devices"] == ["DEV-A", "DEV-B"] + + def test_device_manager_error_returns_empty(self, client, mock_device_mgr): + mock_device_mgr.list_connected.side_effect = Exception("unreachable") + resp = client.get("/sync/devices") + assert resp.status_code == 200 + assert resp.json()["connected_devices"] == [] diff --git a/api/tests/api/test_sync_pending_router.py b/api/tests/api/test_sync_pending_router.py new file mode 100644 index 00000000..0c8a0364 --- /dev/null +++ b/api/tests/api/test_sync_pending_router.py @@ -0,0 +1,226 @@ +"""Tests for sync_pending v4 router (pending devices + folders).""" +import sys +from pathlib import Path + +sys.path.insert(0, str(Path(__file__).parent.parent.parent)) + +from unittest.mock import MagicMock, AsyncMock, PropertyMock, patch + +import pytest +from fastapi import FastAPI +from fastapi.testclient import TestClient + + +@pytest.fixture +def mock_config(): + config = MagicMock() + config.user_id = "jayant" + config.member_tag = "jayant.macbook" + config.syncthing = MagicMock() + config.syncthing.device_id = "DEV-SELF" + config.syncthing.api_key = "test-key" + return config + + +@pytest.fixture +def mock_client(): + client = MagicMock() + client.get_pending_devices = AsyncMock(return_value={}) + client.get_pending_folders = AsyncMock(return_value={}) + client.put_config_device = AsyncMock() + client.put_config_folder = AsyncMock() + client.dismiss_pending_device = AsyncMock() + client.dismiss_pending_folder = AsyncMock() + return client + + +@pytest.fixture +def mock_folder_mgr(): + mgr = MagicMock() + mgr.ensure_inbox_folder = AsyncMock() + return mgr + + +@pytest.fixture +def client(mock_config, mock_client, mock_folder_mgr): + from routers.sync_pending import router, get_syncthing_client, get_folder_mgr + from routers.sync_deps import require_config + + app = FastAPI() + app.include_router(router) + app.dependency_overrides[require_config] = lambda: mock_config + app.dependency_overrides[get_syncthing_client] = lambda: mock_client + app.dependency_overrides[get_folder_mgr] = lambda: mock_folder_mgr + return TestClient(app) + + +# --------------------------------------------------------------------------- +# Pending devices +# --------------------------------------------------------------------------- + + +class TestListPendingDevices: + def test_empty(self, client): + resp = client.get("/sync/pending-devices") + assert resp.status_code == 200 + assert resp.json()["devices"] == [] + + def test_returns_devices(self, client, mock_client): + mock_client.get_pending_devices.return_value = { + "DEV-A": {"name": "alice", "address": "192.168.1.2:22000", "time": "2026-03-18T10:00:00Z"}, + "DEV-B": {"name": "bob", "address": "192.168.1.3:22000", "time": "2026-03-18T10:05:00Z"}, + } + resp = client.get("/sync/pending-devices") + assert resp.status_code == 200 + devices = resp.json()["devices"] + assert len(devices) == 2 + ids = {d["device_id"] for d in devices} + assert "DEV-A" in ids + assert "DEV-B" in ids + + def test_syncthing_error_returns_empty(self, client, mock_client): + mock_client.get_pending_devices.side_effect = Exception("unreachable") + resp = client.get("/sync/pending-devices") + assert resp.status_code == 200 + assert resp.json()["devices"] == [] + + +class TestAcceptPendingDevice: + def test_returns_ok(self, client, mock_client): + resp = client.post( + "/sync/pending-devices/DEV-A/accept", + json={}, + ) + assert resp.status_code == 200 + assert resp.json()["ok"] is True + assert resp.json()["device_id"] == "DEV-A" + mock_client.put_config_device.assert_called_once() + call_args = mock_client.put_config_device.call_args[0][0] + assert call_args["deviceID"] == "DEV-A" + + def test_with_name(self, client, mock_client): + resp = client.post( + "/sync/pending-devices/DEV-A/accept", + json={"name": "Alice Laptop"}, + ) + assert resp.status_code == 200 + call_args = mock_client.put_config_device.call_args[0][0] + assert call_args["name"] == "Alice Laptop" + + def test_syncthing_error_returns_500(self, client, mock_client): + mock_client.put_config_device.side_effect = Exception("config error") + resp = client.post( + "/sync/pending-devices/DEV-A/accept", + json={}, + ) + assert resp.status_code == 500 + + def test_empty_body_accepted(self, client, mock_client): + resp = client.post("/sync/pending-devices/DEV-A/accept", json={}) + assert resp.status_code == 200 + + +class TestDismissPendingDevice: + def test_returns_ok(self, client, mock_client): + resp = client.delete("/sync/pending-devices/DEV-A") + assert resp.status_code == 200 + assert resp.json()["ok"] is True + mock_client.dismiss_pending_device.assert_called_once_with("DEV-A") + + def test_syncthing_error_returns_500(self, client, mock_client): + mock_client.dismiss_pending_device.side_effect = Exception("fail") + resp = client.delete("/sync/pending-devices/DEV-A") + assert resp.status_code == 500 + + +# --------------------------------------------------------------------------- +# Pending folders +# --------------------------------------------------------------------------- + + +class TestListPendingFolders: + def test_empty(self, client): + resp = client.get("/sync/pending") + assert resp.status_code == 200 + assert resp.json()["folders"] == [] + + def test_returns_folders(self, client, mock_client): + mock_client.get_pending_folders.return_value = { + "karma-out--alice.laptop--user-repo": { + "DEV-A": { + "label": "karma-out--alice.laptop--user-repo", + "time": "2026-03-18T10:00:00Z", + } + }, + } + resp = client.get("/sync/pending") + assert resp.status_code == 200 + folders = resp.json()["folders"] + assert len(folders) == 1 + f = folders[0] + assert f["folder_id"] == "karma-out--alice.laptop--user-repo" + assert f["from_device"] == "DEV-A" + assert f["from_member"] == "alice.laptop" + assert f["folder_type"] == "out" + + def test_multiple_devices_per_folder(self, client, mock_client): + mock_client.get_pending_folders.return_value = { + "karma-out--a.mac--repo": { + "DEV-A": {"label": "folder", "time": "t1"}, + "DEV-B": {"label": "folder", "time": "t2"}, + }, + } + resp = client.get("/sync/pending") + folders = resp.json()["folders"] + assert len(folders) == 2 + + def test_syncthing_error_returns_empty(self, client, mock_client): + mock_client.get_pending_folders.side_effect = Exception("unreachable") + resp = client.get("/sync/pending") + assert resp.status_code == 200 + assert resp.json()["folders"] == [] + + +class TestAcceptPendingFolder: + def test_returns_ok(self, client, mock_client): + mock_client.get_pending_folders.return_value = { + "karma-out--alice.laptop--repo": { + "DEV-A": {"label": "karma-out--alice.laptop--repo", "time": "t1"}, + }, + } + with patch("config.settings") as mock_settings: + mock_settings.karma_base = Path("/tmp/karma-test") + resp = client.post("/sync/pending/accept/karma-out--alice.laptop--repo") + assert resp.status_code == 200 + assert resp.json()["ok"] is True + mock_client.put_config_folder.assert_called_once() + + def test_folder_not_found_returns_404(self, client, mock_client): + mock_client.get_pending_folders.return_value = {} + resp = client.post("/sync/pending/accept/nonexistent-folder") + assert resp.status_code == 404 + + +class TestRejectPendingFolder: + def test_returns_ok(self, client, mock_client): + resp = client.post( + "/sync/pending/reject/karma-out--alice.laptop--repo", + json={"device_id": "DEV-A"}, + ) + assert resp.status_code == 200 + assert resp.json()["ok"] is True + mock_client.dismiss_pending_folder.assert_called_once_with( + "karma-out--alice.laptop--repo", "DEV-A" + ) + + def test_syncthing_error_returns_500(self, client, mock_client): + mock_client.dismiss_pending_folder.side_effect = Exception("fail") + resp = client.post( + "/sync/pending/reject/karma-out--alice.laptop--repo", + json={"device_id": "DEV-A"}, + ) + assert resp.status_code == 500 + + def test_missing_device_id_returns_422(self, client): + resp = client.post("/sync/pending/reject/some-folder", json={}) + assert resp.status_code == 422 diff --git a/api/tests/api/test_sync_projects_router.py b/api/tests/api/test_sync_projects_router.py new file mode 100644 index 00000000..8a44a32a --- /dev/null +++ b/api/tests/api/test_sync_projects_router.py @@ -0,0 +1,281 @@ +"""Tests for sync_projects v4 router.""" +import sys +from pathlib import Path + +sys.path.insert(0, str(Path(__file__).parent.parent.parent)) + +import sqlite3 +from unittest.mock import MagicMock, AsyncMock + +import pytest +from fastapi import FastAPI +from fastapi.testclient import TestClient + +from db.schema import ensure_schema +from domain.project import SharedProject, SharedProjectStatus +from domain.subscription import Subscription, SubscriptionStatus, SyncDirection +from domain.team import Team, AuthorizationError + + +@pytest.fixture +def conn(): + c = sqlite3.connect(":memory:", check_same_thread=False) + c.row_factory = sqlite3.Row + c.execute("PRAGMA foreign_keys=ON") + ensure_schema(c) + return c + + +@pytest.fixture +def mock_config(): + config = MagicMock() + config.user_id = "jayant" + config.member_tag = "jayant.macbook" + config.syncthing = MagicMock() + config.syncthing.device_id = "DEV-SELF" + return config + + +@pytest.fixture +def mock_project_svc(): + svc = MagicMock() + svc.share_project = AsyncMock() + svc.remove_project = AsyncMock() + svc.accept_subscription = AsyncMock() + svc.pause_subscription = AsyncMock() + svc.resume_subscription = AsyncMock() + svc.decline_subscription = AsyncMock() + svc.change_direction = AsyncMock() + return svc + + +@pytest.fixture +def client(conn, mock_config, mock_project_svc): + from routers.sync_projects import router, get_project_svc + from routers.sync_deps import get_conn, get_read_conn, require_config + + app = FastAPI() + app.include_router(router) + app.dependency_overrides[get_conn] = lambda: conn + app.dependency_overrides[get_read_conn] = lambda: conn + app.dependency_overrides[require_config] = lambda: mock_config + app.dependency_overrides[get_project_svc] = lambda: mock_project_svc + return TestClient(app) + + +class TestShareProject: + def test_returns_201(self, client, mock_project_svc): + mock_project_svc.share_project.return_value = SharedProject( + team_name="karma", + git_identity="jayantdevkar/claude-karma", + folder_suffix="jayantdevkar-claude-karma", + ) + resp = client.post( + "/sync/teams/karma/projects", + json={"git_identity": "jayantdevkar/claude-karma"}, + ) + assert resp.status_code == 201 + data = resp.json() + assert data["git_identity"] == "jayantdevkar/claude-karma" + assert data["folder_suffix"] == "jayantdevkar-claude-karma" + mock_project_svc.share_project.assert_called_once() + + def test_auth_error_returns_403(self, client, mock_project_svc): + mock_project_svc.share_project.side_effect = AuthorizationError("not leader") + resp = client.post( + "/sync/teams/karma/projects", + json={"git_identity": "org/repo"}, + ) + assert resp.status_code == 403 + + def test_missing_git_identity_returns_422(self, client): + resp = client.post("/sync/teams/karma/projects", json={}) + assert resp.status_code == 422 + + +class TestRemoveProject: + def test_returns_200(self, client, mock_project_svc): + mock_project_svc.remove_project.return_value = SharedProject( + team_name="karma", + git_identity="org/repo", + folder_suffix="org-repo", + status=SharedProjectStatus.REMOVED, + ) + resp = client.delete("/sync/teams/karma/projects/org/repo") + assert resp.status_code == 200 + assert resp.json()["ok"] is True + assert resp.json()["status"] == "removed" + + def test_not_found_returns_404(self, client, mock_project_svc): + mock_project_svc.remove_project.side_effect = ValueError("not found") + resp = client.delete("/sync/teams/karma/projects/org/missing") + assert resp.status_code == 404 + + +class TestListProjects: + def test_team_not_found(self, client): + resp = client.get("/sync/teams/nonexistent/projects") + assert resp.status_code == 404 + + def test_returns_projects(self, client, conn): + from repositories.team_repo import TeamRepository + from repositories.project_repo import ProjectRepository + + TeamRepository().save( + conn, + Team(name="karma", leader_device_id="D", leader_member_tag="j.m"), + ) + ProjectRepository().save( + conn, + SharedProject( + team_name="karma", + git_identity="org/repo", + folder_suffix="org-repo", + ), + ) + resp = client.get("/sync/teams/karma/projects") + assert resp.status_code == 200 + projects = resp.json()["projects"] + assert len(projects) == 1 + assert projects[0]["git_identity"] == "org/repo" + + +class TestAcceptSubscription: + def test_accept_with_direction(self, client, mock_project_svc): + mock_project_svc.accept_subscription.return_value = Subscription( + member_tag="jayant.macbook", + team_name="karma", + project_git_identity="org/repo", + status=SubscriptionStatus.ACCEPTED, + direction=SyncDirection.BOTH, + ) + resp = client.post( + "/sync/subscriptions/karma/org/repo/accept", + json={"direction": "both"}, + ) + assert resp.status_code == 200 + data = resp.json() + assert data["status"] == "accepted" + assert data["direction"] == "both" + + def test_invalid_direction_returns_400(self, client): + resp = client.post( + "/sync/subscriptions/karma/org/repo/accept", + json={"direction": "invalid"}, + ) + assert resp.status_code == 400 + + def test_not_found_returns_404(self, client, mock_project_svc): + mock_project_svc.accept_subscription.side_effect = ValueError("not found") + resp = client.post( + "/sync/subscriptions/karma/org/repo/accept", + json={"direction": "both"}, + ) + assert resp.status_code == 404 + + +class TestPauseSubscription: + def test_pause(self, client, mock_project_svc): + mock_project_svc.pause_subscription.return_value = Subscription( + member_tag="jayant.macbook", + team_name="karma", + project_git_identity="org/repo", + status=SubscriptionStatus.PAUSED, + ) + resp = client.post("/sync/subscriptions/karma/org/repo/pause") + assert resp.status_code == 200 + assert resp.json()["status"] == "paused" + + +class TestResumeSubscription: + def test_resume(self, client, mock_project_svc): + mock_project_svc.resume_subscription.return_value = Subscription( + member_tag="jayant.macbook", + team_name="karma", + project_git_identity="org/repo", + status=SubscriptionStatus.ACCEPTED, + direction=SyncDirection.BOTH, + ) + resp = client.post("/sync/subscriptions/karma/org/repo/resume") + assert resp.status_code == 200 + assert resp.json()["status"] == "accepted" + + +class TestDeclineSubscription: + def test_decline(self, client, mock_project_svc): + mock_project_svc.decline_subscription.return_value = Subscription( + member_tag="jayant.macbook", + team_name="karma", + project_git_identity="org/repo", + status=SubscriptionStatus.DECLINED, + ) + resp = client.post("/sync/subscriptions/karma/org/repo/decline") + assert resp.status_code == 200 + assert resp.json()["status"] == "declined" + + +class TestChangeDirection: + def test_change(self, client, mock_project_svc): + mock_project_svc.change_direction.return_value = Subscription( + member_tag="jayant.macbook", + team_name="karma", + project_git_identity="org/repo", + status=SubscriptionStatus.ACCEPTED, + direction=SyncDirection.RECEIVE, + ) + resp = client.patch( + "/sync/subscriptions/karma/org/repo/direction", + json={"direction": "receive"}, + ) + assert resp.status_code == 200 + assert resp.json()["direction"] == "receive" + + def test_invalid_direction_returns_400(self, client): + resp = client.patch( + "/sync/subscriptions/karma/org/repo/direction", + json={"direction": "bad"}, + ) + assert resp.status_code == 400 + + +class TestListSubscriptions: + def test_returns_subs(self, client, conn): + from repositories.team_repo import TeamRepository + from repositories.member_repo import MemberRepository + from repositories.project_repo import ProjectRepository + from repositories.subscription_repo import SubscriptionRepository + from domain.member import Member, MemberStatus + + TeamRepository().save( + conn, + Team(name="karma", leader_device_id="D", leader_member_tag="jayant.macbook"), + ) + MemberRepository().save( + conn, + Member( + member_tag="jayant.macbook", team_name="karma", + device_id="D", user_id="jayant", machine_tag="macbook", + status=MemberStatus.ACTIVE, + ), + ) + ProjectRepository().save( + conn, + SharedProject( + team_name="karma", + git_identity="org/repo", + folder_suffix="org-repo", + ), + ) + SubscriptionRepository().save( + conn, + Subscription( + member_tag="jayant.macbook", + team_name="karma", + project_git_identity="org/repo", + ), + ) + resp = client.get("/sync/subscriptions") + assert resp.status_code == 200 + subs = resp.json()["subscriptions"] + assert len(subs) == 1 + assert subs[0]["status"] == "offered" diff --git a/api/tests/api/test_sync_system_router.py b/api/tests/api/test_sync_system_router.py new file mode 100644 index 00000000..c9c845dc --- /dev/null +++ b/api/tests/api/test_sync_system_router.py @@ -0,0 +1,104 @@ +"""Tests for sync_system v4 router.""" +import sys +from pathlib import Path + +sys.path.insert(0, str(Path(__file__).parent.parent.parent)) + +import sqlite3 +from unittest.mock import MagicMock, AsyncMock + +import pytest +from fastapi import FastAPI +from fastapi.testclient import TestClient + +from db.schema import ensure_schema +from domain.team import Team + + +@pytest.fixture +def conn(): + c = sqlite3.connect(":memory:", check_same_thread=False) + c.row_factory = sqlite3.Row + c.execute("PRAGMA foreign_keys=ON") + ensure_schema(c) + return c + + +@pytest.fixture +def mock_config(): + config = MagicMock() + config.user_id = "jayant" + config.machine_id = "abc123" + config.member_tag = "jayant.macbook" + config.syncthing = MagicMock() + config.syncthing.device_id = "DEV-SELF" + config.syncthing.api_key = "test-key" + return config + + +@pytest.fixture +def mock_recon_svc(): + svc = MagicMock() + svc.run_cycle = AsyncMock() + return svc + + +@pytest.fixture +def client(conn, mock_config, mock_recon_svc): + from routers.sync_system import router, get_recon_svc + from routers.sync_deps import get_conn, get_read_conn, get_optional_config, require_config + + app = FastAPI() + app.include_router(router) + app.dependency_overrides[get_conn] = lambda: conn + app.dependency_overrides[get_read_conn] = lambda: conn + app.dependency_overrides[get_optional_config] = lambda: mock_config + app.dependency_overrides[require_config] = lambda: mock_config + app.dependency_overrides[get_recon_svc] = lambda: mock_recon_svc + return TestClient(app) + + +class TestStatus: + def test_configured(self, client, conn): + from repositories.team_repo import TeamRepository + + TeamRepository().save( + conn, + Team(name="karma", leader_device_id="D1", leader_member_tag="j.m"), + ) + resp = client.get("/sync/status") + assert resp.status_code == 200 + data = resp.json() + assert data["configured"] is True + assert data["user_id"] == "jayant" + assert data["member_tag"] == "jayant.macbook" + team_names = [t["name"] for t in data["teams"]] + assert "karma" in team_names + + def test_not_configured(self, conn): + from routers.sync_system import router + from routers.sync_deps import get_conn, get_read_conn, get_optional_config + + app = FastAPI() + app.include_router(router) + app.dependency_overrides[get_conn] = lambda: conn + app.dependency_overrides[get_read_conn] = lambda: conn + app.dependency_overrides[get_optional_config] = lambda: None + + c = TestClient(app) + resp = c.get("/sync/status") + assert resp.status_code == 200 + assert resp.json() == {"configured": False} + + +class TestReconcile: + def test_ok(self, client, mock_recon_svc): + resp = client.post("/sync/reconcile") + assert resp.status_code == 200 + assert resp.json()["ok"] is True + mock_recon_svc.run_cycle.assert_called_once() + + def test_failure_returns_500(self, client, mock_recon_svc): + mock_recon_svc.run_cycle.side_effect = RuntimeError("boom") + resp = client.post("/sync/reconcile") + assert resp.status_code == 500 diff --git a/api/tests/api/test_sync_teams_router.py b/api/tests/api/test_sync_teams_router.py new file mode 100644 index 00000000..b79f5f9b --- /dev/null +++ b/api/tests/api/test_sync_teams_router.py @@ -0,0 +1,490 @@ +"""Tests for sync_teams v4 router.""" +import sys +from pathlib import Path + +sys.path.insert(0, str(Path(__file__).parent.parent.parent)) + +import sqlite3 +from unittest.mock import MagicMock, AsyncMock + +import pytest +from fastapi import FastAPI +from fastapi.testclient import TestClient + +from db.schema import ensure_schema +from domain.team import Team, TeamStatus, AuthorizationError +from domain.member import Member, MemberStatus +from services.sync.pairing_service import PairingInfo + + +@pytest.fixture +def conn(): + c = sqlite3.connect(":memory:", check_same_thread=False) + c.row_factory = sqlite3.Row + c.execute("PRAGMA foreign_keys=ON") + ensure_schema(c) + return c + + +@pytest.fixture +def mock_config(): + config = MagicMock() + config.user_id = "jayant" + config.machine_tag = "macbook" + config.member_tag = "jayant.macbook" + config.syncthing = MagicMock() + config.syncthing.device_id = "DEV-SELF" + config.syncthing.api_key = "test-key" + return config + + +@pytest.fixture +def mock_team_svc(): + svc = MagicMock() + svc.create_team = AsyncMock() + svc.add_member = AsyncMock() + svc.remove_member = AsyncMock() + svc.dissolve_team = AsyncMock() + return svc + + +@pytest.fixture +def mock_pairing_svc(): + svc = MagicMock() + svc.validate_code = MagicMock() + svc.generate_code = MagicMock() + return svc + + +@pytest.fixture +def client(conn, mock_config, mock_team_svc, mock_pairing_svc): + from routers.sync_teams import router, get_team_svc, get_pairing_svc + from routers.sync_deps import get_conn, get_read_conn, require_config + + app = FastAPI() + app.include_router(router) + app.dependency_overrides[get_conn] = lambda: conn + app.dependency_overrides[get_read_conn] = lambda: conn + app.dependency_overrides[require_config] = lambda: mock_config + app.dependency_overrides[get_team_svc] = lambda: mock_team_svc + app.dependency_overrides[get_pairing_svc] = lambda: mock_pairing_svc + return TestClient(app) + + +class TestCreateTeam: + def test_returns_201(self, client, mock_team_svc): + mock_team_svc.create_team.return_value = Team( + name="karma", + leader_device_id="DEV-SELF", + leader_member_tag="jayant.macbook", + ) + resp = client.post("/sync/teams", json={"name": "karma"}) + assert resp.status_code == 201 + data = resp.json() + assert data["name"] == "karma" + assert data["leader_member_tag"] == "jayant.macbook" + assert data["status"] == "active" + mock_team_svc.create_team.assert_called_once() + + def test_missing_name_returns_422(self, client): + resp = client.post("/sync/teams", json={}) + assert resp.status_code == 422 + + def test_invalid_name_returns_400(self, client): + resp = client.post("/sync/teams", json={"name": "a"}) + assert resp.status_code == 400 + + def test_service_error_returns_400(self, client, mock_team_svc): + mock_team_svc.create_team.side_effect = ValueError("already exists") + resp = client.post("/sync/teams", json={"name": "karma"}) + assert resp.status_code == 400 + + +class TestListTeams: + def test_empty_list(self, client): + resp = client.get("/sync/teams") + assert resp.status_code == 200 + assert resp.json()["teams"] == [] + + def test_returns_teams(self, client, conn): + from repositories.team_repo import TeamRepository + + TeamRepository().save( + conn, + Team(name="alpha", leader_device_id="D1", leader_member_tag="a.mac"), + ) + resp = client.get("/sync/teams") + assert resp.status_code == 200 + teams = resp.json()["teams"] + assert len(teams) == 1 + assert teams[0]["name"] == "alpha" + + +class TestGetTeam: + def test_returns_detail(self, client, conn): + from repositories.team_repo import TeamRepository + + TeamRepository().save( + conn, + Team(name="beta", leader_device_id="D2", leader_member_tag="b.mac"), + ) + resp = client.get("/sync/teams/beta") + assert resp.status_code == 200 + data = resp.json() + assert data["name"] == "beta" + assert "members" in data + assert "projects" in data + assert "subscriptions" in data + + def test_not_found_returns_404(self, client): + resp = client.get("/sync/teams/nonexistent") + assert resp.status_code == 404 + + +class TestAddMember: + def test_with_pairing_code(self, client, mock_team_svc, mock_pairing_svc): + mock_pairing_svc.validate_code.return_value = PairingInfo( + member_tag="ayush.laptop", device_id="DEV-A", + ) + mock_team_svc.add_member.return_value = Member( + member_tag="ayush.laptop", + team_name="karma", + device_id="DEV-A", + user_id="ayush", + machine_tag="laptop", + status=MemberStatus.ADDED, + ) + resp = client.post( + "/sync/teams/karma/members", + json={"pairing_code": "ABCD-1234"}, + ) + assert resp.status_code == 201 + assert resp.json()["member_tag"] == "ayush.laptop" + assert resp.json()["status"] == "added" + + def test_invalid_code_returns_400(self, client, mock_pairing_svc): + mock_pairing_svc.validate_code.side_effect = ValueError("bad code") + resp = client.post( + "/sync/teams/karma/members", + json={"pairing_code": "BAD"}, + ) + assert resp.status_code == 400 + + def test_auth_error_returns_403(self, client, mock_team_svc, mock_pairing_svc): + mock_pairing_svc.validate_code.return_value = PairingInfo( + member_tag="x.y", device_id="D", + ) + mock_team_svc.add_member.side_effect = AuthorizationError("not leader") + resp = client.post( + "/sync/teams/karma/members", + json={"pairing_code": "ABCD-1234"}, + ) + assert resp.status_code == 403 + + +class TestRemoveMember: + def test_returns_200(self, client, mock_team_svc): + mock_team_svc.remove_member.return_value = Member( + member_tag="ayush.laptop", + team_name="karma", + device_id="DEV-A", + user_id="ayush", + machine_tag="laptop", + status=MemberStatus.REMOVED, + ) + resp = client.delete("/sync/teams/karma/members/ayush.laptop") + assert resp.status_code == 200 + assert resp.json()["status"] == "removed" + + def test_auth_error_returns_403(self, client, mock_team_svc): + mock_team_svc.remove_member.side_effect = AuthorizationError("not leader") + resp = client.delete("/sync/teams/karma/members/x.y") + assert resp.status_code == 403 + + +class TestDissolveTeam: + def test_returns_200(self, client, mock_team_svc): + mock_team_svc.dissolve_team.return_value = Team( + name="karma", + leader_device_id="DEV-SELF", + leader_member_tag="jayant.macbook", + status=TeamStatus.DISSOLVED, + ) + resp = client.delete("/sync/teams/karma") + assert resp.status_code == 200 + assert resp.json()["ok"] is True + assert resp.json()["status"] == "dissolved" + + def test_auth_error_returns_403(self, client, mock_team_svc): + mock_team_svc.dissolve_team.side_effect = AuthorizationError("not leader") + resp = client.delete("/sync/teams/karma") + assert resp.status_code == 403 + + +class TestListMembers: + def test_team_not_found(self, client): + resp = client.get("/sync/teams/nonexistent/members") + assert resp.status_code == 404 + + def test_returns_members(self, client, conn): + from repositories.team_repo import TeamRepository + from repositories.member_repo import MemberRepository + + TeamRepository().save( + conn, + Team(name="gamma", leader_device_id="D3", leader_member_tag="c.mac"), + ) + MemberRepository().save( + conn, + Member( + member_tag="c.mac", + team_name="gamma", + device_id="D3", + user_id="c", + machine_tag="mac", + status=MemberStatus.ACTIVE, + ), + ) + resp = client.get("/sync/teams/gamma/members") + assert resp.status_code == 200 + members = resp.json()["members"] + assert len(members) == 1 + assert members[0]["member_tag"] == "c.mac" + + +class TestJoinCode: + def test_returns_code(self, client, conn, mock_config, mock_pairing_svc): + from repositories.team_repo import TeamRepository + + TeamRepository().save( + conn, + Team(name="delta", leader_device_id="D4", leader_member_tag="d.mac"), + ) + mock_pairing_svc.generate_code.return_value = "WXYZ-5678" + resp = client.get("/sync/teams/delta/join-code") + assert resp.status_code == 200 + data = resp.json() + assert data["code"] == "WXYZ-5678" + assert data["member_tag"] == "jayant.macbook" + assert data["device_id"] == "DEV-SELF" + mock_pairing_svc.generate_code.assert_called_once_with( + "jayant.macbook", "DEV-SELF" + ) + + def test_team_not_found_returns_404(self, client): + resp = client.get("/sync/teams/nonexistent/join-code") + assert resp.status_code == 404 + + def test_no_device_id_returns_400(self, client, conn, mock_config): + from repositories.team_repo import TeamRepository + + TeamRepository().save( + conn, + Team(name="epsilon", leader_device_id="D5", leader_member_tag="e.mac"), + ) + mock_config.syncthing.device_id = "" + resp = client.get("/sync/teams/epsilon/join-code") + assert resp.status_code == 400 + + +class TestTeamActivity: + def test_returns_events(self, client, conn): + from repositories.team_repo import TeamRepository + from repositories.event_repo import EventRepository + from domain.events import SyncEvent, SyncEventType + + TeamRepository().save( + conn, + Team(name="zeta", leader_device_id="D6", leader_member_tag="f.mac"), + ) + EventRepository().log( + conn, + SyncEvent( + event_type=SyncEventType.team_created, + team_name="zeta", + member_tag="f.mac", + ), + ) + resp = client.get("/sync/teams/zeta/activity") + assert resp.status_code == 200 + events = resp.json()["events"] + assert len(events) == 1 + assert events[0]["event_type"] == "team_created" + assert events[0]["team_name"] == "zeta" + + def test_team_not_found_returns_404(self, client): + resp = client.get("/sync/teams/nonexistent/activity") + assert resp.status_code == 404 + + def test_limit_param(self, client, conn): + from repositories.team_repo import TeamRepository + from repositories.event_repo import EventRepository + from domain.events import SyncEvent, SyncEventType + + TeamRepository().save( + conn, + Team(name="eta", leader_device_id="D7", leader_member_tag="g.mac"), + ) + for _ in range(5): + EventRepository().log( + conn, + SyncEvent( + event_type=SyncEventType.member_added, + team_name="eta", + member_tag="g.mac", + ), + ) + resp = client.get("/sync/teams/eta/activity?limit=2") + assert resp.status_code == 200 + assert len(resp.json()["events"]) == 2 + + def test_empty_activity(self, client, conn): + from repositories.team_repo import TeamRepository + + TeamRepository().save( + conn, + Team(name="theta", leader_device_id="D8", leader_member_tag="h.mac"), + ) + resp = client.get("/sync/teams/theta/activity") + assert resp.status_code == 200 + assert resp.json()["events"] == [] + + +class TestProjectStatus: + def test_returns_project_subscription_counts(self, client, conn): + from repositories.team_repo import TeamRepository + from repositories.member_repo import MemberRepository + from repositories.project_repo import ProjectRepository + from repositories.subscription_repo import SubscriptionRepository + from domain.project import SharedProject + from domain.subscription import Subscription, SubscriptionStatus, SyncDirection + + TeamRepository().save( + conn, + Team(name="iota", leader_device_id="D9", leader_member_tag="i.mac"), + ) + MemberRepository().save( + conn, + Member( + member_tag="i.mac", team_name="iota", device_id="D9", + user_id="i", machine_tag="mac", + ), + ) + MemberRepository().save( + conn, + Member( + member_tag="j.laptop", team_name="iota", device_id="D10", + user_id="j", machine_tag="laptop", + ), + ) + ProjectRepository().save( + conn, + SharedProject( + team_name="iota", git_identity="user/repo", + folder_suffix="user-repo", + ), + ) + SubscriptionRepository().save( + conn, + Subscription( + member_tag="i.mac", team_name="iota", + project_git_identity="user/repo", + status=SubscriptionStatus.ACCEPTED, + ), + ) + SubscriptionRepository().save( + conn, + Subscription( + member_tag="j.laptop", team_name="iota", + project_git_identity="user/repo", + status=SubscriptionStatus.OFFERED, + ), + ) + resp = client.get("/sync/teams/iota/project-status") + assert resp.status_code == 200 + projects = resp.json()["projects"] + assert len(projects) == 1 + p = projects[0] + assert p["git_identity"] == "user/repo" + assert p["subscription_counts"]["accepted"] == 1 + assert p["subscription_counts"]["offered"] == 1 + assert p["subscription_counts"]["paused"] == 0 + assert p["subscription_counts"]["declined"] == 0 + + def test_team_not_found_returns_404(self, client): + resp = client.get("/sync/teams/nonexistent/project-status") + assert resp.status_code == 404 + + def test_no_projects(self, client, conn): + from repositories.team_repo import TeamRepository + + TeamRepository().save( + conn, + Team(name="kappa", leader_device_id="D11", leader_member_tag="k.mac"), + ) + resp = client.get("/sync/teams/kappa/project-status") + assert resp.status_code == 200 + assert resp.json()["projects"] == [] + + +class TestSessionStats: + def test_returns_member_stats(self, client, conn): + from repositories.team_repo import TeamRepository + from repositories.member_repo import MemberRepository + from repositories.subscription_repo import SubscriptionRepository + from domain.subscription import Subscription, SubscriptionStatus + + TeamRepository().save( + conn, + Team(name="lambda", leader_device_id="D12", leader_member_tag="l.mac"), + ) + MemberRepository().save( + conn, + Member( + member_tag="l.mac", team_name="lambda", device_id="D12", + user_id="l", machine_tag="mac", status=MemberStatus.ACTIVE, + ), + ) + # Need a project for the FK constraint + from repositories.project_repo import ProjectRepository + from domain.project import SharedProject + + ProjectRepository().save( + conn, + SharedProject( + team_name="lambda", git_identity="org/proj", + folder_suffix="org-proj", + ), + ) + SubscriptionRepository().save( + conn, + Subscription( + member_tag="l.mac", team_name="lambda", + project_git_identity="org/proj", + status=SubscriptionStatus.ACCEPTED, + ), + ) + resp = client.get("/sync/teams/lambda/session-stats") + assert resp.status_code == 200 + members = resp.json()["members"] + assert len(members) == 1 + m = members[0] + assert m["member_tag"] == "l.mac" + assert m["user_id"] == "l" + assert m["status"] == "active" + assert m["subscription_count"] == 1 + + def test_team_not_found_returns_404(self, client): + resp = client.get("/sync/teams/nonexistent/session-stats") + assert resp.status_code == 404 + + def test_no_members(self, client, conn): + from repositories.team_repo import TeamRepository + + TeamRepository().save( + conn, + Team(name="mu", leader_device_id="D13", leader_member_tag="m.mac"), + ) + resp = client.get("/sync/teams/mu/session-stats") + assert resp.status_code == 200 + assert resp.json()["members"] == [] diff --git a/api/tests/test_cross_team_cleanup.py b/api/tests/test_cross_team_cleanup.py new file mode 100644 index 00000000..76201665 --- /dev/null +++ b/api/tests/test_cross_team_cleanup.py @@ -0,0 +1,231 @@ +"""Tests for cross-team safety in folder cleanup. + +Verifies that leaving/dissolving a team or removing a project does NOT +destroy Syncthing folders that are still needed by another team sharing +the same project (same folder_suffix). +""" +import sys +from pathlib import Path +sys.path.insert(0, str(Path(__file__).parent.parent)) + +import sqlite3 +import pytest +from unittest.mock import MagicMock, AsyncMock + +from db.schema import ensure_schema +from domain.team import Team +from domain.member import Member, MemberStatus +from domain.project import SharedProject, SharedProjectStatus, derive_folder_suffix +from domain.subscription import Subscription, SubscriptionStatus, SyncDirection +from repositories.team_repo import TeamRepository +from repositories.member_repo import MemberRepository +from repositories.project_repo import ProjectRepository +from repositories.subscription_repo import SubscriptionRepository +from repositories.event_repo import EventRepository +from services.syncthing.folder_manager import ( + FolderManager, + build_metadata_folder_id, + build_outbox_folder_id, +) +from services.syncthing.client import SyncthingClient + + +MEMBER_TAG = "alice.laptop" +DEVICE_ID = "DEV-ALICE" +TEAM1 = "team-one" +TEAM2 = "team-two" +GIT_IDENTITY = "owner/repo" +FOLDER_SUFFIX = derive_folder_suffix(GIT_IDENTITY) + + +@pytest.fixture +def conn(): + c = sqlite3.connect(":memory:") + c.row_factory = sqlite3.Row + c.execute("PRAGMA foreign_keys=ON") + ensure_schema(c) + return c + + +@pytest.fixture +def mock_client(): + client = MagicMock(spec=SyncthingClient) + client.get_config_folders = AsyncMock(return_value=[]) + client.put_config_folder = AsyncMock() + client.delete_config_folder = AsyncMock() + return client + + +@pytest.fixture +def manager(mock_client, tmp_path): + base = tmp_path / ".claude_karma" + base.mkdir() + return FolderManager(client=mock_client, karma_base=base) + + +def seed_team(conn, name, leader_tag=MEMBER_TAG, leader_device=DEVICE_ID): + team = Team(name=name, leader_device_id=leader_device, leader_member_tag=leader_tag) + TeamRepository().save(conn, team) + return team + + +def seed_member(conn, member_tag, team_name, device_id=DEVICE_ID): + m = Member.from_member_tag( + member_tag=member_tag, + team_name=team_name, + device_id=device_id, + status=MemberStatus.ADDED, + ).activate() + MemberRepository().save(conn, m) + return m + + +def seed_project(conn, team_name, git_identity=GIT_IDENTITY): + suffix = derive_folder_suffix(git_identity) + p = SharedProject( + team_name=team_name, + git_identity=git_identity, + folder_suffix=suffix, + ) + ProjectRepository().save(conn, p) + return p + + +def seed_subscription(conn, member_tag, team_name, git_identity=GIT_IDENTITY, + status=SubscriptionStatus.ACCEPTED, direction=SyncDirection.BOTH): + sub = Subscription( + member_tag=member_tag, + team_name=team_name, + project_git_identity=git_identity, + status=status, + direction=direction, + ) + SubscriptionRepository().save(conn, sub) + return sub + + +class TestCleanupSkipsFolderNeededByOtherTeam: + """M1 in T1+T2 both sharing P1. Leave T1 -> outbox NOT deleted.""" + + @pytest.mark.asyncio + async def test_cleanup_skips_folder_needed_by_other_team(self, conn, manager, mock_client): + # Setup: alice is in team-one and team-two, both sharing the same project + seed_team(conn, TEAM1) + seed_team(conn, TEAM2) + seed_member(conn, MEMBER_TAG, TEAM1) + seed_member(conn, MEMBER_TAG, TEAM2) + seed_project(conn, TEAM1) + seed_project(conn, TEAM2) + seed_subscription(conn, MEMBER_TAG, TEAM1) + seed_subscription(conn, MEMBER_TAG, TEAM2) + + outbox_id = build_outbox_folder_id(MEMBER_TAG, FOLDER_SUFFIX) + meta_id = build_metadata_folder_id(TEAM1) + + mock_client.get_config_folders.return_value = [ + {"id": outbox_id}, + {"id": meta_id}, + ] + + # Act: cleanup team-one folders WITH conn (cross-team check enabled) + await manager.cleanup_team_folders( + folder_suffixes=[FOLDER_SUFFIX], + member_tags=[MEMBER_TAG], + team_name=TEAM1, + conn=conn, + ) + + # Assert: metadata folder deleted (team-scoped), outbox folder skipped + deleted = [c[0][0] for c in mock_client.delete_config_folder.call_args_list] + assert meta_id in deleted, "metadata folder should always be deleted (team-scoped)" + assert outbox_id not in deleted, "outbox folder should be skipped (needed by team-two)" + + +class TestCleanupDeletesFolderWhenNoOtherTeam: + """M1 only in T1. Leave T1 -> outbox IS deleted.""" + + @pytest.mark.asyncio + async def test_cleanup_deletes_folder_when_no_other_team(self, conn, manager, mock_client): + # Setup: alice is only in team-one + seed_team(conn, TEAM1) + seed_member(conn, MEMBER_TAG, TEAM1) + seed_project(conn, TEAM1) + seed_subscription(conn, MEMBER_TAG, TEAM1) + + outbox_id = build_outbox_folder_id(MEMBER_TAG, FOLDER_SUFFIX) + meta_id = build_metadata_folder_id(TEAM1) + + mock_client.get_config_folders.return_value = [ + {"id": outbox_id}, + {"id": meta_id}, + ] + + # Act: cleanup team-one folders WITH conn + await manager.cleanup_team_folders( + folder_suffixes=[FOLDER_SUFFIX], + member_tags=[MEMBER_TAG], + team_name=TEAM1, + conn=conn, + ) + + # Assert: both metadata and outbox folders are deleted + deleted = [c[0][0] for c in mock_client.delete_config_folder.call_args_list] + assert meta_id in deleted + assert outbox_id in deleted, "outbox folder should be deleted (no other team needs it)" + + +class TestCleanupProjectSkipsCrossTeamFolder: + """Remove P1 from T1 while T2 still shares P1 -> outbox NOT deleted.""" + + @pytest.mark.asyncio + async def test_cleanup_project_skips_cross_team_folder(self, conn, manager, mock_client): + # Setup: alice is in team-one and team-two, both sharing the same project + seed_team(conn, TEAM1) + seed_team(conn, TEAM2) + seed_member(conn, MEMBER_TAG, TEAM1) + seed_member(conn, MEMBER_TAG, TEAM2) + seed_project(conn, TEAM1) + seed_project(conn, TEAM2) + seed_subscription(conn, MEMBER_TAG, TEAM1) + seed_subscription(conn, MEMBER_TAG, TEAM2) + + outbox_id = build_outbox_folder_id(MEMBER_TAG, FOLDER_SUFFIX) + + mock_client.get_config_folders.return_value = [ + {"id": outbox_id}, + ] + + # Act: cleanup project folders for team-one WITH conn + team_name + await manager.cleanup_project_folders( + folder_suffix=FOLDER_SUFFIX, + member_tags=[MEMBER_TAG], + conn=conn, + team_name=TEAM1, + ) + + # Assert: outbox folder should NOT be deleted (team-two still needs it) + mock_client.delete_config_folder.assert_not_called() + + @pytest.mark.asyncio + async def test_cleanup_project_deletes_when_no_cross_team(self, conn, manager, mock_client): + """When only one team shares the project, folder IS deleted.""" + seed_team(conn, TEAM1) + seed_member(conn, MEMBER_TAG, TEAM1) + seed_project(conn, TEAM1) + seed_subscription(conn, MEMBER_TAG, TEAM1) + + outbox_id = build_outbox_folder_id(MEMBER_TAG, FOLDER_SUFFIX) + + mock_client.get_config_folders.return_value = [ + {"id": outbox_id}, + ] + + await manager.cleanup_project_folders( + folder_suffix=FOLDER_SUFFIX, + member_tags=[MEMBER_TAG], + conn=conn, + team_name=TEAM1, + ) + + # Assert: folder IS deleted (no other team shares this project) + mock_client.delete_config_folder.assert_called_once_with(outbox_id) diff --git a/api/tests/test_device_manager.py b/api/tests/test_device_manager.py new file mode 100644 index 00000000..78ca5f02 --- /dev/null +++ b/api/tests/test_device_manager.py @@ -0,0 +1,158 @@ +""" +Tests for DeviceManager — pair/unpair/ensure_paired/is_connected/list_connected. +""" + +import sys +from pathlib import Path + +sys.path.insert(0, str(Path(__file__).parent.parent)) + +from unittest.mock import AsyncMock, MagicMock + +import pytest + +from services.syncthing.client import SyncthingClient +from services.syncthing.device_manager import DeviceManager + + +@pytest.fixture +def mock_client(): + client = MagicMock(spec=SyncthingClient) + # Make all methods async + client.get_config_devices = AsyncMock() + client.put_config_device = AsyncMock() + client.delete_config_device = AsyncMock() + client.get_connections = AsyncMock() + return client + + +@pytest.fixture +def manager(mock_client): + return DeviceManager(client=mock_client) + + +DEVICE_ID = "AAAAAAA-BBBBBBB-CCCCCCC-DDDDDDD-EEEEEEE-FFFFFFF-GGGGGGG-HHHHHHH" +DEVICE_ID_2 = "ZZZZZZZ-YYYYYYY-XXXXXXX-WWWWWWW-VVVVVVV-UUUUUUU-TTTTTTT-SSSSSSS" + + +class TestPair: + async def test_adds_device_to_config(self, manager, mock_client): + mock_client.get_config_devices.return_value = [] + await manager.pair(DEVICE_ID) + mock_client.put_config_device.assert_called_once() + call_args = mock_client.put_config_device.call_args[0][0] + assert call_args["deviceID"] == DEVICE_ID + + async def test_device_has_dynamic_address(self, manager, mock_client): + mock_client.get_config_devices.return_value = [] + await manager.pair(DEVICE_ID) + call_args = mock_client.put_config_device.call_args[0][0] + assert "dynamic" in call_args["addresses"] + + async def test_device_has_auto_accept(self, manager, mock_client): + mock_client.get_config_devices.return_value = [] + await manager.pair(DEVICE_ID) + call_args = mock_client.put_config_device.call_args[0][0] + assert call_args["autoAcceptFolders"] is False + + async def test_pair_already_existing_overwrites(self, manager, mock_client): + """pair() always calls put, even if device already exists.""" + mock_client.get_config_devices.return_value = [{"deviceID": DEVICE_ID}] + await manager.pair(DEVICE_ID) + mock_client.put_config_device.assert_called_once() + + +class TestUnpair: + async def test_removes_device(self, manager, mock_client): + await manager.unpair(DEVICE_ID) + mock_client.delete_config_device.assert_called_once_with(DEVICE_ID) + + async def test_does_not_call_put(self, manager, mock_client): + await manager.unpair(DEVICE_ID) + mock_client.put_config_device.assert_not_called() + + +class TestEnsurePaired: + async def test_pairs_when_not_present(self, manager, mock_client): + mock_client.get_config_devices.return_value = [] + await manager.ensure_paired(DEVICE_ID) + mock_client.put_config_device.assert_called_once() + + async def test_skips_pair_when_already_present(self, manager, mock_client): + mock_client.get_config_devices.return_value = [{"deviceID": DEVICE_ID}] + await manager.ensure_paired(DEVICE_ID) + mock_client.put_config_device.assert_not_called() + + async def test_idempotent_multiple_calls(self, manager, mock_client): + """Second call with device present skips put.""" + mock_client.get_config_devices.return_value = [{"deviceID": DEVICE_ID}] + await manager.ensure_paired(DEVICE_ID) + await manager.ensure_paired(DEVICE_ID) + mock_client.put_config_device.assert_not_called() + + +class TestIsConnected: + async def test_returns_true_when_connected(self, manager, mock_client): + mock_client.get_connections.return_value = { + "connections": { + DEVICE_ID: {"connected": True}, + } + } + result = await manager.is_connected(DEVICE_ID) + assert result is True + + async def test_returns_false_when_disconnected(self, manager, mock_client): + mock_client.get_connections.return_value = { + "connections": { + DEVICE_ID: {"connected": False}, + } + } + result = await manager.is_connected(DEVICE_ID) + assert result is False + + async def test_returns_false_when_device_absent(self, manager, mock_client): + mock_client.get_connections.return_value = {"connections": {}} + result = await manager.is_connected(DEVICE_ID) + assert result is False + + async def test_returns_false_on_missing_connections_key(self, manager, mock_client): + mock_client.get_connections.return_value = {} + result = await manager.is_connected(DEVICE_ID) + assert result is False + + +class TestListConnected: + async def test_returns_connected_device_ids(self, manager, mock_client): + mock_client.get_connections.return_value = { + "connections": { + DEVICE_ID: {"connected": True}, + DEVICE_ID_2: {"connected": False}, + } + } + result = await manager.list_connected() + assert DEVICE_ID in result + assert DEVICE_ID_2 not in result + + async def test_empty_when_none_connected(self, manager, mock_client): + mock_client.get_connections.return_value = { + "connections": { + DEVICE_ID: {"connected": False}, + } + } + result = await manager.list_connected() + assert result == [] + + async def test_empty_on_no_connections_key(self, manager, mock_client): + mock_client.get_connections.return_value = {} + result = await manager.list_connected() + assert result == [] + + async def test_returns_all_connected(self, manager, mock_client): + mock_client.get_connections.return_value = { + "connections": { + DEVICE_ID: {"connected": True}, + DEVICE_ID_2: {"connected": True}, + } + } + result = await manager.list_connected() + assert sorted(result) == sorted([DEVICE_ID, DEVICE_ID_2]) diff --git a/api/tests/test_domain_events.py b/api/tests/test_domain_events.py new file mode 100644 index 00000000..83cca6dd --- /dev/null +++ b/api/tests/test_domain_events.py @@ -0,0 +1,139 @@ +"""Tests for the SyncEvent domain model.""" +import sys +from pathlib import Path + +sys.path.insert(0, str(Path(__file__).parent.parent)) + +import pytest +from datetime import datetime, timezone +from domain.events import SyncEvent, SyncEventType + + +class TestSyncEventType: + def test_all_18_event_types_exist(self): + expected = [ + "team_created", "team_dissolved", + "member_added", "member_activated", "member_removed", "member_auto_left", + "project_shared", "project_removed", + "subscription_offered", "subscription_accepted", + "subscription_paused", "subscription_resumed", "subscription_declined", + "direction_changed", + "session_packaged", "session_received", + "device_paired", "device_unpaired", + ] + actual_values = {e.value for e in SyncEventType} + for name in expected: + assert name in actual_values, f"Missing event type: {name}" + + def test_exactly_19_event_types(self): + assert len(SyncEventType) == 19 + + def test_event_type_is_str_enum(self): + assert isinstance(SyncEventType.team_created, str) + assert SyncEventType.team_created == "team_created" + + +class TestSyncEventCreation: + def test_create_team_created_event(self): + event = SyncEvent( + event_type=SyncEventType.team_created, + team_name="karma-team", + ) + assert event.event_type == SyncEventType.team_created + assert event.team_name == "karma-team" + assert event.member_tag is None + assert event.project_git_identity is None + assert event.session_uuid is None + assert event.detail is None + assert event.created_at is not None + + def test_create_member_added_event_with_detail(self): + event = SyncEvent( + event_type=SyncEventType.member_added, + team_name="karma-team", + member_tag="ayush.laptop", + detail={"device_id": "DEV-1", "added_by": "jayant.macbook"}, + ) + assert event.member_tag == "ayush.laptop" + assert event.detail["device_id"] == "DEV-1" + assert event.detail["added_by"] == "jayant.macbook" + + def test_create_session_packaged_event(self): + event = SyncEvent( + event_type=SyncEventType.session_packaged, + team_name="t", + member_tag="j.m", + project_git_identity="owner/repo", + session_uuid="abc-123", + detail={"branches": ["main", "feature-x"]}, + ) + assert event.session_uuid == "abc-123" + assert event.project_git_identity == "owner/repo" + + def test_create_subscription_accepted_event(self): + event = SyncEvent( + event_type=SyncEventType.subscription_accepted, + team_name="t", + member_tag="a.l", + project_git_identity="o/r", + detail={"direction": "both"}, + ) + assert event.detail["direction"] == "both" + + def test_create_direction_changed_event(self): + event = SyncEvent( + event_type=SyncEventType.direction_changed, + team_name="t", + member_tag="a.l", + project_git_identity="o/r", + detail={"old_direction": "both", "new_direction": "receive"}, + ) + assert event.detail["old_direction"] == "both" + + def test_create_device_paired_event(self): + event = SyncEvent( + event_type=SyncEventType.device_paired, + team_name="t", + detail={"device_id": "DEV-123"}, + ) + assert event.detail["device_id"] == "DEV-123" + + def test_create_member_auto_left_event(self): + event = SyncEvent( + event_type=SyncEventType.member_auto_left, + team_name="t", + ) + assert event.event_type == SyncEventType.member_auto_left + + +class TestSyncEventFrozen: + def test_event_is_frozen(self): + event = SyncEvent( + event_type=SyncEventType.team_created, + team_name="t", + ) + with pytest.raises(Exception): + event.team_name = "other" + + +class TestSyncEventOptionalFields: + def test_all_optional_fields_default_none(self): + event = SyncEvent( + event_type=SyncEventType.team_dissolved, + team_name="t", + ) + assert event.member_tag is None + assert event.project_git_identity is None + assert event.session_uuid is None + assert event.detail is None + + def test_team_name_is_optional(self): + event = SyncEvent( + event_type=SyncEventType.device_paired, + ) + assert event.team_name is None + + def test_all_event_types_can_be_instantiated(self): + for event_type in SyncEventType: + event = SyncEvent(event_type=event_type, team_name="t") + assert event.event_type == event_type diff --git a/api/tests/test_domain_member.py b/api/tests/test_domain_member.py new file mode 100644 index 00000000..4fed9c53 --- /dev/null +++ b/api/tests/test_domain_member.py @@ -0,0 +1,124 @@ +"""Tests for the Member domain model.""" +import sys +from pathlib import Path + +sys.path.insert(0, str(Path(__file__).parent.parent)) + +import pytest +from datetime import datetime, timezone +from domain.member import Member, MemberStatus +from domain.team import InvalidTransitionError + + +def make_member(**kwargs): + defaults = dict( + member_tag="alice.macbook", + team_name="team-abc", + user_id="alice", + machine_tag="macbook", + device_id="DEVICE123", + ) + defaults.update(kwargs) + return Member(**defaults) + + +class TestMemberModel: + def test_create_member_defaults(self): + m = make_member() + assert m.member_tag == "alice.macbook" + assert m.team_name == "team-abc" + assert m.user_id == "alice" + assert m.machine_tag == "macbook" + assert m.device_id == "DEVICE123" + assert m.status == MemberStatus.ADDED + assert isinstance(m.added_at, datetime) + assert m.added_at.tzinfo is not None + assert isinstance(m.updated_at, datetime) + assert m.updated_at.tzinfo is not None + + def test_member_is_frozen(self): + m = make_member() + with pytest.raises(Exception): + m.user_id = "changed" + + def test_is_active_false_when_added(self): + m = make_member() + assert m.is_active is False + + def test_is_active_true_when_active(self): + m = make_member() + activated = m.activate() + assert activated.is_active is True + + def test_is_active_false_when_removed(self): + m = make_member() + removed = m.remove() + assert removed.is_active is False + + def test_from_member_tag_classmethod(self): + m = Member.from_member_tag( + member_tag="bob.desktop", + team_name="team-abc", + device_id="DEVICE456", + ) + assert m.user_id == "bob" + assert m.machine_tag == "desktop" + assert m.member_tag == "bob.desktop" + + def test_from_member_tag_no_dot_raises(self): + with pytest.raises(ValueError, match="must contain a dot"): + Member.from_member_tag( + member_tag="nodot", + team_name="team-abc", + device_id="DEVICE000", + ) + + def test_from_member_tag_with_dot_in_machine_tag(self): + # user_id cannot contain dots per spec — first dot splits user.machine + m = Member.from_member_tag( + member_tag="alice.work.laptop", + team_name="team-abc", + device_id="DEVICE789", + ) + assert m.user_id == "alice" + assert m.machine_tag == "work.laptop" + + def test_activate_from_added(self): + m = make_member() + assert m.status == MemberStatus.ADDED + activated = m.activate() + assert activated.status == MemberStatus.ACTIVE + + def test_activate_from_active_raises(self): + m = make_member() + active = m.activate() + with pytest.raises(InvalidTransitionError): + active.activate() + + def test_activate_from_removed_raises(self): + m = make_member() + removed = m.remove() + with pytest.raises(InvalidTransitionError): + removed.activate() + + def test_remove_from_added(self): + m = make_member() + removed = m.remove() + assert removed.status == MemberStatus.REMOVED + + def test_remove_from_active(self): + m = make_member() + active = m.activate() + removed = active.remove() + assert removed.status == MemberStatus.REMOVED + + def test_remove_from_removed_raises(self): + m = make_member() + removed = m.remove() + with pytest.raises(InvalidTransitionError): + removed.remove() + + def test_member_status_enum_values(self): + assert MemberStatus.ADDED.value == "added" + assert MemberStatus.ACTIVE.value == "active" + assert MemberStatus.REMOVED.value == "removed" diff --git a/api/tests/test_domain_project.py b/api/tests/test_domain_project.py new file mode 100644 index 00000000..020b3058 --- /dev/null +++ b/api/tests/test_domain_project.py @@ -0,0 +1,95 @@ +"""Tests for the SharedProject domain model.""" +import sys +from pathlib import Path + +sys.path.insert(0, str(Path(__file__).parent.parent)) + +import pytest +from datetime import datetime, timezone +from domain.project import SharedProject, SharedProjectStatus, derive_folder_suffix + + +def make_project(**kwargs): + defaults = dict( + team_name="team-abc", + git_identity="https://github.com/user/repo.git", + folder_suffix=derive_folder_suffix("https://github.com/user/repo.git"), + ) + defaults.update(kwargs) + return SharedProject(**defaults) + + +class TestDeriveFolderSuffix: + def test_simple_path(self): + assert derive_folder_suffix("my-repo") == "my-repo" + + def test_strips_dot_git(self): + assert derive_folder_suffix("my-repo.git") == "my-repo" + + def test_replaces_slashes_with_dashes(self): + assert derive_folder_suffix("user/repo") == "user-repo" + + def test_replaces_slashes_and_strips_git(self): + assert derive_folder_suffix("user/repo.git") == "user-repo" + + def test_full_https_url(self): + result = derive_folder_suffix("https://github.com/user/repo.git") + assert "/" not in result + assert "repo" in result + + def test_multiple_path_segments(self): + result = derive_folder_suffix("org/team/repo") + assert result == "org-team-repo" + + +class TestSharedProjectModel: + def test_create_project_defaults(self): + p = make_project() + assert p.team_name == "team-abc" + assert p.git_identity == "https://github.com/user/repo.git" + assert p.status == SharedProjectStatus.SHARED + assert p.encoded_name is None + assert isinstance(p.shared_at, datetime) + assert p.shared_at.tzinfo is not None + + def test_project_is_frozen(self): + p = make_project() + with pytest.raises(Exception): + p.git_identity = "changed" + + def test_encoded_name_optional(self): + p = make_project(encoded_name="-Users-alice-repo") + assert p.encoded_name == "-Users-alice-repo" + + def test_encoded_name_none_by_default(self): + p = make_project() + assert p.encoded_name is None + + def test_folder_suffix_field(self): + p = make_project(git_identity="user/myrepo.git", folder_suffix="user-myrepo") + assert p.folder_suffix == "user-myrepo" + assert "/" not in p.folder_suffix + + def test_folder_suffix_derived_helper(self): + p = make_project( + git_identity="https://github.com/user/myrepo.git", + folder_suffix=derive_folder_suffix("https://github.com/user/myrepo.git"), + ) + assert p.folder_suffix is not None + assert "myrepo" in p.folder_suffix + assert "/" not in p.folder_suffix + + def test_remove_project(self): + p = make_project() + removed = p.remove() + assert removed.status == SharedProjectStatus.REMOVED + + def test_remove_already_removed_raises(self): + p = make_project() + removed = p.remove() + with pytest.raises(Exception): + removed.remove() + + def test_shared_project_status_enum_values(self): + assert SharedProjectStatus.SHARED.value == "shared" + assert SharedProjectStatus.REMOVED.value == "removed" diff --git a/api/tests/test_domain_subscription.py b/api/tests/test_domain_subscription.py new file mode 100644 index 00000000..9496d24e --- /dev/null +++ b/api/tests/test_domain_subscription.py @@ -0,0 +1,182 @@ +"""Tests for the Subscription domain model.""" +import sys +from pathlib import Path + +sys.path.insert(0, str(Path(__file__).parent.parent)) + +import pytest +from datetime import datetime, timezone +from domain.subscription import Subscription, SubscriptionStatus, SyncDirection +from domain.team import InvalidTransitionError + + +def make_sub(**kwargs): + defaults = dict( + member_tag="alice.macbook", + team_name="team-abc", + project_git_identity="owner/repo", + direction=SyncDirection.BOTH, + ) + defaults.update(kwargs) + return Subscription(**defaults) + + +class TestSyncDirection: + def test_enum_values(self): + assert SyncDirection.SEND.value == "send" + assert SyncDirection.RECEIVE.value == "receive" + assert SyncDirection.BOTH.value == "both" + + +class TestSubscriptionStatus: + def test_enum_values(self): + assert SubscriptionStatus.OFFERED.value == "offered" + assert SubscriptionStatus.ACCEPTED.value == "accepted" + assert SubscriptionStatus.PAUSED.value == "paused" + assert SubscriptionStatus.DECLINED.value == "declined" + + +class TestSubscriptionModel: + def test_create_defaults(self): + s = make_sub() + assert s.member_tag == "alice.macbook" + assert s.team_name == "team-abc" + assert s.project_git_identity == "owner/repo" + assert s.direction == SyncDirection.BOTH + assert s.status == SubscriptionStatus.OFFERED + assert isinstance(s.updated_at, datetime) + assert s.updated_at.tzinfo is not None + + def test_subscription_is_frozen(self): + s = make_sub() + with pytest.raises(Exception): + s.direction = SyncDirection.SEND + + # ------------------------------------------------------------------ + # accept: OFFERED → ACCEPTED + # ------------------------------------------------------------------ + + def test_accept_from_offered(self): + s = make_sub() + accepted = s.accept(SyncDirection.BOTH) + assert accepted.status == SubscriptionStatus.ACCEPTED + + def test_accept_sets_direction(self): + s = make_sub(direction=SyncDirection.BOTH) + accepted = s.accept(SyncDirection.RECEIVE) + assert accepted.direction == SyncDirection.RECEIVE + + def test_accept_from_paused_raises(self): + s = make_sub() + accepted = s.accept(SyncDirection.BOTH) + paused = accepted.pause() + with pytest.raises(InvalidTransitionError): + paused.accept(SyncDirection.BOTH) + + def test_accept_from_accepted_raises(self): + s = make_sub() + accepted = s.accept(SyncDirection.BOTH) + with pytest.raises(InvalidTransitionError): + accepted.accept(SyncDirection.BOTH) + + def test_accept_from_declined_raises(self): + s = make_sub() + declined = s.decline() + with pytest.raises(InvalidTransitionError): + declined.accept(SyncDirection.BOTH) + + # ------------------------------------------------------------------ + # pause: ACCEPTED → PAUSED + # ------------------------------------------------------------------ + + def test_pause_from_accepted(self): + s = make_sub() + accepted = s.accept(SyncDirection.BOTH) + paused = accepted.pause() + assert paused.status == SubscriptionStatus.PAUSED + + def test_pause_from_offered_raises(self): + s = make_sub() + with pytest.raises(InvalidTransitionError): + s.pause() + + def test_pause_from_paused_raises(self): + s = make_sub() + accepted = s.accept(SyncDirection.BOTH) + paused = accepted.pause() + with pytest.raises(InvalidTransitionError): + paused.pause() + + # ------------------------------------------------------------------ + # resume: PAUSED → ACCEPTED + # ------------------------------------------------------------------ + + def test_resume_from_paused(self): + s = make_sub() + paused = s.accept(SyncDirection.BOTH).pause() + resumed = paused.resume() + assert resumed.status == SubscriptionStatus.ACCEPTED + + def test_resume_from_accepted_raises(self): + s = make_sub() + accepted = s.accept(SyncDirection.BOTH) + with pytest.raises(InvalidTransitionError): + accepted.resume() + + def test_resume_from_offered_raises(self): + s = make_sub() + with pytest.raises(InvalidTransitionError): + s.resume() + + # ------------------------------------------------------------------ + # decline: any except DECLINED → DECLINED + # ------------------------------------------------------------------ + + def test_decline_from_offered(self): + s = make_sub() + declined = s.decline() + assert declined.status == SubscriptionStatus.DECLINED + + def test_decline_from_accepted(self): + s = make_sub() + declined = s.accept(SyncDirection.BOTH).decline() + assert declined.status == SubscriptionStatus.DECLINED + + def test_decline_from_paused(self): + s = make_sub() + declined = s.accept(SyncDirection.BOTH).pause().decline() + assert declined.status == SubscriptionStatus.DECLINED + + def test_decline_from_declined_raises(self): + s = make_sub() + declined = s.decline() + with pytest.raises(InvalidTransitionError): + declined.decline() + + # ------------------------------------------------------------------ + # change_direction: only when ACCEPTED + # ------------------------------------------------------------------ + + def test_change_direction_when_accepted(self): + s = make_sub(direction=SyncDirection.BOTH) + accepted = s.accept(SyncDirection.BOTH) + changed = accepted.change_direction(SyncDirection.SEND) + assert changed.direction == SyncDirection.SEND + assert changed.status == SubscriptionStatus.ACCEPTED + + def test_change_direction_when_offered_raises(self): + s = make_sub() + with pytest.raises(InvalidTransitionError): + s.change_direction(SyncDirection.SEND) + + def test_change_direction_when_paused_raises(self): + s = make_sub() + paused = s.accept(SyncDirection.BOTH).pause() + with pytest.raises(InvalidTransitionError): + paused.change_direction(SyncDirection.SEND) + + def test_change_direction_when_declined_raises(self): + s = make_sub() + declined = s.decline() + with pytest.raises(InvalidTransitionError): + declined.change_direction(SyncDirection.SEND) diff --git a/api/tests/test_domain_team.py b/api/tests/test_domain_team.py new file mode 100644 index 00000000..cc2b211f --- /dev/null +++ b/api/tests/test_domain_team.py @@ -0,0 +1,146 @@ +"""Tests for the Team domain model.""" +import sys +from pathlib import Path + +sys.path.insert(0, str(Path(__file__).parent.parent)) + +import pytest +from datetime import datetime, timezone +from domain.team import Team, TeamStatus, AuthorizationError, InvalidTransitionError +from domain.member import Member + + +def make_team(**kwargs): + defaults = dict( + name="My Team", + leader_device_id="alice.macbook", + leader_member_tag="alice.macbook", + ) + defaults.update(kwargs) + return Team(**defaults) + + +def make_member(member_tag="bob.desktop", team_name="My Team", device_id="DEVICE456", **kwargs): + user_id, machine_tag = member_tag.split(".", 1) + return Member( + member_tag=member_tag, + team_name=team_name, + device_id=device_id, + user_id=user_id, + machine_tag=machine_tag, + **kwargs, + ) + + +class TestTeamModel: + def test_create_team_defaults(self): + team = make_team() + assert team.name == "My Team" + assert team.leader_device_id == "alice.macbook" + assert team.leader_member_tag == "alice.macbook" + assert team.status == TeamStatus.ACTIVE + assert isinstance(team.created_at, datetime) + assert team.created_at.tzinfo is not None + + def test_team_is_frozen(self): + team = make_team() + with pytest.raises(Exception): + team.name = "changed" + + def test_is_leader_true(self): + team = make_team(leader_device_id="alice.macbook") + assert team.is_leader("alice.macbook") is True + + def test_is_leader_false(self): + team = make_team(leader_device_id="alice.macbook") + assert team.is_leader("bob.desktop") is False + + def test_dissolve_by_leader(self): + team = make_team() + dissolved = team.dissolve(by_device="alice.macbook") + assert dissolved.status == TeamStatus.DISSOLVED + assert dissolved.name == team.name + + def test_dissolve_by_non_leader_raises(self): + team = make_team() + with pytest.raises(AuthorizationError): + team.dissolve(by_device="bob.desktop") + + def test_dissolve_already_dissolved_raises(self): + team = make_team() + dissolved = team.dissolve(by_device="alice.macbook") + with pytest.raises(InvalidTransitionError): + dissolved.dissolve(by_device="alice.macbook") + + def test_add_member_by_leader(self): + team = make_team() + member = make_member() + returned = team.add_member(member, by_device="alice.macbook") + assert returned.member_tag == "bob.desktop" + + def test_add_member_by_non_leader_raises(self): + team = make_team() + member = make_member() + with pytest.raises(AuthorizationError): + team.add_member(member, by_device="bob.desktop") + + def test_add_member_returns_member(self): + team = make_team() + member = make_member() + result = team.add_member(member, by_device="alice.macbook") + assert isinstance(result, Member) + assert result.member_tag == member.member_tag + + def test_remove_member_by_leader(self): + team = make_team() + member = make_member() + removed = team.remove_member(member, by_device="alice.macbook") + from domain.member import MemberStatus + assert removed.status == MemberStatus.REMOVED + + def test_remove_member_by_non_leader_raises(self): + team = make_team() + member = make_member() + with pytest.raises(AuthorizationError): + team.remove_member(member, by_device="carol.laptop") + + def test_remove_member_returns_removed_member(self): + team = make_team() + member = make_member() + result = team.remove_member(member, by_device="alice.macbook") + assert isinstance(result, Member) + from domain.member import MemberStatus + assert result.status == MemberStatus.REMOVED + + def test_team_status_enum_values(self): + assert TeamStatus.ACTIVE.value == "active" + assert TeamStatus.DISSOLVED.value == "dissolved" + + + def test_add_member_on_dissolved_team_raises(self): + team = make_team() + dissolved = team.dissolve(by_device="alice.macbook") + member = make_member() + with pytest.raises(InvalidTransitionError, match="dissolved"): + dissolved.add_member(member, by_device="alice.macbook") + + def test_remove_member_on_dissolved_team_raises(self): + team = make_team() + dissolved = team.dissolve(by_device="alice.macbook") + member = make_member() + with pytest.raises(InvalidTransitionError, match="dissolved"): + dissolved.remove_member(member, by_device="alice.macbook") + + +class TestAuthorizationError: + def test_is_exception(self): + err = AuthorizationError("not allowed") + assert isinstance(err, Exception) + assert str(err) == "not allowed" + + +class TestInvalidTransitionError: + def test_is_value_error(self): + err = InvalidTransitionError("bad transition") + assert isinstance(err, ValueError) + assert str(err) == "bad transition" diff --git a/api/tests/test_folder_manager.py b/api/tests/test_folder_manager.py new file mode 100644 index 00000000..6d5ed970 --- /dev/null +++ b/api/tests/test_folder_manager.py @@ -0,0 +1,268 @@ +""" +Tests for FolderManager — ensure_outbox_folder, ensure_inbox_folder, +remove_outbox_folder, set_folder_devices, remove_device_from_team_folders, +cleanup_team_folders, cleanup_project_folders, and helper functions. +""" + +import sys +from pathlib import Path + +sys.path.insert(0, str(Path(__file__).parent.parent)) + +from unittest.mock import AsyncMock, MagicMock, call + +import pytest + +from services.syncthing.client import SyncthingClient +from services.syncthing.folder_manager import ( + FolderManager, + build_metadata_folder_id, + build_outbox_folder_id, +) + +MEMBER_TAG = "alice.laptop" +REMOTE_MEMBER_TAG = "bob.desktop" +FOLDER_SUFFIX = "abc123" +TEAM_NAME = "team-alpha" +DEVICE_ID = "AAAAAAA-BBBBBBB-CCCCCCC-DDDDDDD-EEEEEEE-FFFFFFF-GGGGGGG-HHHHHHH" +DEVICE_ID_2 = "ZZZZZZZ-YYYYYYY-XXXXXXX-WWWWWWW-VVVVVVV-UUUUUUU-TTTTTTT-SSSSSSS" + + +@pytest.fixture +def mock_client(): + client = MagicMock(spec=SyncthingClient) + client.get_config_folders = AsyncMock(return_value=[]) + client.put_config_folder = AsyncMock() + client.delete_config_folder = AsyncMock() + return client + + +@pytest.fixture +def karma_base(tmp_path): + base = tmp_path / ".claude_karma" + base.mkdir() + return base + + +@pytest.fixture +def manager(mock_client, karma_base): + return FolderManager(client=mock_client, karma_base=karma_base) + + +class TestBuildOutboxFolderId: + def test_builds_correct_id(self): + fid = build_outbox_folder_id("alice.laptop", "abc123") + assert fid == "karma-out--alice.laptop--abc123" + + def test_different_member_tag(self): + fid = build_outbox_folder_id("bob.desktop", "xyz789") + assert fid == "karma-out--bob.desktop--xyz789" + + +class TestBuildMetadataFolderId: + def test_builds_correct_id(self): + fid = build_metadata_folder_id("team-alpha") + assert fid == "karma-meta--team-alpha" + + def test_different_team(self): + fid = build_metadata_folder_id("my-team") + assert fid == "karma-meta--my-team" + + +class TestEnsureOutboxFolder: + async def test_creates_folder_when_absent(self, manager, mock_client): + mock_client.get_config_folders.return_value = [] + await manager.ensure_outbox_folder(MEMBER_TAG, FOLDER_SUFFIX) + mock_client.put_config_folder.assert_called_once() + + async def test_folder_id_is_correct(self, manager, mock_client): + mock_client.get_config_folders.return_value = [] + await manager.ensure_outbox_folder(MEMBER_TAG, FOLDER_SUFFIX) + folder_arg = mock_client.put_config_folder.call_args[0][0] + assert folder_arg["id"] == f"karma-out--{MEMBER_TAG}--{FOLDER_SUFFIX}" + + async def test_folder_type_is_sendonly(self, manager, mock_client): + mock_client.get_config_folders.return_value = [] + await manager.ensure_outbox_folder(MEMBER_TAG, FOLDER_SUFFIX) + folder_arg = mock_client.put_config_folder.call_args[0][0] + assert folder_arg["type"] == "sendonly" + + async def test_folder_path_under_karma_base(self, manager, mock_client, karma_base): + mock_client.get_config_folders.return_value = [] + await manager.ensure_outbox_folder(MEMBER_TAG, FOLDER_SUFFIX) + folder_arg = mock_client.put_config_folder.call_args[0][0] + assert folder_arg["path"].startswith(str(karma_base)) + + async def test_skips_creation_when_already_exists(self, manager, mock_client): + folder_id = build_outbox_folder_id(MEMBER_TAG, FOLDER_SUFFIX) + mock_client.get_config_folders.return_value = [{"id": folder_id}] + await manager.ensure_outbox_folder(MEMBER_TAG, FOLDER_SUFFIX) + mock_client.put_config_folder.assert_not_called() + + +class TestEnsureInboxFolder: + async def test_creates_folder_when_absent(self, manager, mock_client): + mock_client.get_config_folders.return_value = [] + await manager.ensure_inbox_folder(REMOTE_MEMBER_TAG, FOLDER_SUFFIX, DEVICE_ID) + mock_client.put_config_folder.assert_called_once() + + async def test_folder_id_matches_remote_outbox(self, manager, mock_client): + """Inbox folder ID mirrors the remote's outbox folder ID.""" + mock_client.get_config_folders.return_value = [] + await manager.ensure_inbox_folder(REMOTE_MEMBER_TAG, FOLDER_SUFFIX, DEVICE_ID) + folder_arg = mock_client.put_config_folder.call_args[0][0] + expected_id = f"karma-out--{REMOTE_MEMBER_TAG}--{FOLDER_SUFFIX}" + assert folder_arg["id"] == expected_id + + async def test_folder_type_is_receiveonly(self, manager, mock_client): + mock_client.get_config_folders.return_value = [] + await manager.ensure_inbox_folder(REMOTE_MEMBER_TAG, FOLDER_SUFFIX, DEVICE_ID) + folder_arg = mock_client.put_config_folder.call_args[0][0] + assert folder_arg["type"] == "receiveonly" + + async def test_folder_includes_remote_device(self, manager, mock_client): + mock_client.get_config_folders.return_value = [] + await manager.ensure_inbox_folder(REMOTE_MEMBER_TAG, FOLDER_SUFFIX, DEVICE_ID) + folder_arg = mock_client.put_config_folder.call_args[0][0] + device_ids = [d["deviceID"] for d in folder_arg.get("devices", [])] + assert DEVICE_ID in device_ids + + async def test_skips_when_already_exists(self, manager, mock_client): + folder_id = build_outbox_folder_id(REMOTE_MEMBER_TAG, FOLDER_SUFFIX) + mock_client.get_config_folders.return_value = [{"id": folder_id}] + await manager.ensure_inbox_folder(REMOTE_MEMBER_TAG, FOLDER_SUFFIX, DEVICE_ID) + mock_client.put_config_folder.assert_not_called() + + +class TestRemoveOutboxFolder: + async def test_deletes_folder(self, manager, mock_client): + await manager.remove_outbox_folder(MEMBER_TAG, FOLDER_SUFFIX) + expected_id = build_outbox_folder_id(MEMBER_TAG, FOLDER_SUFFIX) + mock_client.delete_config_folder.assert_called_once_with(expected_id) + + +class TestSetFolderDevices: + async def test_updates_folder_device_list(self, manager, mock_client): + folder_id = "karma-out--alice.laptop--abc" + mock_client.get_config_folders.return_value = [ + {"id": folder_id, "devices": [{"deviceID": DEVICE_ID}]} + ] + await manager.set_folder_devices(folder_id, {DEVICE_ID_2}) + folder_arg = mock_client.put_config_folder.call_args[0][0] + device_ids = [d["deviceID"] for d in folder_arg["devices"]] + assert device_ids == [DEVICE_ID_2] + + async def test_replaces_device_list_declaratively(self, manager, mock_client): + """Old devices are removed, new ones set.""" + folder_id = "karma-out--alice.laptop--abc" + mock_client.get_config_folders.return_value = [ + {"id": folder_id, "devices": [{"deviceID": DEVICE_ID}, {"deviceID": DEVICE_ID_2}]} + ] + await manager.set_folder_devices(folder_id, {DEVICE_ID}) + folder_arg = mock_client.put_config_folder.call_args[0][0] + device_ids = [d["deviceID"] for d in folder_arg["devices"]] + assert DEVICE_ID in device_ids + assert DEVICE_ID_2 not in device_ids + + async def test_noop_when_folder_not_found(self, manager, mock_client): + mock_client.get_config_folders.return_value = [] + await manager.set_folder_devices("nonexistent-folder", {DEVICE_ID}) + mock_client.put_config_folder.assert_not_called() + + +class TestRemoveDeviceFromTeamFolders: + async def test_removes_device_from_matching_folders(self, manager, mock_client): + folder_id_1 = build_outbox_folder_id("alice.laptop", FOLDER_SUFFIX) + folder_id_2 = build_outbox_folder_id("bob.desktop", FOLDER_SUFFIX) + mock_client.get_config_folders.return_value = [ + {"id": folder_id_1, "devices": [{"deviceID": DEVICE_ID}, {"deviceID": DEVICE_ID_2}]}, + {"id": folder_id_2, "devices": [{"deviceID": DEVICE_ID}]}, + ] + await manager.remove_device_from_team_folders( + folder_suffixes=[FOLDER_SUFFIX], + member_tags=["alice.laptop", "bob.desktop"], + device_id=DEVICE_ID, + ) + # Both matching folders should be updated + assert mock_client.put_config_folder.call_count == 2 + + async def test_only_touches_matching_folders(self, manager, mock_client): + """Folders with different suffix/member are not touched.""" + folder_id_match = build_outbox_folder_id("alice.laptop", FOLDER_SUFFIX) + folder_id_other = build_outbox_folder_id("alice.laptop", "other-suffix") + mock_client.get_config_folders.return_value = [ + {"id": folder_id_match, "devices": [{"deviceID": DEVICE_ID}]}, + {"id": folder_id_other, "devices": [{"deviceID": DEVICE_ID}]}, + ] + await manager.remove_device_from_team_folders( + folder_suffixes=[FOLDER_SUFFIX], + member_tags=["alice.laptop"], + device_id=DEVICE_ID, + ) + # Only the matching folder updated + assert mock_client.put_config_folder.call_count == 1 + folder_arg = mock_client.put_config_folder.call_args[0][0] + assert folder_arg["id"] == folder_id_match + + +class TestCleanupTeamFolders: + async def test_deletes_all_team_related_folders(self, manager, mock_client): + outbox_1 = build_outbox_folder_id("alice.laptop", FOLDER_SUFFIX) + outbox_2 = build_outbox_folder_id("bob.desktop", FOLDER_SUFFIX) + meta = build_metadata_folder_id(TEAM_NAME) + mock_client.get_config_folders.return_value = [ + {"id": outbox_1}, + {"id": outbox_2}, + {"id": meta}, + {"id": "karma-out--carol.pc--other"}, # different suffix, should NOT be deleted + ] + await manager.cleanup_team_folders( + folder_suffixes=[FOLDER_SUFFIX], + member_tags=["alice.laptop", "bob.desktop"], + team_name=TEAM_NAME, + ) + deleted = [c[0][0] for c in mock_client.delete_config_folder.call_args_list] + assert outbox_1 in deleted + assert outbox_2 in deleted + assert meta in deleted + assert "karma-out--carol.pc--other" not in deleted + + async def test_deletes_metadata_folder(self, manager, mock_client): + meta = build_metadata_folder_id(TEAM_NAME) + mock_client.get_config_folders.return_value = [{"id": meta}] + await manager.cleanup_team_folders( + folder_suffixes=[], + member_tags=[], + team_name=TEAM_NAME, + ) + mock_client.delete_config_folder.assert_called_with(meta) + + +class TestCleanupProjectFolders: + async def test_deletes_outbox_and_inbox_for_project(self, manager, mock_client): + outbox = build_outbox_folder_id("alice.laptop", FOLDER_SUFFIX) + remote_inbox = build_outbox_folder_id("bob.desktop", FOLDER_SUFFIX) + unrelated = build_outbox_folder_id("alice.laptop", "other") + mock_client.get_config_folders.return_value = [ + {"id": outbox}, + {"id": remote_inbox}, + {"id": unrelated}, + ] + await manager.cleanup_project_folders( + folder_suffix=FOLDER_SUFFIX, + member_tags=["alice.laptop", "bob.desktop"], + ) + deleted = [c[0][0] for c in mock_client.delete_config_folder.call_args_list] + assert outbox in deleted + assert remote_inbox in deleted + assert unrelated not in deleted + + async def test_no_deletions_when_no_matching_folders(self, manager, mock_client): + mock_client.get_config_folders.return_value = [ + {"id": "karma-out--alice.laptop--other"} + ] + await manager.cleanup_project_folders( + folder_suffix=FOLDER_SUFFIX, + member_tags=["alice.laptop"], + ) + mock_client.delete_config_folder.assert_not_called() diff --git a/api/tests/test_git_identity.py b/api/tests/test_git_identity.py new file mode 100644 index 00000000..4c82a0e6 --- /dev/null +++ b/api/tests/test_git_identity.py @@ -0,0 +1,102 @@ +"""Tests for detect_git_identity() utility.""" + +import subprocess +from unittest.mock import patch + +import pytest + +import sys +from pathlib import Path + +# Add API to path +sys.path.insert(0, str(Path(__file__).parent.parent)) + +from utils.git import detect_git_identity + + +def _mock_git_output(url: str): + """Create a mock for subprocess.run that returns the given URL.""" + return subprocess.CompletedProcess( + args=[], returncode=0, stdout=f"{url}\n", stderr="" + ) + + +def _mock_git_failure(): + return subprocess.CompletedProcess( + args=[], returncode=128, stdout="", stderr="fatal: not a git repository" + ) + + +class TestSSHUrls: + @patch("subprocess.run") + def test_standard_ssh(self, mock_run): + mock_run.return_value = _mock_git_output("git@github.com:Owner/Repo.git") + assert detect_git_identity("/some/path") == "owner/repo" + + @patch("subprocess.run") + def test_ssh_no_dot_git(self, mock_run): + mock_run.return_value = _mock_git_output("git@github.com:Owner/Repo") + assert detect_git_identity("/some/path") == "owner/repo" + + @patch("subprocess.run") + def test_ssh_gitlab(self, mock_run): + mock_run.return_value = _mock_git_output("git@gitlab.com:MyOrg/MyProject.git") + assert detect_git_identity("/some/path") == "myorg/myproject" + + @patch("subprocess.run") + def test_ssh_nested_path(self, mock_run): + mock_run.return_value = _mock_git_output("git@github.com:org/sub/repo.git") + assert detect_git_identity("/some/path") == "org/sub/repo" + + +class TestHTTPSUrls: + @patch("subprocess.run") + def test_standard_https(self, mock_run): + mock_run.return_value = _mock_git_output("https://github.com/Owner/Repo.git") + assert detect_git_identity("/some/path") == "owner/repo" + + @patch("subprocess.run") + def test_https_no_dot_git(self, mock_run): + mock_run.return_value = _mock_git_output("https://github.com/Owner/Repo") + assert detect_git_identity("/some/path") == "owner/repo" + + @patch("subprocess.run") + def test_http_url(self, mock_run): + mock_run.return_value = _mock_git_output("http://github.com/Owner/Repo.git") + assert detect_git_identity("/some/path") == "owner/repo" + + +class TestCaseNormalization: + @patch("subprocess.run") + def test_uppercase_normalized(self, mock_run): + mock_run.return_value = _mock_git_output("git@github.com:UPPERCASE/REPO.git") + assert detect_git_identity("/some/path") == "uppercase/repo" + + @patch("subprocess.run") + def test_mixed_case(self, mock_run): + mock_run.return_value = _mock_git_output("https://github.com/JayantDevkar/Claude-Karma.git") + assert detect_git_identity("/some/path") == "jayantdevkar/claude-karma" + + +class TestNonGitDirs: + @patch("subprocess.run") + def test_not_a_git_repo(self, mock_run): + mock_run.return_value = _mock_git_failure() + assert detect_git_identity("/some/path") is None + + @patch("subprocess.run") + def test_empty_output(self, mock_run): + mock_run.return_value = subprocess.CompletedProcess( + args=[], returncode=0, stdout="", stderr="" + ) + assert detect_git_identity("/some/path") is None + + @patch("subprocess.run") + def test_timeout(self, mock_run): + mock_run.side_effect = subprocess.TimeoutExpired(cmd="git", timeout=5) + assert detect_git_identity("/some/path") is None + + @patch("subprocess.run") + def test_git_not_installed(self, mock_run): + mock_run.side_effect = FileNotFoundError("git not found") + assert detect_git_identity("/some/path") is None diff --git a/api/tests/test_metadata_service.py b/api/tests/test_metadata_service.py new file mode 100644 index 00000000..f11333f0 --- /dev/null +++ b/api/tests/test_metadata_service.py @@ -0,0 +1,169 @@ +# api/tests/test_metadata_service.py +import sys +from pathlib import Path +sys.path.insert(0, str(Path(__file__).parent.parent)) + +import json +import pytest +from domain.team import Team +from domain.member import Member, MemberStatus +from domain.project import SharedProject +from domain.subscription import Subscription, SubscriptionStatus, SyncDirection +from services.sync.metadata_service import MetadataService + + +@pytest.fixture +def meta_base(tmp_path): + return tmp_path / "karma-metadata" + + +@pytest.fixture +def service(meta_base): + return MetadataService(meta_base=meta_base) + + +@pytest.fixture +def team(): + return Team(name="karma-team", leader_device_id="DEV-L", leader_member_tag="jayant.macbook") + + +@pytest.fixture +def leader(): + return Member( + member_tag="jayant.macbook", team_name="karma-team", + device_id="DEV-L", user_id="jayant", machine_tag="macbook", + status=MemberStatus.ACTIVE, + ) + + +@pytest.fixture +def member(): + return Member( + member_tag="ayush.laptop", team_name="karma-team", + device_id="DEV-A", user_id="ayush", machine_tag="laptop", + status=MemberStatus.ACTIVE, + ) + + +class TestWriteTeamState: + def test_creates_team_json(self, service, team, leader): + service.write_team_state(team, [leader]) + team_file = service._team_dir(team.name) / "team.json" + assert team_file.exists() + data = json.loads(team_file.read_text()) + assert data["name"] == "karma-team" + assert data["created_by"] == "jayant.macbook" + assert data["leader_device_id"] == "DEV-L" + + def test_creates_member_state_file(self, service, team, leader): + service.write_team_state(team, [leader]) + member_file = service._team_dir(team.name) / "members" / "jayant.macbook.json" + assert member_file.exists() + data = json.loads(member_file.read_text()) + assert data["member_tag"] == "jayant.macbook" + assert data["device_id"] == "DEV-L" + + +class TestWriteMemberState: + def test_writes_basic_fields(self, service): + service.write_member_state( + "karma-team", "ayush.laptop", + device_id="DEV-A", user_id="ayush", machine_tag="laptop", status="active", + ) + state_file = service._team_dir("karma-team") / "members" / "ayush.laptop.json" + data = json.loads(state_file.read_text()) + assert data["member_tag"] == "ayush.laptop" + assert data["device_id"] == "DEV-A" + assert data["status"] == "active" + assert "updated_at" in data + + def test_writes_projects_and_subscriptions(self, service): + service.write_member_state( + "karma-team", "ayush.laptop", + projects=[{"git_identity": "o/r", "folder_suffix": "o-r"}], + subscriptions={"o/r": {"status": "accepted", "direction": "both"}}, + ) + state_file = service._team_dir("karma-team") / "members" / "ayush.laptop.json" + data = json.loads(state_file.read_text()) + assert data["projects"][0]["git_identity"] == "o/r" + assert data["subscriptions"]["o/r"]["status"] == "accepted" + + def test_read_merge_write_preserves_existing_fields(self, service): + """Key test: basic info write followed by project write preserves both.""" + # Step 1: write basic info (as write_team_state does) + service.write_member_state( + "karma-team", "ayush.laptop", + device_id="DEV-A", user_id="ayush", machine_tag="laptop", status="active", + ) + # Step 2: write projects/subscriptions (as _publish_member_metadata does) + service.write_member_state( + "karma-team", "ayush.laptop", + projects=[{"git_identity": "o/r", "folder_suffix": "o-r"}], + subscriptions={"o/r": {"status": "accepted", "direction": "both"}}, + ) + state_file = service._team_dir("karma-team") / "members" / "ayush.laptop.json" + data = json.loads(state_file.read_text()) + # Both basic AND enriched fields must coexist + assert data["device_id"] == "DEV-A" + assert data["user_id"] == "ayush" + assert data["status"] == "active" + assert data["projects"][0]["git_identity"] == "o/r" + assert data["subscriptions"]["o/r"]["direction"] == "both" + + def test_reverse_order_also_preserves(self, service): + """Projects written first, basic info written second — both preserved.""" + service.write_member_state( + "karma-team", "ayush.laptop", + projects=[{"git_identity": "o/r", "folder_suffix": "o-r"}], + ) + service.write_member_state( + "karma-team", "ayush.laptop", + device_id="DEV-A", status="active", + ) + state_file = service._team_dir("karma-team") / "members" / "ayush.laptop.json" + data = json.loads(state_file.read_text()) + assert data["device_id"] == "DEV-A" + assert data["projects"][0]["git_identity"] == "o/r" + + def test_write_team_state_preserves_enriched_fields(self, service, team, leader): + """write_team_state() must not wipe projects/subscriptions.""" + # Pre-enrich leader's state file + service.write_member_state( + "karma-team", "jayant.macbook", + device_id="DEV-L", projects=[{"git_identity": "o/r", "folder_suffix": "o-r"}], + ) + # Now call write_team_state (which re-writes basic fields for all members) + service.write_team_state(team, [leader]) + state_file = service._team_dir("karma-team") / "members" / "jayant.macbook.json" + data = json.loads(state_file.read_text()) + assert data["device_id"] == "DEV-L" + assert data["projects"][0]["git_identity"] == "o/r" + + +class TestWriteRemovalSignal: + def test_creates_removal_file(self, service): + service.write_removal_signal("karma-team", "ayush.laptop", removed_by="jayant.macbook") + removal_file = service._team_dir("karma-team") / "removed" / "ayush.laptop.json" + assert removal_file.exists() + data = json.loads(removal_file.read_text()) + assert data["member_tag"] == "ayush.laptop" + assert data["removed_by"] == "jayant.macbook" + + +class TestReadTeamMetadata: + def test_reads_all_member_states(self, service, team, leader, member): + service.write_team_state(team, [leader, member]) + states = service.read_team_metadata("karma-team") + assert "jayant.macbook" in states + assert "ayush.laptop" in states + assert states["jayant.macbook"]["device_id"] == "DEV-L" + + def test_reads_removal_signals(self, service, team, leader): + service.write_team_state(team, [leader]) + service.write_removal_signal("karma-team", "ayush.laptop", removed_by="jayant.macbook") + states = service.read_team_metadata("karma-team") + assert states.get("__removals", {}).get("ayush.laptop") is not None + + def test_empty_team_returns_empty(self, service): + states = service.read_team_metadata("nonexistent") + assert states == {} diff --git a/api/tests/test_packaging_service.py b/api/tests/test_packaging_service.py new file mode 100644 index 00000000..dbaf868f --- /dev/null +++ b/api/tests/test_packaging_service.py @@ -0,0 +1,255 @@ +"""Tests for PackagingService.resolve_packagable_projects().""" +import sys +from pathlib import Path + +sys.path.insert(0, str(Path(__file__).parent.parent)) + +import sqlite3 + +import pytest + +from db.schema import ensure_schema +from domain.member import Member +from domain.project import SharedProject +from domain.subscription import Subscription, SubscriptionStatus, SyncDirection +from domain.team import Team +from repositories.member_repo import MemberRepository +from repositories.project_repo import ProjectRepository +from repositories.subscription_repo import SubscriptionRepository +from repositories.team_repo import TeamRepository +from services.sync.packaging_service import PackagingService + + +@pytest.fixture +def conn(): + c = sqlite3.connect(":memory:") + c.row_factory = sqlite3.Row + c.execute("PRAGMA foreign_keys=ON") + ensure_schema(c) + return c + + +@pytest.fixture +def setup(conn): + """Pre-populate: team 'alpha', member 'jay.mac1', project 'org/repo' (shared).""" + TeamRepository().save(conn, Team( + name="alpha", leader_device_id="DEV1", leader_member_tag="jay.mac1", + )) + MemberRepository().save(conn, Member( + member_tag="jay.mac1", team_name="alpha", + device_id="DEV1", user_id="jay", machine_tag="mac1", + )) + ProjectRepository().save(conn, SharedProject( + team_name="alpha", git_identity="org/repo", + encoded_name="-Users-jay-repo", folder_suffix="org-repo", + )) + return conn + + +class TestResolvePackagableProjects: + """Tests for PackagingService.resolve_packagable_projects.""" + + def test_returns_accepted_send_subscription(self, setup): + """Accepted subscription with direction=send should be included.""" + conn = setup + sub = Subscription( + member_tag="jay.mac1", team_name="alpha", + project_git_identity="org/repo", + ).accept(SyncDirection.SEND) + SubscriptionRepository().save(conn, sub) + + svc = PackagingService(member_tag="jay.mac1") + results = svc.resolve_packagable_projects(conn) + + assert len(results) == 1 + assert results[0]["team_name"] == "alpha" + assert results[0]["git_identity"] == "org/repo" + assert results[0]["encoded_name"] == "-Users-jay-repo" + assert results[0]["folder_suffix"] == "org-repo" + + def test_returns_accepted_both_subscription(self, setup): + """Accepted subscription with direction=both should be included.""" + conn = setup + sub = Subscription( + member_tag="jay.mac1", team_name="alpha", + project_git_identity="org/repo", + ).accept(SyncDirection.BOTH) + SubscriptionRepository().save(conn, sub) + + svc = PackagingService(member_tag="jay.mac1") + results = svc.resolve_packagable_projects(conn) + + assert len(results) == 1 + assert results[0]["team_name"] == "alpha" + + def test_skips_receive_only_subscription(self, setup): + """Accepted subscription with direction=receive should NOT be included.""" + conn = setup + sub = Subscription( + member_tag="jay.mac1", team_name="alpha", + project_git_identity="org/repo", + ).accept(SyncDirection.RECEIVE) + SubscriptionRepository().save(conn, sub) + + svc = PackagingService(member_tag="jay.mac1") + results = svc.resolve_packagable_projects(conn) + + assert len(results) == 0 + + def test_skips_offered_subscription(self, setup): + """Offered (not yet accepted) subscription should NOT be included.""" + conn = setup + sub = Subscription( + member_tag="jay.mac1", team_name="alpha", + project_git_identity="org/repo", + ) + SubscriptionRepository().save(conn, sub) + + svc = PackagingService(member_tag="jay.mac1") + results = svc.resolve_packagable_projects(conn) + + assert len(results) == 0 + + def test_skips_declined_subscription(self, setup): + """Declined subscription should NOT be included.""" + conn = setup + sub = Subscription( + member_tag="jay.mac1", team_name="alpha", + project_git_identity="org/repo", + ).accept(SyncDirection.BOTH).decline() + SubscriptionRepository().save(conn, sub) + + svc = PackagingService(member_tag="jay.mac1") + results = svc.resolve_packagable_projects(conn) + + assert len(results) == 0 + + def test_skips_removed_project(self, setup): + """Accepted sub but project status=removed should NOT be included.""" + conn = setup + # Remove the project + proj = ProjectRepository().get(conn, "alpha", "org/repo") + ProjectRepository().save(conn, proj.remove()) + + sub = Subscription( + member_tag="jay.mac1", team_name="alpha", + project_git_identity="org/repo", + ).accept(SyncDirection.BOTH) + SubscriptionRepository().save(conn, sub) + + svc = PackagingService(member_tag="jay.mac1") + results = svc.resolve_packagable_projects(conn) + + assert len(results) == 0 + + def test_filters_by_team_name(self, setup): + """When team_name param is given, only that team's projects are returned.""" + conn = setup + # Add a second team + project + TeamRepository().save(conn, Team( + name="beta", leader_device_id="DEV1", leader_member_tag="jay.mac1", + )) + MemberRepository().save(conn, Member( + member_tag="jay.mac1", team_name="beta", + device_id="DEV1", user_id="jay", machine_tag="mac1", + )) + ProjectRepository().save(conn, SharedProject( + team_name="beta", git_identity="org/repo2", + encoded_name="-Users-jay-repo2", folder_suffix="org-repo2", + )) + + # Accept subs for both teams + for tn, gi in [("alpha", "org/repo"), ("beta", "org/repo2")]: + sub = Subscription( + member_tag="jay.mac1", team_name=tn, project_git_identity=gi, + ).accept(SyncDirection.BOTH) + SubscriptionRepository().save(conn, sub) + + svc = PackagingService(member_tag="jay.mac1") + + # Filter to alpha only + results = svc.resolve_packagable_projects(conn, team_name="alpha") + assert len(results) == 1 + assert results[0]["team_name"] == "alpha" + + # Filter to beta only + results = svc.resolve_packagable_projects(conn, team_name="beta") + assert len(results) == 1 + assert results[0]["team_name"] == "beta" + + def test_filters_by_git_identity(self, setup): + """When git_identity param is given, only matching projects are returned.""" + conn = setup + # Add a second project to the same team + ProjectRepository().save(conn, SharedProject( + team_name="alpha", git_identity="org/other", + encoded_name="-Users-jay-other", folder_suffix="org-other", + )) + for gi in ["org/repo", "org/other"]: + sub = Subscription( + member_tag="jay.mac1", team_name="alpha", project_git_identity=gi, + ).accept(SyncDirection.BOTH) + SubscriptionRepository().save(conn, sub) + + svc = PackagingService(member_tag="jay.mac1") + results = svc.resolve_packagable_projects(conn, git_identity="org/other") + + assert len(results) == 1 + assert results[0]["git_identity"] == "org/other" + + def test_dedup_same_project_two_teams(self, setup): + """Same project in two teams produces two entries (different dedup keys).""" + conn = setup + # Add beta team with the SAME git_identity + TeamRepository().save(conn, Team( + name="beta", leader_device_id="DEV1", leader_member_tag="jay.mac1", + )) + MemberRepository().save(conn, Member( + member_tag="jay.mac1", team_name="beta", + device_id="DEV1", user_id="jay", machine_tag="mac1", + )) + ProjectRepository().save(conn, SharedProject( + team_name="beta", git_identity="org/repo", + encoded_name="-Users-jay-repo", folder_suffix="org-repo", + )) + + # Accept subs for both teams + for tn in ["alpha", "beta"]: + sub = Subscription( + member_tag="jay.mac1", team_name=tn, + project_git_identity="org/repo", + ).accept(SyncDirection.BOTH) + SubscriptionRepository().save(conn, sub) + + svc = PackagingService(member_tag="jay.mac1") + results = svc.resolve_packagable_projects(conn) + + assert len(results) == 2 + team_names = {r["team_name"] for r in results} + assert team_names == {"alpha", "beta"} + + def test_dedup_same_encoded_same_team(self, setup): + """Multiple subs for same (encoded_name, team_name) should be deduped to one entry.""" + conn = setup + # Create two projects in same team with same encoded_name but different git_identity + ProjectRepository().save(conn, SharedProject( + team_name="alpha", git_identity="org/repo-fork", + encoded_name="-Users-jay-repo", folder_suffix="org-repo-fork", + )) + for gi in ["org/repo", "org/repo-fork"]: + sub = Subscription( + member_tag="jay.mac1", team_name="alpha", project_git_identity=gi, + ).accept(SyncDirection.SEND) + SubscriptionRepository().save(conn, sub) + + svc = PackagingService(member_tag="jay.mac1") + results = svc.resolve_packagable_projects(conn) + + # Both share encoded_name "-Users-jay-repo" + team "alpha" → dedup to 1 + assert len(results) == 1 + + def test_empty_when_no_subscriptions(self, setup): + """No subscriptions at all returns empty list.""" + svc = PackagingService(member_tag="jay.mac1") + results = svc.resolve_packagable_projects(setup) + assert results == [] diff --git a/api/tests/test_pairing_service.py b/api/tests/test_pairing_service.py new file mode 100644 index 00000000..86ec6903 --- /dev/null +++ b/api/tests/test_pairing_service.py @@ -0,0 +1,252 @@ +""" +Tests for PairingService — permanent, deterministic pairing codes using base64url. +Backwards-compatible with legacy base32 codes. +""" + +import sys +from pathlib import Path + +sys.path.insert(0, str(Path(__file__).parent.parent)) + +import pytest + +from services.sync.pairing_service import PairingInfo, PairingService + + +@pytest.fixture +def service(): + return PairingService() + + +MEMBER_TAG = "alice.laptop" +DEVICE_ID = "AAAAAAA-BBBBBBB-CCCCCCC-DDDDDDD-EEEEEEE-FFFFFFF-GGGGGGG-HHHHHHH" + + +class TestGenerateCode: + def test_returns_string(self, service): + code = service.generate_code(MEMBER_TAG, DEVICE_ID) + assert isinstance(code, str) + + def test_code_contains_dashes(self, service): + code = service.generate_code(MEMBER_TAG, DEVICE_ID) + assert "-" in code + + def test_code_is_base64url_chars(self, service): + code = service.generate_code(MEMBER_TAG, DEVICE_ID) + # All non-dash chars should be base64url-safe + for part in code.split("-"): + assert all(c.isalnum() or c in ("_", "-") for c in part) + + def test_code_blocks_are_1_to_6_chars(self, service): + code = service.generate_code(MEMBER_TAG, DEVICE_ID) + for part in code.split("-"): + assert 1 <= len(part) <= 6 + + def test_deterministic_same_input(self, service): + code1 = service.generate_code(MEMBER_TAG, DEVICE_ID) + code2 = service.generate_code(MEMBER_TAG, DEVICE_ID) + assert code1 == code2 + + def test_different_member_tag_different_code(self, service): + code1 = service.generate_code("alice.laptop", DEVICE_ID) + code2 = service.generate_code("bob.desktop", DEVICE_ID) + assert code1 != code2 + + def test_different_device_id_different_code(self, service): + device2 = "ZZZZZZZ-YYYYYYY-XXXXXXX-WWWWWWW-VVVVVVV-UUUUUUU-TTTTTTT-SSSSSSS" + code1 = service.generate_code(MEMBER_TAG, DEVICE_ID) + code2 = service.generate_code(MEMBER_TAG, device2) + assert code1 != code2 + + def test_code_matches_expected_format(self, service): + """Code should look like amF5LW-1hY2Jv (groups of up to 6 separated by dashes).""" + code = service.generate_code(MEMBER_TAG, DEVICE_ID) + parts = code.split("-") + assert len(parts) >= 2 # At least 2 groups + for part in parts: + assert 1 <= len(part) <= 6 + assert all(c.isalnum() or c in ("_",) for c in part) + + +class TestValidateCode: + def test_roundtrip_member_tag(self, service): + code = service.generate_code(MEMBER_TAG, DEVICE_ID) + info = service.validate_code(code) + assert info.member_tag == MEMBER_TAG + + def test_roundtrip_device_id(self, service): + code = service.generate_code(MEMBER_TAG, DEVICE_ID) + info = service.validate_code(code) + assert info.device_id == DEVICE_ID + + def test_returns_pairing_info_model(self, service): + code = service.generate_code(MEMBER_TAG, DEVICE_ID) + info = service.validate_code(code) + assert isinstance(info, PairingInfo) + + def test_invalid_code_raises_value_error(self, service): + with pytest.raises(ValueError): + service.validate_code("INVALID-CODE-HERE") + + def test_empty_code_raises_value_error(self, service): + with pytest.raises(ValueError): + service.validate_code("") + + def test_whitespace_tolerant_validation(self, service): + """Codes should decode successfully with extra spaces.""" + code = service.generate_code(MEMBER_TAG, DEVICE_ID) + info = service.validate_code(f" {code} ") + assert info.member_tag == MEMBER_TAG + assert info.device_id == DEVICE_ID + + def test_legacy_base32_code_still_works(self, service): + """Old base32 codes (all uppercase) should still decode.""" + import base64 as b64 + payload = f"{MEMBER_TAG}:{DEVICE_ID}" + old_encoded = b64.b32encode(payload.encode()).decode().rstrip("=") + old_blocks = [old_encoded[i:i+4] for i in range(0, len(old_encoded), 4)] + old_code = "-".join(old_blocks) + info = service.validate_code(old_code) + assert info.member_tag == MEMBER_TAG + assert info.device_id == DEVICE_ID + + def test_different_members_roundtrip(self, service): + members = [ + ("alice.laptop", "AAAAAAA-BBBBBBB-CCCCCCC-DDDDDDD-EEEEEEE-FFFFFFF-GGGGGGG-HHHHHHH"), + ("bob.desktop", "ZZZZZZZ-YYYYYYY-XXXXXXX-WWWWWWW-VVVVVVV-UUUUUUU-TTTTTTT-SSSSSSS"), + ("carol.server", "1111111-2222222-3333333-4444444-5555555-6666666-7777777-8888888"), + ] + for member_tag, device_id in members: + code = service.generate_code(member_tag, device_id) + info = service.validate_code(code) + assert info.member_tag == member_tag + assert info.device_id == device_id + + +class TestMemberGeneratesLeaderDecodes: + """End-to-end: member generates code on their machine, leader decodes on theirs. + + This simulates the real v4 flow: + 1. Member runs `GET /sync/pairing/code` → gets their pairing code + 2. Member shares code out-of-band (Slack, text, etc.) + 3. Leader pastes code into `POST /sync/teams/{name}/members` → decoded to PairingInfo + 4. Leader's TeamService uses PairingInfo to add the member + """ + + def test_member_code_decoded_by_separate_service_instance(self): + """Simulates member and leader having separate PairingService instances.""" + member_svc = PairingService() # member's machine + leader_svc = PairingService() # leader's machine + + member_tag = "ayush.work-laptop" + device_id = "VRE7WLU-CXIVLS5-ARODGO7-22PNRQ3-7AAQ3ET-5CHXGA4-T5FKVKU-UM5QLQW" + + # Member generates + code = member_svc.generate_code(member_tag, device_id) + + # Leader decodes + info = leader_svc.validate_code(code) + assert info.member_tag == member_tag + assert info.device_id == device_id + + def test_verbose_hostname_member_tag(self): + """Real-world case: auto-derived hostname creates long member_tag.""" + svc = PairingService() + member_tag = "jay-macbook.jayants-macbook-pro-local" + device_id = "VRE7WLU-CXIVLS5-ARODGO7-22PNRQ3-7AAQ3ET-5CHXGA4-T5FKVKU-UM5QLQW" + + code = svc.generate_code(member_tag, device_id) + info = svc.validate_code(code) + + assert info.member_tag == member_tag + assert info.device_id == device_id + # Code should be manageable size (< 200 chars with base64url) + assert len(code) < 200, f"Pairing code too long: {len(code)} chars" + + def test_code_survives_copy_paste_artifacts(self): + """Code should decode even with trailing whitespace or newlines from paste.""" + svc = PairingService() + code = svc.generate_code("alice.laptop", "MFZWI3D-BONSGYC-YLTMRWG-C43ENR5-QXGZDMM-FZWI3DP-BONSGYC-YLTMRWA") + + # Simulate sloppy paste with whitespace/newlines + sloppy = f"\n {code} \n" + info = svc.validate_code(sloppy) + assert info.member_tag == "alice.laptop" + + def test_multiple_members_same_team(self): + """Leader can decode codes from multiple different members.""" + leader_svc = PairingService() + + members = [ + ("alice.laptop", "MFZWI3D-BONSGYC-YLTMRWG-C43ENR5-QXGZDMM-FZWI3DP-BONSGYC-YLTMRWA"), + ("bob.desktop", "VRE7WLU-CXIVLS5-ARODGO7-22PNRQ3-7AAQ3ET-5CHXGA4-T5FKVKU-UM5QLQW"), + ("carol.server-rack-01", "XYZAAAA-BBBCCCC-DDDEEEE-FFFGGGG-HHHIIII-JJJKKKK-LLLMMMM-NNNOOOO"), + ] + + for member_tag, device_id in members: + member_svc = PairingService() # each member has own instance + code = member_svc.generate_code(member_tag, device_id) + + # Leader decodes each + info = leader_svc.validate_code(code) + assert info.member_tag == member_tag + assert info.device_id == device_id + + def test_member_tag_with_special_characters(self): + """Member tags derived from hostnames may have dashes and dots.""" + svc = PairingService() + member_tag = "dev-user.my-machine-name" + device_id = "ABCDEFG-HIJKLMN-OPQRSTU-VWXYZ23-4567ABC-DEFGHIJ-KLMNOPQ-RSTUVWX" + + code = svc.generate_code(member_tag, device_id) + info = svc.validate_code(code) + assert info.member_tag == member_tag + assert info.device_id == device_id + + def test_same_member_different_teams_same_code(self): + """A member's pairing code is permanent — works for any team.""" + svc = PairingService() + member_tag = "alice.laptop" + device_id = "MFZWI3D-BONSGYC-YLTMRWG-C43ENR5-QXGZDMM-FZWI3DP-BONSGYC-YLTMRWA" + + code1 = svc.generate_code(member_tag, device_id) + code2 = svc.generate_code(member_tag, device_id) + + # Deterministic — same code every time (permanent, not per-team) + assert code1 == code2 + + # Leader of team A and leader of team B both decode the same identity + info = svc.validate_code(code1) + assert info.member_tag == member_tag + assert info.device_id == device_id + + def test_legacy_v1_code_from_member_decoded_by_leader(self): + """Member who generated a v1 (base32) code can still be added by a leader.""" + import base64 as b64 + + member_tag = "old-user.old-machine" + device_id = "MFZWI3D-BONSGYC-YLTMRWG-C43ENR5-QXGZDMM-FZWI3DP-BONSGYC-YLTMRWA" + + # Simulate old v1 code generation (base32, 4-char blocks) + payload = f"{member_tag}:{device_id}" + encoded = b64.b32encode(payload.encode()).decode().rstrip("=") + blocks = [encoded[i:i+4] for i in range(0, len(encoded), 4)] + v1_code = "-".join(blocks) + + # Leader with current service can still decode it + leader_svc = PairingService() + info = leader_svc.validate_code(v1_code) + assert info.member_tag == member_tag + assert info.device_id == device_id + + +class TestPairingInfo: + def test_is_pydantic_model(self): + info = PairingInfo(member_tag="alice.laptop", device_id="DEV-123") + assert info.member_tag == "alice.laptop" + assert info.device_id == "DEV-123" + + def test_immutable(self): + info = PairingInfo(member_tag="alice.laptop", device_id="DEV-123") + with pytest.raises(Exception): + info.member_tag = "modified" diff --git a/api/tests/test_pending_folder_scan.py b/api/tests/test_pending_folder_scan.py new file mode 100644 index 00000000..6f0c1725 --- /dev/null +++ b/api/tests/test_pending_folder_scan.py @@ -0,0 +1,104 @@ +"""Tests for pending folder scan in phase_team_discovery.""" +import pytest +from unittest.mock import AsyncMock, MagicMock, patch + +from services.sync.reconciliation_service import ReconciliationService +from services.sync.metadata_service import MetadataService + + +@pytest.fixture +def meta_base(tmp_path): + base = tmp_path / "metadata-folders" + base.mkdir() + return base + + +@pytest.fixture +def metadata(meta_base): + return MetadataService(meta_base) + + +@pytest.fixture +def syncthing_client(): + client = AsyncMock() + client.get_pending_folders = AsyncMock(return_value={ + "karma-meta--new-team": { + "offeredBy": { + "DEVICE-BOB": {"time": "2026-03-20T00:00:00Z", "label": "karma-meta--new-team"} + } + } + }) + return client + + +@pytest.fixture +def reconciliation(metadata, syncthing_client): + folders = AsyncMock() + # No configured folders + folders.get_configured_folders = AsyncMock(return_value=[]) + folders._client = syncthing_client + return ReconciliationService( + teams=MagicMock(), + members=MagicMock(), + projects=MagicMock(), + subs=MagicMock(), + events=MagicMock(), + devices=AsyncMock(), + folders=folders, + metadata=metadata, + my_member_tag="alice.mac-mini", + my_device_id="DEVICE-ALICE", + ) + + +@pytest.mark.asyncio +async def test_phase_team_discovery_accepts_pending_metadata_folders(reconciliation, syncthing_client): + """phase_team_discovery should auto-accept pending karma-meta--* folders.""" + reconciliation.teams.get = MagicMock(return_value=None) + + conn = MagicMock() + with patch("services.sync.reconciliation_service.ReconciliationService.phase_team_discovery", + wraps=reconciliation.phase_team_discovery): + await reconciliation.phase_team_discovery(conn) + + # Should have tried to accept the pending folder + syncthing_client.put_config_folder.assert_called_once() + call_args = syncthing_client.put_config_folder.call_args[0][0] + assert call_args["id"] == "karma-meta--new-team" + + # Should have dismissed the pending folder after accepting + syncthing_client.dismiss_pending_folder.assert_called_once_with( + "karma-meta--new-team", "DEVICE-BOB" + ) + + +@pytest.mark.asyncio +async def test_phase_team_discovery_skips_already_configured(reconciliation, syncthing_client): + """phase_team_discovery should NOT re-accept a folder already in Syncthing config.""" + # Folder already configured + reconciliation.folders.get_configured_folders = AsyncMock(return_value=[ + {"id": "karma-meta--new-team", "path": "/tmp/meta"} + ]) + reconciliation.teams.get = MagicMock(return_value=MagicMock()) # Team exists + + conn = MagicMock() + await reconciliation.phase_team_discovery(conn) + + # Should NOT have tried to accept since it's already configured + syncthing_client.put_config_folder.assert_not_called() + + +@pytest.mark.asyncio +async def test_phase_team_discovery_skips_non_meta_pending(reconciliation, syncthing_client): + """phase_team_discovery should ignore non-karma-meta pending folders.""" + syncthing_client.get_pending_folders = AsyncMock(return_value={ + "karma-out--bob.macbook--some-project": { + "offeredBy": {"DEVICE-BOB": {"time": "2026-03-20T00:00:00Z"}} + } + }) + + reconciliation.teams.get = MagicMock(return_value=None) + conn = MagicMock() + await reconciliation.phase_team_discovery(conn) + + syncthing_client.put_config_folder.assert_not_called() diff --git a/api/tests/test_phase3_folder_recovery.py b/api/tests/test_phase3_folder_recovery.py new file mode 100644 index 00000000..92e7090a --- /dev/null +++ b/api/tests/test_phase3_folder_recovery.py @@ -0,0 +1,291 @@ +"""Tests for Phase 3 folder existence recovery. + +When a folder is accidentally deleted (e.g., by a cross-team cleanup bug), +Phase 3 should re-create outbox folders for members with ACCEPTED send|both +subscriptions before attempting to set device lists. +""" +import sys +from pathlib import Path +sys.path.insert(0, str(Path(__file__).parent.parent)) + +import sqlite3 +import pytest +from unittest.mock import MagicMock, AsyncMock + +from db.schema import ensure_schema +from domain.team import Team +from domain.member import Member, MemberStatus +from domain.project import SharedProject, SharedProjectStatus, derive_folder_suffix +from domain.subscription import Subscription, SubscriptionStatus, SyncDirection +from repositories.team_repo import TeamRepository +from repositories.member_repo import MemberRepository +from repositories.project_repo import ProjectRepository +from repositories.subscription_repo import SubscriptionRepository +from repositories.event_repo import EventRepository +from services.sync.reconciliation_service import ReconciliationService + + +MY_TAG = "me.laptop" +MY_DEVICE = "DEV-ME" +PEER_TAG = "peer.desktop" +PEER_DEVICE = "DEV-PEER" +LEADER_TAG = "leader.server" +LEADER_DEVICE = "DEV-LEADER" +TEAM = "alpha" +GIT_ID = "owner/repo" +SUFFIX = derive_folder_suffix(GIT_ID) # "owner-repo" + + +# --------------------------------------------------------------------------- +# Fixtures +# --------------------------------------------------------------------------- + + +@pytest.fixture +def conn(): + c = sqlite3.connect(":memory:") + c.row_factory = sqlite3.Row + c.execute("PRAGMA foreign_keys=ON") + ensure_schema(c) + return c + + +@pytest.fixture +def mock_devices(): + m = MagicMock() + m.ensure_paired = AsyncMock() + m.unpair = AsyncMock() + return m + + +@pytest.fixture +def mock_folders(): + m = MagicMock() + m.set_folder_devices = AsyncMock() + m.cleanup_team_folders = AsyncMock() + m.ensure_outbox_folder = AsyncMock() + m.get_configured_folders = AsyncMock(return_value=[]) + return m + + +@pytest.fixture +def mock_metadata(): + m = MagicMock() + m.read_team_metadata = MagicMock(return_value={}) + return m + + +def make_service(mock_metadata, mock_devices, mock_folders, my_tag=MY_TAG): + return ReconciliationService( + teams=TeamRepository(), + members=MemberRepository(), + projects=ProjectRepository(), + subs=SubscriptionRepository(), + events=EventRepository(), + devices=mock_devices, + folders=mock_folders, + metadata=mock_metadata, + my_member_tag=my_tag, + ) + + +def seed_team(conn, name=TEAM, leader_tag=LEADER_TAG, leader_device=LEADER_DEVICE): + team = Team(name=name, leader_device_id=leader_device, leader_member_tag=leader_tag) + TeamRepository().save(conn, team) + return team + + +def seed_member(conn, member_tag, team_name=TEAM, device_id=None, status=MemberStatus.ACTIVE): + device_id = device_id or f"DEV-{member_tag}" + m = Member.from_member_tag( + member_tag=member_tag, + team_name=team_name, + device_id=device_id, + status=MemberStatus.ADDED, + ) + if status == MemberStatus.ACTIVE: + m = m.activate() + MemberRepository().save(conn, m) + return m + + +def seed_project(conn, git_identity=GIT_ID, team_name=TEAM, status=SharedProjectStatus.SHARED): + suffix = derive_folder_suffix(git_identity) + p = SharedProject( + team_name=team_name, + git_identity=git_identity, + folder_suffix=suffix, + status=status, + ) + ProjectRepository().save(conn, p) + return p + + +def seed_subscription(conn, member_tag, git_identity=GIT_ID, team_name=TEAM, + status=SubscriptionStatus.ACCEPTED, direction=SyncDirection.BOTH): + sub = Subscription( + member_tag=member_tag, + team_name=team_name, + project_git_identity=git_identity, + status=status, + direction=direction, + ) + SubscriptionRepository().save(conn, sub) + return sub + + +# --------------------------------------------------------------------------- +# Tests +# --------------------------------------------------------------------------- + + +class TestPhase3FolderRecovery: + """Phase 3 should ensure outbox folders exist before setting device lists.""" + + @pytest.mark.asyncio + async def test_ensure_outbox_called_for_accepted_both_sub( + self, conn, mock_metadata, mock_devices, mock_folders + ): + """Active member with ACCEPTED/BOTH subscription triggers ensure_outbox_folder.""" + team = seed_team(conn) + seed_member(conn, PEER_TAG, device_id=PEER_DEVICE) + seed_project(conn) + seed_subscription(conn, PEER_TAG, direction=SyncDirection.BOTH) + + service = make_service(mock_metadata, mock_devices, mock_folders) + await service.phase_device_lists(conn, team) + + mock_folders.ensure_outbox_folder.assert_any_call(PEER_TAG, SUFFIX) + + @pytest.mark.asyncio + async def test_ensure_outbox_called_for_accepted_send_sub( + self, conn, mock_metadata, mock_devices, mock_folders + ): + """Active member with ACCEPTED/SEND subscription triggers ensure_outbox_folder.""" + team = seed_team(conn) + seed_member(conn, PEER_TAG, device_id=PEER_DEVICE) + seed_project(conn) + seed_subscription(conn, PEER_TAG, direction=SyncDirection.SEND) + + service = make_service(mock_metadata, mock_devices, mock_folders) + await service.phase_device_lists(conn, team) + + mock_folders.ensure_outbox_folder.assert_any_call(PEER_TAG, SUFFIX) + + @pytest.mark.asyncio + async def test_ensure_outbox_not_called_for_receive_only( + self, conn, mock_metadata, mock_devices, mock_folders + ): + """RECEIVE-only subscription does NOT trigger ensure_outbox_folder.""" + team = seed_team(conn) + seed_member(conn, PEER_TAG, device_id=PEER_DEVICE) + seed_project(conn) + seed_subscription(conn, PEER_TAG, direction=SyncDirection.RECEIVE) + + service = make_service(mock_metadata, mock_devices, mock_folders) + await service.phase_device_lists(conn, team) + + mock_folders.ensure_outbox_folder.assert_not_called() + + @pytest.mark.asyncio + async def test_ensure_outbox_not_called_for_inactive_member( + self, conn, mock_metadata, mock_devices, mock_folders + ): + """ADDED (not active) member does NOT trigger ensure_outbox_folder.""" + team = seed_team(conn) + m = Member.from_member_tag( + member_tag=PEER_TAG, team_name=TEAM, device_id=PEER_DEVICE, + status=MemberStatus.ADDED, + ) + MemberRepository().save(conn, m) + seed_project(conn) + seed_subscription(conn, PEER_TAG, direction=SyncDirection.BOTH) + + service = make_service(mock_metadata, mock_devices, mock_folders) + await service.phase_device_lists(conn, team) + + mock_folders.ensure_outbox_folder.assert_not_called() + + @pytest.mark.asyncio + async def test_ensure_outbox_skips_other_team_subs( + self, conn, mock_metadata, mock_devices, mock_folders + ): + """Subscriptions from another team are NOT recovered in this team's phase.""" + team_a = seed_team(conn, name="team-a") + team_b = seed_team(conn, name="team-b", leader_tag="lb.srv", leader_device="DEV-LB") + + # Member active in both teams + seed_member(conn, PEER_TAG, team_name="team-a", device_id=PEER_DEVICE) + seed_member(conn, PEER_TAG, team_name="team-b", device_id=PEER_DEVICE) + + # Same git identity shared in both teams (same folder_suffix) + seed_project(conn, team_name="team-a") + seed_project(conn, team_name="team-b") + + # ACCEPTED/BOTH in both teams + seed_subscription(conn, PEER_TAG, team_name="team-a", direction=SyncDirection.BOTH) + seed_subscription(conn, PEER_TAG, team_name="team-b", direction=SyncDirection.BOTH) + + service = make_service(mock_metadata, mock_devices, mock_folders) + + # Run phase_device_lists for team-a only + await service.phase_device_lists(conn, team_a) + + # ensure_outbox_folder should be called only once — for team-a's sub + # (list_accepted_for_suffix returns subs from BOTH teams via JOIN, + # but the team_name filter ensures only team-a's sub triggers recovery) + calls = mock_folders.ensure_outbox_folder.call_args_list + assert len(calls) == 1 + assert calls[0].args == (PEER_TAG, SUFFIX) + + @pytest.mark.asyncio + async def test_ensure_outbox_called_before_set_folder_devices( + self, conn, mock_metadata, mock_devices, mock_folders + ): + """ensure_outbox_folder is called BEFORE set_folder_devices for the same project.""" + team = seed_team(conn) + seed_member(conn, PEER_TAG, device_id=PEER_DEVICE) + seed_project(conn) + seed_subscription(conn, PEER_TAG, direction=SyncDirection.BOTH) + + # Track call order + call_order = [] + original_ensure = mock_folders.ensure_outbox_folder + original_set = mock_folders.set_folder_devices + + async def track_ensure(*args, **kwargs): + call_order.append("ensure_outbox_folder") + return await original_ensure(*args, **kwargs) + + async def track_set(*args, **kwargs): + call_order.append("set_folder_devices") + return await original_set(*args, **kwargs) + + mock_folders.ensure_outbox_folder = AsyncMock(side_effect=track_ensure) + mock_folders.set_folder_devices = AsyncMock(side_effect=track_set) + + service = make_service(mock_metadata, mock_devices, mock_folders) + await service.phase_device_lists(conn, team) + + # ensure must come before set + ensure_idx = call_order.index("ensure_outbox_folder") + set_idx = call_order.index("set_folder_devices") + assert ensure_idx < set_idx, ( + f"ensure_outbox_folder (idx={ensure_idx}) must be called before " + f"set_folder_devices (idx={set_idx}). Order: {call_order}" + ) + + @pytest.mark.asyncio + async def test_ensure_outbox_not_called_for_removed_project( + self, conn, mock_metadata, mock_devices, mock_folders + ): + """REMOVED projects are skipped entirely — no ensure_outbox_folder call.""" + team = seed_team(conn) + seed_member(conn, PEER_TAG, device_id=PEER_DEVICE) + seed_project(conn, status=SharedProjectStatus.REMOVED) + seed_subscription(conn, PEER_TAG, direction=SyncDirection.BOTH) + + service = make_service(mock_metadata, mock_devices, mock_folders) + await service.phase_device_lists(conn, team) + + mock_folders.ensure_outbox_folder.assert_not_called() diff --git a/api/tests/test_phase4.py b/api/tests/test_phase4.py deleted file mode 100644 index 7928fdf1..00000000 --- a/api/tests/test_phase4.py +++ /dev/null @@ -1,347 +0,0 @@ -""" -Tests for Phase 4 optimizations: Async and structural improvements. - -Phase 4 focuses on: -- Early date filtering -- Parallel subagent processing -- Batch session loading -- Async file I/O -""" - -import importlib.util -import json -from datetime import datetime, timedelta, timezone -from pathlib import Path - -import pytest - -from models import Project -from models.batch_loader import BatchSessionLoader, load_sessions_metadata_batch - -# ============================================================================= -# Fixtures for Phase 4 tests -# ============================================================================= - - -@pytest.fixture -def multi_session_project(temp_claude_dir: Path) -> tuple[Path, list[str]]: - """Create a project with multiple sessions at different times.""" - project_dir = temp_claude_dir / "projects" / "-Users-test-multiproject" - project_dir.mkdir(parents=True) - - # Create sessions with different timestamps - sessions = [] - base_time = datetime.now(timezone.utc) - timedelta(days=30) - - for i in range(5): - session_uuid = f"session-{i:03d}" - sessions.append(session_uuid) - jsonl_path = project_dir / f"{session_uuid}.jsonl" - - # Create a session with timestamp at day i - session_time = base_time + timedelta(days=i * 7) - message_data = { - "type": "user", - "message": {"role": "user", "content": f"Message for session {i}"}, - "uuid": f"msg-{i}", - "timestamp": session_time.isoformat(), - "cwd": "/Users/test/multiproject", - "slug": f"session-slug-{i}", - } - - with open(jsonl_path, "w") as f: - f.write(json.dumps(message_data) + "\n") - - # Touch file to set mtime to match session time (for early filtering tests) - import os - - os.utime(jsonl_path, (session_time.timestamp(), session_time.timestamp())) - - return project_dir, sessions - - -@pytest.fixture -def project_with_many_subagents(temp_claude_dir: Path) -> Path: - """Create a session with multiple subagents for parallel processing tests.""" - project_dir = temp_claude_dir / "projects" / "-Users-test-manysubagents" - project_dir.mkdir(parents=True) - - session_uuid = "session-with-subagents" - jsonl_path = project_dir / f"{session_uuid}.jsonl" - - # Create main session - main_message = { - "type": "user", - "message": {"role": "user", "content": "Main session content"}, - "uuid": "main-msg", - "timestamp": datetime.now(timezone.utc).isoformat(), - "cwd": "/Users/test/manysubagents", - } - - with open(jsonl_path, "w") as f: - f.write(json.dumps(main_message) + "\n") - - # Create subagents directory and files - subagents_dir = project_dir / session_uuid / "subagents" - subagents_dir.mkdir(parents=True) - - for i in range(10): - agent_id = f"agent{i:02d}" - agent_path = subagents_dir / f"agent-{agent_id}.jsonl" - - agent_message = { - "type": "user", - "isSidechain": True, - "agentId": agent_id, - "message": {"role": "user", "content": f"Subagent {i} task"}, - "uuid": f"subagent-msg-{i}", - "timestamp": datetime.now(timezone.utc).isoformat(), - } - - with open(agent_path, "w") as f: - f.write(json.dumps(agent_message) + "\n") - - return project_dir - - -# ============================================================================= -# Test Early Date Filtering -# ============================================================================= - - -class TestListSessionsFiltered: - """Tests for Project.list_sessions_filtered().""" - - def test_no_filters_returns_all(self, multi_session_project): - """Without date filters, all sessions should be returned.""" - project_dir, session_uuids = multi_session_project - project = Project.from_encoded_name( - "-Users-test-multiproject", - claude_projects_dir=project_dir.parent, - ) - - sessions = project.list_sessions_filtered() - assert len(sessions) == 5 - - def test_start_date_filter(self, multi_session_project): - """Start date filter should exclude older sessions.""" - project_dir, session_uuids = multi_session_project - project = Project.from_encoded_name( - "-Users-test-multiproject", - claude_projects_dir=project_dir.parent, - ) - - # Filter to only sessions from last 2 weeks - start_date = datetime.now(timezone.utc) - timedelta(days=14) - sessions = project.list_sessions_filtered(start_date=start_date) - - # Should get fewer sessions - assert len(sessions) < 5 - - def test_end_date_filter(self, multi_session_project): - """End date filter should exclude newer sessions.""" - project_dir, session_uuids = multi_session_project - project = Project.from_encoded_name( - "-Users-test-multiproject", - claude_projects_dir=project_dir.parent, - ) - - # Filter to only sessions from before 2 weeks ago - end_date = datetime.now(timezone.utc) - timedelta(days=14) - sessions = project.list_sessions_filtered(end_date=end_date) - - # Should get fewer sessions - assert len(sessions) < 5 - - def test_limit_parameter(self, multi_session_project): - """Limit parameter should cap number of returned sessions.""" - project_dir, session_uuids = multi_session_project - project = Project.from_encoded_name( - "-Users-test-multiproject", - claude_projects_dir=project_dir.parent, - ) - - sessions = project.list_sessions_filtered(limit=2) - assert len(sessions) == 2 - - def test_sort_by_mtime(self, multi_session_project): - """Sessions should be sorted by modification time by default.""" - project_dir, session_uuids = multi_session_project - project = Project.from_encoded_name( - "-Users-test-multiproject", - claude_projects_dir=project_dir.parent, - ) - - sessions = project.list_sessions_filtered(sort_by_mtime=True) - assert len(sessions) == 5 - - # Most recent should be first - # Note: exact order depends on file mtime which we set in fixture - - -# ============================================================================= -# Test Batch Session Loader -# ============================================================================= - - -class TestBatchSessionLoader: - """Tests for BatchSessionLoader.""" - - def test_load_all_metadata(self, multi_session_project): - """Should load metadata from all session files.""" - project_dir, session_uuids = multi_session_project - session_paths = list(project_dir.glob("*.jsonl")) - - loader = BatchSessionLoader(session_paths) - metadata_list = loader.load_all_metadata() - - assert len(metadata_list) == 5 - for metadata in metadata_list: - assert "path" in metadata - assert "uuid" in metadata - assert "start_time" in metadata or "end_time" in metadata - - def test_load_sessions_metadata_batch_function(self, multi_session_project): - """Convenience function should work the same as class method.""" - project_dir, session_uuids = multi_session_project - session_paths = list(project_dir.glob("*.jsonl")) - - metadata_list = load_sessions_metadata_batch(session_paths) - assert len(metadata_list) == 5 - - def test_handles_empty_files(self, temp_claude_dir): - """Should handle empty files gracefully.""" - project_dir = temp_claude_dir / "projects" / "-Users-test-empty" - project_dir.mkdir(parents=True) - - empty_file = project_dir / "empty-session.jsonl" - empty_file.touch() - - loader = BatchSessionLoader([empty_file]) - metadata_list = loader.load_all_metadata() - - # Empty file should be skipped or have None values - assert len(metadata_list) == 0 or metadata_list[0]["start_time"] is None - - def test_handles_malformed_json(self, temp_claude_dir): - """Should handle files with invalid JSON.""" - project_dir = temp_claude_dir / "projects" / "-Users-test-malformed" - project_dir.mkdir(parents=True) - - malformed_file = project_dir / "malformed.jsonl" - malformed_file.write_text("not valid json\n") - - loader = BatchSessionLoader([malformed_file]) - metadata_list = loader.load_all_metadata() - - # Should not crash, may return empty or partial data - assert isinstance(metadata_list, list) - - -# ============================================================================= -# Test Fast Latest Session Time -# ============================================================================= - - -class TestGetLatestSessionTimeFast: - """Tests for Project.get_latest_session_time_fast().""" - - def test_returns_datetime_for_project_with_sessions(self, multi_session_project): - """Should return a datetime for projects with sessions.""" - project_dir, _ = multi_session_project - project = Project.from_encoded_name( - "-Users-test-multiproject", - claude_projects_dir=project_dir.parent, - ) - - latest_time = project.get_latest_session_time_fast() - assert latest_time is not None - assert isinstance(latest_time, datetime) - - def test_returns_none_for_empty_project(self, temp_claude_dir): - """Should return None for projects with no sessions.""" - project_dir = temp_claude_dir / "projects" / "-Users-test-empty" - project_dir.mkdir(parents=True) - - project = Project.from_encoded_name( - "-Users-test-empty", - claude_projects_dir=project_dir.parent, - ) - - latest_time = project.get_latest_session_time_fast() - assert latest_time is None - - def test_returns_none_for_nonexistent_project(self, temp_claude_dir): - """Should return None for non-existent projects.""" - project = Project.from_encoded_name( - "-Users-test-nonexistent", - claude_projects_dir=temp_claude_dir / "projects", - ) - - latest_time = project.get_latest_session_time_fast() - assert latest_time is None - - -# ============================================================================= -# Test Parallel Processing (Basic) -# ============================================================================= - - -class TestParallelProcessing: - """Tests for parallel processing utilities.""" - - def test_session_with_subagents_loads(self, project_with_many_subagents): - """Session with many subagents should load correctly.""" - project = Project.from_encoded_name( - "-Users-test-manysubagents", - claude_projects_dir=project_with_many_subagents.parent, - ) - - sessions = project.list_sessions() - assert len(sessions) == 1 - - session = sessions[0] - subagents = session.list_subagents() - assert len(subagents) == 10 - - -# ============================================================================= -# Test Async Session (if aiofiles available) -# ============================================================================= - -# Check for async dependencies -ASYNC_DEPS_AVAILABLE = ( - importlib.util.find_spec("aiofiles") is not None - and importlib.util.find_spec("pytest_asyncio") is not None -) - - -@pytest.mark.skipif(not ASYNC_DEPS_AVAILABLE, reason="aiofiles or pytest-asyncio not installed") -class TestAsyncSession: - """Tests for AsyncSession - skipped if aiofiles not available.""" - - @pytest.mark.asyncio - async def test_async_session_loads_metadata(self, multi_session_project): - """AsyncSession should load metadata correctly.""" - from models.async_session import AsyncSession - - project_dir, session_uuids = multi_session_project - session_path = project_dir / f"{session_uuids[0]}.jsonl" - - session = AsyncSession(session_path) - metadata = await session.get_metadata() - - assert metadata["uuid"] == session_uuids[0] - assert "start_time" in metadata - assert "message_count" in metadata - - @pytest.mark.asyncio - async def test_get_sessions_metadata_async(self, multi_session_project): - """Async bulk metadata loading should work.""" - from models.async_session import get_sessions_metadata_async - - project_dir, _ = multi_session_project - session_paths = list(project_dir.glob("*.jsonl")) - - metadata_list = await get_sessions_metadata_async(session_paths) - assert len(metadata_list) == 5 diff --git a/api/tests/test_project_service.py b/api/tests/test_project_service.py new file mode 100644 index 00000000..558707fa --- /dev/null +++ b/api/tests/test_project_service.py @@ -0,0 +1,449 @@ +"""Tests for ProjectService — project sharing + subscription management.""" +import sys +from pathlib import Path +sys.path.insert(0, str(Path(__file__).parent.parent)) + +import sqlite3 +import pytest +from unittest.mock import MagicMock, AsyncMock + +from db.schema import ensure_schema +from domain.team import AuthorizationError +from domain.member import MemberStatus +from domain.project import SharedProject, SharedProjectStatus, derive_folder_suffix +from domain.subscription import SubscriptionStatus, SyncDirection +from repositories.team_repo import TeamRepository +from repositories.member_repo import MemberRepository +from repositories.project_repo import ProjectRepository +from repositories.subscription_repo import SubscriptionRepository +from repositories.event_repo import EventRepository +from services.sync.project_service import ProjectService + + +@pytest.fixture +def conn(): + c = sqlite3.connect(":memory:") + c.row_factory = sqlite3.Row + c.execute("PRAGMA foreign_keys=ON") + ensure_schema(c) + return c + + +@pytest.fixture +def mock_folders(): + m = MagicMock() + m.ensure_outbox_folder = AsyncMock() + m.ensure_inbox_folder = AsyncMock() + m.remove_outbox_folder = AsyncMock() + m.set_folder_devices = AsyncMock() + m.remove_device_from_team_folders = AsyncMock() + m.cleanup_team_folders = AsyncMock() + m.cleanup_project_folders = AsyncMock() + return m + + +@pytest.fixture +def mock_metadata(tmp_path): + from services.sync.metadata_service import MetadataService + return MetadataService(meta_base=tmp_path / "meta") + + +@pytest.fixture +def service(mock_folders, mock_metadata): + return ProjectService( + projects=ProjectRepository(), + subs=SubscriptionRepository(), + members=MemberRepository(), + teams=TeamRepository(), + folders=mock_folders, + metadata=mock_metadata, + events=EventRepository(), + ) + + +def _setup_team_with_member(conn, service): + """Helper: create a team + add one member. Returns (team_repo, member_repo).""" + from domain.team import Team + from domain.member import Member + + teams = service.teams + members = service.members + + team = Team(name="t", leader_device_id="DEV-L", leader_member_tag="j.m") + teams.save(conn, team) + + leader = Member.from_member_tag( + member_tag="j.m", team_name="t", device_id="DEV-L", status=MemberStatus.ACTIVE, + ) + members.save(conn, leader) + + member = Member.from_member_tag( + member_tag="a.l", team_name="t", device_id="DEV-A", status=MemberStatus.ACTIVE, + ) + members.save(conn, member) + return team + + +class TestShareProject: + @pytest.mark.asyncio + async def test_shares_project_and_creates_subscriptions(self, service, conn): + _setup_team_with_member(conn, service) + project = await service.share_project( + conn, team_name="t", by_device="DEV-L", + git_identity="owner/repo", + ) + assert project.status == SharedProjectStatus.SHARED + assert project.folder_suffix == "owner-repo" + + # Active non-leader member gets OFFERED subscription + subs = service.subs.list_for_member(conn, "a.l") + assert len(subs) == 1 + assert subs[0].status == SubscriptionStatus.OFFERED + + @pytest.mark.asyncio + async def test_non_leader_cannot_share(self, service, conn): + _setup_team_with_member(conn, service) + with pytest.raises(AuthorizationError): + await service.share_project( + conn, team_name="t", by_device="DEV-OTHER", + git_identity="owner/repo", + ) + + @pytest.mark.asyncio + async def test_requires_git_identity(self, service, conn): + _setup_team_with_member(conn, service) + with pytest.raises(ValueError): + await service.share_project( + conn, team_name="t", by_device="DEV-L", + git_identity="", + ) + + @pytest.mark.asyncio + async def test_creates_outbox_when_encoded_name_provided(self, service, conn, mock_folders): + _setup_team_with_member(conn, service) + await service.share_project( + conn, team_name="t", by_device="DEV-L", + git_identity="owner/repo", + encoded_name="-Users-j-repo", + ) + mock_folders.ensure_outbox_folder.assert_called_once_with("j.m", "owner-repo") + + @pytest.mark.asyncio + async def test_no_outbox_without_encoded_name(self, service, conn, mock_folders): + _setup_team_with_member(conn, service) + await service.share_project( + conn, team_name="t", by_device="DEV-L", + git_identity="owner/repo", + ) + mock_folders.ensure_outbox_folder.assert_not_called() + + @pytest.mark.asyncio + async def test_logs_project_shared_event(self, service, conn): + _setup_team_with_member(conn, service) + await service.share_project( + conn, team_name="t", by_device="DEV-L", + git_identity="owner/repo", + ) + events = service.events.query(conn, team="t") + assert any(e.event_type.value == "project_shared" for e in events) + + @pytest.mark.asyncio + async def test_leader_gets_accepted_subscription(self, service, conn): + """Leader gets an ACCEPTED/BOTH subscription for their own shared project.""" + _setup_team_with_member(conn, service) + await service.share_project( + conn, team_name="t", by_device="DEV-L", + git_identity="owner/repo", + ) + # Leader (j.m) should have an ACCEPTED subscription with direction=BOTH + leader_subs = service.subs.list_for_member(conn, "j.m") + assert len(leader_subs) == 1 + assert leader_subs[0].status.value == "accepted" + assert leader_subs[0].direction.value == "both" + + +class TestAcceptSubscription: + def _create_offered_sub(self, conn, service, git_identity="owner/repo"): + from domain.subscription import Subscription + # Save project FIRST (FK requires it before subscription) + project = SharedProject( + team_name="t", git_identity=git_identity, + folder_suffix=derive_folder_suffix(git_identity), + ) + service.projects.save(conn, project) + sub = Subscription( + member_tag="a.l", team_name="t", + project_git_identity=git_identity, + status=SubscriptionStatus.OFFERED, + ) + service.subs.save(conn, sub) + return sub + + def _setup_team_member(self, conn, service): + from domain.team import Team + from domain.member import Member + team = Team(name="t", leader_device_id="DEV-L", leader_member_tag="j.m") + service.teams.save(conn, team) + leader = Member.from_member_tag( + member_tag="j.m", team_name="t", device_id="DEV-L", status=MemberStatus.ACTIVE, + ) + service.members.save(conn, leader) + member = Member.from_member_tag( + member_tag="a.l", team_name="t", device_id="DEV-A", status=MemberStatus.ACTIVE, + ) + service.members.save(conn, member) + + @pytest.mark.asyncio + async def test_accept_with_both_direction(self, service, conn, mock_folders): + self._setup_team_member(conn, service) + self._create_offered_sub(conn, service) + accepted = await service.accept_subscription( + conn, member_tag="a.l", team_name="t", + git_identity="owner/repo", direction=SyncDirection.BOTH, + ) + assert accepted.status == SubscriptionStatus.ACCEPTED + assert accepted.direction == SyncDirection.BOTH + # Both outbox + inbox created + mock_folders.ensure_outbox_folder.assert_called_once_with("a.l", "owner-repo") + mock_folders.ensure_inbox_folder.assert_called() + + @pytest.mark.asyncio + async def test_accept_receive_only(self, service, conn, mock_folders): + self._setup_team_member(conn, service) + self._create_offered_sub(conn, service) + accepted = await service.accept_subscription( + conn, member_tag="a.l", team_name="t", + git_identity="owner/repo", direction=SyncDirection.RECEIVE, + ) + assert accepted.direction == SyncDirection.RECEIVE + # No outbox created, only inbox + mock_folders.ensure_outbox_folder.assert_not_called() + mock_folders.ensure_inbox_folder.assert_called() + + @pytest.mark.asyncio + async def test_accept_send_only(self, service, conn, mock_folders): + self._setup_team_member(conn, service) + self._create_offered_sub(conn, service) + accepted = await service.accept_subscription( + conn, member_tag="a.l", team_name="t", + git_identity="owner/repo", direction=SyncDirection.SEND, + ) + assert accepted.direction == SyncDirection.SEND + # Outbox created, no inbox + mock_folders.ensure_outbox_folder.assert_called_once_with("a.l", "owner-repo") + mock_folders.ensure_inbox_folder.assert_not_called() + + @pytest.mark.asyncio + async def test_logs_subscription_accepted_event(self, service, conn): + self._setup_team_member(conn, service) + self._create_offered_sub(conn, service) + await service.accept_subscription( + conn, member_tag="a.l", team_name="t", + git_identity="owner/repo", direction=SyncDirection.BOTH, + ) + events = service.events.query(conn, team="t") + assert any(e.event_type.value == "subscription_accepted" for e in events) + + +class TestPauseResumeDecline: + def _setup(self, conn, service): + from domain.team import Team + from domain.member import Member + from domain.subscription import Subscription + team = Team(name="t", leader_device_id="DEV-L", leader_member_tag="j.m") + service.teams.save(conn, team) + member = Member.from_member_tag( + member_tag="a.l", team_name="t", device_id="DEV-A", status=MemberStatus.ACTIVE, + ) + service.members.save(conn, member) + project = SharedProject(team_name="t", git_identity="o/r", folder_suffix="o-r") + service.projects.save(conn, project) + # Start with accepted sub + sub = Subscription( + member_tag="a.l", team_name="t", project_git_identity="o/r", + status=SubscriptionStatus.ACCEPTED, + ) + service.subs.save(conn, sub) + + @pytest.mark.asyncio + async def test_pause_subscription(self, service, conn): + self._setup(conn, service) + paused = await service.pause_subscription( + conn, member_tag="a.l", team_name="t", git_identity="o/r", + ) + assert paused.status == SubscriptionStatus.PAUSED + saved = service.subs.get(conn, "a.l", "t", "o/r") + assert saved.status == SubscriptionStatus.PAUSED + + @pytest.mark.asyncio + async def test_resume_subscription(self, service, conn): + self._setup(conn, service) + await service.pause_subscription( + conn, member_tag="a.l", team_name="t", git_identity="o/r", + ) + resumed = await service.resume_subscription( + conn, member_tag="a.l", team_name="t", git_identity="o/r", + ) + assert resumed.status == SubscriptionStatus.ACCEPTED + + @pytest.mark.asyncio + async def test_decline_subscription(self, service, conn): + self._setup(conn, service) + declined = await service.decline_subscription( + conn, member_tag="a.l", team_name="t", git_identity="o/r", + ) + assert declined.status == SubscriptionStatus.DECLINED + saved = service.subs.get(conn, "a.l", "t", "o/r") + assert saved.status == SubscriptionStatus.DECLINED + + @pytest.mark.asyncio + async def test_logs_pause_event(self, service, conn): + self._setup(conn, service) + await service.pause_subscription( + conn, member_tag="a.l", team_name="t", git_identity="o/r", + ) + events = service.events.query(conn, team="t") + assert any(e.event_type.value == "subscription_paused" for e in events) + + @pytest.mark.asyncio + async def test_logs_resume_event(self, service, conn): + self._setup(conn, service) + await service.pause_subscription( + conn, member_tag="a.l", team_name="t", git_identity="o/r", + ) + await service.resume_subscription( + conn, member_tag="a.l", team_name="t", git_identity="o/r", + ) + events = service.events.query(conn, team="t") + assert any(e.event_type.value == "subscription_resumed" for e in events) + + @pytest.mark.asyncio + async def test_logs_decline_event(self, service, conn): + self._setup(conn, service) + await service.decline_subscription( + conn, member_tag="a.l", team_name="t", git_identity="o/r", + ) + events = service.events.query(conn, team="t") + assert any(e.event_type.value == "subscription_declined" for e in events) + + +class TestChangeDirection: + def _setup(self, conn, service): + from domain.team import Team + from domain.member import Member + from domain.subscription import Subscription + team = Team(name="t", leader_device_id="DEV-L", leader_member_tag="j.m") + service.teams.save(conn, team) + member = Member.from_member_tag( + member_tag="a.l", team_name="t", device_id="DEV-A", status=MemberStatus.ACTIVE, + ) + service.members.save(conn, member) + project = SharedProject(team_name="t", git_identity="o/r", folder_suffix="o-r") + service.projects.save(conn, project) + sub = Subscription( + member_tag="a.l", team_name="t", project_git_identity="o/r", + status=SubscriptionStatus.ACCEPTED, direction=SyncDirection.BOTH, + ) + service.subs.save(conn, sub) + + @pytest.mark.asyncio + async def test_change_to_receive_removes_outbox(self, service, conn, mock_folders): + self._setup(conn, service) + changed = await service.change_direction( + conn, member_tag="a.l", team_name="t", + git_identity="o/r", direction=SyncDirection.RECEIVE, + ) + assert changed.direction == SyncDirection.RECEIVE + mock_folders.remove_outbox_folder.assert_called_once_with("a.l", "o-r") + + @pytest.mark.asyncio + async def test_change_to_send_only(self, service, conn, mock_folders): + from domain.subscription import Subscription + from domain.team import Team + from domain.member import Member + # Create parent rows FIRST (FK requires team → member → project → subscription) + team = Team(name="t", leader_device_id="DEV-L", leader_member_tag="j.m") + service.teams.save(conn, team) + member = Member.from_member_tag( + member_tag="a.l", team_name="t", device_id="DEV-A", status=MemberStatus.ACTIVE, + ) + service.members.save(conn, member) + project = SharedProject(team_name="t", git_identity="o/r", folder_suffix="o-r") + service.projects.save(conn, project) + # Now save subscription (all FK parents exist) + sub = Subscription( + member_tag="a.l", team_name="t", project_git_identity="o/r", + status=SubscriptionStatus.ACCEPTED, direction=SyncDirection.RECEIVE, + ) + service.subs.save(conn, sub) + + changed = await service.change_direction( + conn, member_tag="a.l", team_name="t", + git_identity="o/r", direction=SyncDirection.SEND, + ) + assert changed.direction == SyncDirection.SEND + mock_folders.ensure_outbox_folder.assert_called_once_with("a.l", "o-r") + mock_folders.remove_outbox_folder.assert_not_called() + + @pytest.mark.asyncio + async def test_logs_direction_changed_event(self, service, conn): + self._setup(conn, service) + await service.change_direction( + conn, member_tag="a.l", team_name="t", + git_identity="o/r", direction=SyncDirection.RECEIVE, + ) + events = service.events.query(conn, team="t") + assert any(e.event_type.value == "direction_changed" for e in events) + + +class TestRemoveProject: + def _setup(self, conn, service): + from domain.team import Team + from domain.member import Member + from domain.subscription import Subscription + team = Team(name="t", leader_device_id="DEV-L", leader_member_tag="j.m") + service.teams.save(conn, team) + leader = Member.from_member_tag( + member_tag="j.m", team_name="t", device_id="DEV-L", status=MemberStatus.ACTIVE, + ) + service.members.save(conn, leader) + member = Member.from_member_tag( + member_tag="a.l", team_name="t", device_id="DEV-A", status=MemberStatus.ACTIVE, + ) + service.members.save(conn, member) + project = SharedProject(team_name="t", git_identity="o/r", folder_suffix="o-r") + service.projects.save(conn, project) + sub = Subscription( + member_tag="a.l", team_name="t", project_git_identity="o/r", + status=SubscriptionStatus.ACCEPTED, + ) + service.subs.save(conn, sub) + + @pytest.mark.asyncio + async def test_removes_project_and_declines_all_subs(self, service, conn, mock_folders): + self._setup(conn, service) + removed = await service.remove_project( + conn, team_name="t", by_device="DEV-L", git_identity="o/r", + ) + assert removed.status == SharedProjectStatus.REMOVED + # All subs declined + subs = service.subs.list_for_project(conn, "t", "o/r") + assert all(s.status == SubscriptionStatus.DECLINED for s in subs) + mock_folders.cleanup_project_folders.assert_called_once() + + @pytest.mark.asyncio + async def test_non_leader_cannot_remove_project(self, service, conn): + self._setup(conn, service) + with pytest.raises(AuthorizationError): + await service.remove_project( + conn, team_name="t", by_device="DEV-OTHER", git_identity="o/r", + ) + + @pytest.mark.asyncio + async def test_logs_project_removed_event(self, service, conn): + self._setup(conn, service) + await service.remove_project( + conn, team_name="t", by_device="DEV-L", git_identity="o/r", + ) + events = service.events.query(conn, team="t") + assert any(e.event_type.value == "project_removed" for e in events) diff --git a/api/tests/test_project_status_gap.py b/api/tests/test_project_status_gap.py new file mode 100644 index 00000000..94073712 --- /dev/null +++ b/api/tests/test_project_status_gap.py @@ -0,0 +1,75 @@ +import sys +from pathlib import Path +sys.path.insert(0, str(Path(__file__).parent.parent)) + +import json +from datetime import datetime, timezone, timedelta +import pytest + + +def _write_live_session(live_dir, slug, session_id, encoded_name, state="RUNNING", idle_minutes=0): + now = datetime.now(timezone.utc) + updated = now - timedelta(minutes=idle_minutes) + data = { + "session_id": session_id, + "state": state, + "transcript_path": f"/Users/me/.claude/projects/{encoded_name}/{session_id}.jsonl", + "updated_at": updated.isoformat(), + } + (live_dir / f"{slug}.json").write_text(json.dumps(data)) + + +@pytest.fixture +def live_sessions_dir(tmp_path): + live_dir = tmp_path / "live-sessions" + live_dir.mkdir() + return live_dir + + +class TestGetActiveCounts: + def test_empty_dir_returns_empty(self, live_sessions_dir): + from routers.sync_teams import _get_active_counts + assert _get_active_counts(live_sessions_dir) == {} + + def test_running_session_counted(self, live_sessions_dir): + from routers.sync_teams import _get_active_counts + _write_live_session(live_sessions_dir, "s1", "uuid-1", "-Users-me-repo", state="RUNNING") + result = _get_active_counts(live_sessions_dir) + assert result.get("-Users-me-repo", 0) == 1 + + def test_ended_session_not_counted(self, live_sessions_dir): + from routers.sync_teams import _get_active_counts + _write_live_session(live_sessions_dir, "s1", "uuid-1", "-Users-me-repo", state="ENDED") + result = _get_active_counts(live_sessions_dir) + assert result.get("-Users-me-repo", 0) == 0 + + def test_stale_session_not_counted(self, live_sessions_dir): + from routers.sync_teams import _get_active_counts + _write_live_session(live_sessions_dir, "s1", "uuid-1", "-Users-me-repo", state="RUNNING", idle_minutes=35) + result = _get_active_counts(live_sessions_dir) + assert result.get("-Users-me-repo", 0) == 0 + + def test_multiple_projects(self, live_sessions_dir): + from routers.sync_teams import _get_active_counts + _write_live_session(live_sessions_dir, "s1", "uuid-1", "-Users-me-a", state="RUNNING") + _write_live_session(live_sessions_dir, "s2", "uuid-2", "-Users-me-a", state="RUNNING") + _write_live_session(live_sessions_dir, "s3", "uuid-3", "-Users-me-b", state="RUNNING") + result = _get_active_counts(live_sessions_dir) + assert result["-Users-me-a"] == 2 + assert result["-Users-me-b"] == 1 + + def test_worktree_resolution_with_git_root(self, live_sessions_dir): + from routers.sync_teams import _get_active_counts + now = datetime.now(timezone.utc) + data = { + "session_id": "uuid-wt", + "state": "RUNNING", + "transcript_path": "/Users/me/.claude/projects/-Users-me--claude-worktrees-repo-focused-jepsen/uuid-wt.jsonl", + "updated_at": now.isoformat(), + "git_root": "/Users/me/repo", + } + (live_sessions_dir / "wt.json").write_text(json.dumps(data)) + result = _get_active_counts(live_sessions_dir) + # Should resolve to -Users-me-repo, not the worktree encoded name + assert result.get("-Users-me-repo", 0) == 1 + assert "-Users-me--claude-worktrees-repo-focused-jepsen" not in result diff --git a/api/tests/test_reconciliation_service.py b/api/tests/test_reconciliation_service.py new file mode 100644 index 00000000..90a5878a --- /dev/null +++ b/api/tests/test_reconciliation_service.py @@ -0,0 +1,503 @@ +"""Tests for ReconciliationService — 3-phase reconciliation pipeline.""" +import sys +from pathlib import Path +sys.path.insert(0, str(Path(__file__).parent.parent)) + +import sqlite3 +import pytest +from unittest.mock import MagicMock, AsyncMock + +from db.schema import ensure_schema +from domain.team import Team +from domain.member import Member, MemberStatus +from domain.project import SharedProject, SharedProjectStatus +from domain.subscription import Subscription, SubscriptionStatus, SyncDirection +from domain.events import SyncEventType +from repositories.team_repo import TeamRepository +from repositories.member_repo import MemberRepository +from repositories.project_repo import ProjectRepository +from repositories.subscription_repo import SubscriptionRepository +from repositories.event_repo import EventRepository +from services.sync.metadata_service import MetadataService +from services.sync.reconciliation_service import ReconciliationService + + +MY_TAG = "me.laptop" +MY_DEVICE = "DEV-ME" +PEER_TAG = "peer.desktop" +PEER_DEVICE = "DEV-PEER" +LEADER_TAG = "leader.server" +LEADER_DEVICE = "DEV-LEADER" +TEAM = "alpha" + + +# --------------------------------------------------------------------------- +# Fixtures +# --------------------------------------------------------------------------- + + +@pytest.fixture +def conn(): + c = sqlite3.connect(":memory:") + c.row_factory = sqlite3.Row + c.execute("PRAGMA foreign_keys=ON") + ensure_schema(c) + return c + + +@pytest.fixture +def metadata(tmp_path): + return MetadataService(meta_base=tmp_path / "meta") + + +@pytest.fixture +def mock_devices(): + m = MagicMock() + m.ensure_paired = AsyncMock() + m.unpair = AsyncMock() + return m + + +@pytest.fixture +def mock_folders(): + m = MagicMock() + m.set_folder_devices = AsyncMock() + m.cleanup_team_folders = AsyncMock() + m.ensure_outbox_folder = AsyncMock() + return m + + +def make_service(metadata, mock_devices, mock_folders, my_tag=MY_TAG): + return ReconciliationService( + teams=TeamRepository(), + members=MemberRepository(), + projects=ProjectRepository(), + subs=SubscriptionRepository(), + events=EventRepository(), + devices=mock_devices, + folders=mock_folders, + metadata=metadata, + my_member_tag=my_tag, + ) + + +def seed_team(conn, name=TEAM, leader_tag=LEADER_TAG, leader_device=LEADER_DEVICE): + """Insert a team row (no FK violation since sync_teams has no parent).""" + team = Team(name=name, leader_device_id=leader_device, leader_member_tag=leader_tag) + TeamRepository().save(conn, team) + return team + + +def seed_member(conn, member_tag, team_name=TEAM, device_id=None, status=MemberStatus.ACTIVE): + device_id = device_id or f"DEV-{member_tag}" + m = Member.from_member_tag( + member_tag=member_tag, + team_name=team_name, + device_id=device_id, + status=MemberStatus.ADDED, + ) + if status == MemberStatus.ACTIVE: + m = m.activate() + MemberRepository().save(conn, m) + return m + + +def seed_project(conn, git_identity="owner/repo", team_name=TEAM, status=SharedProjectStatus.SHARED): + from domain.project import derive_folder_suffix + suffix = derive_folder_suffix(git_identity) + p = SharedProject( + team_name=team_name, + git_identity=git_identity, + folder_suffix=suffix, + status=status, + ) + ProjectRepository().save(conn, p) + return p + + +def seed_subscription(conn, member_tag, git_identity="owner/repo", team_name=TEAM, + status=SubscriptionStatus.ACCEPTED, direction=SyncDirection.BOTH): + sub = Subscription( + member_tag=member_tag, + team_name=team_name, + project_git_identity=git_identity, + status=status, + direction=direction, + ) + SubscriptionRepository().save(conn, sub) + return sub + + +# --------------------------------------------------------------------------- +# TestPhaseMetadata +# --------------------------------------------------------------------------- + + +class TestPhaseMetadata: + @pytest.mark.asyncio + async def test_detects_removal_signal_and_auto_leaves( + self, conn, metadata, mock_devices, mock_folders + ): + """When own member_tag is in removal signals, team is deleted from DB.""" + team = seed_team(conn) + service = make_service(metadata, mock_devices, mock_folders, my_tag=MY_TAG) + + # Write a removal signal for our own tag + metadata.write_removal_signal(TEAM, MY_TAG, removed_by=LEADER_TAG) + + await service.phase_metadata(conn, team) + + # Team must be gone from DB + assert TeamRepository().get(conn, TEAM) is None + # cleanup_team_folders was called + mock_folders.cleanup_team_folders.assert_called_once() + + @pytest.mark.asyncio + async def test_auto_leave_logs_event(self, conn, metadata, mock_devices, mock_folders): + """auto-leave logs member_auto_left event before deleting team.""" + team = seed_team(conn) + service = make_service(metadata, mock_devices, mock_folders, my_tag=MY_TAG) + metadata.write_removal_signal(TEAM, MY_TAG, removed_by=LEADER_TAG) + + # Capture events before deletion via a secondary in-memory fixture won't work + # (team deleted cascades events). Just verify no exception is raised and + # cleanup was attempted — event logging is verified by unit-level inspection. + await service.phase_metadata(conn, team) + assert TeamRepository().get(conn, TEAM) is None + + @pytest.mark.asyncio + async def test_discovers_new_member_from_metadata( + self, conn, metadata, mock_devices, mock_folders + ): + """Unknown member in metadata state → registered as ACTIVE in DB.""" + team = seed_team(conn) + service = make_service(metadata, mock_devices, mock_folders, my_tag=MY_TAG) + + # Write a peer's state to metadata (simulates peer writing own file) + (metadata._team_dir(TEAM) / "members").mkdir(parents=True, exist_ok=True) + import json + state_file = metadata._team_dir(TEAM) / "members" / f"{PEER_TAG}.json" + state_file.write_text(json.dumps({ + "member_tag": PEER_TAG, + "device_id": PEER_DEVICE, + "projects": [], + "subscriptions": {}, + })) + + await service.phase_metadata(conn, team) + + saved = MemberRepository().get(conn, TEAM, PEER_TAG) + assert saved is not None + assert saved.device_id == PEER_DEVICE + # Should be ACTIVE (publish implies acknowledgment) + assert saved.status == MemberStatus.ACTIVE + + @pytest.mark.asyncio + async def test_skips_own_tag_when_discovering_members( + self, conn, metadata, mock_devices, mock_folders + ): + """Own member_tag is never re-registered from metadata.""" + team = seed_team(conn) + service = make_service(metadata, mock_devices, mock_folders, my_tag=MY_TAG) + + import json + (metadata._team_dir(TEAM) / "members").mkdir(parents=True, exist_ok=True) + state_file = metadata._team_dir(TEAM) / "members" / f"{MY_TAG}.json" + state_file.write_text(json.dumps({ + "member_tag": MY_TAG, + "device_id": MY_DEVICE, + "projects": [], + })) + + await service.phase_metadata(conn, team) + + # Self should NOT be registered (we're not in the members table via this path) + saved = MemberRepository().get(conn, TEAM, MY_TAG) + assert saved is None + + @pytest.mark.asyncio + async def test_detects_removed_project_declines_sub( + self, conn, metadata, mock_devices, mock_folders + ): + """Project present locally but absent from leader metadata → sub declined.""" + team = seed_team(conn) + project = seed_project(conn, git_identity="owner/repo") + seed_member(conn, MY_TAG, device_id=MY_DEVICE) + seed_subscription(conn, MY_TAG, git_identity="owner/repo") + + service = make_service(metadata, mock_devices, mock_folders, my_tag=MY_TAG) + + # Leader's state has NO projects listed + import json + (metadata._team_dir(TEAM) / "members").mkdir(parents=True, exist_ok=True) + leader_file = metadata._team_dir(TEAM) / "members" / f"{LEADER_TAG}.json" + leader_file.write_text(json.dumps({ + "member_tag": LEADER_TAG, + "device_id": LEADER_DEVICE, + "projects": [], # empty — project was removed + })) + + await service.phase_metadata(conn, team) + + sub = SubscriptionRepository().get(conn, MY_TAG, TEAM, "owner/repo") + assert sub is not None + assert sub.status == SubscriptionStatus.DECLINED + + @pytest.mark.asyncio + async def test_does_nothing_when_no_metadata( + self, conn, metadata, mock_devices, mock_folders + ): + """Empty metadata folder → no side effects.""" + team = seed_team(conn) + service = make_service(metadata, mock_devices, mock_folders) + + # No metadata written — _team_dir doesn't exist + await service.phase_metadata(conn, team) + + assert TeamRepository().get(conn, TEAM) is not None # team untouched + mock_folders.cleanup_team_folders.assert_not_called() + + @pytest.mark.asyncio + async def test_activates_added_member_seen_in_metadata( + self, conn, metadata, mock_devices, mock_folders + ): + """Member in ADDED status that appears in metadata transitions to ACTIVE.""" + team = seed_team(conn) + # Seed member as ADDED (not yet active) + m = Member.from_member_tag( + member_tag=PEER_TAG, team_name=TEAM, device_id=PEER_DEVICE, + status=MemberStatus.ADDED, + ) + MemberRepository().save(conn, m) + + service = make_service(metadata, mock_devices, mock_folders, my_tag=MY_TAG) + + import json + (metadata._team_dir(TEAM) / "members").mkdir(parents=True, exist_ok=True) + state_file = metadata._team_dir(TEAM) / "members" / f"{PEER_TAG}.json" + state_file.write_text(json.dumps({ + "member_tag": PEER_TAG, + "device_id": PEER_DEVICE, + "projects": [], + })) + + await service.phase_metadata(conn, team) + + saved = MemberRepository().get(conn, TEAM, PEER_TAG) + assert saved.status == MemberStatus.ACTIVE + + +# --------------------------------------------------------------------------- +# TestPhaseMeshPair +# --------------------------------------------------------------------------- + + +class TestPhaseMeshPair: + @pytest.mark.asyncio + async def test_pairs_with_unpaired_active_members( + self, conn, metadata, mock_devices, mock_folders + ): + """Active peer member → ensure_paired called with their device_id.""" + team = seed_team(conn) + seed_member(conn, PEER_TAG, device_id=PEER_DEVICE, status=MemberStatus.ACTIVE) + + service = make_service(metadata, mock_devices, mock_folders) + await service.phase_mesh_pair(conn, team) + + mock_devices.ensure_paired.assert_called_once_with(PEER_DEVICE) + + @pytest.mark.asyncio + async def test_skips_self(self, conn, metadata, mock_devices, mock_folders): + """Own member_tag is never paired (skip self).""" + team = seed_team(conn) + seed_member(conn, MY_TAG, device_id=MY_DEVICE, status=MemberStatus.ACTIVE) + + service = make_service(metadata, mock_devices, mock_folders, my_tag=MY_TAG) + await service.phase_mesh_pair(conn, team) + + mock_devices.ensure_paired.assert_not_called() + + @pytest.mark.asyncio + async def test_skips_removed_members(self, conn, metadata, mock_devices, mock_folders): + """REMOVED members are not paired.""" + team = seed_team(conn) + # Seed member then mark removed + m = Member.from_member_tag( + member_tag=PEER_TAG, team_name=TEAM, device_id=PEER_DEVICE, + status=MemberStatus.ADDED, + ) + removed = m.remove() + MemberRepository().save(conn, removed) + + service = make_service(metadata, mock_devices, mock_folders) + await service.phase_mesh_pair(conn, team) + + mock_devices.ensure_paired.assert_not_called() + + @pytest.mark.asyncio + async def test_skips_added_members(self, conn, metadata, mock_devices, mock_folders): + """ADDED (not yet active) members are not paired.""" + team = seed_team(conn) + m = Member.from_member_tag( + member_tag=PEER_TAG, team_name=TEAM, device_id=PEER_DEVICE, + status=MemberStatus.ADDED, + ) + MemberRepository().save(conn, m) + + service = make_service(metadata, mock_devices, mock_folders) + await service.phase_mesh_pair(conn, team) + + mock_devices.ensure_paired.assert_not_called() + + @pytest.mark.asyncio + async def test_pairs_multiple_active_members( + self, conn, metadata, mock_devices, mock_folders + ): + """Multiple active peers → ensure_paired called for each.""" + team = seed_team(conn) + seed_member(conn, "a.x", device_id="DEV-A", status=MemberStatus.ACTIVE) + seed_member(conn, "b.y", device_id="DEV-B", status=MemberStatus.ACTIVE) + + service = make_service(metadata, mock_devices, mock_folders) + await service.phase_mesh_pair(conn, team) + + calls = {c.args[0] for c in mock_devices.ensure_paired.call_args_list} + assert calls == {"DEV-A", "DEV-B"} + + +# --------------------------------------------------------------------------- +# TestPhaseDeviceLists +# --------------------------------------------------------------------------- + + +class TestPhaseDeviceLists: + @pytest.mark.asyncio + async def test_computes_device_list_from_accepted_subs( + self, conn, metadata, mock_devices, mock_folders + ): + """Accepted BOTH subscription → device included in set_folder_devices call.""" + team = seed_team(conn) + project = seed_project(conn, git_identity="owner/repo") + peer = seed_member(conn, PEER_TAG, device_id=PEER_DEVICE, status=MemberStatus.ACTIVE) + seed_subscription(conn, PEER_TAG, git_identity="owner/repo", + status=SubscriptionStatus.ACCEPTED, direction=SyncDirection.BOTH) + + service = make_service(metadata, mock_devices, mock_folders) + await service.phase_device_lists(conn, team) + + assert mock_folders.set_folder_devices.called + # At least one call should include PEER_DEVICE + all_device_sets = [ + call.args[1] for call in mock_folders.set_folder_devices.call_args_list + ] + assert any(PEER_DEVICE in ds for ds in all_device_sets) + + @pytest.mark.asyncio + async def test_excludes_receive_only_from_device_list( + self, conn, metadata, mock_devices, mock_folders + ): + """RECEIVE-only subscription → device excluded from device list.""" + team = seed_team(conn) + seed_project(conn, git_identity="owner/repo") + seed_member(conn, PEER_TAG, device_id=PEER_DEVICE, status=MemberStatus.ACTIVE) + seed_subscription(conn, PEER_TAG, git_identity="owner/repo", + status=SubscriptionStatus.ACCEPTED, direction=SyncDirection.RECEIVE) + + service = make_service(metadata, mock_devices, mock_folders) + await service.phase_device_lists(conn, team) + + all_device_sets = [ + call.args[1] for call in mock_folders.set_folder_devices.call_args_list + ] + # PEER_DEVICE must not appear in any device set + for ds in all_device_sets: + assert PEER_DEVICE not in ds + + @pytest.mark.asyncio + async def test_computes_union_from_multiple_subs( + self, conn, metadata, mock_devices, mock_folders + ): + """Two accepted SEND subs for the same project → both devices in set.""" + team = seed_team(conn) + seed_project(conn, git_identity="owner/repo") + seed_member(conn, "a.x", device_id="DEV-A", status=MemberStatus.ACTIVE) + seed_member(conn, "b.y", device_id="DEV-B", status=MemberStatus.ACTIVE) + seed_subscription(conn, "a.x", git_identity="owner/repo", + status=SubscriptionStatus.ACCEPTED, direction=SyncDirection.SEND) + seed_subscription(conn, "b.y", git_identity="owner/repo", + status=SubscriptionStatus.ACCEPTED, direction=SyncDirection.BOTH) + + service = make_service(metadata, mock_devices, mock_folders) + await service.phase_device_lists(conn, team) + + all_device_sets = [ + call.args[1] for call in mock_folders.set_folder_devices.call_args_list + ] + combined = set().union(*all_device_sets) + assert "DEV-A" in combined + assert "DEV-B" in combined + + @pytest.mark.asyncio + async def test_skips_removed_projects(self, conn, metadata, mock_devices, mock_folders): + """REMOVED project folders are skipped — set_folder_devices not called.""" + team = seed_team(conn) + seed_project(conn, git_identity="owner/repo", status=SharedProjectStatus.REMOVED) + + service = make_service(metadata, mock_devices, mock_folders) + await service.phase_device_lists(conn, team) + + mock_folders.set_folder_devices.assert_not_called() + + @pytest.mark.asyncio + async def test_excludes_inactive_member_from_device_list( + self, conn, metadata, mock_devices, mock_folders + ): + """Member with ADDED (not active) status is excluded from desired set.""" + team = seed_team(conn) + seed_project(conn, git_identity="owner/repo") + # Member in ADDED state + m = Member.from_member_tag( + member_tag=PEER_TAG, team_name=TEAM, device_id=PEER_DEVICE, + status=MemberStatus.ADDED, + ) + MemberRepository().save(conn, m) + seed_subscription(conn, PEER_TAG, git_identity="owner/repo", + status=SubscriptionStatus.ACCEPTED, direction=SyncDirection.BOTH) + + service = make_service(metadata, mock_devices, mock_folders) + await service.phase_device_lists(conn, team) + + all_device_sets = [ + call.args[1] for call in mock_folders.set_folder_devices.call_args_list + ] + for ds in all_device_sets: + assert PEER_DEVICE not in ds + + +# --------------------------------------------------------------------------- +# TestRunCycle +# --------------------------------------------------------------------------- + + +class TestRunCycle: + @pytest.mark.asyncio + async def test_run_cycle_processes_all_teams( + self, conn, metadata, mock_devices, mock_folders + ): + """run_cycle iterates over all teams.""" + TeamRepository().save(conn, Team(name="t1", leader_device_id="D1", leader_member_tag="u.m1")) + TeamRepository().save(conn, Team(name="t2", leader_device_id="D2", leader_member_tag="u.m2")) + + service = make_service(metadata, mock_devices, mock_folders) + # Should complete without errors for teams with no metadata / members / projects + await service.run_cycle(conn) + + @pytest.mark.asyncio + async def test_run_cycle_empty_teams_no_error( + self, conn, metadata, mock_devices, mock_folders + ): + """run_cycle with no teams completes silently.""" + service = make_service(metadata, mock_devices, mock_folders) + await service.run_cycle(conn) + mock_folders.set_folder_devices.assert_not_called() + mock_devices.ensure_paired.assert_not_called() diff --git a/api/tests/test_remote_roundtrip.py b/api/tests/test_remote_roundtrip.py new file mode 100644 index 00000000..7a8ad463 --- /dev/null +++ b/api/tests/test_remote_roundtrip.py @@ -0,0 +1,245 @@ +""" +End-to-end roundtrip test: remote session with ALL resources → +find_remote_session() → verify data → index_remote_sessions() → verify SQLite. +""" + +import json +import sqlite3 +from pathlib import Path +from unittest.mock import patch + +import pytest + +from db.indexer import index_remote_sessions +from db.schema import ensure_schema +from services.remote_sessions import find_remote_session + + +def _make_full_jsonl(uuid: str) -> str: + """Build JSONL with user + assistant messages.""" + lines = [ + json.dumps({ + "type": "user", + "uuid": f"msg-{uuid}", + "message": {"role": "user", "content": "Build feature X"}, + "timestamp": "2026-03-03T12:00:00.000Z", + "sessionId": "roundtrip-slug", + }), + json.dumps({ + "type": "assistant", + "uuid": f"resp-{uuid}", + "message": { + "role": "assistant", + "content": [{"type": "text", "text": "On it."}], + "model": "claude-sonnet-4-20250514", + "usage": {"input_tokens": 100, "output_tokens": 50}, + }, + "timestamp": "2026-03-03T12:00:05.000Z", + }), + ] + return "\n".join(lines) + "\n" + + +@pytest.fixture +def full_roundtrip_env(tmp_path): + """Create a complete roundtrip environment with all resource types.""" + karma_base = tmp_path / ".claude_karma" + karma_base.mkdir() + + user_id = "alice" + encoded = "-Users-alice-acme" + uuid = "roundtrip-001" + + alice_dir = karma_base / "remote-sessions" / user_id / encoded + sessions_dir = alice_dir / "sessions" + sessions_dir.mkdir(parents=True) + + # JSONL + (sessions_dir / f"{uuid}.jsonl").write_text(_make_full_jsonl(uuid)) + + # Subagent + sub_dir = sessions_dir / uuid / "subagents" + sub_dir.mkdir(parents=True) + (sub_dir / "agent-aaa.jsonl").write_text( + json.dumps({ + "type": "user", + "message": {"role": "user", "content": "sub task"}, + "timestamp": "2026-03-03T12:01:00Z", + }) + + "\n" + ) + + # Tool result + tr_dir = sessions_dir / uuid / "tool-results" + tr_dir.mkdir(parents=True) + (tr_dir / "toolu_xyz.txt").write_text("file content here") + + # Todos + todos_dir = alice_dir / "todos" + todos_dir.mkdir() + (todos_dir / f"{uuid}-item.json").write_text( + json.dumps([{"content": "Fix bug", "status": "pending"}]) + ) + + # Tasks + task_dir = alice_dir / "tasks" / uuid + task_dir.mkdir(parents=True) + (task_dir / "1.json").write_text( + json.dumps({ + "id": "1", + "subject": "Parse CLI args", + "description": "Implement argument parsing", + "status": "in_progress", + }) + ) + + # File-history + fh_dir = alice_dir / "file-history" / uuid + fh_dir.mkdir(parents=True) + (fh_dir / "snapshot.json").write_text('{"file": "main.py"}') + + # Debug log + debug_dir = alice_dir / "debug" + debug_dir.mkdir() + (debug_dir / f"{uuid}.txt").write_text("DEBUG: started") + + # Sync config (local user != alice) + (karma_base / "sync-config.json").write_text( + json.dumps({"user_id": "local-me", "machine_id": "my-mac"}) + ) + + return { + "karma_base": karma_base, + "user_id": user_id, + "encoded": encoded, + "uuid": uuid, + } + + +@pytest.fixture(autouse=True) +def _clear_cache(): + """Clear caches before each test.""" + import services.remote_sessions as mod + + mod._local_user_cache = None + mod._local_user_cache_time = 0.0 + mod._project_mapping_cache = None + mod._project_mapping_cache_time = 0.0 + yield + mod._local_user_cache = None + mod._local_user_cache_time = 0.0 + mod._project_mapping_cache = None + mod._project_mapping_cache_time = 0.0 + + +class TestFullRoundtrip: + def test_find_remote_session_resolves_all_resources(self, full_roundtrip_env): + """find_remote_session should resolve all resource types.""" + env = full_roundtrip_env + + with patch("services.remote_sessions.settings") as mock_settings: + mock_settings.karma_base = env["karma_base"] + result = find_remote_session(env["uuid"]) + + assert result is not None + assert result.user_id == "alice" + + session = result.session + assert session.message_count >= 2 + + # All resource types accessible + assert len(session.list_todos()) >= 1 + assert len(session.list_tasks()) >= 1 + assert len(session.list_subagents()) >= 1 + assert len(session.list_tool_results()) >= 1 + assert session.has_file_history is True + assert session.has_debug_log is True + assert "DEBUG: started" in session.read_debug_log() + + def test_indexer_picks_up_remote_session(self, full_roundtrip_env): + """index_remote_sessions should index the session into SQLite.""" + from unittest.mock import PropertyMock + + from config import Settings + + env = full_roundtrip_env + + conn = sqlite3.connect(":memory:") + conn.row_factory = sqlite3.Row + ensure_schema(conn) + + with ( + patch.object( + Settings, "karma_base", + new_callable=PropertyMock, return_value=env["karma_base"], + ), + patch("services.remote_sessions.get_project_mapping", return_value={}), + ): + stats = index_remote_sessions(conn) + + assert stats["indexed"] >= 1 + assert stats["errors"] == 0 + + # Verify indexed data + row = conn.execute( + "SELECT * FROM sessions WHERE uuid = ?", (env["uuid"],) + ).fetchone() + assert row is not None + assert row["source"] == "remote" + assert row["remote_user_id"] == "alice" + assert row["message_count"] >= 2 + + conn.close() + + def test_full_pipeline(self, full_roundtrip_env): + """Full pipeline: find → verify resources → index → verify DB row.""" + from unittest.mock import PropertyMock + + from config import Settings + + env = full_roundtrip_env + + # Step 1: Find and verify session + with patch("services.remote_sessions.settings") as mock_settings: + mock_settings.karma_base = env["karma_base"] + result = find_remote_session(env["uuid"]) + + assert result is not None + session = result.session + + # Verify all resources + assert session.message_count >= 2 + assert len(session.list_todos()) >= 1 + assert len(session.list_tasks()) >= 1 + assert len(session.list_subagents()) >= 1 + assert session.has_file_history is True + assert session.has_debug_log is True + + # Step 2: Index into SQLite + conn = sqlite3.connect(":memory:") + conn.row_factory = sqlite3.Row + ensure_schema(conn) + + with ( + patch.object( + Settings, "karma_base", + new_callable=PropertyMock, return_value=env["karma_base"], + ), + patch("services.remote_sessions.get_project_mapping", return_value={}), + ): + stats = index_remote_sessions(conn) + + # Step 3: Verify DB row + assert stats["indexed"] >= 1 + assert stats["errors"] == 0 + + row = conn.execute( + "SELECT * FROM sessions WHERE uuid = ?", (env["uuid"],) + ).fetchone() + assert row is not None + assert row["source"] == "remote" + assert row["remote_user_id"] == "alice" + assert row["message_count"] >= 2 + assert row["project_encoded_name"] == env["encoded"] + + conn.close() diff --git a/api/tests/test_remote_sessions.py b/api/tests/test_remote_sessions.py new file mode 100644 index 00000000..96fe0b91 --- /dev/null +++ b/api/tests/test_remote_sessions.py @@ -0,0 +1,942 @@ +"""Tests for remote session service and filtering.""" + +import json +from pathlib import Path +from unittest.mock import patch + +import pytest + +from services.remote_sessions import ( + _is_local_user, + _resolve_user_id, + find_remote_session, + get_project_mapping, + iter_all_remote_session_metadata, + list_remote_sessions_for_project, +) +from services.session_filter import SessionFilter, SessionMetadata, SessionSource + +# ============================================================================ +# Fixtures +# ============================================================================ + + +def _make_session_jsonl(uuid: str, prompt: str = "hello") -> str: + """Build minimal valid JSONL for a session.""" + lines = [ + json.dumps( + { + "type": "user", + "uuid": f"msg-{uuid}", + "message": {"role": "user", "content": prompt}, + "timestamp": "2026-03-03T12:00:00.000Z", + } + ), + json.dumps( + { + "type": "assistant", + "uuid": f"resp-{uuid}", + "message": {"role": "assistant", "content": [{"type": "text", "text": "ok"}]}, + "timestamp": "2026-03-03T12:00:01.000Z", + } + ), + ] + return "\n".join(lines) + "\n" + + +@pytest.fixture +def karma_base(tmp_path: Path) -> Path: + """Create fake karma base directory with remote sessions. + + Directory structure matches what Syncthing sync produces: + remote-sessions/{user_id}/{encoded_name}/sessions/{uuid}.jsonl + + The local user's outbox is at remote-sessions/jayant/ and should be skipped. + Remote users' inboxes use the LOCAL encoded name. + """ + karma = tmp_path / ".claude_karma" + karma.mkdir() + + local_encoded = "-Users-jayant-acme" + + # Alice's sessions (inbox from alice) + alice_sessions = karma / "remote-sessions" / "alice" / local_encoded / "sessions" + alice_sessions.mkdir(parents=True) + (alice_sessions / "sess-001.jsonl").write_text(_make_session_jsonl("001", "hello")) + (alice_sessions / "sess-002.jsonl").write_text(_make_session_jsonl("002", "build X")) + + # Bob's sessions (inbox from bob) + bob_sessions = karma / "remote-sessions" / "bob" / local_encoded / "sessions" + bob_sessions.mkdir(parents=True) + (bob_sessions / "sess-003.jsonl").write_text(_make_session_jsonl("003", "fix bug")) + + # Local user's outbox (should be skipped by the service) + jayant_sessions = karma / "remote-sessions" / "jayant" / local_encoded / "sessions" + jayant_sessions.mkdir(parents=True) + (jayant_sessions / "sess-local.jsonl").write_text(_make_session_jsonl("local", "my session")) + + # sync-config.json — Syncthing format + sync_config = { + "user_id": "jayant", + "machine_id": "Jayants-MacBook-Pro.local", + "teams": { + "my-team": { + "backend": "syncthing", + "projects": { + "acme": { + "path": "/Users/jayant/acme", + "encoded_name": local_encoded, + } + }, + "syncthing_members": { + "alice": {"syncthing_device_id": "ALICE-DEVICE-ID"}, + "bob": {"syncthing_device_id": "BOB-DEVICE-ID"}, + }, + } + }, + } + (karma / "sync-config.json").write_text(json.dumps(sync_config)) + + return karma + + +@pytest.fixture +def karma_base_legacy(tmp_path: Path) -> Path: + """Create karma base with legacy paths-based config (for backwards compat).""" + karma = tmp_path / ".claude_karma_legacy" + karma.mkdir() + + local_encoded = "-Users-jayant-acme" + + # Alice's sessions + alice_sessions = karma / "remote-sessions" / "alice" / local_encoded / "sessions" + alice_sessions.mkdir(parents=True) + (alice_sessions / "sess-001.jsonl").write_text(_make_session_jsonl("001", "hello")) + + # sync-config.json — legacy paths format + sync_config = { + "local_user_id": "jayant", + "teams": { + "my-team": { + "projects": { + "acme": { + "paths": { + "jayant": "-Users-jayant-acme", + "alice": "-Users-alice-acme", + "bob": "-Users-bob-acme", + } + } + } + } + }, + } + (karma / "sync-config.json").write_text(json.dumps(sync_config)) + + return karma + + +@pytest.fixture(autouse=True) +def _clear_cache(): + """Clear caches before each test.""" + import services.remote_sessions as mod + + mod._local_user_cache = None + mod._local_user_cache_time = 0.0 + mod._project_mapping_cache = None + mod._project_mapping_cache_time = 0.0 + mod._manifest_worktree_cache = {} + mod._titles_cache = {} + mod._resolved_user_cache = {} + yield + mod._local_user_cache = None + mod._local_user_cache_time = 0.0 + mod._project_mapping_cache = None + mod._project_mapping_cache_time = 0.0 + mod._manifest_worktree_cache = {} + mod._titles_cache = {} + mod._resolved_user_cache = {} + + +# ============================================================================ +# Tests: get_project_mapping +# ============================================================================ + + +class TestGetProjectMapping: + def test_returns_mapping_syncthing_format(self, karma_base): + with patch("services.remote_sessions.settings") as mock_settings: + mock_settings.karma_base = karma_base + mapping = get_project_mapping() + + # Syncthing members mapped to local encoded name + assert mapping[("alice", "-Users-jayant-acme")] == "-Users-jayant-acme" + assert mapping[("bob", "-Users-jayant-acme")] == "-Users-jayant-acme" + + def test_excludes_local_user(self, karma_base): + with patch("services.remote_sessions.settings") as mock_settings: + mock_settings.karma_base = karma_base + mapping = get_project_mapping() + + # Local user should NOT appear in mapping + assert ("jayant", "-Users-jayant-acme") not in mapping + + def test_returns_mapping_legacy_paths_format(self, karma_base_legacy): + with patch("services.remote_sessions.settings") as mock_settings: + mock_settings.karma_base = karma_base_legacy + mapping = get_project_mapping() + + assert mapping[("alice", "-Users-alice-acme")] == "-Users-jayant-acme" + assert mapping[("bob", "-Users-bob-acme")] == "-Users-jayant-acme" + + def test_returns_empty_when_no_config(self, tmp_path): + with patch("services.remote_sessions.settings") as mock_settings: + mock_settings.karma_base = tmp_path + mapping = get_project_mapping() + + assert mapping == {} + + def test_caches_result(self, karma_base): + with patch("services.remote_sessions.settings") as mock_settings: + mock_settings.karma_base = karma_base + mapping1 = get_project_mapping() + mapping2 = get_project_mapping() + + assert mapping1 is mapping2 # Same object = cached + + +# ============================================================================ +# Tests: find_remote_session +# ============================================================================ + + +class TestFindRemoteSession: + def test_finds_existing_session(self, karma_base): + with patch("services.remote_sessions.settings") as mock_settings: + mock_settings.karma_base = karma_base + result = find_remote_session("sess-001") + + assert result is not None + assert result.user_id == "alice" + assert result.local_encoded_name == "-Users-jayant-acme" + + def test_finds_session_from_different_user(self, karma_base): + with patch("services.remote_sessions.settings") as mock_settings: + mock_settings.karma_base = karma_base + result = find_remote_session("sess-003") + + assert result is not None + assert result.user_id == "bob" + + def test_skips_local_user_outbox(self, karma_base): + """Sessions in local user's outbox should NOT be found.""" + with patch("services.remote_sessions.settings") as mock_settings: + mock_settings.karma_base = karma_base + result = find_remote_session("sess-local") + + assert result is None + + def test_returns_none_for_missing_session(self, karma_base): + with patch("services.remote_sessions.settings") as mock_settings: + mock_settings.karma_base = karma_base + result = find_remote_session("nonexistent-uuid") + + assert result is None + + def test_returns_none_when_no_remote_dir(self, tmp_path): + with patch("services.remote_sessions.settings") as mock_settings: + mock_settings.karma_base = tmp_path + result = find_remote_session("sess-001") + + assert result is None + + +# ============================================================================ +# Tests: list_remote_sessions_for_project +# ============================================================================ + + +class TestListRemoteSessionsForProject: + def test_lists_sessions_for_project(self, karma_base): + with patch("services.remote_sessions.settings") as mock_settings: + mock_settings.karma_base = karma_base + results = list_remote_sessions_for_project("-Users-jayant-acme") + + # Should find Alice's 2 sessions + Bob's 1 session (NOT local user's) + assert len(results) == 3 + uuids = {r.uuid for r in results} + assert uuids == {"sess-001", "sess-002", "sess-003"} + + def test_excludes_local_user_outbox(self, karma_base): + with patch("services.remote_sessions.settings") as mock_settings: + mock_settings.karma_base = karma_base + results = list_remote_sessions_for_project("-Users-jayant-acme") + + uuids = {r.uuid for r in results} + assert "sess-local" not in uuids + + def test_all_results_have_remote_source(self, karma_base): + with patch("services.remote_sessions.settings") as mock_settings: + mock_settings.karma_base = karma_base + results = list_remote_sessions_for_project("-Users-jayant-acme") + + for meta in results: + assert meta.source == "remote" + assert meta.remote_user_id is not None + assert meta.remote_machine_id is not None + + def test_returns_empty_for_unknown_project(self, karma_base): + with patch("services.remote_sessions.settings") as mock_settings: + mock_settings.karma_base = karma_base + results = list_remote_sessions_for_project("-Users-jayant-unknown") + + assert results == [] + + def test_returns_empty_when_no_remote_dir(self, tmp_path): + with patch("services.remote_sessions.settings") as mock_settings: + mock_settings.karma_base = tmp_path + results = list_remote_sessions_for_project("-Users-jayant-acme") + + assert results == [] + + +# ============================================================================ +# Tests: iter_all_remote_session_metadata +# ============================================================================ + + +class TestIterAllRemoteSessionMetadata: + def test_yields_all_remote_sessions(self, karma_base): + with patch("services.remote_sessions.settings") as mock_settings: + mock_settings.karma_base = karma_base + results = list(iter_all_remote_session_metadata()) + + # 3 remote sessions (NOT the local user's outbox session) + assert len(results) == 3 + uuids = {r.uuid for r in results} + assert uuids == {"sess-001", "sess-002", "sess-003"} + + def test_excludes_local_user_outbox(self, karma_base): + with patch("services.remote_sessions.settings") as mock_settings: + mock_settings.karma_base = karma_base + results = list(iter_all_remote_session_metadata()) + + uuids = {r.uuid for r in results} + assert "sess-local" not in uuids + + def test_yields_correct_user_ids(self, karma_base): + with patch("services.remote_sessions.settings") as mock_settings: + mock_settings.karma_base = karma_base + results = list(iter_all_remote_session_metadata()) + + user_ids = {r.remote_user_id for r in results} + assert user_ids == {"alice", "bob"} + + def test_yields_nothing_when_no_remote_dir(self, tmp_path): + with patch("services.remote_sessions.settings") as mock_settings: + mock_settings.karma_base = tmp_path + results = list(iter_all_remote_session_metadata()) + + assert results == [] + + +# ============================================================================ +# Tests: SessionFilter source filtering +# ============================================================================ + + +class TestSessionFilterSource: + def _make_meta(self, uuid: str, source: str = "local", user_id: str = None) -> SessionMetadata: + return SessionMetadata( + uuid=uuid, + encoded_name="-Users-jayant-acme", + project_path="/Users/jayant/acme", + message_count=5, + start_time=None, + end_time=None, + slug=None, + initial_prompt=None, + git_branch=None, + source=source, + remote_user_id=user_id, + remote_machine_id="mbp" if user_id else None, + ) + + def test_source_all_returns_everything(self): + filt = SessionFilter(source=SessionSource.ALL) + local = self._make_meta("s1", source="local") + remote = self._make_meta("s2", source="remote", user_id="alice") + assert filt.matches_metadata(local) + assert filt.matches_metadata(remote) + + def test_source_local_excludes_remote(self): + filt = SessionFilter(source=SessionSource.LOCAL) + local = self._make_meta("s1", source="local") + remote = self._make_meta("s2", source="remote", user_id="alice") + assert filt.matches_metadata(local) + assert not filt.matches_metadata(remote) + + def test_source_remote_excludes_local(self): + filt = SessionFilter(source=SessionSource.REMOTE) + local = self._make_meta("s1", source="local") + remote = self._make_meta("s2", source="remote", user_id="alice") + assert not filt.matches_metadata(local) + assert filt.matches_metadata(remote) + + def test_none_source_treated_as_local(self): + filt = SessionFilter(source=SessionSource.LOCAL) + meta = self._make_meta("s1", source=None) + assert filt.matches_metadata(meta) + + +# ============================================================================ +# Tests: Schema migration +# ============================================================================ + + +class TestRemoteSessionSubagentAccess: + def test_subagent_dir_resolves_correctly(self, karma_base): + """Subagent files should be findable from remote session paths.""" + # Add a subagent file alongside a remote session + alice_sessions = ( + karma_base / "remote-sessions" / "alice" / "-Users-jayant-acme" / "sessions" + ) + sub_dir = alice_sessions / "sess-001" / "subagents" + sub_dir.mkdir(parents=True) + (sub_dir / "agent-abc.jsonl").write_text( + json.dumps( + { + "type": "user", + "message": {"role": "user", "content": "sub task"}, + "timestamp": "2026-03-03T12:00:00Z", + } + ) + + "\n" + ) + + with patch("services.remote_sessions.settings") as mock_settings: + mock_settings.karma_base = karma_base + result = find_remote_session("sess-001") + + assert result is not None + session = result.session + # subagents_dir should point to the correct location + assert session.subagents_dir == sub_dir + assert session.subagents_dir.exists() + agents = session.list_subagents() + assert len(agents) >= 1 + + +class TestRemoteSessionTodos: + def test_todos_resolve_for_remote_session(self, karma_base): + """Todos packaged into remote staging dir should be loadable.""" + encoded = "-Users-jayant-acme" + alice_dir = karma_base / "remote-sessions" / "alice" / encoded + + sessions_dir = alice_dir / "sessions" + sessions_dir.mkdir(parents=True, exist_ok=True) + (sessions_dir / "sess-todo-001.jsonl").write_text( + _make_session_jsonl("todo-001") + ) + + # Create todo file in staging structure + todos_dir = alice_dir / "todos" + todos_dir.mkdir(parents=True, exist_ok=True) + (todos_dir / "sess-todo-001-task1.json").write_text( + json.dumps([{ + "content": "Fix the bug", + "status": "in_progress", + }]) + ) + + with patch("services.remote_sessions.settings") as mock_settings: + mock_settings.karma_base = karma_base + result = find_remote_session("sess-todo-001") + + assert result is not None + session = result.session + + # Verify todos_dir points to correct location + assert session.todos_dir == todos_dir + assert session.todos_dir.exists() + + # Verify todos are loadable + todos = session.list_todos() + assert len(todos) >= 1 + assert todos[0].content == "Fix the bug" + + +class TestRemoteSessionTasks: + def test_tasks_resolve_for_remote_session(self, karma_base): + """Tasks packaged into remote staging dir should be loadable.""" + encoded = "-Users-jayant-acme" + alice_dir = karma_base / "remote-sessions" / "alice" / encoded + + sessions_dir = alice_dir / "sessions" + sessions_dir.mkdir(parents=True, exist_ok=True) + (sessions_dir / "sess-task-001.jsonl").write_text( + _make_session_jsonl("task-001") + ) + + # Create task files in staging structure + task_dir = alice_dir / "tasks" / "sess-task-001" + task_dir.mkdir(parents=True) + (task_dir / "1.json").write_text( + json.dumps({ + "id": "1", + "subject": "Implement feature", + "description": "Build the thing", + "status": "in_progress", + }) + ) + + with patch("services.remote_sessions.settings") as mock_settings: + mock_settings.karma_base = karma_base + result = find_remote_session("sess-task-001") + + assert result is not None + session = result.session + + assert session.tasks_dir == task_dir + assert session.tasks_dir.exists() + + tasks = session.list_tasks() + assert len(tasks) >= 1 + + +class TestRemoteSessionToolResults: + def test_tool_results_resolve_for_remote_session(self, karma_base): + """Tool result files packaged alongside JSONL should be accessible.""" + encoded = "-Users-jayant-acme" + alice_sessions = ( + karma_base / "remote-sessions" / "alice" / encoded / "sessions" + ) + alice_sessions.mkdir(parents=True, exist_ok=True) + + (alice_sessions / "sess-tr-001.jsonl").write_text( + _make_session_jsonl("tr-001") + ) + + # Create tool-results directory + tr_dir = alice_sessions / "sess-tr-001" / "tool-results" + tr_dir.mkdir(parents=True) + (tr_dir / "toolu_abc123.txt").write_text("Tool output here") + + with patch("services.remote_sessions.settings") as mock_settings: + mock_settings.karma_base = karma_base + result = find_remote_session("sess-tr-001") + + assert result is not None + session = result.session + assert session.tool_results_dir == tr_dir + assert session.tool_results_dir.exists() + + tool_results = session.list_tool_results() + assert len(tool_results) >= 1 + + +class TestRemoteSessionFileHistory: + def test_file_history_resolves_for_remote_session(self, karma_base): + """File-history packaged into remote staging should be accessible.""" + encoded = "-Users-jayant-acme" + alice_dir = karma_base / "remote-sessions" / "alice" / encoded + + sessions_dir = alice_dir / "sessions" + sessions_dir.mkdir(parents=True, exist_ok=True) + (sessions_dir / "sess-fh-001.jsonl").write_text( + _make_session_jsonl("fh-001") + ) + + # Create file-history in staging structure + fh_dir = alice_dir / "file-history" / "sess-fh-001" + fh_dir.mkdir(parents=True) + (fh_dir / "snapshot.json").write_text('{"file": "main.py"}') + + with patch("services.remote_sessions.settings") as mock_settings: + mock_settings.karma_base = karma_base + result = find_remote_session("sess-fh-001") + + assert result is not None + session = result.session + assert session.file_history_dir == fh_dir + assert session.has_file_history is True + + +class TestRemoteSessionDebugLog: + def test_debug_log_resolves_for_remote_session(self, karma_base): + """Debug logs packaged into remote staging should be readable.""" + encoded = "-Users-jayant-acme" + alice_dir = karma_base / "remote-sessions" / "alice" / encoded + + sessions_dir = alice_dir / "sessions" + sessions_dir.mkdir(parents=True, exist_ok=True) + (sessions_dir / "sess-dbg-001.jsonl").write_text( + _make_session_jsonl("dbg-001") + ) + + debug_dir = alice_dir / "debug" + debug_dir.mkdir(parents=True) + (debug_dir / "sess-dbg-001.txt").write_text("DEBUG: started") + + with patch("services.remote_sessions.settings") as mock_settings: + mock_settings.karma_base = karma_base + result = find_remote_session("sess-dbg-001") + + assert result is not None + session = result.session + assert session.has_debug_log is True + assert session.read_debug_log() == "DEBUG: started" + + +class TestRemoteSessionMissingResources: + def test_missing_todos_returns_empty(self, karma_base): + """Remote session without todos dir should return empty list.""" + encoded = "-Users-jayant-acme" + alice_dir = karma_base / "remote-sessions" / "alice" / encoded + sessions_dir = alice_dir / "sessions" + sessions_dir.mkdir(parents=True, exist_ok=True) + (sessions_dir / "sess-empty-001.jsonl").write_text( + _make_session_jsonl("empty-001") + ) + + with patch("services.remote_sessions.settings") as mock_settings: + mock_settings.karma_base = karma_base + result = find_remote_session("sess-empty-001") + + session = result.session + assert session.list_todos() == [] + assert session.list_tasks() == [] + assert session.has_file_history is False + assert session.has_debug_log is False + + +class TestSchemaMigration: + def test_schema_v17_adds_remote_columns(self): + import sqlite3 + + from db.schema import SCHEMA_VERSION, ensure_schema + + assert SCHEMA_VERSION >= 13 # v13 added remote columns; now at v17+ + + conn = sqlite3.connect(":memory:") + conn.row_factory = sqlite3.Row + ensure_schema(conn) + + cols = {r[1] for r in conn.execute("PRAGMA table_info(sessions)").fetchall()} + assert "source" in cols + assert "remote_user_id" in cols + assert "remote_machine_id" in cols + + indexes = {r[1] for r in conn.execute("PRAGMA index_list(sessions)").fetchall()} + assert "idx_sessions_source" in indexes + + conn.close() + + +# ============================================================================ +# Tests: SessionSummary schema +# ============================================================================ + + +class TestSessionSummaryRemoteFields: + def test_schema_accepts_remote_fields(self): + from schemas import SessionSummary + + s = SessionSummary( + uuid="test", + message_count=1, + source="remote", + remote_user_id="alice", + remote_machine_id="alice-mbp", + ) + assert s.source == "remote" + assert s.remote_user_id == "alice" + assert s.remote_machine_id == "alice-mbp" + + def test_schema_defaults_none(self): + from schemas import SessionSummary + + s = SessionSummary(uuid="test", message_count=1) + assert s.source is None + assert s.remote_user_id is None + assert s.remote_machine_id is None + + +# ============================================================================ +# Tests: Remote session titles +# ============================================================================ + + +class TestRemoteSessionTitles: + def test_loads_title_from_titles_json(self, karma_base): + """Sessions should have session_titles populated from titles.json.""" + # Write titles.json into alice's inbox + titles_dir = karma_base / "remote-sessions" / "alice" / "-Users-jayant-acme" + titles_data = { + "version": 1, + "titles": { + "sess-001": {"title": "Refactor auth module", "source": "git", "generated_at": "2026-03-08T12:00:00Z"}, + "sess-002": {"title": "Build new dashboard", "source": "haiku", "generated_at": "2026-03-08T13:00:00Z"}, + }, + } + (titles_dir / "titles.json").write_text(json.dumps(titles_data)) + + with patch("services.remote_sessions.settings") as mock_settings: + mock_settings.karma_base = karma_base + results = list_remote_sessions_for_project("-Users-jayant-acme") + + # Find alice's sessions and check titles + by_uuid = {r.uuid: r for r in results} + assert by_uuid["sess-001"].session_titles == ["Refactor auth module"] + assert by_uuid["sess-002"].session_titles == ["Build new dashboard"] + # Bob has no titles.json, so his session should have no titles + assert by_uuid["sess-003"].session_titles is None + + def test_handles_missing_titles_json(self, karma_base): + """Sessions should still work without titles.json (backward compat).""" + with patch("services.remote_sessions.settings") as mock_settings: + mock_settings.karma_base = karma_base + results = list_remote_sessions_for_project("-Users-jayant-acme") + + # All sessions should have session_titles=None (no titles.json exists) + for meta in results: + assert meta.session_titles is None + + def test_iter_all_includes_titles(self, karma_base): + """iter_all_remote_session_metadata() should also include titles.""" + # Write titles.json for alice + titles_dir = karma_base / "remote-sessions" / "alice" / "-Users-jayant-acme" + titles_data = { + "version": 1, + "titles": { + "sess-001": {"title": "Refactor auth module", "source": "git", "generated_at": "2026-03-08T12:00:00Z"}, + }, + } + (titles_dir / "titles.json").write_text(json.dumps(titles_data)) + + with patch("services.remote_sessions.settings") as mock_settings: + mock_settings.karma_base = karma_base + results = list(iter_all_remote_session_metadata()) + + by_uuid = {r.uuid: r for r in results} + assert by_uuid["sess-001"].session_titles == ["Refactor auth module"] + # sess-002 has no title entry + assert by_uuid["sess-002"].session_titles is None + # Bob's session has no titles.json at all + assert by_uuid["sess-003"].session_titles is None + + +# ============================================================================ +# Tests: member_tag directory support +# ============================================================================ + + +@pytest.fixture +def karma_base_member_tag(tmp_path: Path) -> Path: + """Create karma base with member_tag directory names. + + Uses ``{user_id}.{machine_tag}`` format for remote user directories, + mixing with bare user_id directories for backward compatibility. + """ + karma = tmp_path / ".claude_karma_mt" + karma.mkdir() + + local_encoded = "-Users-jayant-acme" + + # Alice with member_tag directory (alice.macbook-pro) + alice_sessions = ( + karma / "remote-sessions" / "alice.macbook-pro" / local_encoded / "sessions" + ) + alice_sessions.mkdir(parents=True) + (alice_sessions / "sess-mt-001.jsonl").write_text( + _make_session_jsonl("mt-001", "member tag session") + ) + + # Bob with bare user_id directory (legacy) + bob_sessions = karma / "remote-sessions" / "bob" / local_encoded / "sessions" + bob_sessions.mkdir(parents=True) + (bob_sessions / "sess-mt-002.jsonl").write_text( + _make_session_jsonl("mt-002", "bare user session") + ) + + # Local user with member_tag directory (jayant.mac-mini) + jayant_sessions = ( + karma / "remote-sessions" / "jayant.mac-mini" / local_encoded / "sessions" + ) + jayant_sessions.mkdir(parents=True) + (jayant_sessions / "sess-mt-local.jsonl").write_text( + _make_session_jsonl("mt-local", "local outbox") + ) + + # Local user with bare directory too (jayant) + jayant_bare = karma / "remote-sessions" / "jayant" / local_encoded / "sessions" + jayant_bare.mkdir(parents=True) + (jayant_bare / "sess-mt-local2.jsonl").write_text( + _make_session_jsonl("mt-local2", "local outbox bare") + ) + + # sync-config.json + sync_config = { + "user_id": "jayant", + "machine_id": "Jayants-Mac-mini.local", + "teams": { + "my-team": { + "backend": "syncthing", + "projects": { + "acme": { + "path": "/Users/jayant/acme", + "encoded_name": local_encoded, + } + }, + "syncthing_members": { + "alice.macbook-pro": {"syncthing_device_id": "ALICE-DEVICE-ID"}, + "bob": {"syncthing_device_id": "BOB-DEVICE-ID"}, + }, + } + }, + } + (karma / "sync-config.json").write_text(json.dumps(sync_config)) + + return karma + + +class TestIsLocalUser: + def test_bare_match(self): + assert _is_local_user("jayant", "jayant") is True + + def test_bare_no_match(self): + assert _is_local_user("alice", "jayant") is False + + def test_member_tag_match(self): + assert _is_local_user("jayant.mac-mini", "jayant") is True + + def test_member_tag_no_match(self): + assert _is_local_user("alice.macbook-pro", "jayant") is False + + def test_none_local_user(self): + assert _is_local_user("jayant", None) is False + + def test_empty_local_user(self): + assert _is_local_user("jayant", "") is False + + def test_dot_in_machine_tag_only(self): + # user_id "alice" with machine_tag "mbp.local" + assert _is_local_user("alice.mbp.local", "alice") is True + + def test_different_user_with_dot(self): + assert _is_local_user("bob.desktop", "jayant") is False + + +class TestResolveUserIdMemberTag: + def test_bare_dirname_no_manifest(self, tmp_path): + """Bare dir name without manifest returns the dir name.""" + user_dir = tmp_path / "alice" + user_dir.mkdir() + assert _resolve_user_id(user_dir) == "alice" + + def test_member_tag_dirname_no_manifest(self, tmp_path): + """member_tag dir name without manifest extracts user_id.""" + user_dir = tmp_path / "alice.macbook-pro" + user_dir.mkdir() + assert _resolve_user_id(user_dir) == "alice" + + def test_manifest_takes_precedence_over_member_tag(self, tmp_path): + """Manifest user_id wins over member_tag parsing.""" + user_dir = tmp_path / "hostname.local" + user_dir.mkdir() + project_dir = user_dir / "-Users-alice-proj" + project_dir.mkdir() + manifest = {"user_id": "alice", "device_id": "DEVICE-123"} + (project_dir / "manifest.json").write_text(json.dumps(manifest)) + assert _resolve_user_id(user_dir) == "alice" + + def test_hostname_with_multi_dots_not_treated_as_member_tag(self, tmp_path): + """alice.mbp.local is a hostname (machine_part has dots), not a member_tag. + _sanitize_machine_tag would produce 'mbp-local', not 'mbp.local'.""" + user_dir = tmp_path / "alice.mbp.local" + user_dir.mkdir() + # Dots in machine_part → not a valid sanitized machine_tag → treat as raw dirname + assert _resolve_user_id(user_dir) == "alice.mbp.local" + + +class TestFindRemoteSessionMemberTag: + def test_finds_session_in_member_tag_dir(self, karma_base_member_tag): + with patch("services.remote_sessions.settings") as mock_settings: + mock_settings.karma_base = karma_base_member_tag + result = find_remote_session("sess-mt-001") + + assert result is not None + assert result.user_id == "alice" + assert result.machine_id == "alice.macbook-pro" + + def test_finds_session_in_bare_dir(self, karma_base_member_tag): + with patch("services.remote_sessions.settings") as mock_settings: + mock_settings.karma_base = karma_base_member_tag + result = find_remote_session("sess-mt-002") + + assert result is not None + assert result.user_id == "bob" + assert result.machine_id == "bob" + + def test_skips_local_member_tag_outbox(self, karma_base_member_tag): + """Local user's member_tag dir (jayant.mac-mini) should be skipped.""" + with patch("services.remote_sessions.settings") as mock_settings: + mock_settings.karma_base = karma_base_member_tag + result = find_remote_session("sess-mt-local") + + assert result is None + + def test_skips_local_bare_outbox(self, karma_base_member_tag): + """Local user's bare dir (jayant) should also be skipped.""" + with patch("services.remote_sessions.settings") as mock_settings: + mock_settings.karma_base = karma_base_member_tag + result = find_remote_session("sess-mt-local2") + + assert result is None + + +class TestListRemoteSessionsMemberTag: + def test_lists_both_formats(self, karma_base_member_tag): + with patch("services.remote_sessions.settings") as mock_settings: + mock_settings.karma_base = karma_base_member_tag + results = list_remote_sessions_for_project("-Users-jayant-acme") + + # Should find alice.macbook-pro's session + bob's session (NOT local user's) + assert len(results) == 2 + uuids = {r.uuid for r in results} + assert uuids == {"sess-mt-001", "sess-mt-002"} + + def test_excludes_local_member_tag_and_bare(self, karma_base_member_tag): + with patch("services.remote_sessions.settings") as mock_settings: + mock_settings.karma_base = karma_base_member_tag + results = list_remote_sessions_for_project("-Users-jayant-acme") + + uuids = {r.uuid for r in results} + assert "sess-mt-local" not in uuids + assert "sess-mt-local2" not in uuids + + def test_user_id_resolved_from_member_tag(self, karma_base_member_tag): + with patch("services.remote_sessions.settings") as mock_settings: + mock_settings.karma_base = karma_base_member_tag + results = list_remote_sessions_for_project("-Users-jayant-acme") + + by_uuid = {r.uuid: r for r in results} + # alice.macbook-pro dir -> user_id resolved to "alice" + assert by_uuid["sess-mt-001"].remote_user_id == "alice" + # machine_id is the raw dir name + assert by_uuid["sess-mt-001"].remote_machine_id == "alice.macbook-pro" + # bob (bare) -> user_id stays "bob" + assert by_uuid["sess-mt-002"].remote_user_id == "bob" + + +class TestIterAllMemberTag: + def test_yields_both_formats_skips_local(self, karma_base_member_tag): + with patch("services.remote_sessions.settings") as mock_settings: + mock_settings.karma_base = karma_base_member_tag + results = list(iter_all_remote_session_metadata()) + + assert len(results) == 2 + uuids = {r.uuid for r in results} + assert uuids == {"sess-mt-001", "sess-mt-002"} + # No local user sessions + assert "sess-mt-local" not in uuids + assert "sess-mt-local2" not in uuids diff --git a/api/tests/test_remote_user_id_normalization.py b/api/tests/test_remote_user_id_normalization.py new file mode 100644 index 00000000..9ab6889d --- /dev/null +++ b/api/tests/test_remote_user_id_normalization.py @@ -0,0 +1,142 @@ +import sys +from pathlib import Path +sys.path.insert(0, str(Path(__file__).parent.parent)) + +import json +import sqlite3 +import pytest +from db.schema import ensure_schema +from domain.team import Team +from domain.member import Member, MemberStatus +from repositories.team_repo import TeamRepository +from repositories.member_repo import MemberRepository + + +@pytest.fixture +def conn(): + c = sqlite3.connect(":memory:") + c.row_factory = sqlite3.Row + c.execute("PRAGMA foreign_keys=ON") + ensure_schema(c) + return c + + +@pytest.fixture +def seeded_conn(conn): + TeamRepository().save(conn, Team(name="t1", leader_device_id="D1", leader_member_tag="jay.mac")) + MemberRepository().save(conn, Member( + team_name="t1", member_tag="jay.mac", device_id="D1", + user_id="jay", machine_tag="mac", status=MemberStatus.ACTIVE, + )) + return conn + + +class TestResolveUserIdNormalization: + def test_priority2_resolves_to_member_tag(self, seeded_conn, tmp_path): + """When manifest has user_id but no device_id match, resolve to member_tag via DB.""" + from services.remote_sessions import _resolve_user_id, _resolved_user_cache + _resolved_user_cache.clear() + + user_dir = tmp_path / "jay" + user_dir.mkdir() + proj_dir = user_dir / "project1" + proj_dir.mkdir() + manifest = {"user_id": "jay"} + (proj_dir / "manifest.json").write_text(json.dumps(manifest)) + + result = _resolve_user_id(user_dir, conn=seeded_conn) + assert result == "jay.mac" + + def test_priority3_resolves_dir_name_to_member_tag(self, seeded_conn, tmp_path): + """When no manifest exists and dir_name is a bare user_id, resolve via DB.""" + from services.remote_sessions import _resolve_user_id, _resolved_user_cache + _resolved_user_cache.clear() + + user_dir = tmp_path / "jay" + user_dir.mkdir() + + result = _resolve_user_id(user_dir, conn=seeded_conn) + assert result == "jay.mac" + + def test_unknown_user_id_stays_as_is(self, seeded_conn, tmp_path): + """When user_id has no DB match, keep as-is.""" + from services.remote_sessions import _resolve_user_id, _resolved_user_cache + _resolved_user_cache.clear() + + user_dir = tmp_path / "unknown" + user_dir.mkdir() + proj_dir = user_dir / "project1" + proj_dir.mkdir() + manifest = {"user_id": "unknown"} + (proj_dir / "manifest.json").write_text(json.dumps(manifest)) + + result = _resolve_user_id(user_dir, conn=seeded_conn) + assert result == "unknown" + + def test_already_member_tag_not_changed(self, seeded_conn, tmp_path): + """If resolved is already a member_tag (has dot), don't double-resolve.""" + from services.remote_sessions import _resolve_user_id, _resolved_user_cache + _resolved_user_cache.clear() + + user_dir = tmp_path / "jay.mac" + user_dir.mkdir() + + result = _resolve_user_id(user_dir, conn=seeded_conn) + # Should stay as-is or resolve to jay (existing Priority 3 logic) + # The final normalization block should NOT try to look up "jay.mac" + # as a user_id since it already contains a dot. + assert "." in result # Has dot — either jay.mac or resolved member_tag + + +class TestV20Migration: + def test_stale_remote_user_id_fixed(self, seeded_conn): + """v20 migration SQL normalizes bare user_id to member_tag.""" + seeded_conn.execute( + "INSERT INTO sessions (uuid, project_encoded_name, jsonl_mtime, source, remote_user_id) " + "VALUES ('s1', '-Users-me-repo', 1.0, 'remote', 'jay')" + ) + seeded_conn.commit() + + # Run the migration SQL directly + seeded_conn.execute(""" + UPDATE sessions SET remote_user_id = ( + SELECT m.member_tag FROM sync_members m + WHERE m.user_id = sessions.remote_user_id + LIMIT 1 + ) WHERE source = 'remote' + AND remote_user_id IS NOT NULL + AND remote_user_id NOT LIKE '%.%' + AND EXISTS ( + SELECT 1 FROM sync_members m + WHERE m.user_id = sessions.remote_user_id + ) + """) + seeded_conn.commit() + + row = seeded_conn.execute("SELECT remote_user_id FROM sessions WHERE uuid = 's1'").fetchone() + assert row[0] == "jay.mac" + + def test_already_normalized_not_touched(self, seeded_conn): + """Sessions with member_tag format are left unchanged.""" + seeded_conn.execute( + "INSERT INTO sessions (uuid, project_encoded_name, jsonl_mtime, source, remote_user_id) " + "VALUES ('s2', '-Users-me-repo', 1.0, 'remote', 'jay.mac')" + ) + seeded_conn.commit() + + seeded_conn.execute(""" + UPDATE sessions SET remote_user_id = ( + SELECT m.member_tag FROM sync_members m + WHERE m.user_id = sessions.remote_user_id + LIMIT 1 + ) WHERE source = 'remote' + AND remote_user_id IS NOT NULL + AND remote_user_id NOT LIKE '%.%' + AND EXISTS ( + SELECT 1 FROM sync_members m + WHERE m.user_id = sessions.remote_user_id + ) + """) + + row = seeded_conn.execute("SELECT remote_user_id FROM sessions WHERE uuid = 's2'").fetchone() + assert row[0] == "jay.mac" diff --git a/api/tests/test_repo_event.py b/api/tests/test_repo_event.py new file mode 100644 index 00000000..1767d7bc --- /dev/null +++ b/api/tests/test_repo_event.py @@ -0,0 +1,115 @@ +import sys +from pathlib import Path +sys.path.insert(0, str(Path(__file__).parent.parent)) + +import sqlite3 +import pytest +from db.schema import ensure_schema +from domain.events import SyncEvent, SyncEventType +from repositories.event_repo import EventRepository + + +@pytest.fixture +def conn(): + c = sqlite3.connect(":memory:") + c.row_factory = sqlite3.Row + c.execute("PRAGMA foreign_keys=ON") + ensure_schema(c) + return c + + +@pytest.fixture +def repo(): + return EventRepository() + + +class TestEventRepoLog: + def test_log_returns_id(self, conn, repo): + event = SyncEvent(event_type=SyncEventType.team_created, team_name="t") + event_id = repo.log(conn, event) + assert isinstance(event_id, int) + assert event_id >= 1 + + def test_log_increments_id(self, conn, repo): + e1 = repo.log(conn, SyncEvent(event_type=SyncEventType.team_created, team_name="t")) + e2 = repo.log(conn, SyncEvent(event_type=SyncEventType.team_dissolved, team_name="t")) + assert e2 > e1 + + def test_log_with_detail(self, conn, repo): + event = SyncEvent( + event_type=SyncEventType.member_added, + team_name="t", + member_tag="a.l", + detail={"device_id": "DEV-1", "added_by": "j.m"}, + ) + repo.log(conn, event) + results = repo.query(conn, team="t") + assert len(results) == 1 + assert results[0].detail["device_id"] == "DEV-1" + assert results[0].detail["added_by"] == "j.m" + + def test_log_with_no_detail(self, conn, repo): + event = SyncEvent(event_type=SyncEventType.team_created, team_name="t") + repo.log(conn, event) + results = repo.query(conn, team="t") + assert results[0].detail is None + + def test_log_with_all_fields(self, conn, repo): + event = SyncEvent( + event_type=SyncEventType.session_packaged, + team_name="t", + member_tag="j.m", + project_git_identity="owner/repo", + session_uuid="abc-123", + detail={"branches": ["main"]}, + ) + repo.log(conn, event) + results = repo.query(conn, team="t") + r = results[0] + assert r.project_git_identity == "owner/repo" + assert r.session_uuid == "abc-123" + assert r.member_tag == "j.m" + + +class TestEventRepoQuery: + def test_query_all_returns_latest_first(self, conn, repo): + repo.log(conn, SyncEvent(event_type=SyncEventType.team_created, team_name="t")) + repo.log(conn, SyncEvent(event_type=SyncEventType.member_added, team_name="t")) + results = repo.query(conn) + assert len(results) == 2 + # Latest first + assert results[0].event_type == SyncEventType.member_added + assert results[1].event_type == SyncEventType.team_created + + def test_query_filter_by_team(self, conn, repo): + repo.log(conn, SyncEvent(event_type=SyncEventType.team_created, team_name="team-a")) + repo.log(conn, SyncEvent(event_type=SyncEventType.team_created, team_name="team-b")) + results = repo.query(conn, team="team-a") + assert len(results) == 1 + assert results[0].team_name == "team-a" + + def test_query_filter_by_event_type(self, conn, repo): + repo.log(conn, SyncEvent(event_type=SyncEventType.team_created, team_name="t")) + repo.log(conn, SyncEvent(event_type=SyncEventType.member_added, team_name="t", member_tag="a.l")) + repo.log(conn, SyncEvent(event_type=SyncEventType.member_added, team_name="t", member_tag="b.x")) + results = repo.query(conn, event_type="member_added") + assert len(results) == 2 + assert all(r.event_type == SyncEventType.member_added for r in results) + + def test_query_filter_by_team_and_type(self, conn, repo): + repo.log(conn, SyncEvent(event_type=SyncEventType.member_added, team_name="t1")) + repo.log(conn, SyncEvent(event_type=SyncEventType.member_added, team_name="t2")) + repo.log(conn, SyncEvent(event_type=SyncEventType.team_created, team_name="t1")) + results = repo.query(conn, team="t1", event_type="member_added") + assert len(results) == 1 + assert results[0].team_name == "t1" + assert results[0].event_type == SyncEventType.member_added + + def test_query_limit(self, conn, repo): + for i in range(10): + repo.log(conn, SyncEvent(event_type=SyncEventType.team_created, team_name=f"t{i}")) + results = repo.query(conn, limit=3) + assert len(results) == 3 + + def test_query_empty_returns_empty_list(self, conn, repo): + assert repo.query(conn) == [] diff --git a/api/tests/test_repo_member.py b/api/tests/test_repo_member.py new file mode 100644 index 00000000..e1d114fa --- /dev/null +++ b/api/tests/test_repo_member.py @@ -0,0 +1,133 @@ +import sys +from pathlib import Path +sys.path.insert(0, str(Path(__file__).parent.parent)) + +import sqlite3 +import pytest +from db.schema import ensure_schema +from domain.team import Team +from domain.member import Member, MemberStatus +from repositories.team_repo import TeamRepository +from repositories.member_repo import MemberRepository + + +@pytest.fixture +def conn(): + c = sqlite3.connect(":memory:") + c.row_factory = sqlite3.Row + c.execute("PRAGMA foreign_keys=ON") + ensure_schema(c) + return c + + +@pytest.fixture +def conn_with_team(conn): + """Connection with a team already inserted (needed for FK constraints).""" + TeamRepository().save(conn, Team(name="t", leader_device_id="D", leader_member_tag="j.m")) + return conn + + +@pytest.fixture +def repo(): + return MemberRepository() + + +class TestMemberRepoSave: + def test_save_new_member(self, conn_with_team, repo): + m = Member( + member_tag="a.l", team_name="t", device_id="D2", + user_id="a", machine_tag="l", + ) + repo.save(conn_with_team, m) + result = repo.get(conn_with_team, "t", "a.l") + assert result is not None + assert result.member_tag == "a.l" + assert result.status == MemberStatus.ADDED + + def test_save_upsert_updates_status(self, conn_with_team, repo): + m = Member( + member_tag="a.l", team_name="t", device_id="D2", + user_id="a", machine_tag="l", + ) + repo.save(conn_with_team, m) + activated = m.activate() + repo.save(conn_with_team, activated) + result = repo.get(conn_with_team, "t", "a.l") + assert result.status == MemberStatus.ACTIVE + + +class TestMemberRepoGet: + def test_get_nonexistent_returns_none(self, conn_with_team, repo): + assert repo.get(conn_with_team, "t", "nobody.nowhere") is None + + def test_get_by_device(self, conn_with_team, repo): + m = Member( + member_tag="a.l", team_name="t", device_id="DEV-X", + user_id="a", machine_tag="l", + ) + repo.save(conn_with_team, m) + results = repo.get_by_device(conn_with_team, "DEV-X") + assert len(results) == 1 + assert results[0].member_tag == "a.l" + + def test_get_by_device_returns_empty_for_unknown(self, conn_with_team, repo): + results = repo.get_by_device(conn_with_team, "UNKNOWN") + assert results == [] + + +class TestMemberRepoListForTeam: + def test_list_for_team(self, conn_with_team, repo): + repo.save(conn_with_team, Member( + member_tag="a.l", team_name="t", device_id="D2", user_id="a", machine_tag="l", + )) + repo.save(conn_with_team, Member( + member_tag="b.x", team_name="t", device_id="D3", user_id="b", machine_tag="x", + )) + members = repo.list_for_team(conn_with_team, "t") + assert len(members) == 2 + tags = {m.member_tag for m in members} + assert tags == {"a.l", "b.x"} + + def test_list_for_nonexistent_team_returns_empty(self, conn_with_team, repo): + assert repo.list_for_team(conn_with_team, "nosuchteam") == [] + + +class TestMemberRepoGetAllByMemberTag: + def test_returns_members_across_teams(self, conn, repo): + TeamRepository().save(conn, Team(name="t1", leader_device_id="D1", leader_member_tag="jay.mac")) + TeamRepository().save(conn, Team(name="t2", leader_device_id="D1", leader_member_tag="jay.mac")) + m1 = Member(team_name="t1", member_tag="jay.mac", device_id="D1", user_id="jay", machine_tag="mac") + m2 = Member(team_name="t2", member_tag="jay.mac", device_id="D1", user_id="jay", machine_tag="mac") + repo.save(conn, m1) + repo.save(conn, m2) + results = repo.get_all_by_member_tag(conn, "jay.mac") + assert len(results) == 2 + assert {r.team_name for r in results} == {"t1", "t2"} + + def test_returns_empty_for_unknown_tag(self, conn, repo): + assert repo.get_all_by_member_tag(conn, "nobody.nope") == [] + + +class TestMemberRepoGetByUserId: + def test_returns_members_by_user_id(self, conn, repo): + TeamRepository().save(conn, Team(name="t1", leader_device_id="D1", leader_member_tag="jay.mac")) + repo.save(conn, Member(team_name="t1", member_tag="jay.mac", device_id="D1", user_id="jay", machine_tag="mac")) + results = repo.get_by_user_id(conn, "jay") + assert len(results) == 1 + assert results[0].member_tag == "jay.mac" + + def test_returns_empty_for_unknown_user(self, conn, repo): + assert repo.get_by_user_id(conn, "nobody") == [] + + +class TestMemberRepoRemoval: + def test_was_removed_false_initially(self, conn_with_team, repo): + assert repo.was_removed(conn_with_team, "t", "DEV-X") is False + + def test_record_and_check_removal(self, conn_with_team, repo): + repo.record_removal(conn_with_team, "t", "DEV-X", "a.l") + assert repo.was_removed(conn_with_team, "t", "DEV-X") is True + + def test_record_removal_without_member_tag(self, conn_with_team, repo): + repo.record_removal(conn_with_team, "t", "DEV-Y") + assert repo.was_removed(conn_with_team, "t", "DEV-Y") is True diff --git a/api/tests/test_repo_project.py b/api/tests/test_repo_project.py new file mode 100644 index 00000000..94638bc9 --- /dev/null +++ b/api/tests/test_repo_project.py @@ -0,0 +1,135 @@ +import sys +from pathlib import Path +sys.path.insert(0, str(Path(__file__).parent.parent)) + +import sqlite3 +import pytest +from db.schema import ensure_schema +from domain.team import Team +from domain.project import SharedProject, SharedProjectStatus, derive_folder_suffix +from repositories.team_repo import TeamRepository +from repositories.project_repo import ProjectRepository + + +@pytest.fixture +def conn(): + c = sqlite3.connect(":memory:") + c.row_factory = sqlite3.Row + c.execute("PRAGMA foreign_keys=ON") + ensure_schema(c) + return c + + +@pytest.fixture +def conn_with_team(conn): + TeamRepository().save(conn, Team(name="t", leader_device_id="D", leader_member_tag="j.m")) + return conn + + +@pytest.fixture +def repo(): + return ProjectRepository() + + +class TestProjectRepoSave: + def test_save_new_project(self, conn_with_team, repo): + p = SharedProject( + team_name="t", git_identity="owner/repo", + folder_suffix="owner-repo", + ) + repo.save(conn_with_team, p) + result = repo.get(conn_with_team, "t", "owner/repo") + assert result is not None + assert result.git_identity == "owner/repo" + assert result.status == SharedProjectStatus.SHARED + assert result.encoded_name is None + + def test_save_upsert_updates_status(self, conn_with_team, repo): + p = SharedProject( + team_name="t", git_identity="o/r", folder_suffix="o-r", + ) + repo.save(conn_with_team, p) + removed = p.remove() + repo.save(conn_with_team, removed) + result = repo.get(conn_with_team, "t", "o/r") + assert result.status == SharedProjectStatus.REMOVED + + def test_save_with_encoded_name(self, conn_with_team, repo): + p = SharedProject( + team_name="t", git_identity="o/r", + encoded_name="-Users-me-repo", folder_suffix="o-r", + ) + repo.save(conn_with_team, p) + result = repo.get(conn_with_team, "t", "o/r") + assert result.encoded_name == "-Users-me-repo" + + +class TestProjectRepoGet: + def test_get_nonexistent_returns_none(self, conn_with_team, repo): + assert repo.get(conn_with_team, "t", "no/such") is None + + +class TestProjectRepoListForTeam: + def test_list_for_team(self, conn_with_team, repo): + repo.save(conn_with_team, SharedProject( + team_name="t", git_identity="o/r1", folder_suffix="o-r1", + )) + repo.save(conn_with_team, SharedProject( + team_name="t", git_identity="o/r2", folder_suffix="o-r2", + )) + projects = repo.list_for_team(conn_with_team, "t") + assert len(projects) == 2 + identities = {p.git_identity for p in projects} + assert identities == {"o/r1", "o/r2"} + + def test_list_excludes_removed_by_default(self, conn_with_team, repo): + repo.save(conn_with_team, SharedProject( + team_name="t", git_identity="o/active", folder_suffix="o-active", + )) + removed = SharedProject( + team_name="t", git_identity="o/gone", folder_suffix="o-gone", + ).remove() + repo.save(conn_with_team, removed) + projects = repo.list_for_team(conn_with_team, "t") + assert len(projects) == 1 + assert projects[0].git_identity == "o/active" + + def test_list_includes_removed_when_requested(self, conn_with_team, repo): + repo.save(conn_with_team, SharedProject( + team_name="t", git_identity="o/active", folder_suffix="o-active", + )) + removed = SharedProject( + team_name="t", git_identity="o/gone", folder_suffix="o-gone", + ).remove() + repo.save(conn_with_team, removed) + projects = repo.list_for_team(conn_with_team, "t", include_removed=True) + assert len(projects) == 2 + + def test_list_for_nonexistent_team_returns_empty(self, conn_with_team, repo): + assert repo.list_for_team(conn_with_team, "nope") == [] + + +class TestProjectRepoFindBySuffix: + def test_find_by_suffix(self, conn_with_team, repo): + repo.save(conn_with_team, SharedProject( + team_name="t", git_identity="jayant/karma", + folder_suffix=derive_folder_suffix("jayant/karma"), + )) + results = repo.find_by_suffix(conn_with_team, "jayant-karma") + assert len(results) == 1 + assert results[0].git_identity == "jayant/karma" + + def test_find_by_suffix_no_match(self, conn_with_team, repo): + assert repo.find_by_suffix(conn_with_team, "no-such-suffix") == [] + + +class TestProjectRepoFindByGitIdentity: + def test_find_by_git_identity_across_teams(self, conn, repo): + TeamRepository().save(conn, Team(name="t1", leader_device_id="D1", leader_member_tag="j.m")) + TeamRepository().save(conn, Team(name="t2", leader_device_id="D2", leader_member_tag="j.m")) + repo.save(conn, SharedProject(team_name="t1", git_identity="o/r", folder_suffix="o-r")) + repo.save(conn, SharedProject(team_name="t2", git_identity="o/r", folder_suffix="o-r")) + results = repo.find_by_git_identity(conn, "o/r") + assert len(results) == 2 + team_names = {p.team_name for p in results} + assert team_names == {"t1", "t2"} diff --git a/api/tests/test_repo_subscription.py b/api/tests/test_repo_subscription.py new file mode 100644 index 00000000..0cd8199f --- /dev/null +++ b/api/tests/test_repo_subscription.py @@ -0,0 +1,116 @@ +import sys +from pathlib import Path +sys.path.insert(0, str(Path(__file__).parent.parent)) + +import sqlite3 +import pytest +from db.schema import ensure_schema +from domain.team import Team +from domain.member import Member +from domain.project import SharedProject +from domain.subscription import Subscription, SubscriptionStatus, SyncDirection +from repositories.team_repo import TeamRepository +from repositories.member_repo import MemberRepository +from repositories.project_repo import ProjectRepository +from repositories.subscription_repo import SubscriptionRepository + + +@pytest.fixture +def conn(): + c = sqlite3.connect(":memory:") + c.row_factory = sqlite3.Row + c.execute("PRAGMA foreign_keys=ON") + ensure_schema(c) + return c + + +@pytest.fixture +def conn_setup(conn): + """Pre-populated connection: team + member + project.""" + TeamRepository().save(conn, Team(name="t", leader_device_id="D", leader_member_tag="j.m")) + MemberRepository().save(conn, Member( + member_tag="a.l", team_name="t", device_id="D2", user_id="a", machine_tag="l", + )) + ProjectRepository().save(conn, SharedProject( + team_name="t", git_identity="o/r", folder_suffix="o-r", + )) + return conn + + +@pytest.fixture +def repo(): + return SubscriptionRepository() + + +class TestSubscriptionRepoSave: + def test_save_new_subscription(self, conn_setup, repo): + sub = Subscription(member_tag="a.l", team_name="t", project_git_identity="o/r") + repo.save(conn_setup, sub) + result = repo.get(conn_setup, "a.l", "t", "o/r") + assert result is not None + assert result.status == SubscriptionStatus.OFFERED + assert result.direction == SyncDirection.BOTH + + def test_save_upsert_updates_status(self, conn_setup, repo): + sub = Subscription(member_tag="a.l", team_name="t", project_git_identity="o/r") + repo.save(conn_setup, sub) + accepted = sub.accept(SyncDirection.RECEIVE) + repo.save(conn_setup, accepted) + result = repo.get(conn_setup, "a.l", "t", "o/r") + assert result.status == SubscriptionStatus.ACCEPTED + assert result.direction == SyncDirection.RECEIVE + + +class TestSubscriptionRepoGet: + def test_get_nonexistent_returns_none(self, conn_setup, repo): + assert repo.get(conn_setup, "nobody.nowhere", "t", "o/r") is None + + +class TestSubscriptionRepoListForMember: + def test_list_for_member(self, conn_setup, repo): + # Add a second project + ProjectRepository().save(conn_setup, SharedProject( + team_name="t", git_identity="o/r2", folder_suffix="o-r2", + )) + repo.save(conn_setup, Subscription(member_tag="a.l", team_name="t", project_git_identity="o/r")) + repo.save(conn_setup, Subscription(member_tag="a.l", team_name="t", project_git_identity="o/r2")) + subs = repo.list_for_member(conn_setup, "a.l") + assert len(subs) == 2 + + def test_list_for_member_returns_empty_when_none(self, conn_setup, repo): + assert repo.list_for_member(conn_setup, "nobody.here") == [] + + +class TestSubscriptionRepoListForProject: + def test_list_for_project(self, conn_setup, repo): + # Add a second member + MemberRepository().save(conn_setup, Member( + member_tag="b.x", team_name="t", device_id="D3", user_id="b", machine_tag="x", + )) + repo.save(conn_setup, Subscription(member_tag="a.l", team_name="t", project_git_identity="o/r")) + repo.save(conn_setup, Subscription(member_tag="b.x", team_name="t", project_git_identity="o/r")) + subs = repo.list_for_project(conn_setup, "t", "o/r") + assert len(subs) == 2 + tags = {s.member_tag for s in subs} + assert tags == {"a.l", "b.x"} + + +class TestSubscriptionRepoListAcceptedForSuffix: + def test_list_accepted_for_suffix(self, conn_setup, repo): + # Save one offered, one accepted subscription + sub_offered = Subscription(member_tag="a.l", team_name="t", project_git_identity="o/r") + repo.save(conn_setup, sub_offered) + # Add second member with accepted sub + MemberRepository().save(conn_setup, Member( + member_tag="b.x", team_name="t", device_id="D3", user_id="b", machine_tag="x", + )) + sub_accepted = Subscription( + member_tag="b.x", team_name="t", project_git_identity="o/r", + status=SubscriptionStatus.ACCEPTED, + ) + repo.save(conn_setup, sub_accepted) + + results = repo.list_accepted_for_suffix(conn_setup, "o-r") + assert len(results) == 1 + assert results[0].member_tag == "b.x" + assert results[0].status == SubscriptionStatus.ACCEPTED diff --git a/api/tests/test_repo_team.py b/api/tests/test_repo_team.py new file mode 100644 index 00000000..ee421d60 --- /dev/null +++ b/api/tests/test_repo_team.py @@ -0,0 +1,72 @@ +import sys +from pathlib import Path +sys.path.insert(0, str(Path(__file__).parent.parent)) + +import sqlite3 +import pytest +from db.schema import ensure_schema +from domain.team import Team, TeamStatus +from repositories.team_repo import TeamRepository + + +@pytest.fixture +def conn(): + c = sqlite3.connect(":memory:") + c.row_factory = sqlite3.Row + c.execute("PRAGMA foreign_keys=ON") + ensure_schema(c) + return c + + +@pytest.fixture +def repo(): + return TeamRepository() + + +class TestTeamRepoSave: + def test_save_new_team(self, conn, repo): + team = Team(name="t", leader_device_id="D", leader_member_tag="j.m") + repo.save(conn, team) + result = repo.get(conn, "t") + assert result is not None + assert result.name == "t" + assert result.status == TeamStatus.ACTIVE + + def test_save_updates_existing(self, conn, repo): + team = Team(name="t", leader_device_id="D", leader_member_tag="j.m") + repo.save(conn, team) + dissolved = team.dissolve(by_device="D") + repo.save(conn, dissolved) + result = repo.get(conn, "t") + assert result.status == TeamStatus.DISSOLVED + + +class TestTeamRepoGet: + def test_get_nonexistent_returns_none(self, conn, repo): + assert repo.get(conn, "nope") is None + + +class TestTeamRepoList: + def test_list_all(self, conn, repo): + repo.save(conn, Team(name="a", leader_device_id="D1", leader_member_tag="j.m1")) + repo.save(conn, Team(name="b", leader_device_id="D2", leader_member_tag="j.m2")) + teams = repo.list_all(conn) + assert len(teams) == 2 + names = {t.name for t in teams} + assert names == {"a", "b"} + + +class TestTeamRepoDelete: + def test_delete_team(self, conn, repo): + repo.save(conn, Team(name="t", leader_device_id="D", leader_member_tag="j.m")) + repo.delete(conn, "t") + assert repo.get(conn, "t") is None + + +class TestTeamRepoGetByLeader: + def test_get_by_leader(self, conn, repo): + repo.save(conn, Team(name="t1", leader_device_id="D", leader_member_tag="j.m")) + repo.save(conn, Team(name="t2", leader_device_id="D", leader_member_tag="j.m")) + repo.save(conn, Team(name="t3", leader_device_id="OTHER", leader_member_tag="a.l")) + teams = repo.get_by_leader(conn, "D") + assert len(teams) == 2 diff --git a/api/tests/test_schema_v19.py b/api/tests/test_schema_v19.py new file mode 100644 index 00000000..ef35f172 --- /dev/null +++ b/api/tests/test_schema_v19.py @@ -0,0 +1,128 @@ +import sys +from pathlib import Path +sys.path.insert(0, str(Path(__file__).parent.parent)) + +import sqlite3 +import pytest +from db.schema import ensure_schema + + +@pytest.fixture +def conn(): + c = sqlite3.connect(":memory:") + c.row_factory = sqlite3.Row + c.execute("PRAGMA foreign_keys=ON") + ensure_schema(c) + return c + + +class TestV19Tables: + def test_sync_teams_exists(self, conn): + conn.execute("INSERT INTO sync_teams (name, leader_device_id, leader_member_tag) VALUES ('t', 'D', 'j.m')") + row = conn.execute("SELECT * FROM sync_teams WHERE name='t'").fetchone() + assert row["status"] == "active" + + def test_sync_members_exists(self, conn): + conn.execute("INSERT INTO sync_teams (name, leader_device_id, leader_member_tag) VALUES ('t', 'D', 'j.m')") + conn.execute( + "INSERT INTO sync_members (team_name, member_tag, device_id, user_id, machine_tag) " + "VALUES ('t', 'j.m', 'D', 'j', 'm')" + ) + row = conn.execute("SELECT * FROM sync_members WHERE member_tag='j.m'").fetchone() + assert row["status"] == "added" + assert row["updated_at"] is not None + + def test_sync_projects_pk_is_git_identity(self, conn): + conn.execute("INSERT INTO sync_teams (name, leader_device_id, leader_member_tag) VALUES ('t', 'D', 'j.m')") + conn.execute( + "INSERT INTO sync_projects (team_name, git_identity, folder_suffix) " + "VALUES ('t', 'owner/repo', 'owner-repo')" + ) + row = conn.execute("SELECT * FROM sync_projects WHERE git_identity='owner/repo'").fetchone() + assert row["encoded_name"] is None # nullable + assert row["status"] == "shared" + + def test_sync_subscriptions_exists(self, conn): + conn.execute("INSERT INTO sync_teams (name, leader_device_id, leader_member_tag) VALUES ('t', 'D', 'j.m')") + conn.execute( + "INSERT INTO sync_members (team_name, member_tag, device_id, user_id, machine_tag) " + "VALUES ('t', 'a.l', 'D2', 'a', 'l')" + ) + conn.execute( + "INSERT INTO sync_projects (team_name, git_identity, folder_suffix) " + "VALUES ('t', 'o/r', 'o-r')" + ) + conn.execute( + "INSERT INTO sync_subscriptions (member_tag, team_name, project_git_identity) " + "VALUES ('a.l', 't', 'o/r')" + ) + row = conn.execute("SELECT * FROM sync_subscriptions").fetchone() + assert row["status"] == "offered" + assert row["direction"] == "both" + + def test_sync_events_uses_git_identity_column(self, conn): + conn.execute( + "INSERT INTO sync_events (event_type, team_name, project_git_identity) " + "VALUES ('team_created', 't', 'o/r')" + ) + row = conn.execute("SELECT * FROM sync_events").fetchone() + assert row["project_git_identity"] == "o/r" + + +class TestV19Cascades: + def test_delete_team_cascades_members(self, conn): + conn.execute("INSERT INTO sync_teams (name, leader_device_id, leader_member_tag) VALUES ('t', 'D', 'j.m')") + conn.execute( + "INSERT INTO sync_members (team_name, member_tag, device_id, user_id, machine_tag) " + "VALUES ('t', 'a.l', 'D2', 'a', 'l')" + ) + conn.execute("DELETE FROM sync_teams WHERE name='t'") + assert conn.execute("SELECT COUNT(*) FROM sync_members").fetchone()[0] == 0 + + def test_delete_team_cascades_subscriptions(self, conn): + conn.execute("INSERT INTO sync_teams (name, leader_device_id, leader_member_tag) VALUES ('t', 'D', 'j.m')") + conn.execute( + "INSERT INTO sync_members (team_name, member_tag, device_id, user_id, machine_tag) " + "VALUES ('t', 'a.l', 'D2', 'a', 'l')" + ) + conn.execute( + "INSERT INTO sync_projects (team_name, git_identity, folder_suffix) VALUES ('t', 'o/r', 'o-r')" + ) + conn.execute( + "INSERT INTO sync_subscriptions (member_tag, team_name, project_git_identity) " + "VALUES ('a.l', 't', 'o/r')" + ) + conn.execute("DELETE FROM sync_teams WHERE name='t'") + assert conn.execute("SELECT COUNT(*) FROM sync_subscriptions").fetchone()[0] == 0 + + +class TestV19Constraints: + def test_team_status_check(self, conn): + with pytest.raises(sqlite3.IntegrityError): + conn.execute( + "INSERT INTO sync_teams (name, leader_device_id, leader_member_tag, status) " + "VALUES ('t', 'D', 'j.m', 'invalid')" + ) + + def test_member_status_check(self, conn): + conn.execute("INSERT INTO sync_teams (name, leader_device_id, leader_member_tag) VALUES ('t', 'D', 'j.m')") + with pytest.raises(sqlite3.IntegrityError): + conn.execute( + "INSERT INTO sync_members (team_name, member_tag, device_id, user_id, machine_tag, status) " + "VALUES ('t', 'a.l', 'D2', 'a', 'l', 'invalid')" + ) + + def test_subscription_direction_check(self, conn): + conn.execute("INSERT INTO sync_teams (name, leader_device_id, leader_member_tag) VALUES ('t', 'D', 'j.m')") + conn.execute( + "INSERT INTO sync_members (team_name, member_tag, device_id, user_id, machine_tag) " + "VALUES ('t', 'a.l', 'D2', 'a', 'l')" + ) + conn.execute( + "INSERT INTO sync_projects (team_name, git_identity, folder_suffix) VALUES ('t', 'o/r', 'o-r')" + ) + with pytest.raises(sqlite3.IntegrityError): + conn.execute( + "INSERT INTO sync_subscriptions (member_tag, team_name, project_git_identity, direction) " + "VALUES ('a.l', 't', 'o/r', 'invalid')" + ) diff --git a/api/tests/test_stale_removal_signals.py b/api/tests/test_stale_removal_signals.py new file mode 100644 index 00000000..4902f77a --- /dev/null +++ b/api/tests/test_stale_removal_signals.py @@ -0,0 +1,183 @@ +"""Tests for stale removal signal cleanup on team re-creation.""" +import json +import sqlite3 +from datetime import datetime, timezone +from unittest.mock import AsyncMock, MagicMock + +import pytest +from pathlib import Path + +from services.sync.metadata_service import MetadataService + + +@pytest.fixture +def meta_base(tmp_path): + return tmp_path / "metadata-folders" + + +@pytest.fixture +def metadata(meta_base): + meta_base.mkdir() + return MetadataService(meta_base) + + +def test_purge_stale_removals_clears_old_signals(metadata, meta_base): + """purge_stale_removals() should delete all files in removed/ dir.""" + team_dir = meta_base / "karma-meta--test-team" + removed_dir = team_dir / "removed" + removed_dir.mkdir(parents=True) + + # Plant a stale removal signal + stale = {"member_tag": "alice.mac-mini", "removed_by": "bob.macbook", "removed_at": "2026-03-01T00:00:00+00:00"} + (removed_dir / "alice.mac-mini.json").write_text(json.dumps(stale)) + + metadata.purge_stale_removals("test-team") + + assert not list(removed_dir.glob("*.json")), "Stale removal signals should be purged" + assert removed_dir.exists(), "removed/ directory itself should still exist" + + +def test_purge_stale_removals_noop_when_no_dir(metadata): + """purge_stale_removals() should not fail if removed/ doesn't exist.""" + metadata.purge_stale_removals("nonexistent-team") # Should not raise + + +def test_purge_stale_removals_preserves_members(metadata, meta_base): + """purge_stale_removals() should NOT touch members/ directory.""" + team_dir = meta_base / "karma-meta--test-team" + members_dir = team_dir / "members" + removed_dir = team_dir / "removed" + members_dir.mkdir(parents=True) + removed_dir.mkdir(parents=True) + + (members_dir / "alice.mac-mini.json").write_text('{"member_tag": "alice.mac-mini"}') + (removed_dir / "alice.mac-mini.json").write_text('{"member_tag": "alice.mac-mini"}') + + metadata.purge_stale_removals("test-team") + + assert (members_dir / "alice.mac-mini.json").exists(), "Members should be untouched" + assert not (removed_dir / "alice.mac-mini.json").exists(), "Removal signal should be purged" + + +# ------------------------------------------------------------------ +# TeamService integration test +# ------------------------------------------------------------------ + +from services.sync.team_service import TeamService + + +@pytest.fixture +def team_service(metadata): + teams = MagicMock() + members = MagicMock() + projects = MagicMock() + subs = MagicMock() + events = MagicMock() + devices = MagicMock() + folders = AsyncMock() + return TeamService(teams, members, projects, subs, events, devices, metadata, folders) + + +@pytest.fixture +def conn(): + c = sqlite3.connect(":memory:") + return c + + +@pytest.mark.asyncio +async def test_create_team_purges_stale_removal_signals(team_service, meta_base, conn): + """TeamService.create_team() should purge stale removal signals.""" + # Plant a stale removal signal from a prior team with the same name + team_dir = meta_base / "karma-meta--recycled-team" + removed_dir = team_dir / "removed" + removed_dir.mkdir(parents=True) + (removed_dir / "victim.mac-mini.json").write_text( + json.dumps({"member_tag": "victim.mac-mini", "removed_by": "leader.macbook", "removed_at": "2026-03-01T00:00:00+00:00"}) + ) + + await team_service.create_team( + conn, + name="recycled-team", + leader_member_tag="leader.macbook", + leader_device_id="DEVICE-ID-123", + ) + + assert not list(removed_dir.glob("*.json")), "Stale signals should be purged after create_team" + + +# ------------------------------------------------------------------ +# Reconciliation staleness check tests +# ------------------------------------------------------------------ + +from services.sync.reconciliation_service import ReconciliationService +from domain.team import Team + + +@pytest.fixture +def reconciliation(metadata): + return ReconciliationService( + teams=MagicMock(), + members=MagicMock(), + projects=MagicMock(), + subs=MagicMock(), + events=MagicMock(), + devices=AsyncMock(), + folders=AsyncMock(), + metadata=metadata, + my_member_tag="alice.mac-mini", + my_device_id="DEVICE-ALICE", + ) + + +@pytest.mark.asyncio +async def test_phase_metadata_ignores_stale_removal_signal(reconciliation, meta_base): + """phase_metadata should skip removal signals older than team.created_at.""" + team_dir = meta_base / "karma-meta--test-team" + removed_dir = team_dir / "removed" + removed_dir.mkdir(parents=True) + (team_dir / "members").mkdir(parents=True) + + # Stale removal signal from March 1 (well over 60s before team creation) + (removed_dir / "alice.mac-mini.json").write_text(json.dumps({ + "member_tag": "alice.mac-mini", + "removed_by": "bob.macbook", + "removed_at": "2026-03-01T00:00:00+00:00", + })) + + # Team was created on March 20 (19 days newer — clearly a different incarnation) + team = Team(name="test-team", leader_member_tag="bob.macbook", leader_device_id="DEVICE-BOB", + created_at=datetime(2026, 3, 20, tzinfo=timezone.utc)) + + conn = MagicMock() + reconciliation._auto_leave = AsyncMock() + + await reconciliation.phase_metadata(conn, team) + + reconciliation._auto_leave.assert_not_called() + + +@pytest.mark.asyncio +async def test_phase_metadata_honors_fresh_removal_signal(reconciliation, meta_base): + """phase_metadata should auto-leave when removal signal is newer than team.created_at.""" + team_dir = meta_base / "karma-meta--test-team" + removed_dir = team_dir / "removed" + removed_dir.mkdir(parents=True) + (team_dir / "members").mkdir(parents=True) + + # Fresh removal signal from March 20 + (removed_dir / "alice.mac-mini.json").write_text(json.dumps({ + "member_tag": "alice.mac-mini", + "removed_by": "bob.macbook", + "removed_at": "2026-03-20T12:00:00+00:00", + })) + + # Team was created on March 15 (older than removal) + team = Team(name="test-team", leader_member_tag="bob.macbook", leader_device_id="DEVICE-BOB", + created_at=datetime(2026, 3, 15, tzinfo=timezone.utc)) + + conn = MagicMock() + reconciliation._auto_leave = AsyncMock() + + await reconciliation.phase_metadata(conn, team) + + reconciliation._auto_leave.assert_called_once() diff --git a/api/tests/test_sync_own_outbox_detection.py b/api/tests/test_sync_own_outbox_detection.py new file mode 100644 index 00000000..334613be --- /dev/null +++ b/api/tests/test_sync_own_outbox_detection.py @@ -0,0 +1,139 @@ +"""Tests for own-outbox detection in pending folder classification. + +Reproduces the bug where the leader stores a sanitized hostname (e.g., +"jayants-mac-mini") instead of the correct member_tag ("jay-mac-mini. +jayants-mac-mini-local"). The joiner's _is_own_outbox check then fails +to recognize the folder as its own outbox, causing it to be misclassified +as "sessions" instead of "outbox" and merged with the leader's real outbox +(device_count=2). + +Note: ``build_own_names`` was originally in ``services.sync_identity_match`` +(deleted as dead v3 code). The function is inlined here so the test +remains self-contained. +""" +from __future__ import annotations + +import sys +from pathlib import Path +from typing import Optional + +sys.path.insert(0, str(Path(__file__).parent.parent)) + +# Domain suffixes commonly stripped by Syncthing device name sanitization. +_HOSTNAME_SUFFIXES = (".local", ".lan", ".home", ".internal", ".localdomain") + + +def _sanitize_hostname(raw: str) -> str: + """Strip domain suffix and lowercase.""" + lower = raw.strip().lower() + for suffix in _HOSTNAME_SUFFIXES: + if lower.endswith(suffix): + return lower[: -len(suffix)] + return lower + + +def build_own_names( + user_id: Optional[str], + machine_id: Optional[str], + machine_tag: Optional[str], + member_tag: Optional[str], +) -> set[str]: + """Build the set of all name variants that identify this machine.""" + names: set[str] = set() + if user_id: + names.add(user_id) + if machine_id: + names.add(machine_id) + names.add(_sanitize_hostname(machine_id)) + if machine_tag: + names.add(machine_tag) + if member_tag: + names.add(member_tag) + return names + + +class TestBuildOwnNames: + """Test that build_own_names produces all reasonable identity variants.""" + + def test_includes_user_id(self): + names = build_own_names("jay-mac-mini", "Jayants-Mac-mini.local", "jayants-mac-mini-local", "jay-mac-mini.jayants-mac-mini-local") + assert "jay-mac-mini" in names + + def test_includes_machine_id(self): + names = build_own_names("jay-mac-mini", "Jayants-Mac-mini.local", "jayants-mac-mini-local", "jay-mac-mini.jayants-mac-mini-local") + assert "Jayants-Mac-mini.local" in names + + def test_includes_member_tag(self): + names = build_own_names("jay-mac-mini", "Jayants-Mac-mini.local", "jayants-mac-mini-local", "jay-mac-mini.jayants-mac-mini-local") + assert "jay-mac-mini.jayants-mac-mini-local" in names + + def test_includes_machine_tag(self): + names = build_own_names("jay-mac-mini", "Jayants-Mac-mini.local", "jayants-mac-mini-local", "jay-mac-mini.jayants-mac-mini-local") + assert "jayants-mac-mini-local" in names + + def test_includes_sanitized_hostname(self): + """The exact scenario that caused the bug: leader used sanitized + hostname 'jayants-mac-mini' (stripped .local suffix) as the + folder owner tag. + """ + names = build_own_names("jay-mac-mini", "Jayants-Mac-mini.local", "jayants-mac-mini-local", "jay-mac-mini.jayants-mac-mini-local") + assert "jayants-mac-mini" in names + + def test_sanitizes_common_suffixes(self): + """All common hostname suffixes should be stripped.""" + for hostname in [ + "my-mac.local", + "my-mac.lan", + "my-mac.home", + "my-mac.internal", + "my-mac.localdomain", + ]: + names = build_own_names("user", hostname, "my-mac-local", "user.my-mac-local") + assert "my-mac" in names, f"Failed for hostname {hostname}" + + def test_lowercases_sanitized_hostname(self): + names = build_own_names("user", "MyMac.local", "mymac-local", "user.mymac-local") + assert "mymac" in names + + def test_handles_none_values(self): + names = build_own_names(None, None, None, None) + assert len(names) == 0 + + def test_handles_partial_none(self): + names = build_own_names("user", None, None, "user") + assert "user" in names + assert len(names) == 1 + + def test_no_suffix_hostname(self): + """Hostname without a known suffix should still be included lowercase.""" + names = build_own_names("user", "myhost", "myhost", "user.myhost") + assert "myhost" in names + + +class TestIsOwnOutbox: + """Integration test: own_names recognizes folders created with hostname fallback.""" + + def test_recognizes_sanitized_hostname_folder(self): + """Reproduce the exact bug: leader creates karma-out--jayants-mac-mini--suffix + but joiner's member_tag is jay-mac-mini.jayants-mac-mini-local.""" + from services.syncthing.folder_manager import parse_outbox_id + + # Leader created inbox with sanitized hostname + folder_id = "karma-out--jayants-mac-mini--the-non-expert-humanassaince" + parsed = parse_outbox_id(folder_id) + assert parsed is not None + owner, _ = parsed + + # Joiner's identity + names = build_own_names( + user_id="jay-mac-mini", + machine_id="Jayants-Mac-mini.local", + machine_tag="jayants-mac-mini-local", + member_tag="jay-mac-mini.jayants-mac-mini-local", + ) + + # This was the bug — "jayants-mac-mini" was NOT in own_names + assert owner in names, ( + f"Sanitized hostname '{owner}' not recognized as own. " + f"own_names={names}" + ) diff --git a/api/tests/test_sync_v4_bugfixes.py b/api/tests/test_sync_v4_bugfixes.py new file mode 100644 index 00000000..c66a65ef --- /dev/null +++ b/api/tests/test_sync_v4_bugfixes.py @@ -0,0 +1,483 @@ +"""Tests for sync v4 bugfixes: cross-team safety, state machine, dissolution.""" +import sys +from pathlib import Path + +sys.path.insert(0, str(Path(__file__).parent.parent)) + +import sqlite3 + +import pytest +from unittest.mock import MagicMock, AsyncMock + +from db.schema import ensure_schema + +from domain.team import Team, InvalidTransitionError +from domain.member import Member, MemberStatus +from domain.subscription import Subscription, SubscriptionStatus, SyncDirection +from repositories.team_repo import TeamRepository +from repositories.member_repo import MemberRepository +from repositories.project_repo import ProjectRepository +from repositories.subscription_repo import SubscriptionRepository +from repositories.event_repo import EventRepository +from services.sync.team_service import TeamService +from services.sync.project_service import ProjectService +from services.sync.metadata_service import MetadataService +from services.sync.reconciliation_service import ReconciliationService + + +@pytest.fixture +def conn(): + c = sqlite3.connect(":memory:") + c.row_factory = sqlite3.Row + c.execute("PRAGMA foreign_keys=ON") + ensure_schema(c) + return c + + +@pytest.fixture +def meta_base(tmp_path): + return tmp_path / "meta" + + +@pytest.fixture +def stack(conn, meta_base): + """Build full service stack with mocked Syncthing managers.""" + devices = MagicMock() + devices.pair = AsyncMock() + devices.unpair = AsyncMock() + devices.ensure_paired = AsyncMock() + + folders = MagicMock() + folders.ensure_metadata_folder = AsyncMock() + folders.ensure_outbox_folder = AsyncMock() + folders.ensure_inbox_folder = AsyncMock() + folders.set_folder_devices = AsyncMock() + folders.get_configured_folders = AsyncMock(return_value=[]) + folders.remove_outbox_folder = AsyncMock() + folders.remove_device_from_team_folders = AsyncMock() + folders.cleanup_team_folders = AsyncMock() + folders.cleanup_project_folders = AsyncMock() + + repos = { + "teams": TeamRepository(), + "members": MemberRepository(), + "projects": ProjectRepository(), + "subs": SubscriptionRepository(), + "events": EventRepository(), + } + metadata = MetadataService(meta_base=meta_base) + + team_svc = TeamService( + **repos, devices=devices, metadata=metadata, folders=folders, + ) + project_svc = ProjectService( + **repos, folders=folders, metadata=metadata, + ) + + return { + "team_svc": team_svc, + "project_svc": project_svc, + "devices": devices, + "folders": folders, + "metadata": metadata, + **repos, + } + + +async def _setup_two_teams_shared_project(conn, stack): + """Helper: create 2 teams sharing the same project (org/webapp). + + Team alpha: leader=alice, member=dave + Team beta: leader=bob, member=alice + Both share org/webapp (same git_identity → same folder_suffix). + """ + team_svc = stack["team_svc"] + project_svc = stack["project_svc"] + + # Create teams + await team_svc.create_team( + conn, name="alpha", leader_member_tag="alice.mac", leader_device_id="DEV-ALICE", + ) + await team_svc.create_team( + conn, name="beta", leader_member_tag="bob.linux", leader_device_id="DEV-BOB", + ) + + # Add cross-members + await team_svc.add_member( + conn, team_name="alpha", by_device="DEV-ALICE", + new_member_tag="dave.win", new_device_id="DEV-DAVE", + ) + await team_svc.add_member( + conn, team_name="beta", by_device="DEV-BOB", + new_member_tag="alice.mac", new_device_id="DEV-ALICE", + ) + + # Activate members BEFORE sharing (so share_project creates OFFERED subs) + dave = stack["members"].get(conn, "alpha", "dave.win") + stack["members"].save(conn, dave.activate()) + alice_beta = stack["members"].get(conn, "beta", "alice.mac") + stack["members"].save(conn, alice_beta.activate()) + + # Share same project in both teams + await project_svc.share_project( + conn, team_name="alpha", by_device="DEV-ALICE", + git_identity="org/webapp", encoded_name="-org-webapp", + ) + await project_svc.share_project( + conn, team_name="beta", by_device="DEV-BOB", + git_identity="org/webapp", encoded_name="-org-webapp", + ) + + # All members accept subscriptions + await project_svc.accept_subscription( + conn, member_tag="dave.win", team_name="alpha", + git_identity="org/webapp", direction=SyncDirection.BOTH, + ) + await project_svc.accept_subscription( + conn, member_tag="alice.mac", team_name="beta", + git_identity="org/webapp", direction=SyncDirection.BOTH, + ) + + +# ============================================================================== +# Bug 1: Phase 3 cross-team device list pollution +# ============================================================================== + +class TestBug1CrossTeamDeviceListIsolation: + """Phase 3 must compute device lists per-team, not as cross-team union.""" + + async def test_device_lists_are_team_scoped(self, conn, stack): + """Dave (alpha only) should NOT appear in beta's device lists.""" + await _setup_two_teams_shared_project(conn, stack) + + # Build reconciliation for alpha (alice's perspective) + recon = ReconciliationService( + **{k: stack[k] for k in ("teams", "members", "projects", "subs", "events")}, + devices=stack["devices"], + folders=stack["folders"], + metadata=stack["metadata"], + my_member_tag="alice.mac", + my_device_id="DEV-ALICE", + ) + + # Run Phase 3 for team alpha + alpha = stack["teams"].get(conn, "alpha") + await recon.phase_device_lists(conn, alpha) + + # Get the device sets that were applied to folders + calls = stack["folders"].set_folder_devices.call_args_list + + # Extract all device sets applied during alpha's Phase 3 + alpha_device_sets = [set(call.args[1]) if len(call.args) > 1 else set(call.kwargs.get("device_ids", [])) + for call in calls] + + # Dave (DEV-DAVE) should be in alpha's device sets + # But let's verify bob (DEV-BOB, beta leader) is NOT in alpha's device sets + for device_set in alpha_device_sets: + assert "DEV-BOB" not in device_set, \ + "Beta leader's device leaked into alpha's folder device lists" + + async def test_cross_team_member_excluded_from_device_set(self, conn, stack): + """Members from other teams with same project must not pollute device lists.""" + await _setup_two_teams_shared_project(conn, stack) + + recon = ReconciliationService( + **{k: stack[k] for k in ("teams", "members", "projects", "subs", "events")}, + devices=stack["devices"], + folders=stack["folders"], + metadata=stack["metadata"], + my_member_tag="bob.linux", + my_device_id="DEV-BOB", + ) + + stack["folders"].set_folder_devices.reset_mock() + + # Run Phase 3 for team beta + beta = stack["teams"].get(conn, "beta") + await recon.phase_device_lists(conn, beta) + + calls = stack["folders"].set_folder_devices.call_args_list + for call in calls: + device_set = set(call.args[1]) if len(call.args) > 1 else set() + assert "DEV-DAVE" not in device_set, \ + "Alpha member Dave leaked into beta's folder device lists" + + +# ============================================================================== +# Bug 2: DECLINED subscription reopen +# ============================================================================== + +class TestBug2DeclinedReopen: + """DECLINED subscriptions can be reopened back to OFFERED.""" + + def test_reopen_transitions_declined_to_offered(self): + sub = Subscription( + member_tag="bob.linux", team_name="team1", + project_git_identity="org/repo", + status=SubscriptionStatus.DECLINED, + ) + reopened = sub.reopen() + assert reopened.status == SubscriptionStatus.OFFERED + + def test_reopen_from_non_declined_raises(self): + sub = Subscription( + member_tag="bob.linux", team_name="team1", + project_git_identity="org/repo", + status=SubscriptionStatus.OFFERED, + ) + with pytest.raises(InvalidTransitionError, match="DECLINED"): + sub.reopen() + + def test_reopen_from_accepted_raises(self): + sub = Subscription( + member_tag="bob.linux", team_name="team1", + project_git_identity="org/repo", + status=SubscriptionStatus.ACCEPTED, + ) + with pytest.raises(InvalidTransitionError, match="DECLINED"): + sub.reopen() + + async def test_reopen_then_accept_full_flow(self, conn, stack): + """Decline → reopen → accept is a valid lifecycle.""" + team_svc = stack["team_svc"] + project_svc = stack["project_svc"] + + # Setup: team with member, shared project + await team_svc.create_team( + conn, name="t1", leader_member_tag="alice.mac", leader_device_id="DEV-A", + ) + await team_svc.add_member( + conn, team_name="t1", by_device="DEV-A", + new_member_tag="bob.linux", new_device_id="DEV-B", + ) + # Activate bob + bob = stack["members"].get(conn, "t1", "bob.linux") + stack["members"].save(conn, bob.activate()) + + await project_svc.share_project( + conn, team_name="t1", by_device="DEV-A", + git_identity="org/repo", + ) + + # Bob declines + sub = await project_svc.decline_subscription( + conn, member_tag="bob.linux", team_name="t1", git_identity="org/repo", + ) + assert sub.status == SubscriptionStatus.DECLINED + + # Bob reopens + sub = await project_svc.reopen_subscription( + conn, member_tag="bob.linux", team_name="t1", git_identity="org/repo", + ) + assert sub.status == SubscriptionStatus.OFFERED + + # Bob accepts with direction + sub = await project_svc.accept_subscription( + conn, member_tag="bob.linux", team_name="t1", + git_identity="org/repo", direction=SyncDirection.RECEIVE, + ) + assert sub.status == SubscriptionStatus.ACCEPTED + assert sub.direction == SyncDirection.RECEIVE + + +# ============================================================================== +# Bug 3: Team dissolution notifies remote members +# ============================================================================== + +class TestBug3DissolutionNotification: + """dissolve_team() must write removal signals for all non-leader members.""" + + async def test_dissolution_writes_removal_signals(self, conn, stack, meta_base): + team_svc = stack["team_svc"] + + # Create team with 2 members + await team_svc.create_team( + conn, name="t1", leader_member_tag="alice.mac", leader_device_id="DEV-A", + ) + await team_svc.add_member( + conn, team_name="t1", by_device="DEV-A", + new_member_tag="bob.linux", new_device_id="DEV-B", + ) + await team_svc.add_member( + conn, team_name="t1", by_device="DEV-A", + new_member_tag="carol.air", new_device_id="DEV-C", + ) + + # Dissolve team + await team_svc.dissolve_team(conn, team_name="t1", by_device="DEV-A") + + # Verify removal signals were written for bob and carol + meta_dir = meta_base / "karma-meta--t1" / "removed" + assert (meta_dir / "bob.linux.json").exists(), \ + "Removal signal missing for bob" + assert (meta_dir / "carol.air.json").exists(), \ + "Removal signal missing for carol" + + async def test_dissolution_no_removal_signal_for_leader(self, conn, stack, meta_base): + team_svc = stack["team_svc"] + + await team_svc.create_team( + conn, name="t1", leader_member_tag="alice.mac", leader_device_id="DEV-A", + ) + await team_svc.add_member( + conn, team_name="t1", by_device="DEV-A", + new_member_tag="bob.linux", new_device_id="DEV-B", + ) + + await team_svc.dissolve_team(conn, team_name="t1", by_device="DEV-A") + + meta_dir = meta_base / "karma-meta--t1" / "removed" + assert not (meta_dir / "alice.mac.json").exists(), \ + "Leader should NOT get a removal signal" + + async def test_dissolution_signal_triggers_auto_leave(self, conn, stack, meta_base): + """Simulates: leader dissolves, bob's reconciliation detects signal → auto-leaves.""" + team_svc = stack["team_svc"] + + await team_svc.create_team( + conn, name="t1", leader_member_tag="alice.mac", leader_device_id="DEV-A", + ) + await team_svc.add_member( + conn, team_name="t1", by_device="DEV-A", + new_member_tag="bob.linux", new_device_id="DEV-B", + ) + + # Dissolve writes removal signals (with team_id) + original_team = stack["teams"].get(conn, "t1") + await team_svc.dissolve_team(conn, team_name="t1", by_device="DEV-A") + + # Now simulate bob's machine: recreate team in a fresh DB + bob_conn = sqlite3.connect(":memory:") + bob_conn.row_factory = sqlite3.Row + bob_conn.execute("PRAGMA foreign_keys=ON") + ensure_schema(bob_conn) + + # Bob's machine has the team (from earlier Phase 0 discovery) + # Uses the same team_id — in production, Phase 0 reads this from team.json + stack["teams"].save(bob_conn, Team( + name="t1", leader_device_id="DEV-A", leader_member_tag="alice.mac", + team_id=original_team.team_id, + )) + bob_member = Member.from_member_tag( + member_tag="bob.linux", team_name="t1", + device_id="DEV-B", status=MemberStatus.ACTIVE, + ) + stack["members"].save(bob_conn, bob_member) + + # Bob's reconciliation reads metadata — finds removal signal + recon = ReconciliationService( + **{k: stack[k] for k in ("teams", "members", "projects", "subs", "events")}, + devices=stack["devices"], + folders=stack["folders"], + metadata=stack["metadata"], + my_member_tag="bob.linux", + my_device_id="DEV-B", + ) + + team = stack["teams"].get(bob_conn, "t1") + await recon.phase_metadata(bob_conn, team) + + # Bob's team should be deleted (auto-leave triggered) + assert stack["teams"].get(bob_conn, "t1") is None, \ + "Bob's team should be deleted after auto-leave" + + +# ============================================================================== +# Bug 4: Leader self-removal guard +# ============================================================================== + +class TestBug4LeaderSelfRemovalGuard: + """Leader cannot remove themselves — must dissolve instead.""" + + async def test_leader_cannot_self_remove(self, conn, stack): + team_svc = stack["team_svc"] + + await team_svc.create_team( + conn, name="t1", leader_member_tag="alice.mac", leader_device_id="DEV-A", + ) + + with pytest.raises(InvalidTransitionError, match="leader"): + await team_svc.remove_member( + conn, team_name="t1", by_device="DEV-A", member_tag="alice.mac", + ) + + async def test_leader_can_remove_others(self, conn, stack): + team_svc = stack["team_svc"] + + await team_svc.create_team( + conn, name="t1", leader_member_tag="alice.mac", leader_device_id="DEV-A", + ) + await team_svc.add_member( + conn, team_name="t1", by_device="DEV-A", + new_member_tag="bob.linux", new_device_id="DEV-B", + ) + + removed = await team_svc.remove_member( + conn, team_name="t1", by_device="DEV-A", member_tag="bob.linux", + ) + assert removed.status == MemberStatus.REMOVED + + def test_domain_model_blocks_leader_removal(self): + team = Team( + name="t1", leader_device_id="DEV-A", leader_member_tag="alice.mac", + ) + member = Member.from_member_tag( + member_tag="alice.mac", team_name="t1", + device_id="DEV-A", status=MemberStatus.ACTIVE, + ) + with pytest.raises(InvalidTransitionError, match="leader"): + team.remove_member(member, by_device="DEV-A") + + +# ============================================================================== +# Bug 5: change_direction cross-team outbox safety +# ============================================================================== + +class TestBug5ChangeDirectionCrossTeamSafety: + """Changing direction should not delete outbox if another team needs it.""" + + async def test_outbox_preserved_when_other_team_needs_it(self, conn, stack): + """Bob has BOTH in alpha, SEND in beta (same project). + Changing alpha to RECEIVE should NOT delete outbox.""" + await _setup_two_teams_shared_project(conn, stack) + project_svc = stack["project_svc"] + + # Bob accepts in both teams: BOTH in alpha (via add_member OFFERED), + # but bob isn't in alpha. Let's set up bob in alpha too. + # Actually, let's create a simpler scenario: + # alice has ACCEPTED/BOTH in alpha (leader auto-accept) + # alice has ACCEPTED/BOTH in beta (accepted above) + # Change alpha direction to RECEIVE → should NOT delete outbox + + stack["folders"].remove_outbox_folder.reset_mock() + + await project_svc.change_direction( + conn, member_tag="alice.mac", team_name="alpha", + git_identity="org/webapp", direction=SyncDirection.RECEIVE, + ) + + # Outbox should NOT be removed because beta still has BOTH + stack["folders"].remove_outbox_folder.assert_not_called() + + async def test_outbox_removed_when_no_other_team_needs_it(self, conn, stack): + """If alice only has one team, changing to RECEIVE should delete outbox.""" + team_svc = stack["team_svc"] + project_svc = stack["project_svc"] + + await team_svc.create_team( + conn, name="solo", leader_member_tag="eve.ubuntu", leader_device_id="DEV-E", + ) + await project_svc.share_project( + conn, team_name="solo", by_device="DEV-E", + git_identity="org/solo-repo", encoded_name="-org-solo-repo", + ) + + stack["folders"].remove_outbox_folder.reset_mock() + + await project_svc.change_direction( + conn, member_tag="eve.ubuntu", team_name="solo", + git_identity="org/solo-repo", direction=SyncDirection.RECEIVE, + ) + + # Outbox SHOULD be removed — no other team has this project + stack["folders"].remove_outbox_folder.assert_called_once() diff --git a/api/tests/test_sync_v4_e2e.py b/api/tests/test_sync_v4_e2e.py new file mode 100644 index 00000000..eedf9450 --- /dev/null +++ b/api/tests/test_sync_v4_e2e.py @@ -0,0 +1,294 @@ +"""End-to-end smoke test: full sync v4 stack from router to domain model.""" +import sys +from pathlib import Path + +sys.path.insert(0, str(Path(__file__).parent.parent)) + +import sqlite3 + +import pytest +from unittest.mock import MagicMock, AsyncMock + +from db.schema import ensure_schema + +from domain.team import Team, TeamStatus +from domain.member import Member, MemberStatus +from domain.project import SharedProject, derive_folder_suffix +from domain.subscription import Subscription, SubscriptionStatus, SyncDirection +from domain.events import SyncEvent, SyncEventType +from repositories.team_repo import TeamRepository +from repositories.member_repo import MemberRepository +from repositories.project_repo import ProjectRepository +from repositories.subscription_repo import SubscriptionRepository +from repositories.event_repo import EventRepository +from services.sync.team_service import TeamService +from services.sync.project_service import ProjectService +from services.sync.pairing_service import PairingService +from services.sync.metadata_service import MetadataService +from services.sync.reconciliation_service import ReconciliationService + + +@pytest.fixture +def conn(): + c = sqlite3.connect(":memory:") + c.row_factory = sqlite3.Row + c.execute("PRAGMA foreign_keys=ON") + ensure_schema(c) + return c + + +@pytest.fixture +def meta_base(tmp_path): + return tmp_path / "meta" + + +@pytest.fixture +def stack(conn, meta_base): + """Build full service stack with mocked Syncthing managers.""" + devices = MagicMock() + devices.pair = AsyncMock() + devices.unpair = AsyncMock() + devices.ensure_paired = AsyncMock() + + folders = MagicMock() + folders.ensure_metadata_folder = AsyncMock() + folders.ensure_outbox_folder = AsyncMock() + folders.ensure_inbox_folder = AsyncMock() + folders.set_folder_devices = AsyncMock() + folders.get_configured_folders = AsyncMock(return_value=[]) + folders.remove_outbox_folder = AsyncMock() + folders.remove_device_from_team_folders = AsyncMock() + folders.cleanup_team_folders = AsyncMock() + folders.cleanup_project_folders = AsyncMock() + + repos = { + "teams": TeamRepository(), + "members": MemberRepository(), + "projects": ProjectRepository(), + "subs": SubscriptionRepository(), + "events": EventRepository(), + } + metadata = MetadataService(meta_base=meta_base) + + team_svc = TeamService( + **repos, devices=devices, metadata=metadata, folders=folders, + ) + project_svc = ProjectService( + **repos, + folders=folders, + metadata=metadata, + ) + recon_svc = ReconciliationService( + **repos, + devices=devices, + folders=folders, + metadata=metadata, + my_member_tag="jayant.macbook", + ) + pairing_svc = PairingService() + + return { + "team_svc": team_svc, + "project_svc": project_svc, + "recon_svc": recon_svc, + "pairing_svc": pairing_svc, + "devices": devices, + "folders": folders, + **repos, + } + + +class TestFullE2EFlow: + """Tests the complete user journey from spec Flows 1-5.""" + + async def test_complete_sync_lifecycle(self, conn, stack): + team_svc = stack["team_svc"] + project_svc = stack["project_svc"] + pairing_svc = stack["pairing_svc"] + + # Flow 1: Leader creates team + team = await team_svc.create_team( + conn, + name="karma", + leader_member_tag="jayant.macbook", + leader_device_id="DEV-L", + ) + assert team.status == TeamStatus.ACTIVE + + # Leader shares project (git-only, with encoded_name) + project = await project_svc.share_project( + conn, + team_name="karma", + by_device="DEV-L", + git_identity="jayantdevkar/claude-karma", + encoded_name="-Users-jayant-GitHub-claude-karma", + ) + assert project.git_identity == "jayantdevkar/claude-karma" + assert project.folder_suffix == derive_folder_suffix("jayantdevkar/claude-karma") + # Leader has local copy — outbox folder should be created + stack["folders"].ensure_outbox_folder.assert_called_once() + + # Flow 2: Member generates pairing code, leader validates and adds member + code = pairing_svc.generate_code("ayush.laptop", "DEV-A") + info = pairing_svc.validate_code(code) + assert info.member_tag == "ayush.laptop" + assert info.device_id == "DEV-A" + + member = await team_svc.add_member( + conn, + team_name="karma", + by_device="DEV-L", + new_member_tag=info.member_tag, + new_device_id=info.device_id, + ) + assert member.status == MemberStatus.ADDED + stack["devices"].pair.assert_called_once_with("DEV-A") + + # Verify subscription was auto-created as OFFERED + subs = stack["subs"].list_for_member(conn, "ayush.laptop") + assert len(subs) == 1 + assert subs[0].status == SubscriptionStatus.OFFERED + assert subs[0].project_git_identity == "jayantdevkar/claude-karma" + + # Flow 3: Member accepts project with direction=BOTH + stack["folders"].ensure_outbox_folder.reset_mock() + stack["folders"].ensure_inbox_folder.reset_mock() + + accepted = await project_svc.accept_subscription( + conn, + member_tag="ayush.laptop", + team_name="karma", + git_identity="jayantdevkar/claude-karma", + direction=SyncDirection.BOTH, + ) + assert accepted.status == SubscriptionStatus.ACCEPTED + assert accepted.direction == SyncDirection.BOTH + # BOTH direction: outbox (send) + inbox (receive from each active teammate) + stack["folders"].ensure_outbox_folder.assert_called() + stack["folders"].ensure_inbox_folder.assert_called() + + # Flow 5: Member changes direction to RECEIVE only + stack["folders"].remove_outbox_folder.reset_mock() + + changed = await project_svc.change_direction( + conn, + member_tag="ayush.laptop", + team_name="karma", + git_identity="jayantdevkar/claude-karma", + direction=SyncDirection.RECEIVE, + ) + assert changed.direction == SyncDirection.RECEIVE + # Was sending (BOTH), now not sending — outbox should be removed + stack["folders"].remove_outbox_folder.assert_called_once_with( + "ayush.laptop", project.folder_suffix, + ) + + # Flow 4: Leader removes member + removed = await team_svc.remove_member( + conn, + team_name="karma", + by_device="DEV-L", + member_tag="ayush.laptop", + ) + assert removed.status == MemberStatus.REMOVED + # Device not in other teams — should be unpaired + stack["devices"].unpair.assert_called_once_with("DEV-A") + + # Verify removal signal written to metadata folder + meta = metadata_service_from_stack(stack) + team_meta = meta.read_team_metadata("karma") + assert "__removals" in team_meta + assert "ayush.laptop" in team_meta["__removals"] + + # Verify all expected events were logged + events = stack["events"].query(conn, team="karma", limit=100) + event_types = {e.event_type.value for e in events} + assert "team_created" in event_types + assert "project_shared" in event_types + assert "member_added" in event_types + assert "subscription_accepted" in event_types + assert "direction_changed" in event_types + assert "member_removed" in event_types + + async def test_pairing_code_roundtrip(self, stack): + """Pairing code encodes and decodes member_tag + device_id losslessly.""" + pairing_svc = stack["pairing_svc"] + code = pairing_svc.generate_code("alice.desktop", "DEV-XYZ") + assert isinstance(code, str) + assert len(code) > 0 + + info = pairing_svc.validate_code(code) + assert info.member_tag == "alice.desktop" + assert info.device_id == "DEV-XYZ" + + async def test_team_create_logs_event(self, conn, stack): + """Creating a team always logs team_created event.""" + await stack["team_svc"].create_team( + conn, + name="alpha", + leader_member_tag="bob.server", + leader_device_id="DEV-B", + ) + events = stack["events"].query(conn, team="alpha") + assert any(e.event_type == SyncEventType.team_created for e in events) + + async def test_share_project_without_local_repo_skips_outbox(self, conn, stack): + """Sharing a project without encoded_name (git-only) skips outbox creation.""" + await stack["team_svc"].create_team( + conn, + name="beta", + leader_member_tag="carol.laptop", + leader_device_id="DEV-C", + ) + stack["folders"].ensure_outbox_folder.reset_mock() + + project = await stack["project_svc"].share_project( + conn, + team_name="beta", + by_device="DEV-C", + git_identity="org/remote-only-repo", + encoded_name=None, # no local copy + ) + assert project.git_identity == "org/remote-only-repo" + # No local copy → no outbox folder + stack["folders"].ensure_outbox_folder.assert_not_called() + + async def test_decline_subscription(self, conn, stack): + """Member can decline an offered subscription.""" + # Setup + await stack["team_svc"].create_team( + conn, + name="gamma", + leader_member_tag="dave.mac", + leader_device_id="DEV-D", + ) + await stack["project_svc"].share_project( + conn, + team_name="gamma", + by_device="DEV-D", + git_identity="dave/project", + ) + await stack["team_svc"].add_member( + conn, + team_name="gamma", + by_device="DEV-D", + new_member_tag="eve.laptop", + new_device_id="DEV-E", + ) + + declined = await stack["project_svc"].decline_subscription( + conn, + member_tag="eve.laptop", + team_name="gamma", + git_identity="dave/project", + ) + assert declined.status == SubscriptionStatus.DECLINED + + events = stack["events"].query(conn, team="gamma", limit=100) + event_types = {e.event_type.value for e in events} + assert "subscription_declined" in event_types + + +def metadata_service_from_stack(stack: dict) -> "MetadataService": + """Extract MetadataService from the team_svc (shared reference).""" + return stack["team_svc"].metadata diff --git a/api/tests/test_sync_v4_multi_team_e2e.py b/api/tests/test_sync_v4_multi_team_e2e.py new file mode 100644 index 00000000..ab545ae0 --- /dev/null +++ b/api/tests/test_sync_v4_multi_team_e2e.py @@ -0,0 +1,569 @@ +"""Multi-team overlap E2E test — verifies cross-team safety. + +Exercises the exact scenario from the v3 audit: two teams sharing the same +project with an overlapping member. Validates that leave/dissolve/remove-project +operations on one team never corrupt the other team's data. +""" +import sys +from pathlib import Path + +sys.path.insert(0, str(Path(__file__).parent.parent)) + +import sqlite3 + +import pytest +from unittest.mock import MagicMock, AsyncMock + +from db.schema import ensure_schema + +from domain.team import TeamStatus +from domain.member import MemberStatus +from domain.project import SharedProject, SharedProjectStatus, derive_folder_suffix +from domain.subscription import Subscription, SubscriptionStatus, SyncDirection +from domain.events import SyncEvent, SyncEventType +from repositories.team_repo import TeamRepository +from repositories.member_repo import MemberRepository +from repositories.project_repo import ProjectRepository +from repositories.subscription_repo import SubscriptionRepository +from repositories.event_repo import EventRepository +from services.sync.team_service import TeamService +from services.sync.project_service import ProjectService +from services.sync.reconciliation_service import ReconciliationService +from services.sync.metadata_service import MetadataService + + +# --------------------------------------------------------------------------- +# Fixtures +# --------------------------------------------------------------------------- + +@pytest.fixture +def conn(): + c = sqlite3.connect(":memory:") + c.row_factory = sqlite3.Row + c.execute("PRAGMA foreign_keys=ON") + ensure_schema(c) + return c + + +@pytest.fixture +def meta_base(tmp_path): + return tmp_path / "meta" + + +@pytest.fixture +def stack(conn, meta_base): + """Build full service stack with mocked Syncthing managers.""" + devices = MagicMock() + devices.pair = AsyncMock() + devices.unpair = AsyncMock() + devices.ensure_paired = AsyncMock() + + folders = MagicMock() + folders.ensure_metadata_folder = AsyncMock() + folders.ensure_outbox_folder = AsyncMock() + folders.ensure_inbox_folder = AsyncMock() + folders.set_folder_devices = AsyncMock() + folders.get_configured_folders = AsyncMock(return_value=[]) + folders.remove_outbox_folder = AsyncMock() + folders.remove_device_from_team_folders = AsyncMock() + folders.cleanup_team_folders = AsyncMock() + folders.cleanup_project_folders = AsyncMock() + + repos = { + "teams": TeamRepository(), + "members": MemberRepository(), + "projects": ProjectRepository(), + "subs": SubscriptionRepository(), + "events": EventRepository(), + } + metadata = MetadataService(meta_base=meta_base) + + team_svc = TeamService( + **repos, devices=devices, metadata=metadata, folders=folders, + ) + project_svc = ProjectService( + **repos, folders=folders, metadata=metadata, + ) + + return { + "team_svc": team_svc, + "project_svc": project_svc, + "devices": devices, + "folders": folders, + "metadata": metadata, + **repos, + } + + +# --------------------------------------------------------------------------- +# Helpers — build the two-team, overlapping-member scenario +# --------------------------------------------------------------------------- + +async def _setup_two_teams_shared_project(conn, stack): + """Create T1 (leader=L1) and T2 (leader=L2), both sharing 'owner/repo'. + + Alice is added to both teams and accepts the project in both (direction=BOTH). + Returns dict with keys: t1, t2, p1, p2, alice_sub_t1, alice_sub_t2. + """ + team_svc = stack["team_svc"] + project_svc = stack["project_svc"] + + # --- Team 1 --- + t1 = await team_svc.create_team( + conn, + name="team-1", + leader_member_tag="leader1.desktop", + leader_device_id="DEV-L1", + ) + + p1 = await project_svc.share_project( + conn, + team_name="team-1", + by_device="DEV-L1", + git_identity="owner/repo", + encoded_name="-Users-owner-repo", + ) + + # --- Team 2 --- + t2 = await team_svc.create_team( + conn, + name="team-2", + leader_member_tag="leader2.laptop", + leader_device_id="DEV-L2", + ) + + p2 = await project_svc.share_project( + conn, + team_name="team-2", + by_device="DEV-L2", + git_identity="owner/repo", + encoded_name="-Users-owner-repo", + ) + + # --- Alice joins both teams --- + await team_svc.add_member( + conn, + team_name="team-1", + by_device="DEV-L1", + new_member_tag="alice.laptop", + new_device_id="DEV-ALICE", + ) + + await team_svc.add_member( + conn, + team_name="team-2", + by_device="DEV-L2", + new_member_tag="alice.laptop", + new_device_id="DEV-ALICE", + ) + + # --- Activate Alice in both teams (simulates reconciliation Phase 1) --- + members_repo = stack["members"] + alice_t1 = members_repo.get(conn, "team-1", "alice.laptop") + members_repo.save(conn, alice_t1.activate()) + alice_t2 = members_repo.get(conn, "team-2", "alice.laptop") + members_repo.save(conn, alice_t2.activate()) + + # --- Alice accepts project in both teams --- + alice_sub_t1 = await project_svc.accept_subscription( + conn, + member_tag="alice.laptop", + team_name="team-1", + git_identity="owner/repo", + direction=SyncDirection.BOTH, + ) + + alice_sub_t2 = await project_svc.accept_subscription( + conn, + member_tag="alice.laptop", + team_name="team-2", + git_identity="owner/repo", + direction=SyncDirection.BOTH, + ) + + return { + "t1": t1, + "t2": t2, + "p1": p1, + "p2": p2, + "alice_sub_t1": alice_sub_t1, + "alice_sub_t2": alice_sub_t2, + } + + +# --------------------------------------------------------------------------- +# Test class +# --------------------------------------------------------------------------- + +class TestMultiTeamOverlapE2E: + """Verifies cross-team safety when two teams share the same project + with an overlapping member (Alice).""" + + async def test_leave_team1_preserves_team2_subscriptions(self, conn, stack): + """Full lifecycle: Alice leaves Team 1, Team 2 subscription stays intact. + + Steps: + 1. Create Team 1 (leader: L1) and Team 2 (leader: L2) + 2. Both leaders share the same project (git_identity="owner/repo") + 3. Add Alice to both teams via pairing flow + 4. Alice accepts project in both teams (direction=BOTH) + 5. Verify Alice has 2 ACCEPTED subscriptions + 6. Alice leaves Team 1 + 7. Verify: Alice's Team 2 subscription is still ACCEPTED with direction=both + 8. Verify: Team 1 data is deleted (team not found) + 9. Run Phase 3 reconciliation for Team 2 — verify it still works + """ + ctx = await _setup_two_teams_shared_project(conn, stack) + team_svc = stack["team_svc"] + subs_repo = stack["subs"] + + # Step 5: Verify Alice has 2 ACCEPTED subscriptions + alice_subs = subs_repo.list_for_member(conn, "alice.laptop") + accepted = [s for s in alice_subs if s.status == SubscriptionStatus.ACCEPTED] + assert len(accepted) == 2, ( + f"Expected 2 ACCEPTED subs for Alice, got {len(accepted)}: " + f"{[(s.team_name, s.status.value) for s in alice_subs]}" + ) + + # Step 6: Alice leaves Team 1 + await team_svc.leave_team( + conn, + team_name="team-1", + member_tag="alice.laptop", + ) + + # Step 7: Team 2 subscription must survive + t2_sub = subs_repo.get(conn, "alice.laptop", "team-2", "owner/repo") + assert t2_sub is not None, "Team 2 subscription must survive after leaving Team 1" + assert t2_sub.status == SubscriptionStatus.ACCEPTED + assert t2_sub.direction == SyncDirection.BOTH + + # Step 8: Team 1 is gone (deleted by leave_team) + teams_repo = stack["teams"] + t1_after = teams_repo.get(conn, "team-1") + assert t1_after is None, "Team 1 should be deleted after Alice leaves" + + # Team 2 still exists and is ACTIVE + t2_after = teams_repo.get(conn, "team-2") + assert t2_after is not None + assert t2_after.status == TeamStatus.ACTIVE + + # Step 9: Phase 3 reconciliation for Team 2 still works + # Build a ReconciliationService as Alice's machine + recon_svc = ReconciliationService( + **{k: v for k, v in stack.items() + if k in ("teams", "members", "projects", "subs", "events")}, + devices=stack["devices"], + folders=stack["folders"], + metadata=stack["metadata"], + my_member_tag="alice.laptop", + my_device_id="DEV-ALICE", + ) + + # Reset mocks so we can check Phase 3 calls + stack["folders"].set_folder_devices.reset_mock() + stack["folders"].ensure_outbox_folder.reset_mock() + + await recon_svc.phase_device_lists(conn, t2_after) + + # Phase 3 should have called set_folder_devices for Team 2's project + assert stack["folders"].set_folder_devices.call_count > 0, ( + "Phase 3 must call set_folder_devices for Team 2 after Alice leaves Team 1" + ) + + # Verify the desired device set includes Alice and L2 (both have ACCEPTED+BOTH) + # Since list_accepted_for_suffix returns all accepted subs for the suffix + # across ALL teams, and Team 1 is deleted, only Team 2 subs remain. + suffix = derive_folder_suffix("owner/repo") + all_accepted = subs_repo.list_accepted_for_suffix(conn, suffix) + accepted_tags = {s.member_tag for s in all_accepted} + assert "alice.laptop" in accepted_tags, ( + "Alice must still appear in accepted subs for the project suffix" + ) + assert "leader2.laptop" in accepted_tags, ( + "Leader 2 must still appear in accepted subs for the project suffix" + ) + # Team 1's leader sub should be gone (CASCADE on team delete) + assert all(s.team_name == "team-2" for s in all_accepted), ( + "All remaining accepted subs should belong to team-2" + ) + + async def test_dissolve_team_preserves_other_team(self, conn, stack): + """Leader dissolves Team 1 — Team 2 and Alice's T2 subscription survive. + + Steps: + 1. Create T1 and T2 sharing same project, Alice in both (accepts both) + 2. L1 dissolves T1 + 3. Verify: T2 and Alice's T2 subscription still intact + """ + ctx = await _setup_two_teams_shared_project(conn, stack) + team_svc = stack["team_svc"] + teams_repo = stack["teams"] + subs_repo = stack["subs"] + projects_repo = stack["projects"] + + # Verify precondition: both teams exist + assert teams_repo.get(conn, "team-1") is not None + assert teams_repo.get(conn, "team-2") is not None + + # L1 dissolves Team 1 + dissolved = await team_svc.dissolve_team( + conn, + team_name="team-1", + by_device="DEV-L1", + ) + assert dissolved.status == TeamStatus.DISSOLVED + + # Team 1 is soft-deleted (DISSOLVED status, still queryable) + t1_after = teams_repo.get(conn, "team-1") + assert t1_after is not None + assert t1_after.status == TeamStatus.DISSOLVED + + # Team 2 is alive and ACTIVE + t2 = teams_repo.get(conn, "team-2") + assert t2 is not None + assert t2.status == TeamStatus.ACTIVE + + # Alice's Team 2 subscription survived + t2_sub = subs_repo.get(conn, "alice.laptop", "team-2", "owner/repo") + assert t2_sub is not None, "Alice's T2 subscription must survive T1 dissolution" + assert t2_sub.status == SubscriptionStatus.ACCEPTED + assert t2_sub.direction == SyncDirection.BOTH + + # Leader 2's subscription survived + l2_sub = subs_repo.get(conn, "leader2.laptop", "team-2", "owner/repo") + assert l2_sub is not None, "Leader 2's subscription must survive T1 dissolution" + assert l2_sub.status == SubscriptionStatus.ACCEPTED + + # Team 2's project is still SHARED + t2_proj = projects_repo.get(conn, "team-2", "owner/repo") + assert t2_proj is not None + assert t2_proj.status == SharedProjectStatus.SHARED + + # Team 1's project is gone (CASCADE) + t1_proj = projects_repo.get(conn, "team-1", "owner/repo") + assert t1_proj is None, "Team 1's project should be deleted by CASCADE" + + # Alice's Team 1 subscription is gone (CASCADE) + t1_sub = subs_repo.get(conn, "alice.laptop", "team-1", "owner/repo") + assert t1_sub is None, "Alice's T1 subscription should be deleted by CASCADE" + + # Team 1 members are gone (CASCADE) + members_repo = stack["members"] + t1_members = members_repo.list_for_team(conn, "team-1") + assert len(t1_members) == 0, "Team 1 members should be deleted by CASCADE" + + # Team 2 members still intact + t2_members = members_repo.list_for_team(conn, "team-2") + t2_tags = {m.member_tag for m in t2_members} + assert "leader2.laptop" in t2_tags + assert "alice.laptop" in t2_tags + + async def test_remove_project_from_one_team_preserves_other(self, conn, stack): + """L1 removes project from T1 — T2's project and Alice's T2 subscription survive. + + Steps: + 1. Create T1 and T2 sharing same project, Alice in both (accepts both) + 2. L1 removes project from T1 + 3. Verify: T2's project still SHARED, Alice's T2 subscription still ACCEPTED + """ + ctx = await _setup_two_teams_shared_project(conn, stack) + project_svc = stack["project_svc"] + subs_repo = stack["subs"] + projects_repo = stack["projects"] + + # Precondition: both teams have the project as SHARED + p1 = projects_repo.get(conn, "team-1", "owner/repo") + p2 = projects_repo.get(conn, "team-2", "owner/repo") + assert p1 is not None and p1.status == SharedProjectStatus.SHARED + assert p2 is not None and p2.status == SharedProjectStatus.SHARED + + # L1 removes project from Team 1 + removed = await project_svc.remove_project( + conn, + team_name="team-1", + by_device="DEV-L1", + git_identity="owner/repo", + ) + assert removed.status == SharedProjectStatus.REMOVED + + # Team 1's project is REMOVED + t1_proj = projects_repo.get(conn, "team-1", "owner/repo") + assert t1_proj is not None + assert t1_proj.status == SharedProjectStatus.REMOVED + + # Team 2's project is still SHARED + t2_proj = projects_repo.get(conn, "team-2", "owner/repo") + assert t2_proj is not None, "T2 project must survive T1 project removal" + assert t2_proj.status == SharedProjectStatus.SHARED + + # Alice's Team 2 subscription still ACCEPTED + t2_sub = subs_repo.get(conn, "alice.laptop", "team-2", "owner/repo") + assert t2_sub is not None, "Alice's T2 subscription must survive T1 project removal" + assert t2_sub.status == SubscriptionStatus.ACCEPTED + assert t2_sub.direction == SyncDirection.BOTH + + # Leader 2's Team 2 subscription still ACCEPTED + l2_sub = subs_repo.get(conn, "leader2.laptop", "team-2", "owner/repo") + assert l2_sub is not None + assert l2_sub.status == SubscriptionStatus.ACCEPTED + + # Alice's Team 1 subscription should be DECLINED (remove_project declines all) + t1_sub = subs_repo.get(conn, "alice.laptop", "team-1", "owner/repo") + assert t1_sub is not None + assert t1_sub.status == SubscriptionStatus.DECLINED + + # Leader 1's Team 1 subscription should also be DECLINED + l1_sub = subs_repo.get(conn, "leader1.desktop", "team-1", "owner/repo") + assert l1_sub is not None + assert l1_sub.status == SubscriptionStatus.DECLINED + + # Phase 3 for Team 2 still produces correct device sets + suffix = derive_folder_suffix("owner/repo") + all_accepted = subs_repo.list_accepted_for_suffix(conn, suffix) + # Only Team 2 subs should be accepted (Team 1 subs are DECLINED) + assert all(s.team_name == "team-2" for s in all_accepted), ( + f"Only T2 subs should be accepted, got: " + f"{[(s.team_name, s.member_tag, s.status.value) for s in all_accepted]}" + ) + accepted_tags = {s.member_tag for s in all_accepted} + assert "alice.laptop" in accepted_tags + assert "leader2.laptop" in accepted_tags + + async def test_phase3_device_lists_cross_team_after_leave(self, conn, stack): + """Phase 3 computes correct device set when Alice is in T2 only. + + Ensures that after leaving T1, Phase 3 includes Alice's device in + outbox device lists for T2's project folders but NOT T1's. + """ + ctx = await _setup_two_teams_shared_project(conn, stack) + team_svc = stack["team_svc"] + teams_repo = stack["teams"] + + # Alice leaves Team 1 + await team_svc.leave_team( + conn, + team_name="team-1", + member_tag="alice.laptop", + ) + + # Phase 3 for Team 2 (as leader 2's machine) + recon_svc = ReconciliationService( + **{k: v for k, v in stack.items() + if k in ("teams", "members", "projects", "subs", "events")}, + devices=stack["devices"], + folders=stack["folders"], + metadata=stack["metadata"], + my_member_tag="leader2.laptop", + my_device_id="DEV-L2", + ) + + stack["folders"].set_folder_devices.reset_mock() + + t2 = teams_repo.get(conn, "team-2") + assert t2 is not None + await recon_svc.phase_device_lists(conn, t2) + + # Verify set_folder_devices was called and includes both L2 and Alice + assert stack["folders"].set_folder_devices.call_count > 0 + + # Collect all device sets passed to set_folder_devices + all_device_sets = [ + call.args[1] if len(call.args) > 1 else call.kwargs.get("device_ids", set()) + for call in stack["folders"].set_folder_devices.call_args_list + ] + # At least one call should include both DEV-L2 and DEV-ALICE + has_both = any( + "DEV-L2" in ds and "DEV-ALICE" in ds + for ds in all_device_sets + ) + assert has_both, ( + f"Phase 3 device sets should include both DEV-L2 and DEV-ALICE: {all_device_sets}" + ) + + async def test_alice_device_not_unpaired_when_in_other_team(self, conn, stack): + """When Alice is removed from T1, her device is NOT unpaired because she's in T2.""" + ctx = await _setup_two_teams_shared_project(conn, stack) + team_svc = stack["team_svc"] + + stack["devices"].unpair.reset_mock() + + # L1 removes Alice from Team 1 + await team_svc.remove_member( + conn, + team_name="team-1", + by_device="DEV-L1", + member_tag="alice.laptop", + ) + + # Alice's device should NOT be unpaired — she's still in Team 2 + stack["devices"].unpair.assert_not_called() + + # Alice's Team 2 subscription is unaffected + t2_sub = stack["subs"].get(conn, "alice.laptop", "team-2", "owner/repo") + assert t2_sub is not None + assert t2_sub.status == SubscriptionStatus.ACCEPTED + + async def test_events_logged_correctly_across_teams(self, conn, stack): + """Event log correctly attributes events to their respective teams.""" + ctx = await _setup_two_teams_shared_project(conn, stack) + events_repo = stack["events"] + + # Check Team 1 events + t1_events = events_repo.query(conn, team="team-1", limit=100) + t1_types = {e.event_type.value for e in t1_events} + assert "team_created" in t1_types + assert "project_shared" in t1_types + assert "member_added" in t1_types + assert "subscription_accepted" in t1_types + + # Check Team 2 events + t2_events = events_repo.query(conn, team="team-2", limit=100) + t2_types = {e.event_type.value for e in t2_events} + assert "team_created" in t2_types + assert "project_shared" in t2_types + assert "member_added" in t2_types + assert "subscription_accepted" in t2_types + + # Dissolve Team 1 and verify event isolation + await stack["team_svc"].dissolve_team( + conn, + team_name="team-1", + by_device="DEV-L1", + ) + + # Team 2 events should not contain team_dissolved + t2_events_after = events_repo.query(conn, team="team-2", limit=100) + t2_types_after = {e.event_type.value for e in t2_events_after} + assert "team_dissolved" not in t2_types_after, ( + "team_dissolved event should be logged against team-1, not team-2" + ) + + async def test_folder_suffix_shared_across_teams(self, conn, stack): + """Both teams produce the same folder_suffix for the same git_identity.""" + ctx = await _setup_two_teams_shared_project(conn, stack) + projects_repo = stack["projects"] + + p1 = projects_repo.get(conn, "team-1", "owner/repo") + p2 = projects_repo.get(conn, "team-2", "owner/repo") + + assert p1 is not None and p2 is not None + assert p1.folder_suffix == p2.folder_suffix + assert p1.folder_suffix == derive_folder_suffix("owner/repo") + + async def test_list_accepted_for_suffix_spans_both_teams(self, conn, stack): + """list_accepted_for_suffix returns subs from BOTH teams before any cleanup.""" + ctx = await _setup_two_teams_shared_project(conn, stack) + subs_repo = stack["subs"] + + suffix = derive_folder_suffix("owner/repo") + all_accepted = subs_repo.list_accepted_for_suffix(conn, suffix) + + # Should include: L1 (auto-created on share), Alice (T1), L2 (auto-created), Alice (T2) + assert len(all_accepted) == 4, ( + f"Expected 4 accepted subs (2 per team), got {len(all_accepted)}: " + f"{[(s.team_name, s.member_tag) for s in all_accepted]}" + ) + + teams_in_subs = {s.team_name for s in all_accepted} + assert teams_in_subs == {"team-1", "team-2"} diff --git a/api/tests/test_syncthing_client.py b/api/tests/test_syncthing_client.py new file mode 100644 index 00000000..2e19efb2 --- /dev/null +++ b/api/tests/test_syncthing_client.py @@ -0,0 +1,273 @@ +""" +Tests for SyncthingClient — pure HTTP wrapper for Syncthing REST API. +""" + +import sys +from pathlib import Path + +sys.path.insert(0, str(Path(__file__).parent.parent)) + +from unittest.mock import AsyncMock, MagicMock, patch + +import httpx +import pytest + +from services.syncthing.client import SyncthingClient + + +@pytest.fixture +def client(): + return SyncthingClient(api_url="http://localhost:8384", api_key="test-api-key") + + +@pytest.fixture +def mock_response(): + def _make(json_data, status_code=200): + resp = MagicMock(spec=httpx.Response) + resp.status_code = status_code + resp.json.return_value = json_data + resp.raise_for_status = MagicMock() + return resp + + return _make + + +class TestSyncthingClientInit: + def test_stores_api_url(self): + c = SyncthingClient(api_url="http://host:8384", api_key="key") + assert c.api_url == "http://host:8384" + + def test_stores_api_key(self): + c = SyncthingClient(api_url="http://host:8384", api_key="key") + assert c.api_key == "key" + + def test_default_timeout(self): + c = SyncthingClient(api_url="http://host:8384", api_key="key") + assert c.timeout == 30.0 + + def test_custom_timeout(self): + c = SyncthingClient(api_url="http://host:8384", api_key="key", timeout=10.0) + assert c.timeout == 10.0 + + +class TestSyncthingClientHeaders: + def test_headers_include_api_key(self, client): + headers = client._headers() + assert headers["X-API-Key"] == "test-api-key" + + def test_headers_include_content_type(self, client): + headers = client._headers() + assert headers["Content-Type"] == "application/json" + + +class TestGetSystemStatus: + async def test_returns_json(self, client, mock_response): + expected = {"myID": "DEVICE-ID-1234", "uptime": 12345} + with patch.object(client, "_get", new=AsyncMock(return_value=expected)): + result = await client.get_system_status() + assert result == expected + + async def test_calls_correct_endpoint(self, client, mock_response): + with patch.object(client, "_get", new=AsyncMock(return_value={})) as mock_get: + await client.get_system_status() + mock_get.assert_called_once_with("/rest/system/status") + + +class TestGetConnections: + async def test_returns_connections_json(self, client): + expected = {"connections": {"DEVICE-ABC": {"connected": True}}} + with patch.object(client, "_get", new=AsyncMock(return_value=expected)): + result = await client.get_connections() + assert result == expected + + async def test_calls_correct_endpoint(self, client): + with patch.object(client, "_get", new=AsyncMock(return_value={})) as mock_get: + await client.get_connections() + mock_get.assert_called_once_with("/rest/system/connections") + + +class TestGetConfig: + async def test_returns_config(self, client): + expected = {"version": 37, "devices": [], "folders": []} + with patch.object(client, "_get", new=AsyncMock(return_value=expected)): + result = await client.get_config() + assert result == expected + + async def test_calls_correct_endpoint(self, client): + with patch.object(client, "_get", new=AsyncMock(return_value={})) as mock_get: + await client.get_config() + mock_get.assert_called_once_with("/rest/config") + + +class TestPostConfig: + async def test_posts_config(self, client): + config = {"version": 37, "devices": [], "folders": []} + with patch.object(client, "_post", new=AsyncMock(return_value=None)) as mock_post: + await client.post_config(config) + mock_post.assert_called_once_with("/rest/config", json=config) + + +class TestGetConfigDevices: + async def test_returns_devices_list(self, client): + expected = [{"deviceID": "AAAA-BBBB", "name": "my-laptop"}] + with patch.object(client, "_get", new=AsyncMock(return_value=expected)): + result = await client.get_config_devices() + assert result == expected + + async def test_calls_correct_endpoint(self, client): + with patch.object(client, "_get", new=AsyncMock(return_value=[])) as mock_get: + await client.get_config_devices() + mock_get.assert_called_once_with("/rest/config/devices") + + +class TestPutConfigDevice: + async def test_puts_device(self, client): + device = {"deviceID": "AAAA-BBBB", "name": "laptop", "addresses": ["dynamic"]} + with patch.object(client, "_put", new=AsyncMock(return_value=None)) as mock_put: + await client.put_config_device(device) + mock_put.assert_called_once_with("/rest/config/devices/AAAA-BBBB", json=device) + + +class TestDeleteConfigDevice: + async def test_deletes_device(self, client): + with patch.object(client, "_delete", new=AsyncMock(return_value=None)) as mock_del: + await client.delete_config_device("AAAA-BBBB") + mock_del.assert_called_once_with("/rest/config/devices/AAAA-BBBB") + + +class TestGetConfigFolders: + async def test_returns_folders_list(self, client): + expected = [{"id": "karma-out--user.host--abc", "label": "test"}] + with patch.object(client, "_get", new=AsyncMock(return_value=expected)): + result = await client.get_config_folders() + assert result == expected + + async def test_calls_correct_endpoint(self, client): + with patch.object(client, "_get", new=AsyncMock(return_value=[])) as mock_get: + await client.get_config_folders() + mock_get.assert_called_once_with("/rest/config/folders") + + +class TestPutConfigFolder: + async def test_puts_folder(self, client): + folder = {"id": "karma-out--user.host--abc", "type": "sendonly"} + with patch.object(client, "_put", new=AsyncMock(return_value=None)) as mock_put: + await client.put_config_folder(folder) + mock_put.assert_called_once_with("/rest/config/folders/karma-out--user.host--abc", json=folder) + + +class TestDeleteConfigFolder: + async def test_deletes_folder(self, client): + with patch.object(client, "_delete", new=AsyncMock(return_value=None)) as mock_del: + await client.delete_config_folder("karma-out--user.host--abc") + mock_del.assert_called_once_with("/rest/config/folders/karma-out--user.host--abc") + + +class TestGetPendingDevices: + async def test_returns_pending_devices(self, client): + expected = {"ZZZZ-YYYY": {"name": "unknown", "time": "2026-01-01T00:00:00Z"}} + with patch.object(client, "_get", new=AsyncMock(return_value=expected)): + result = await client.get_pending_devices() + assert result == expected + + async def test_calls_correct_endpoint(self, client): + with patch.object(client, "_get", new=AsyncMock(return_value={})) as mock_get: + await client.get_pending_devices() + mock_get.assert_called_once_with("/rest/cluster/pending/devices") + + +class TestGetPendingFolders: + async def test_returns_pending_folders(self, client): + expected = {"karma-join--user.host--team1": {"offeredBy": {"AAAA": {}}}} + with patch.object(client, "_get", new=AsyncMock(return_value=expected)): + result = await client.get_pending_folders() + assert result == expected + + async def test_calls_correct_endpoint(self, client): + with patch.object(client, "_get", new=AsyncMock(return_value={})) as mock_get: + await client.get_pending_folders() + mock_get.assert_called_once_with("/rest/cluster/pending/folders") + + +class TestGetFolderStatus: + async def test_returns_folder_status(self, client): + expected = {"state": "idle", "inSyncFiles": 42} + with patch.object(client, "_get", new=AsyncMock(return_value=expected)): + result = await client.get_folder_status("karma-out--user.host--abc") + assert result == expected + + async def test_passes_folder_id_as_param(self, client): + with patch.object(client, "_get", new=AsyncMock(return_value={})) as mock_get: + await client.get_folder_status("my-folder-id") + mock_get.assert_called_once_with("/rest/db/status", params={"folder": "my-folder-id"}) + + +class TestPostFolderRescan: + async def test_posts_rescan(self, client): + with patch.object(client, "_post", new=AsyncMock(return_value=None)) as mock_post: + await client.post_folder_rescan("my-folder-id") + mock_post.assert_called_once_with( + "/rest/db/scan", params={"folder": "my-folder-id"} + ) + + +class TestHttpMethods: + """Test actual HTTP method dispatch (with mocked httpx client).""" + + async def test_get_uses_get_verb(self, client): + mock_resp = MagicMock(spec=httpx.Response) + mock_resp.json.return_value = {"ok": True} + mock_resp.raise_for_status = MagicMock() + + mock_http = AsyncMock() + mock_http.get = AsyncMock(return_value=mock_resp) + + with patch("httpx.AsyncClient") as mock_client_cls: + mock_client_cls.return_value.__aenter__ = AsyncMock(return_value=mock_http) + mock_client_cls.return_value.__aexit__ = AsyncMock(return_value=False) + result = await client._get("/rest/system/status") + + mock_http.get.assert_called_once() + assert result == {"ok": True} + + async def test_post_uses_post_verb(self, client): + mock_resp = MagicMock(spec=httpx.Response) + mock_resp.raise_for_status = MagicMock() + + mock_http = AsyncMock() + mock_http.post = AsyncMock(return_value=mock_resp) + + with patch("httpx.AsyncClient") as mock_client_cls: + mock_client_cls.return_value.__aenter__ = AsyncMock(return_value=mock_http) + mock_client_cls.return_value.__aexit__ = AsyncMock(return_value=False) + await client._post("/rest/config", json={"key": "val"}) + + mock_http.post.assert_called_once() + + async def test_put_uses_put_verb(self, client): + mock_resp = MagicMock(spec=httpx.Response) + mock_resp.raise_for_status = MagicMock() + + mock_http = AsyncMock() + mock_http.put = AsyncMock(return_value=mock_resp) + + with patch("httpx.AsyncClient") as mock_client_cls: + mock_client_cls.return_value.__aenter__ = AsyncMock(return_value=mock_http) + mock_client_cls.return_value.__aexit__ = AsyncMock(return_value=False) + await client._put("/rest/config/devices", json={"deviceID": "X"}) + + mock_http.put.assert_called_once() + + async def test_delete_uses_delete_verb(self, client): + mock_resp = MagicMock(spec=httpx.Response) + mock_resp.raise_for_status = MagicMock() + + mock_http = AsyncMock() + mock_http.delete = AsyncMock(return_value=mock_resp) + + with patch("httpx.AsyncClient") as mock_client_cls: + mock_client_cls.return_value.__aenter__ = AsyncMock(return_value=mock_http) + mock_client_cls.return_value.__aexit__ = AsyncMock(return_value=False) + await client._delete("/rest/config/devices/AAAA") + + mock_http.delete.assert_called_once() diff --git a/api/tests/test_team_service.py b/api/tests/test_team_service.py new file mode 100644 index 00000000..1eccd3a3 --- /dev/null +++ b/api/tests/test_team_service.py @@ -0,0 +1,278 @@ +"""Tests for TeamService — team lifecycle + member management.""" +import sys +from pathlib import Path +sys.path.insert(0, str(Path(__file__).parent.parent)) + +import sqlite3 +import pytest +from unittest.mock import MagicMock, AsyncMock + +from db.schema import ensure_schema +from domain.team import Team, TeamStatus, AuthorizationError +from domain.member import Member, MemberStatus +from domain.subscription import SubscriptionStatus +from repositories.team_repo import TeamRepository +from repositories.member_repo import MemberRepository +from repositories.project_repo import ProjectRepository +from repositories.subscription_repo import SubscriptionRepository +from repositories.event_repo import EventRepository +from services.sync.team_service import TeamService + + +@pytest.fixture +def conn(): + c = sqlite3.connect(":memory:") + c.row_factory = sqlite3.Row + c.execute("PRAGMA foreign_keys=ON") + ensure_schema(c) + return c + + +@pytest.fixture +def mock_devices(): + m = MagicMock() + m.pair = AsyncMock() + m.unpair = AsyncMock() + return m + + +@pytest.fixture +def mock_metadata(tmp_path): + from services.sync.metadata_service import MetadataService + return MetadataService(meta_base=tmp_path / "meta") + + +@pytest.fixture +def mock_folders(): + m = MagicMock() + m.ensure_metadata_folder = AsyncMock() + m.ensure_outbox_folder = AsyncMock() + m.ensure_inbox_folder = AsyncMock() + m.set_folder_devices = AsyncMock() + m.get_configured_folders = AsyncMock(return_value=[]) + m.remove_device_from_team_folders = AsyncMock() + m.cleanup_team_folders = AsyncMock() + m.cleanup_project_folders = AsyncMock() + return m + + +@pytest.fixture +def service(mock_devices, mock_metadata, mock_folders): + return TeamService( + teams=TeamRepository(), + members=MemberRepository(), + projects=ProjectRepository(), + subs=SubscriptionRepository(), + events=EventRepository(), + devices=mock_devices, + metadata=mock_metadata, + folders=mock_folders, + ) + + +class TestCreateTeam: + @pytest.mark.asyncio + async def test_creates_team_and_leader(self, service, conn): + team = await service.create_team( + conn, name="karma", leader_member_tag="jayant.macbook", leader_device_id="DEV-L", + ) + assert team.status == TeamStatus.ACTIVE + assert team.leader_member_tag == "jayant.macbook" + + # Leader is auto-active + leader = service.members.get(conn, "karma", "jayant.macbook") + assert leader is not None + assert leader.status == MemberStatus.ACTIVE + + @pytest.mark.asyncio + async def test_logs_team_created_event(self, service, conn): + await service.create_team( + conn, name="t", leader_member_tag="j.m", leader_device_id="D", + ) + events = service.events.query(conn, team="t") + assert any(e.event_type.value == "team_created" for e in events) + + @pytest.mark.asyncio + async def test_writes_metadata_team_state(self, service, conn, mock_metadata): + await service.create_team( + conn, name="t", leader_member_tag="j.m", leader_device_id="D", + ) + # Metadata folder should have been written + team_dir = mock_metadata._team_dir("t") + assert (team_dir / "team.json").exists() + assert (team_dir / "members" / "j.m.json").exists() + + +class TestAddMember: + @pytest.mark.asyncio + async def test_adds_member_and_pairs(self, service, conn, mock_devices): + await service.create_team( + conn, name="t", leader_member_tag="j.m", leader_device_id="DEV-L", + ) + member = await service.add_member( + conn, team_name="t", by_device="DEV-L", + new_member_tag="a.l", new_device_id="DEV-A", + ) + assert member.status == MemberStatus.ADDED + mock_devices.pair.assert_called_once_with("DEV-A") + + @pytest.mark.asyncio + async def test_creates_offered_subscriptions(self, service, conn): + await service.create_team( + conn, name="t", leader_member_tag="j.m", leader_device_id="DEV-L", + ) + # Share a project first + from domain.project import SharedProject + project = SharedProject(team_name="t", git_identity="o/r", folder_suffix="o-r") + service.projects.save(conn, project) + + await service.add_member( + conn, team_name="t", by_device="DEV-L", + new_member_tag="a.l", new_device_id="DEV-A", + ) + subs = service.subs.list_for_member(conn, "a.l") + assert len(subs) == 1 + assert subs[0].status == SubscriptionStatus.OFFERED + + @pytest.mark.asyncio + async def test_non_leader_cannot_add(self, service, conn): + await service.create_team( + conn, name="t", leader_member_tag="j.m", leader_device_id="DEV-L", + ) + with pytest.raises(AuthorizationError): + await service.add_member( + conn, team_name="t", by_device="DEV-OTHER", + new_member_tag="a.l", new_device_id="DEV-A", + ) + + @pytest.mark.asyncio + async def test_member_saved_to_db(self, service, conn): + await service.create_team( + conn, name="t", leader_member_tag="j.m", leader_device_id="DEV-L", + ) + await service.add_member( + conn, team_name="t", by_device="DEV-L", + new_member_tag="a.l", new_device_id="DEV-A", + ) + saved = service.members.get(conn, "t", "a.l") + assert saved is not None + assert saved.device_id == "DEV-A" + + @pytest.mark.asyncio + async def test_logs_member_added_event(self, service, conn): + await service.create_team( + conn, name="t", leader_member_tag="j.m", leader_device_id="DEV-L", + ) + await service.add_member( + conn, team_name="t", by_device="DEV-L", + new_member_tag="a.l", new_device_id="DEV-A", + ) + events = service.events.query(conn, team="t") + assert any(e.event_type.value == "member_added" for e in events) + + +class TestRemoveMember: + @pytest.mark.asyncio + async def test_removes_and_records(self, service, conn): + await service.create_team( + conn, name="t", leader_member_tag="j.m", leader_device_id="DEV-L", + ) + await service.add_member( + conn, team_name="t", by_device="DEV-L", + new_member_tag="a.l", new_device_id="DEV-A", + ) + removed = await service.remove_member( + conn, team_name="t", by_device="DEV-L", member_tag="a.l", + ) + assert removed.status == MemberStatus.REMOVED + assert service.members.was_removed(conn, "t", "DEV-A") + + @pytest.mark.asyncio + async def test_unpairing_happens_when_no_other_teams(self, service, conn, mock_devices): + await service.create_team( + conn, name="t", leader_member_tag="j.m", leader_device_id="DEV-L", + ) + await service.add_member( + conn, team_name="t", by_device="DEV-L", + new_member_tag="a.l", new_device_id="DEV-A", + ) + await service.remove_member( + conn, team_name="t", by_device="DEV-L", member_tag="a.l", + ) + mock_devices.unpair.assert_called_once_with("DEV-A") + + @pytest.mark.asyncio + async def test_writes_removal_signal_to_metadata(self, service, conn, mock_metadata): + await service.create_team( + conn, name="t", leader_member_tag="j.m", leader_device_id="DEV-L", + ) + await service.add_member( + conn, team_name="t", by_device="DEV-L", + new_member_tag="a.l", new_device_id="DEV-A", + ) + await service.remove_member( + conn, team_name="t", by_device="DEV-L", member_tag="a.l", + ) + removal_file = mock_metadata._team_dir("t") / "removed" / "a.l.json" + assert removal_file.exists() + + @pytest.mark.asyncio + async def test_logs_member_removed_event(self, service, conn): + await service.create_team( + conn, name="t", leader_member_tag="j.m", leader_device_id="DEV-L", + ) + await service.add_member( + conn, team_name="t", by_device="DEV-L", + new_member_tag="a.l", new_device_id="DEV-A", + ) + await service.remove_member( + conn, team_name="t", by_device="DEV-L", member_tag="a.l", + ) + events = service.events.query(conn, team="t") + assert any(e.event_type.value == "member_removed" for e in events) + + @pytest.mark.asyncio + async def test_non_leader_cannot_remove(self, service, conn): + await service.create_team( + conn, name="t", leader_member_tag="j.m", leader_device_id="DEV-L", + ) + await service.add_member( + conn, team_name="t", by_device="DEV-L", + new_member_tag="a.l", new_device_id="DEV-A", + ) + with pytest.raises(AuthorizationError): + await service.remove_member( + conn, team_name="t", by_device="DEV-OTHER", member_tag="a.l", + ) + + +class TestDissolveTeam: + @pytest.mark.asyncio + async def test_dissolves_and_cleans_up(self, service, conn, mock_folders): + await service.create_team( + conn, name="t", leader_member_tag="j.m", leader_device_id="DEV-L", + ) + dissolved = await service.dissolve_team(conn, team_name="t", by_device="DEV-L") + assert dissolved.status == TeamStatus.DISSOLVED + mock_folders.cleanup_team_folders.assert_called_once() + # Team soft-deleted (status=DISSOLVED, still queryable) + team_after = service.teams.get(conn, "t") + assert team_after is not None + assert team_after.status == TeamStatus.DISSOLVED + + @pytest.mark.asyncio + async def test_non_leader_cannot_dissolve(self, service, conn): + await service.create_team( + conn, name="t", leader_member_tag="j.m", leader_device_id="DEV-L", + ) + with pytest.raises(AuthorizationError): + await service.dissolve_team(conn, team_name="t", by_device="DEV-OTHER") + + @pytest.mark.asyncio + async def test_logs_team_dissolved_event(self, service, conn): + await service.create_team( + conn, name="t", leader_member_tag="j.m", leader_device_id="DEV-L", + ) + await service.dissolve_team(conn, team_name="t", by_device="DEV-L") + # Events are deleted with the team via CASCADE, so just verify no error raised + # (the event was logged before team deletion) diff --git a/api/tests/test_watcher_manager.py b/api/tests/test_watcher_manager.py new file mode 100644 index 00000000..9f153a88 --- /dev/null +++ b/api/tests/test_watcher_manager.py @@ -0,0 +1,70 @@ +"""Tests for the in-process watcher manager.""" +from __future__ import annotations + +import sys +from pathlib import Path +from unittest.mock import MagicMock + +import pytest + +sys.path.insert(0, str(Path(__file__).parent.parent)) + +from services.watcher_manager import WatcherManager + + +class TestWatcherManager: + def test_status_when_not_running(self): + mgr = WatcherManager() + status = mgr.status() + assert status["running"] is False + assert status["teams"] == [] + assert status["started_at"] is None + assert status["last_packaged_at"] is None + assert status["projects_watched"] == [] + + def test_is_running_default_false(self): + mgr = WatcherManager() + assert mgr.is_running is False + + def test_cannot_start_twice(self): + mgr = WatcherManager() + mgr._running = True + mgr._teams = ["existing"] + + with pytest.raises(ValueError, match="already running"): + mgr.start("another", {"teams": {"another": {"projects": {}}}}) + + def test_stop_cleans_up(self): + mgr = WatcherManager() + mock_w1 = MagicMock() + mock_w2 = MagicMock() + mgr._running = True + mgr._teams = ["test"] + mgr._watchers = [mock_w1, mock_w2] + mgr._projects_watched = ["proj1"] + mgr._started_at = "2026-03-06T00:00:00Z" + + result = mgr.stop() + + assert result["running"] is False + assert result["teams"] == [] + assert not mgr.is_running + mock_w1.stop.assert_called_once() + mock_w2.stop.assert_called_once() + + def test_stop_handles_watcher_errors(self): + mgr = WatcherManager() + mock_w = MagicMock() + mock_w.stop.side_effect = RuntimeError("boom") + mgr._running = True + mgr._teams = ["test"] + mgr._watchers = [mock_w] + + # Should not raise + result = mgr.stop() + assert result["running"] is False + + def test_stop_when_not_running(self): + mgr = WatcherManager() + result = mgr.stop() + assert result["running"] is False diff --git a/api/utils/__init__.py b/api/utils/__init__.py new file mode 100644 index 00000000..15b18666 --- /dev/null +++ b/api/utils/__init__.py @@ -0,0 +1,16 @@ +"""Utility functions for API routers. + +Re-exports everything from utils.helpers (formerly utils.py) so that +existing ``from utils import ...`` statements continue to work unchanged. +""" + +from utils.helpers import * # noqa: F401, F403 +from utils.helpers import ( + FileOperation, + MessageSource, + ToolResultData, + _PROJECTS_CACHE_TTL, + _list_all_projects_impl, + _register_worktree_mapping, + _strip_git_credentials, +) diff --git a/api/utils/git.py b/api/utils/git.py new file mode 100644 index 00000000..1cbb45bd --- /dev/null +++ b/api/utils/git.py @@ -0,0 +1,64 @@ +"""Sync utilities — path encoding, git identity detection, Claude project discovery.""" + +import re +import subprocess +from pathlib import Path +from typing import Optional + + +def encode_project_path(path: str) -> str: + """Encode a project path the same way Claude Code does. + + Unix: /Users/alice/repo → -Users-alice-repo + Windows: C:\\Users\\alice\\repo → -C-Users-alice-repo + """ + p = path.replace("\\", "/") + # Strip leading slash (Unix) or drive letter colon (Windows: C:/) + if p.startswith("/"): + p = p[1:] + p = p.replace(":", "") + return "-" + p.replace("/", "-") + + +def detect_git_identity(project_path: str) -> Optional[str]: + """Detect git identity from origin remote URL, normalized to lowercase owner/repo. + + SSH: git@github.com:Owner/Repo.git → owner/repo + HTTPS: https://github.com/Owner/Repo.git → owner/repo + Non-git / no origin → None + """ + try: + result = subprocess.run( + ["git", "-C", project_path, "remote", "get-url", "origin"], + capture_output=True, + text=True, + timeout=5, + ) + if result.returncode != 0: + return None + url = result.stdout.strip() + if not url: + return None + + # SSH: git@github.com:Owner/Repo.git + ssh_match = re.match(r"^[\w.-]+@[\w.-]+:(.*?)(?:\.git)?$", url) + if ssh_match: + return ssh_match.group(1).lower() + + # HTTPS: https://github.com/Owner/Repo.git + https_match = re.match(r"^https?://[^/]+/(.*?)(?:\.git)?$", url) + if https_match: + return https_match.group(1).lower() + + return None + except (subprocess.TimeoutExpired, FileNotFoundError, OSError): + return None + + +def find_claude_project_dir(project_path: str) -> Optional[Path]: + """Find the Claude project directory for a given project path.""" + encoded = encode_project_path(project_path) + claude_dir = Path.home() / ".claude" / "projects" / encoded + if claude_dir.is_dir(): + return claude_dir + return None diff --git a/api/utils.py b/api/utils/helpers.py similarity index 96% rename from api/utils.py rename to api/utils/helpers.py index 19b35af4..e9a0bf74 100644 --- a/api/utils.py +++ b/api/utils/helpers.py @@ -92,6 +92,49 @@ def resolve_git_root(path: str) -> Optional[str]: return None +def _strip_git_credentials(url: str) -> str: + """Strip embedded credentials from a git remote URL. + + https://user:token@github.com/org/repo.git → https://github.com/org/repo.git + """ + from urllib.parse import urlparse, urlunparse + + try: + parsed = urlparse(url) + if parsed.username or parsed.password: + # Rebuild without credentials + netloc = parsed.hostname or "" + if parsed.port: + netloc += f":{parsed.port}" + return urlunparse(parsed._replace(netloc=netloc)) + except Exception: + pass + return url + + +def resolve_git_remote_url(path: str) -> Optional[str]: + """Resolve the git remote 'origin' URL for a path. + + Returns the remote URL with credentials stripped + (e.g., 'https://github.com/user/repo.git') + or None if not a git repo or no origin remote. + """ + try: + result = subprocess.run( + ["git", "remote", "get-url", "origin"], + cwd=path, + capture_output=True, + text=True, + timeout=5, + check=False, + ) + if result.returncode == 0 and result.stdout.strip(): + return _strip_git_credentials(result.stdout.strip()) + return None + except (subprocess.TimeoutExpired, FileNotFoundError, OSError, PermissionError): + return None + + def compute_project_slug(encoded_name: str, project_path: str) -> str: """Compute a URL-friendly project slug: lowercased name + 4-char md5 hash.""" name = Path(project_path).name.lower() if project_path else encoded_name.lower() @@ -332,6 +375,10 @@ def get_initial_prompt(session: "Session", max_length: Optional[int] = None) -> # Extract actual prompt from command-wrapped content prompt = extract_prompt_from_content(msg.content) + # Skip empty prompts (e.g., bare command invocations without args) + if not prompt: + continue + if max_length is not None: return prompt[:max_length] return prompt diff --git a/cli/karma/__init__.py b/cli/karma/__init__.py new file mode 100644 index 00000000..43394dee --- /dev/null +++ b/cli/karma/__init__.py @@ -0,0 +1,3 @@ +"""Claude Karma CLI - Syncthing session sync for distributed teams.""" + +__version__ = "0.1.0" diff --git a/cli/karma/config.py b/cli/karma/config.py new file mode 100644 index 00000000..fb8d132f --- /dev/null +++ b/cli/karma/config.py @@ -0,0 +1,94 @@ +"""Sync configuration management. + +Identity and credentials only. Teams/members/projects live in SQLite. +""" + +import json +import os +import re +import socket +from pathlib import Path +from typing import Optional + +from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator + + +KARMA_BASE = Path.home() / ".claude_karma" +SYNC_CONFIG_PATH = KARMA_BASE / "sync-config.json" + + +def _sanitize_machine_tag(hostname: str) -> str: + """Derive a safe machine_tag from hostname. + + Rules: lowercase, alphanumeric + hyphens only, collapse multi-hyphens, + strip leading/trailing hyphens, no '--' (folder ID delimiter). + """ + if not hostname: + return "unknown" + tag = hostname.lower() + tag = re.sub(r"[^a-z0-9-]", "-", tag) # non-alphanum -> hyphen + tag = re.sub(r"-{2,}", "-", tag) # collapse multi-hyphens + tag = tag.strip("-") + return tag or "unknown" + + +class SyncthingSettings(BaseModel): + """Syncthing connection settings.""" + + model_config = ConfigDict(frozen=True) + + api_url: str = Field(default="http://127.0.0.1:8384", description="Syncthing REST API URL") + api_key: Optional[str] = Field(default=None, description="Syncthing API key") + device_id: Optional[str] = Field(default=None, description="This device's Syncthing ID") + + +class SyncConfig(BaseModel): + """Identity and credentials. Teams/members/projects live in SQLite.""" + + model_config = ConfigDict(frozen=True) + + user_id: str = Field(..., description="User identity") + machine_id: str = Field( + default_factory=lambda: socket.gethostname(), + description="Machine hostname", + ) + machine_tag: Optional[str] = Field( + default=None, + description="Sanitized machine identifier (auto-derived from machine_id if not set)", + ) + syncthing: SyncthingSettings = Field(default_factory=SyncthingSettings) + + @field_validator("user_id") + @classmethod + def validate_user_id(cls, v: str) -> str: + if not re.match(r"^[a-zA-Z0-9_-]+$", v): + raise ValueError("user_id must be alphanumeric, dash, or underscore (no dots)") + return v + + @model_validator(mode="after") + def _derive_machine_tag(self) -> "SyncConfig": + if self.machine_tag is None: + object.__setattr__(self, "machine_tag", _sanitize_machine_tag(self.machine_id)) + return self + + @property + def member_tag(self) -> str: + """Unique device identity: user_id.machine_tag""" + return f"{self.user_id}.{self.machine_tag}" + + @staticmethod + def load() -> Optional["SyncConfig"]: + """Load config from disk. Returns None if not initialized.""" + if not SYNC_CONFIG_PATH.exists(): + return None + try: + data = json.loads(SYNC_CONFIG_PATH.read_text()) + return SyncConfig(**data) + except (json.JSONDecodeError, ValueError) as e: + raise RuntimeError(f"Corrupt config at {SYNC_CONFIG_PATH}: {e}") from e + + def save(self) -> None: + """Persist config to disk.""" + SYNC_CONFIG_PATH.parent.mkdir(parents=True, exist_ok=True) + SYNC_CONFIG_PATH.write_text(json.dumps(self.model_dump(), indent=2) + "\n") + os.chmod(SYNC_CONFIG_PATH, 0o600) diff --git a/cli/karma/main.py b/cli/karma/main.py new file mode 100644 index 00000000..e7c612ca --- /dev/null +++ b/cli/karma/main.py @@ -0,0 +1,102 @@ +"""Karma CLI entry point.""" + +import re +from pathlib import Path + +import click + +from karma.config import SyncConfig, SyncthingSettings, SYNC_CONFIG_PATH, KARMA_BASE + +_SAFE_NAME = re.compile(r"^[a-zA-Z0-9_\-]+$") + + +@click.group() +@click.version_option(package_name="claude-karma-cli") +def cli(): + """Claude Karma - Syncthing session sync for distributed teams. + + Sync operations (teams, projects, members, pending folders) have moved + to the API layer. Use the web dashboard or API endpoints instead. + """ + pass + + +# --- init --- + + +@cli.command() +@click.option("--user-id", prompt="Your user ID (e.g., your name)", help="Identity for syncing") +def init(user_id: str): + """Initialize Karma sync on this machine.""" + existing = SyncConfig.load() + if existing: + click.echo(f"Already initialized as '{existing.user_id}' on '{existing.machine_id}'.") + if not click.confirm("Reinitialize?"): + return + + if not _SAFE_NAME.match(user_id): + raise click.ClickException("User ID must be alphanumeric, dash, or underscore only.") + + from karma.syncthing import SyncthingClient, read_local_api_key + + api_key = read_local_api_key() + if api_key: + st = SyncthingClient(api_key=api_key) + if st.is_running(): + device_id = st.get_device_id() + syncthing_settings = SyncthingSettings( + api_url="http://127.0.0.1:8384", + api_key=api_key, + device_id=device_id, + ) + config = SyncConfig(user_id=user_id, syncthing=syncthing_settings) + config.save() + click.echo(f"Initialized as '{user_id}' on '{config.machine_id}'.") + click.echo(f"Your Syncthing Device ID: {device_id}") + click.echo("Share this Device ID with your team leader.") + return + + config = SyncConfig(user_id=user_id) + config.save() + click.echo(f"Initialized as '{user_id}' on '{config.machine_id}'.") + click.echo(f"Config saved to {SYNC_CONFIG_PATH}") + click.echo("\nSyncthing not detected. Start Syncthing and re-run 'karma init' to auto-configure.") + + +# --- ls --- + + +@cli.command("ls") +def list_remote(): + """List available remote sessions.""" + import json + + remote_dir = KARMA_BASE / "remote-sessions" + if not remote_dir.is_dir(): + click.echo("No remote sessions. Run: karma pull") + return + + for user_dir in sorted(remote_dir.iterdir()): + if not user_dir.is_dir(): + continue + click.echo(f"\n{user_dir.name}:") + for project_dir in sorted(user_dir.iterdir()): + if not project_dir.is_dir(): + continue + manifest_path = project_dir / "manifest.json" + if manifest_path.exists(): + try: + manifest = json.loads(manifest_path.read_text()) + click.echo( + f" {project_dir.name}: " + f"{manifest.get('session_count', '?')} sessions " + f"(synced {manifest.get('synced_at', '?')})" + ) + except (json.JSONDecodeError, OSError): + click.echo(f" {project_dir.name}: (corrupt manifest)") + else: + click.echo(f" {project_dir.name}: (no manifest)") + + +if __name__ == "__main__": + cli() diff --git a/cli/karma/syncthing.py b/cli/karma/syncthing.py new file mode 100644 index 00000000..92053c04 --- /dev/null +++ b/cli/karma/syncthing.py @@ -0,0 +1,317 @@ +"""Syncthing REST API wrapper.""" + +import subprocess +import threading +import xml.etree.ElementTree as ET +from contextlib import contextmanager +from pathlib import Path +from typing import Optional + +import requests + + +def read_local_api_key() -> Optional[str]: + """Auto-detect the Syncthing API key from the local config file.""" + # Ask Syncthing itself where its config lives + try: + result = subprocess.run( + ["syncthing", "paths"], + capture_output=True, text=True, timeout=5, + ) + for line in result.stdout.splitlines(): + line = line.strip() + if line.endswith("config.xml"): + config_path = Path(line) + if config_path.exists(): + tree = ET.parse(config_path) + key = tree.getroot().findtext(".//apikey") + return key or None + except (subprocess.SubprocessError, FileNotFoundError, ET.ParseError): + pass + + # Fallback: try known platform locations + candidates = [ + Path.home() / "Library" / "Application Support" / "Syncthing" / "config.xml", + Path.home() / ".local" / "share" / "syncthing" / "config.xml", + Path.home() / ".config" / "syncthing" / "config.xml", + ] + for path in candidates: + if path.exists(): + try: + tree = ET.parse(path) + key = tree.getroot().findtext(".//apikey") + return key or None + except ET.ParseError: + continue + return None + + +class SyncthingClient: + """Wraps the Syncthing REST API for device/folder management. + + All config mutation methods (add_device, add_folder, remove_*, etc.) + are serialized via an RLock to prevent GET-mutate-PUT races when + concurrent callers (watcher peer-check + UI accept) overlap. + RLock (not Lock) because accept_pending_folders calls multiple + mutation methods in sequence from the same thread. + """ + + _config_lock = threading.RLock() + + def __init__(self, api_url: str = "http://127.0.0.1:8384", api_key: Optional[str] = None): + self.api_url = api_url.rstrip("/") + self.headers = {} + if api_key: + self.headers["X-API-Key"] = api_key + + @contextmanager + def _mutate_config(self): + """Context manager: hold the lock, yield the config, PUT on exit.""" + with self._config_lock: + config = self._get_config() + yield config + self._set_config(config) + + def _read_config(self) -> dict: + """Read config under lock (read-only).""" + with self._config_lock: + return self._get_config() + + def is_running(self) -> bool: + """Check if Syncthing is running and accessible.""" + try: + requests.get( + f"{self.api_url}/rest/system/status", + headers=self.headers, + timeout=5, + ) + return True # Any HTTP response means the daemon is up + except (requests.ConnectionError, requests.Timeout): + return False + + def get_device_id(self) -> str: + """Get this device's Syncthing Device ID.""" + resp = requests.get( + f"{self.api_url}/rest/system/status", + headers=self.headers, + timeout=10, + ) + resp.raise_for_status() + return resp.json()["myID"] + + def get_connections(self) -> dict: + """Check which devices are connected.""" + resp = requests.get( + f"{self.api_url}/rest/system/connections", + headers=self.headers, + timeout=10, + ) + resp.raise_for_status() + return resp.json()["connections"] + + def add_device(self, device_id: str, name: str, introducer: bool = False) -> None: + """Pair with a remote device. + + Args: + device_id: The Syncthing device ID to pair with. + name: Human-readable name for the device. + introducer: If True, mark the device as an introducer. Syncthing + will automatically share all folders and devices from this + device to all its peers, enabling automatic mesh discovery. + Only the team leader device should be marked as introducer. + """ + with self._mutate_config() as config: + existing_ids = {d["deviceID"] for d in config.get("devices", [])} + if device_id in existing_ids: + raise ValueError(f"Device {device_id} already configured") + device_config = { + "deviceID": device_id, + "name": name, + "autoAcceptFolders": False, + } + if introducer: + device_config["introducer"] = True + config["devices"].append(device_config) + + def set_device_introducer(self, device_id: str, introducer: bool = True) -> bool: + """Update an existing device's introducer flag. + + Returns True if the config was changed, False if already correct. + """ + with self._config_lock: + config = self._get_config() + for device in config.get("devices", []): + if device["deviceID"] == device_id: + if device.get("introducer", False) == introducer: + return False + device["introducer"] = introducer + self._set_config(config) + return True + raise ValueError(f"Device {device_id} not found in Syncthing config") + + def add_folder( + self, + folder_id: str, + path: str, + devices: list, + folder_type: str = "sendonly", + ) -> None: + """Create or update a shared folder with specified devices.""" + with self._mutate_config() as config: + existing = next((f for f in config["folders"] if f["id"] == folder_id), None) + if existing is not None: + # Update device list on existing folder + current_ids = {d["deviceID"] for d in existing.get("devices", [])} + for d in devices: + if d not in current_ids: + existing["devices"].append({"deviceID": d}) + else: + config["folders"].append({ + "id": folder_id, + "path": path, + "devices": [{"deviceID": d} for d in devices], + "type": folder_type, + }) + + def remove_device(self, device_id: str) -> None: + """Remove a paired device.""" + with self._mutate_config() as config: + config["devices"] = [d for d in config["devices"] if d["deviceID"] != device_id] + + def remove_folder(self, folder_id: str) -> None: + """Remove a shared folder.""" + with self._mutate_config() as config: + config["folders"] = [f for f in config["folders"] if f["id"] != folder_id] + + def remove_device_from_folder(self, folder_id: str, device_id: str) -> bool: + """Remove a device from a folder's sharing list. Returns True if removed.""" + with self._mutate_config() as config: + for folder in config.get("folders", []): + if folder.get("id") != folder_id: + continue + original = folder.get("devices", []) + filtered = [d for d in original if d.get("deviceID") != device_id] + if len(filtered) == len(original): + return False + folder["devices"] = filtered + return True + return False + + def get_pending_devices(self) -> dict: + """Get devices trying to connect that aren't configured. + + Returns: + Dict keyed by device_id with connection details. + """ + resp = requests.get( + f"{self.api_url}/rest/cluster/pending/devices", + headers=self.headers, + timeout=10, + ) + resp.raise_for_status() + return resp.json() + + def get_pending_folders(self) -> dict: + """Get folder offers from remote devices that haven't been accepted. + + Returns: + Dict keyed by folder_id, each with "offeredBy" mapping device_id + to offer details (time, label, etc). + """ + resp = requests.get( + f"{self.api_url}/rest/cluster/pending/folders", + headers=self.headers, + timeout=10, + ) + resp.raise_for_status() + return resp.json() + + def dismiss_pending_device(self, device_id: str) -> None: + """Dismiss a pending device so it no longer appears.""" + resp = requests.delete( + f"{self.api_url}/rest/cluster/pending/devices", + headers=self.headers, + params={"device": device_id}, + timeout=10, + ) + resp.raise_for_status() + + def dismiss_pending_folder(self, folder_id: str, device_id: str) -> None: + """Dismiss a pending folder offer so it no longer appears.""" + resp = requests.delete( + f"{self.api_url}/rest/cluster/pending/folders", + headers=self.headers, + params={"folder": folder_id, "device": device_id}, + timeout=10, + ) + resp.raise_for_status() + + def get_folders(self) -> list[dict]: + """Get all configured folders.""" + return self._read_config().get("folders", []) + + def find_folder_by_path(self, path: str) -> Optional[dict]: + """Find a configured folder by its local path.""" + for folder in self.get_folders(): + if folder.get("path", "").rstrip("/") == path.rstrip("/"): + return folder + return None + + def shutdown(self) -> bool: + """Shut down the Syncthing daemon via REST API. + + Returns True if shutdown was requested, False if daemon was unreachable. + """ + try: + requests.post( + f"{self.api_url}/rest/system/shutdown", + headers=self.headers, + timeout=10, + ) + return True + except (requests.ConnectionError, requests.Timeout): + return False + + def remove_karma_folders(self) -> list[str]: + """Remove all karma-* folders from Syncthing config. + + Returns list of removed folder IDs. + """ + with self._mutate_config() as config: + karma_folders = [f for f in config.get("folders", []) if f.get("id", "").startswith("karma-")] + if not karma_folders: + return [] + removed_ids = [f["id"] for f in karma_folders] + config["folders"] = [f for f in config["folders"] if not f.get("id", "").startswith("karma-")] + return removed_ids + + def remove_all_non_self_devices(self) -> list[str]: + """Remove all non-self devices from Syncthing config. + + Returns list of removed device IDs. + """ + try: + self_id = self.get_device_id() + except Exception: + self_id = None + + with self._mutate_config() as config: + original = config.get("devices", []) + kept = [d for d in original if d.get("deviceID") == self_id] if self_id else [] + removed = [d["deviceID"] for d in original if d.get("deviceID") != self_id] + config["devices"] = kept + return removed + + def _get_config(self) -> dict: + resp = requests.get(f"{self.api_url}/rest/config", headers=self.headers, timeout=10) + resp.raise_for_status() + return resp.json() + + def _set_config(self, config: dict) -> None: + resp = requests.put( + f"{self.api_url}/rest/config", + json=config, + headers=self.headers, + timeout=10, + ) + resp.raise_for_status() diff --git a/cli/pyproject.toml b/cli/pyproject.toml new file mode 100644 index 00000000..1bde167d --- /dev/null +++ b/cli/pyproject.toml @@ -0,0 +1,33 @@ +[build-system] +requires = ["setuptools>=61.0"] +build-backend = "setuptools.build_meta" + +[project] +name = "claude-karma-cli" +version = "0.1.0" +description = "CLI for syncing Claude Code sessions via Syncthing" +requires-python = ">=3.10" +dependencies = [ + "click>=8.0", + "pydantic>=2.0", + "requests>=2.28", + "watchdog>=3.0", +] + +[project.optional-dependencies] +dev = [ + "pytest>=7.0", + "pytest-cov>=4.0", + "ruff>=0.1.0", +] + +[project.scripts] +karma = "karma.main:cli" + +[tool.pytest.ini_options] +testpaths = ["tests"] +addopts = "-v --tb=short" + +[tool.ruff] +target-version = "py310" +line-length = 100 diff --git a/cli/tests/__init__.py b/cli/tests/__init__.py new file mode 100644 index 00000000..e69de29b diff --git a/cli/tests/conftest.py b/cli/tests/conftest.py new file mode 100644 index 00000000..8f729eb6 --- /dev/null +++ b/cli/tests/conftest.py @@ -0,0 +1,26 @@ +"""Shared test fixtures for CLI tests.""" + +import sqlite3 +import sys +from pathlib import Path + +import pytest + +# Add API to path for schema module +_API_PATH = str(Path(__file__).parent.parent.parent / "api") +if _API_PATH not in sys.path: + sys.path.insert(0, _API_PATH) + + +@pytest.fixture +def mock_db(monkeypatch): + """In-memory SQLite with schema, patched into the CLI.""" + from db.schema import ensure_schema + + conn = sqlite3.connect(":memory:", check_same_thread=False) + conn.row_factory = sqlite3.Row + conn.execute("PRAGMA foreign_keys=ON") + ensure_schema(conn) + + monkeypatch.setattr("karma.main._get_db", lambda: conn) + return conn diff --git a/cli/tests/test_cli.py b/cli/tests/test_cli.py new file mode 100644 index 00000000..37abe2ab --- /dev/null +++ b/cli/tests/test_cli.py @@ -0,0 +1,236 @@ +"""Tests for CLI commands.""" + +import json +from pathlib import Path +from unittest.mock import patch, MagicMock + +import pytest +from click.testing import CliRunner + +from karma.main import cli +from karma.config import SyncConfig + + +@pytest.fixture +def runner(): + return CliRunner() + + +@pytest.fixture +def init_config(tmp_path, monkeypatch): + """Initialize a config for testing.""" + config_path = tmp_path / "sync-config.json" + monkeypatch.setattr("karma.config.SYNC_CONFIG_PATH", config_path) + monkeypatch.setattr("karma.config.KARMA_BASE", tmp_path) + monkeypatch.setattr("karma.main.KARMA_BASE", tmp_path) + return config_path + + +class TestInitCommand: + def test_init_creates_config(self, runner, init_config): + result = runner.invoke(cli, ["init", "--user-id", "alice"]) + assert result.exit_code == 0 + assert "Initialized as 'alice'" in result.output + assert init_config.exists() + + +class TestTeamCommands: + def test_team_create(self, runner, init_config, mock_db): + runner.invoke(cli, ["init", "--user-id", "alice"]) + result = runner.invoke(cli, ["team", "create", "alpha"]) + assert result.exit_code == 0 + assert "Created team 'alpha'" in result.output + + # Verify in DB + row = mock_db.execute("SELECT * FROM sync_teams WHERE name = 'alpha'").fetchone() + assert row is not None + assert row["backend"] == "syncthing" + + # Verify event logged + ev = mock_db.execute("SELECT * FROM sync_events WHERE event_type = 'team_created'").fetchone() + assert ev is not None + + def test_team_create_duplicate(self, runner, init_config, mock_db): + runner.invoke(cli, ["init", "--user-id", "alice"]) + runner.invoke(cli, ["team", "create", "alpha"]) + result = runner.invoke(cli, ["team", "create", "alpha"]) + assert result.exit_code != 0 + assert "already exists" in result.output + + def test_team_add_member(self, runner, init_config, mock_db): + runner.invoke(cli, ["init", "--user-id", "alice"]) + runner.invoke(cli, ["team", "create", "alpha"]) + result = runner.invoke(cli, ["team", "add", "bob", "BOB-DEVICE-ID", "--team", "alpha"]) + assert result.exit_code == 0 + assert "Added team member 'bob'" in result.output + + # Verify in DB + row = mock_db.execute( + "SELECT * FROM sync_members WHERE team_name = 'alpha' AND name = 'bob'" + ).fetchone() + assert row is not None + assert row["device_id"] == "BOB-DEVICE-ID" + + def test_team_list(self, runner, init_config, mock_db): + runner.invoke(cli, ["init", "--user-id", "alice"]) + runner.invoke(cli, ["team", "create", "alpha"]) + result = runner.invoke(cli, ["team", "list"]) + assert result.exit_code == 0 + assert "alpha" in result.output + + def test_team_list_empty(self, runner, init_config, mock_db): + runner.invoke(cli, ["init", "--user-id", "alice"]) + result = runner.invoke(cli, ["team", "list"]) + assert result.exit_code == 0 + assert "No teams" in result.output + + def test_team_remove_member(self, runner, init_config, mock_db): + runner.invoke(cli, ["init", "--user-id", "alice"]) + runner.invoke(cli, ["team", "create", "alpha"]) + runner.invoke(cli, ["team", "add", "bob", "BOB-DEVICE-ID", "--team", "alpha"]) + result = runner.invoke(cli, ["team", "remove", "bob", "--team", "alpha"]) + assert result.exit_code == 0 + assert "Removed 'bob' from team 'alpha'" in result.output + + # Verify removed from DB + row = mock_db.execute( + "SELECT * FROM sync_members WHERE team_name = 'alpha' AND name = 'bob'" + ).fetchone() + assert row is None + + def test_team_remove_member_not_found(self, runner, init_config, mock_db): + runner.invoke(cli, ["init", "--user-id", "alice"]) + runner.invoke(cli, ["team", "create", "alpha"]) + result = runner.invoke(cli, ["team", "remove", "bob", "--team", "alpha"]) + assert result.exit_code != 0 + assert "not found" in result.output + + def test_team_leave(self, runner, init_config, mock_db): + runner.invoke(cli, ["init", "--user-id", "alice"]) + runner.invoke(cli, ["team", "create", "alpha"]) + runner.invoke(cli, ["team", "add", "bob", "DEV-BOB", "--team", "alpha"]) + result = runner.invoke(cli, ["team", "leave", "alpha"]) + assert result.exit_code == 0 + assert "Left team 'alpha'" in result.output + + # Verify cascade + assert mock_db.execute("SELECT * FROM sync_teams WHERE name = 'alpha'").fetchone() is None + assert mock_db.execute("SELECT * FROM sync_members WHERE team_name = 'alpha'").fetchone() is None + + +class TestProjectCommands: + def test_project_add(self, runner, init_config, mock_db, tmp_path): + runner.invoke(cli, ["init", "--user-id", "alice"]) + runner.invoke(cli, ["team", "create", "alpha"]) + + project_path = tmp_path / "test-project" + project_path.mkdir(parents=True) + + result = runner.invoke( + cli, ["project", "add", "test-project", "--path", str(project_path), "--team", "alpha"] + ) + assert result.exit_code == 0 + assert "Added project 'test-project'" in result.output + + # Verify in DB + row = mock_db.execute( + "SELECT * FROM sync_team_projects WHERE team_name = 'alpha'" + ).fetchone() + assert row is not None + assert row["path"] == str(project_path) + + def test_project_add_team_not_found(self, runner, init_config, mock_db, tmp_path): + runner.invoke(cli, ["init", "--user-id", "alice"]) + project_path = tmp_path / "test-project" + project_path.mkdir(parents=True) + + result = runner.invoke( + cli, ["project", "add", "test-project", "--path", str(project_path), "--team", "nope"] + ) + assert result.exit_code != 0 + assert "not found" in result.output + + def test_project_list(self, runner, init_config, mock_db, tmp_path): + runner.invoke(cli, ["init", "--user-id", "alice"]) + runner.invoke(cli, ["team", "create", "alpha"]) + + project_path = tmp_path / "myapp" + project_path.mkdir(parents=True) + runner.invoke( + cli, ["project", "add", "myapp", "--path", str(project_path), "--team", "alpha"] + ) + + result = runner.invoke(cli, ["project", "list"]) + assert result.exit_code == 0 + assert "myapp" in result.output + assert "alpha" in result.output + + def test_project_list_empty(self, runner, init_config, mock_db): + runner.invoke(cli, ["init", "--user-id", "alice"]) + result = runner.invoke(cli, ["project", "list"]) + assert result.exit_code == 0 + assert "No projects configured" in result.output + + def test_project_remove(self, runner, init_config, mock_db, tmp_path): + runner.invoke(cli, ["init", "--user-id", "alice"]) + runner.invoke(cli, ["team", "create", "alpha"]) + + project_path = tmp_path / "myapp" + project_path.mkdir(parents=True) + runner.invoke( + cli, ["project", "add", "myapp", "--path", str(project_path), "--team", "alpha"] + ) + + result = runner.invoke(cli, ["project", "remove", "myapp", "--team", "alpha"]) + assert result.exit_code == 0 + assert "Removed project 'myapp'" in result.output + + # Verify removed from DB + row = mock_db.execute( + "SELECT * FROM sync_team_projects WHERE team_name = 'alpha'" + ).fetchone() + assert row is None + + def test_project_remove_not_found(self, runner, init_config, mock_db): + runner.invoke(cli, ["init", "--user-id", "alice"]) + runner.invoke(cli, ["team", "create", "alpha"]) + result = runner.invoke(cli, ["project", "remove", "nope", "--team", "alpha"]) + assert result.exit_code != 0 + assert "not found" in result.output + + +class TestCorruptConfig: + def test_load_corrupt_json(self, runner, init_config): + init_config.write_text("{invalid json") + result = runner.invoke(cli, ["project", "list"]) + assert result.exit_code != 0 + assert "Corrupt config" in result.output + + def test_load_invalid_schema(self, runner, init_config): + init_config.write_text('{"bad_field": true}') + result = runner.invoke(cli, ["project", "list"]) + assert result.exit_code != 0 + assert "Corrupt config" in result.output + + +class TestLsCommand: + def test_ls_no_remote_dir(self, runner, init_config): + result = runner.invoke(cli, ["ls"]) + assert result.exit_code == 0 + assert "No remote sessions" in result.output + + +class TestStatusCommand: + def test_status_with_teams(self, runner, init_config, mock_db): + runner.invoke(cli, ["init", "--user-id", "alice"]) + runner.invoke(cli, ["team", "create", "alpha"]) + result = runner.invoke(cli, ["status"]) + assert result.exit_code == 0 + assert "alice" in result.output + assert "alpha" in result.output + + def test_status_no_teams(self, runner, init_config, mock_db): + runner.invoke(cli, ["init", "--user-id", "alice"]) + result = runner.invoke(cli, ["status"]) + assert result.exit_code == 0 + assert "No teams configured" in result.output diff --git a/cli/tests/test_cli_syncthing.py b/cli/tests/test_cli_syncthing.py new file mode 100644 index 00000000..3b962a2d --- /dev/null +++ b/cli/tests/test_cli_syncthing.py @@ -0,0 +1,435 @@ +"""Tests for Syncthing CLI commands.""" + +from unittest.mock import patch, MagicMock +from click.testing import CliRunner + +import pytest + +from karma.main import cli + + +@pytest.fixture +def runner(): + return CliRunner() + + +@pytest.fixture +def mock_config(tmp_path, monkeypatch): + config_path = tmp_path / "sync-config.json" + monkeypatch.setattr("karma.config.SYNC_CONFIG_PATH", config_path) + monkeypatch.setattr("karma.config.KARMA_BASE", tmp_path) + monkeypatch.setattr("karma.main.KARMA_BASE", tmp_path) + return config_path + + +@pytest.fixture(autouse=True) +def _isolate_syncthing(monkeypatch): + """Prevent init from detecting real Syncthing unless test explicitly mocks it.""" + monkeypatch.setattr("karma.syncthing.read_local_api_key", lambda: None) + + +class TestInit: + def test_init_no_syncthing(self, runner, mock_config): + result = runner.invoke(cli, ["init", "--user-id", "alice"]) + assert result.exit_code == 0 + assert "alice" in result.output + + @patch("karma.syncthing.read_local_api_key", return_value="test-key") + @patch("karma.syncthing.SyncthingClient") + def test_init_with_syncthing_running(self, mock_st_cls, mock_key, runner, mock_config): + mock_st = MagicMock() + mock_st.is_running.return_value = True + mock_st.get_device_id.return_value = "AAAA-BBBB-CCCC" + mock_st_cls.return_value = mock_st + + result = runner.invoke(cli, ["init", "--user-id", "alice"]) + assert result.exit_code == 0 + assert "AAAA-BBBB-CCCC" in result.output + + @patch("karma.syncthing.read_local_api_key", return_value="test-key") + @patch("karma.syncthing.SyncthingClient") + def test_init_syncthing_not_running(self, mock_st_cls, mock_key, runner, mock_config): + mock_st = MagicMock() + mock_st.is_running.return_value = False + mock_st_cls.return_value = mock_st + + result = runner.invoke(cli, ["init", "--user-id", "alice"]) + assert result.exit_code == 0 + assert "not detected" in result.output.lower() + + +class TestTeamCreate: + def test_team_create_syncthing(self, runner, mock_config, mock_db): + runner.invoke(cli, ["init", "--user-id", "alice"]) + result = runner.invoke(cli, ["team", "create", "beta"]) + assert result.exit_code == 0 + assert "beta" in result.output + + def test_team_create_requires_init(self, runner, mock_config): + result = runner.invoke(cli, ["team", "create", "beta"]) + assert result.exit_code != 0 + + +class TestTeamAddSyncthing: + @patch("karma.syncthing.SyncthingClient") + def test_team_add_device_id(self, mock_st_cls, runner, mock_config, mock_db): + runner.invoke(cli, ["init", "--user-id", "alice"]) + runner.invoke(cli, ["team", "create", "beta"]) + result = runner.invoke(cli, ["team", "add", "bob", "DEVICEID123", "--team", "beta"]) + assert result.exit_code == 0 + assert "bob" in result.output + + +class TestProjectAddWithTeam: + def test_project_add_to_team(self, runner, mock_config, mock_db, tmp_path): + runner.invoke(cli, ["init", "--user-id", "alice"]) + runner.invoke(cli, ["team", "create", "beta"]) + project_path = tmp_path / "test-project" + project_path.mkdir() + result = runner.invoke(cli, [ + "project", "add", "app", "--path", str(project_path), "--team", "beta" + ]) + assert result.exit_code == 0 + assert "app" in result.output + + def test_project_add_to_nonexistent_team(self, runner, mock_config, mock_db, tmp_path): + runner.invoke(cli, ["init", "--user-id", "alice"]) + project_path = tmp_path / "test-project" + project_path.mkdir() + result = runner.invoke(cli, [ + "project", "add", "app", "--path", str(project_path), "--team", "nope" + ]) + assert result.exit_code != 0 + + +class TestProjectRemoveWithTeam: + def test_project_remove_from_team(self, runner, mock_config, mock_db, tmp_path): + runner.invoke(cli, ["init", "--user-id", "alice"]) + runner.invoke(cli, ["team", "create", "beta"]) + project_path = tmp_path / "test-project" + project_path.mkdir() + runner.invoke(cli, [ + "project", "add", "app", "--path", str(project_path), "--team", "beta" + ]) + result = runner.invoke(cli, ["project", "remove", "test-project", "--team", "beta"]) + assert result.exit_code == 0 + + def test_project_remove_from_nonexistent_team(self, runner, mock_config, mock_db): + runner.invoke(cli, ["init", "--user-id", "alice"]) + result = runner.invoke(cli, ["project", "remove", "app", "--team", "nope"]) + assert result.exit_code != 0 + + def test_project_remove_nonexistent_from_team(self, runner, mock_config, mock_db): + runner.invoke(cli, ["init", "--user-id", "alice"]) + runner.invoke(cli, ["team", "create", "beta"]) + result = runner.invoke(cli, ["project", "remove", "missing", "--team", "beta"]) + assert result.exit_code != 0 + + +class TestTeamMemberRemove: + @patch("karma.syncthing.SyncthingClient") + def test_remove_syncthing_member(self, mock_st_cls, runner, mock_config, mock_db): + runner.invoke(cli, ["init", "--user-id", "alice"]) + runner.invoke(cli, ["team", "create", "beta"]) + runner.invoke(cli, ["team", "add", "bob", "DEVICEID123", "--team", "beta"]) + result = runner.invoke(cli, ["team", "remove", "bob", "--team", "beta"]) + assert result.exit_code == 0 + assert "bob" in result.output + + def test_remove_nonexistent_member_from_team(self, runner, mock_config, mock_db): + runner.invoke(cli, ["init", "--user-id", "alice"]) + runner.invoke(cli, ["team", "create", "beta"]) + result = runner.invoke(cli, ["team", "remove", "ghost", "--team", "beta"]) + assert result.exit_code != 0 + + +class TestWatchCommand: + def test_watch_requires_init(self, runner, mock_config): + result = runner.invoke(cli, ["watch", "--team", "beta"]) + assert result.exit_code != 0 + + def test_watch_requires_syncthing_team(self, runner, mock_config, mock_db): + runner.invoke(cli, ["init", "--user-id", "alice"]) + result = runner.invoke(cli, ["watch", "--team", "nonexistent"]) + assert result.exit_code != 0 + + @patch("karma.watcher.SessionWatcher") + def test_watch_starts_and_stops_on_interrupt(self, mock_watcher_cls, runner, mock_config, mock_db, tmp_path): + runner.invoke(cli, ["init", "--user-id", "alice"]) + runner.invoke(cli, ["team", "create", "beta"]) + project_path = tmp_path / "test-project" + project_path.mkdir() + runner.invoke(cli, [ + "project", "add", "app", "--path", str(project_path), "--team", "beta" + ]) + + # Create the claude dir that watch() checks for + from karma.sync import encode_project_path + encoded = encode_project_path(str(project_path)) + claude_dir = tmp_path / ".claude" / "projects" / encoded + claude_dir.mkdir(parents=True) + + mock_watcher = MagicMock() + mock_watcher_cls.return_value = mock_watcher + + with patch("karma.main.Path.home", return_value=tmp_path), \ + patch("time.sleep", side_effect=KeyboardInterrupt()): + result = runner.invoke(cli, ["watch", "--team", "beta"]) + + mock_watcher_cls.assert_called_once() + mock_watcher.start.assert_called_once() + mock_watcher.stop.assert_called() + + +class TestAcceptCommand: + def test_accept_requires_init(self, runner, mock_config): + result = runner.invoke(cli, ["accept"]) + assert result.exit_code != 0 + + @patch("karma.syncthing.read_local_api_key", return_value="test-key") + @patch("karma.syncthing.SyncthingClient") + def test_accept_no_pending(self, mock_st_cls, mock_key, runner, mock_config, mock_db): + mock_st = MagicMock() + mock_st.is_running.return_value = True + mock_st.get_device_id.return_value = "MY-DEVICE-ID" + mock_st.get_pending_folders.return_value = {} + mock_st_cls.return_value = mock_st + + runner.invoke(cli, ["init", "--user-id", "alice"]) + result = runner.invoke(cli, ["accept"]) + assert result.exit_code == 0 + assert "No pending" in result.output + + @patch("karma.syncthing.read_local_api_key", return_value="test-key") + @patch("karma.syncthing.SyncthingClient") + def test_accept_from_known_member(self, mock_st_cls, mock_key, runner, mock_config, mock_db, tmp_path): + mock_st = MagicMock() + mock_st.is_running.return_value = True + mock_st.get_device_id.return_value = "MY-DEVICE-ID" + mock_st.get_pending_folders.return_value = {} + mock_st.get_folders.return_value = [] + mock_st.find_folder_by_path.return_value = None + mock_st_cls.return_value = mock_st + + runner.invoke(cli, ["init", "--user-id", "alice"]) + runner.invoke(cli, ["team", "create", "beta"]) + runner.invoke(cli, ["team", "add", "bob", "BOB-DEVICE-ID-FULL", "--team", "beta"]) + project_path = tmp_path / "myapp" + project_path.mkdir() + runner.invoke(cli, [ + "project", "add", "myapp", "--path", str(project_path), "--team", "beta" + ]) + + # Now set up the pending folder for the accept call + mock_st.get_pending_folders.return_value = { + "karma-out--bob--myapp": { + "offeredBy": { + "BOB-DEVICE-ID-FULL": {"time": "2026-03-05T03:45:06Z"} + } + } + } + + result = runner.invoke(cli, ["accept"]) + assert result.exit_code == 0 + assert "Accepted" in result.output or "bob" in result.output.lower() + + @patch("karma.syncthing.read_local_api_key", return_value="test-key") + @patch("karma.syncthing.SyncthingClient") + def test_accept_skips_unknown_device(self, mock_st_cls, mock_key, runner, mock_config, mock_db): + mock_st = MagicMock() + mock_st.is_running.return_value = True + mock_st.get_device_id.return_value = "MY-DEVICE-ID" + mock_st.get_pending_folders.return_value = {} + mock_st.get_folders.return_value = [] + mock_st_cls.return_value = mock_st + + runner.invoke(cli, ["init", "--user-id", "alice"]) + runner.invoke(cli, ["team", "create", "beta"]) + + mock_st.get_pending_folders.return_value = { + "karma-evil-folder": { + "offeredBy": {"UNKNOWN-DEVICE-XYZ": {"time": "2026-03-05T00:00:00Z"}} + } + } + + result = runner.invoke(cli, ["accept"]) + assert result.exit_code == 0 + assert "unknown device" in result.output.lower() + mock_st.add_folder.assert_not_called() + + @patch("karma.syncthing.read_local_api_key", return_value="test-key") + @patch("karma.syncthing.SyncthingClient") + def test_accept_skips_non_karma_prefix(self, mock_st_cls, mock_key, runner, mock_config, mock_db): + mock_st = MagicMock() + mock_st.is_running.return_value = True + mock_st.get_device_id.return_value = "MY-DEVICE-ID" + mock_st.get_pending_folders.return_value = {} + mock_st.get_folders.return_value = [] + mock_st_cls.return_value = mock_st + + runner.invoke(cli, ["init", "--user-id", "alice"]) + runner.invoke(cli, ["team", "create", "beta"]) + runner.invoke(cli, ["team", "add", "bob", "BOB-DEVICE-ID", "--team", "beta"]) + + mock_st.get_pending_folders.return_value = { + "suspicious-folder": { + "offeredBy": {"BOB-DEVICE-ID": {"time": "2026-03-05T00:00:00Z"}} + } + } + + result = runner.invoke(cli, ["accept"]) + assert result.exit_code == 0 + assert "non-karma" in result.output.lower() + mock_st.add_folder.assert_not_called() + + @patch("karma.syncthing.read_local_api_key", return_value="test-key") + @patch("karma.syncthing.SyncthingClient") + def test_accept_replaces_empty_existing_folder(self, mock_st_cls, mock_key, runner, mock_config, mock_db, tmp_path): + mock_st = MagicMock() + mock_st.is_running.return_value = True + mock_st.get_device_id.return_value = "MY-DEVICE-ID" + mock_st.get_pending_folders.return_value = {} + mock_st.get_folders.return_value = [] + mock_st_cls.return_value = mock_st + + runner.invoke(cli, ["init", "--user-id", "alice"]) + runner.invoke(cli, ["team", "create", "beta"]) + runner.invoke(cli, ["team", "add", "bob", "BOB-DEVICE-ID", "--team", "beta"]) + project_path = tmp_path / "myapp" + project_path.mkdir() + runner.invoke(cli, [ + "project", "add", "myapp", "--path", str(project_path), "--team", "beta" + ]) + + mock_st.get_pending_folders.return_value = { + "karma-out--bob--myapp": { + "offeredBy": {"BOB-DEVICE-ID": {"time": "2026-03-05T00:00:00Z"}} + } + } + mock_st.find_folder_by_path.return_value = {"id": "karma-out--bob--old", "path": "/tmp/inbox"} + + result = runner.invoke(cli, ["accept"]) + assert result.exit_code == 0 + assert "Replacing" in result.output + mock_st.remove_folder.assert_called_once_with("karma-out--bob--old") + + +class TestWorktreeDiscoveryIntegration: + def test_watch_discovers_worktree_dirs(self, tmp_path): + """karma watch should find worktree dirs and pass them to packager.""" + from karma.worktree_discovery import find_worktree_dirs + + projects_dir = tmp_path / ".claude" / "projects" + main = projects_dir / "-Users-jay-GitHub-karma" + wt = projects_dir / "-Users-jay-GitHub-karma--claude-worktrees-feat-a" + main.mkdir(parents=True) + wt.mkdir(parents=True) + (main / "s1.jsonl").write_text('{"type":"user"}\n') + (wt / "s2.jsonl").write_text('{"type":"user"}\n') + + dirs = find_worktree_dirs("-Users-jay-GitHub-karma", projects_dir) + assert len(dirs) == 1 + assert dirs[0] == wt + + +class TestEndToEndWorktreeSync: + def test_full_worktree_package_pipeline(self, tmp_path): + """End-to-end: discover worktrees, package, verify manifest.""" + from karma.packager import SessionPackager + from karma.worktree_discovery import find_worktree_dirs + import json + + projects_dir = tmp_path / "projects" + + main = projects_dir / "-Users-jay-karma" + main.mkdir(parents=True) + (main / "main-session.jsonl").write_text( + '{"type":"user","message":{"role":"user","content":"main work"}}\n' + ) + + wt1 = projects_dir / "-Users-jay-karma--claude-worktrees-feat-auth" + wt1.mkdir(parents=True) + (wt1 / "auth-session.jsonl").write_text( + '{"type":"user","message":{"role":"user","content":"auth feature"}}\n' + ) + (wt1 / "auth-session" / "subagents").mkdir(parents=True) + (wt1 / "auth-session" / "subagents" / "agent-a1.jsonl").write_text('{"type":"agent"}\n') + + wt2 = projects_dir / "-Users-jay-karma--claude-worktrees-fix-bug" + wt2.mkdir(parents=True) + (wt2 / "bug-session.jsonl").write_text( + '{"type":"user","message":{"role":"user","content":"bug fix"}}\n' + ) + + wt_dirs = find_worktree_dirs("-Users-jay-karma", projects_dir) + assert len(wt_dirs) == 2 + + staging = tmp_path / "outbox" + packager = SessionPackager( + project_dir=main, + user_id="jay", + machine_id="mac", + extra_dirs=wt_dirs, + ) + manifest = packager.package(staging_dir=staging) + + assert manifest.session_count == 3 + uuids = {s.uuid for s in manifest.sessions} + assert uuids == {"main-session", "auth-session", "bug-session"} + + by_uuid = {s.uuid: s for s in manifest.sessions} + assert by_uuid["main-session"].worktree_name is None + assert by_uuid["auth-session"].worktree_name == "feat-auth" + assert by_uuid["bug-session"].worktree_name == "fix-bug" + + assert (staging / "sessions" / "auth-session.jsonl").exists() + assert (staging / "sessions" / "auth-session" / "subagents" / "agent-a1.jsonl").exists() + assert (staging / "sessions" / "bug-session.jsonl").exists() + + manifest_json = json.loads((staging / "manifest.json").read_text()) + wt_entries = [s for s in manifest_json["sessions"] if s["worktree_name"]] + assert len(wt_entries) == 2 + + +class TestStatusCommand: + def test_status_no_teams(self, runner, mock_config, mock_db): + runner.invoke(cli, ["init", "--user-id", "alice"]) + result = runner.invoke(cli, ["status"]) + assert result.exit_code == 0 + assert "No teams" in result.output + + def test_status_shows_teams(self, runner, mock_config, mock_db): + runner.invoke(cli, ["init", "--user-id", "alice"]) + runner.invoke(cli, ["team", "create", "beta"]) + result = runner.invoke(cli, ["status"]) + assert result.exit_code == 0 + assert "beta" in result.output + + def test_status_shows_worktree_counts(self, runner, mock_config, mock_db, tmp_path): + """karma status should show worktree session counts.""" + runner.invoke(cli, ["init", "--user-id", "jay"]) + runner.invoke(cli, ["team", "create", "beta"]) + project_path = tmp_path / "karma-project" + project_path.mkdir() + runner.invoke(cli, [ + "project", "add", "karma", "--path", str(project_path), "--team", "beta" + ]) + + from karma.sync import encode_project_path + encoded = encode_project_path(str(project_path)) + projects_dir = tmp_path / ".claude" / "projects" + main_dir = projects_dir / encoded + main_dir.mkdir(parents=True) + (main_dir / "s1.jsonl").write_text('{"type":"user"}\n') + (main_dir / "s2.jsonl").write_text('{"type":"user"}\n') + + wt_dir = projects_dir / f"{encoded}--claude-worktrees-feat-x" + wt_dir.mkdir(parents=True) + (wt_dir / "s3.jsonl").write_text('{"type":"user"}\n') + + with patch("karma.main.Path.home", return_value=tmp_path): + result = runner.invoke(cli, ["status"]) + + assert result.exit_code == 0 + assert "worktree" in result.output.lower() + assert "3" in result.output diff --git a/cli/tests/test_config.py b/cli/tests/test_config.py new file mode 100644 index 00000000..e668cf25 --- /dev/null +++ b/cli/tests/test_config.py @@ -0,0 +1,64 @@ +"""Tests for sync configuration (identity-only).""" + +import pytest + +from karma.config import SyncConfig, SyncthingSettings + + +class TestSyncConfig: + def test_create_with_defaults(self): + config = SyncConfig(user_id="alice") + assert config.user_id == "alice" + assert config.machine_id # auto-generated hostname + + def test_save_and_load(self, tmp_path, monkeypatch): + config_path = tmp_path / "sync-config.json" + monkeypatch.setattr("karma.config.SYNC_CONFIG_PATH", config_path) + monkeypatch.setattr("karma.config.KARMA_BASE", tmp_path) + + config = SyncConfig(user_id="bob", machine_id="test-machine") + config.save() + + assert config_path.exists() + loaded = SyncConfig.load() + assert loaded is not None + assert loaded.user_id == "bob" + assert loaded.machine_id == "test-machine" + + def test_load_returns_none_when_missing(self, tmp_path, monkeypatch): + monkeypatch.setattr("karma.config.SYNC_CONFIG_PATH", tmp_path / "nope.json") + assert SyncConfig.load() is None + + def test_frozen(self): + config = SyncConfig(user_id="alice") + with pytest.raises(Exception): + config.user_id = "bob" + + def test_syncthing_settings_preserved(self, tmp_path, monkeypatch): + config_path = tmp_path / "sync-config.json" + monkeypatch.setattr("karma.config.SYNC_CONFIG_PATH", config_path) + monkeypatch.setattr("karma.config.KARMA_BASE", tmp_path) + + config = SyncConfig( + user_id="alice", + machine_id="mac", + syncthing=SyncthingSettings(api_key="key123", device_id="DEV-1"), + ) + config.save() + + loaded = SyncConfig.load() + assert loaded.syncthing.api_key == "key123" + assert loaded.syncthing.device_id == "DEV-1" + + +class TestSyncthingSettings: + def test_defaults(self): + s = SyncthingSettings() + assert s.api_url == "http://127.0.0.1:8384" + assert s.api_key is None + assert s.device_id is None + + def test_custom_values(self): + s = SyncthingSettings(api_url="http://localhost:9999", api_key="abc123") + assert s.api_url == "http://localhost:9999" + assert s.api_key == "abc123" diff --git a/cli/tests/test_config_teams.py b/cli/tests/test_config_teams.py new file mode 100644 index 00000000..1787cc0a --- /dev/null +++ b/cli/tests/test_config_teams.py @@ -0,0 +1,41 @@ +"""Tests for SyncConfig with syncthing settings (identity-only model).""" + +from karma.config import SyncConfig, SyncthingSettings + + +class TestSyncthingSettings: + def test_defaults(self): + s = SyncthingSettings() + assert s.api_url == "http://127.0.0.1:8384" + assert s.api_key is None + assert s.device_id is None + + def test_custom_values(self): + s = SyncthingSettings(api_url="http://localhost:9999", api_key="abc123") + assert s.api_url == "http://localhost:9999" + assert s.api_key == "abc123" + + +class TestSyncConfigWithSyncthing: + def test_config_has_syncthing_settings(self): + config = SyncConfig( + user_id="alice", + syncthing=SyncthingSettings(api_key="test"), + ) + assert config.syncthing.api_key == "test" + + def test_save_and_load_with_syncthing(self, tmp_path, monkeypatch): + config_path = tmp_path / "sync-config.json" + monkeypatch.setattr("karma.config.SYNC_CONFIG_PATH", config_path) + monkeypatch.setattr("karma.config.KARMA_BASE", tmp_path) + + config = SyncConfig( + user_id="alice", + machine_id="test-mac", + syncthing=SyncthingSettings(api_url="http://127.0.0.1:8384", api_key="key123"), + ) + config.save() + + loaded = SyncConfig.load() + assert loaded is not None + assert loaded.syncthing.api_key == "key123" diff --git a/cli/tests/test_integration.py b/cli/tests/test_integration.py new file mode 100644 index 00000000..f72a26f4 --- /dev/null +++ b/cli/tests/test_integration.py @@ -0,0 +1,128 @@ +"""Integration test: full team/project lifecycle with SQLite.""" + +import json + +import pytest +from click.testing import CliRunner + +from karma.main import cli + + +@pytest.fixture +def full_setup(tmp_path, monkeypatch, mock_db): + """Set up a complete test environment.""" + config_path = tmp_path / "sync-config.json" + monkeypatch.setattr("karma.config.SYNC_CONFIG_PATH", config_path) + monkeypatch.setattr("karma.config.KARMA_BASE", tmp_path) + monkeypatch.setattr("karma.main.KARMA_BASE", tmp_path) + + return { + "tmp": tmp_path, + "config_path": config_path, + "db": mock_db, + } + + +class TestFullSyncFlow: + def test_init_and_team_project_flow(self, full_setup): + runner = CliRunner() + tmp = full_setup["tmp"] + + # Step 1: Init + result = runner.invoke(cli, ["init", "--user-id", "alice"]) + assert result.exit_code == 0 + assert "Initialized as 'alice'" in result.output + + # Step 2: Create team + result = runner.invoke(cli, ["team", "create", "beta"]) + assert result.exit_code == 0 + + # Step 3: Add project (path must be absolute) + project_path = tmp / "test-project" + project_path.mkdir() + result = runner.invoke(cli, [ + "project", "add", "test-project", + "--path", str(project_path), + "--team", "beta", + ]) + assert result.exit_code == 0 + assert "Added project 'test-project'" in result.output + + # Verify in DB + row = full_setup["db"].execute( + "SELECT * FROM sync_team_projects WHERE team_name = 'beta'" + ).fetchone() + assert row is not None + + def test_team_management_flow(self, full_setup): + runner = CliRunner() + + # Init + runner.invoke(cli, ["init", "--user-id", "owner"]) + + # Create team + result = runner.invoke(cli, ["team", "create", "alpha"]) + assert result.exit_code == 0 + + # Add team members + result = runner.invoke(cli, ["team", "add", "alice", "ALICE-DEVICE-ID", "--team", "alpha"]) + assert result.exit_code == 0 + + result = runner.invoke(cli, ["team", "add", "bob", "BOB-DEVICE-ID", "--team", "alpha"]) + assert result.exit_code == 0 + + # List team + result = runner.invoke(cli, ["team", "list"]) + assert "alice" in result.output + assert "bob" in result.output + + # Remove member + result = runner.invoke(cli, ["team", "remove", "alice", "--team", "alpha"]) + assert result.exit_code == 0 + + # Verify alice is gone from DB + row = full_setup["db"].execute( + "SELECT * FROM sync_members WHERE team_name = 'alpha' AND name = 'alice'" + ).fetchone() + assert row is None + + # Bob still there + row = full_setup["db"].execute( + "SELECT * FROM sync_members WHERE team_name = 'alpha' AND name = 'bob'" + ).fetchone() + assert row is not None + + def test_project_lifecycle(self, full_setup): + runner = CliRunner() + tmp = full_setup["tmp"] + + # Init + runner.invoke(cli, ["init", "--user-id", "alice"]) + + # Create team + runner.invoke(cli, ["team", "create", "beta"]) + + # Add project + project_path = tmp / "my-app" + project_path.mkdir() + result = runner.invoke(cli, [ + "project", "add", "my-app", + "--path", str(project_path), + "--team", "beta", + ]) + assert result.exit_code == 0 + + # List projects + result = runner.invoke(cli, ["project", "list"]) + assert "my-app" in result.output + + # Remove project + result = runner.invoke(cli, ["project", "remove", "my-app", "--team", "beta"]) + assert result.exit_code == 0 + assert "Removed project 'my-app'" in result.output + + # Verify gone from DB + row = full_setup["db"].execute( + "SELECT * FROM sync_team_projects WHERE team_name = 'beta'" + ).fetchone() + assert row is None diff --git a/cli/tests/test_nongit_projects.py b/cli/tests/test_nongit_projects.py new file mode 100644 index 00000000..b3db0181 --- /dev/null +++ b/cli/tests/test_nongit_projects.py @@ -0,0 +1,328 @@ +"""Tests for non-git project handling (GAP-1 through GAP-7 fixes).""" + +import json +import sqlite3 + +import pytest +from click.testing import CliRunner + +from karma.main import cli + + +@pytest.fixture +def setup(tmp_path, monkeypatch, mock_db): + """Set up test environment with init + team.""" + config_path = tmp_path / "sync-config.json" + monkeypatch.setattr("karma.config.SYNC_CONFIG_PATH", config_path) + monkeypatch.setattr("karma.config.KARMA_BASE", tmp_path) + monkeypatch.setattr("karma.main.KARMA_BASE", tmp_path) + + runner = CliRunner() + runner.invoke(cli, ["init", "--user-id", "alice"]) + runner.invoke(cli, ["team", "create", "beta"]) + + return {"tmp": tmp_path, "db": mock_db, "runner": runner} + + +class TestSuffixStoredAtShareTime: + """Fix A: folder_suffix is stored immediately when project is added.""" + + def test_nongit_project_stores_cli_name_as_suffix(self, setup): + tmp, db, runner = setup["tmp"], setup["db"], setup["runner"] + + project_path = tmp / "my-notes" + project_path.mkdir() + result = runner.invoke(cli, [ + "project", "add", "my-notes", + "--path", str(project_path), + "--team", "beta", + ]) + assert result.exit_code == 0 + + row = db.execute( + "SELECT folder_suffix FROM sync_team_projects WHERE team_name = 'beta'" + ).fetchone() + assert row is not None + assert row["folder_suffix"] == "my-notes" + + def test_git_project_stores_git_identity_as_suffix(self, setup, monkeypatch): + tmp, db, runner = setup["tmp"], setup["db"], setup["runner"] + + project_path = tmp / "repo" + project_path.mkdir() + + # Mock git identity detection + monkeypatch.setattr( + "karma.main.detect_git_identity", + lambda p: "acme/my-repo", + ) + + result = runner.invoke(cli, [ + "project", "add", "repo", + "--path", str(project_path), + "--team", "beta", + ]) + assert result.exit_code == 0 + + row = db.execute( + "SELECT folder_suffix FROM sync_team_projects WHERE team_name = 'beta'" + ).fetchone() + assert row["folder_suffix"] == "acme-my-repo" + + def test_custom_suffix_override(self, setup): + tmp, db, runner = setup["tmp"], setup["db"], setup["runner"] + + project_path = tmp / "design-docs" + project_path.mkdir() + result = runner.invoke(cli, [ + "project", "add", "design-docs", + "--path", str(project_path), + "--team", "beta", + "--suffix", "jay-design-docs", + ]) + assert result.exit_code == 0 + + row = db.execute( + "SELECT folder_suffix FROM sync_team_projects WHERE team_name = 'beta'" + ).fetchone() + assert row["folder_suffix"] == "jay-design-docs" + + +class TestSuffixCollisionDetection: + """Fix B: suffix uniqueness check prevents non-git collision (GAP-1).""" + + def test_same_suffix_different_project_rejected(self, setup): + tmp, db, runner = setup["tmp"], setup["db"], setup["runner"] + + # Add first project + p1 = tmp / "notes-v1" + p1.mkdir() + result = runner.invoke(cli, [ + "project", "add", "my-notes", + "--path", str(p1), + "--team", "beta", + ]) + assert result.exit_code == 0 + + # Add second project with DIFFERENT path but SAME name -> same suffix + p2 = tmp / "notes-v2" + p2.mkdir() + result = runner.invoke(cli, [ + "project", "add", "my-notes", + "--path", str(p2), + "--team", "beta", + ]) + assert result.exit_code != 0 + assert "suffix" in result.output.lower() or "already" in result.output.lower() + + def test_collision_resolved_with_custom_suffix(self, setup): + tmp, db, runner = setup["tmp"], setup["db"], setup["runner"] + + # Add first project + p1 = tmp / "notes-v1" + p1.mkdir() + runner.invoke(cli, [ + "project", "add", "my-notes", + "--path", str(p1), + "--team", "beta", + ]) + + # Add second project with custom suffix to avoid collision + p2 = tmp / "notes-v2" + p2.mkdir() + result = runner.invoke(cli, [ + "project", "add", "my-notes-v2", + "--path", str(p2), + "--team", "beta", + "--suffix", "my-notes-v2", + ]) + assert result.exit_code == 0 + + rows = db.execute( + "SELECT folder_suffix FROM sync_team_projects WHERE team_name = 'beta' ORDER BY folder_suffix" + ).fetchall() + suffixes = [r["folder_suffix"] for r in rows] + assert "my-notes" in suffixes + assert "my-notes-v2" in suffixes + + def test_same_project_readd_allowed(self, setup): + """Re-adding the same project (same encoded name) should not trigger collision.""" + tmp, db, runner = setup["tmp"], setup["db"], setup["runner"] + + p1 = tmp / "my-app" + p1.mkdir() + result = runner.invoke(cli, [ + "project", "add", "my-app", + "--path", str(p1), + "--team", "beta", + ]) + assert result.exit_code == 0 + + # Re-add same project (same path -> same encoded) — should hit UNIQUE constraint + # on (team_name, project_encoded_name), not suffix collision + result = runner.invoke(cli, [ + "project", "add", "my-app", + "--path", str(p1), + "--team", "beta", + ]) + assert result.exit_code != 0 + assert "already exists" in result.output.lower() + + +class TestProjectMap: + """Fix D: manual project mapping CLI for non-git cross-machine resolution.""" + + def test_map_updates_project_path(self, setup): + tmp, db, runner = setup["tmp"], setup["db"], setup["runner"] + + # Add a project (simulating what a receiver would have after accepting folders) + p1 = tmp / "remote-proj" + p1.mkdir() + runner.invoke(cli, [ + "project", "add", "design-docs", + "--path", str(p1), + "--team", "beta", + ]) + + # Create local directory to map to + local = tmp / "my-local-design" + local.mkdir() + + result = runner.invoke(cli, [ + "project", "map", "design-docs", + "--team", "beta", + "--path", str(local), + ]) + assert result.exit_code == 0 + assert "Mapped" in result.output + + # Verify the team project now points to local path + row = db.execute( + "SELECT path FROM sync_team_projects WHERE team_name = 'beta' AND folder_suffix = 'design-docs'" + ).fetchone() + assert row is not None + assert row["path"] == str(local) + + def test_map_nonexistent_suffix_fails(self, setup): + tmp, runner = setup["tmp"], setup["runner"] + + local = tmp / "something" + local.mkdir() + result = runner.invoke(cli, [ + "project", "map", "nonexistent-suffix", + "--team", "beta", + "--path", str(local), + ]) + assert result.exit_code != 0 + assert "No project with suffix" in result.output + + def test_map_nonexistent_team_fails(self, setup): + tmp, runner = setup["tmp"], setup["runner"] + + local = tmp / "something" + local.mkdir() + result = runner.invoke(cli, [ + "project", "map", "some-suffix", + "--team", "no-such-team", + "--path", str(local), + ]) + assert result.exit_code != 0 + assert "not found" in result.output.lower() + + def test_map_nonexistent_path_fails(self, setup): + tmp, runner = setup["tmp"], setup["runner"] + + # Add a project first + p1 = tmp / "remote-proj" + p1.mkdir() + runner.invoke(cli, [ + "project", "add", "design-docs", + "--path", str(p1), + "--team", "beta", + ]) + + result = runner.invoke(cli, [ + "project", "map", "design-docs", + "--team", "beta", + "--path", "/nonexistent/path/foo", + ]) + assert result.exit_code != 0 + assert "does not exist" in result.output.lower() + + def test_map_registers_in_projects_table(self, setup): + tmp, db, runner = setup["tmp"], setup["db"], setup["runner"] + + p1 = tmp / "remote-proj" + p1.mkdir() + runner.invoke(cli, [ + "project", "add", "my-proj", + "--path", str(p1), + "--team", "beta", + ]) + + local = tmp / "local-proj" + local.mkdir() + runner.invoke(cli, [ + "project", "map", "my-proj", + "--team", "beta", + "--path", str(local), + ]) + + # Check projects table has the local path + row = db.execute( + "SELECT project_path FROM projects WHERE project_path = ?", + (str(local),), + ).fetchone() + assert row is not None + + +class TestManifestProjectName: + """Fix C: SyncManifest includes project_name field.""" + + def test_manifest_has_project_name_field(self): + from karma.manifest import SyncManifest + + m = SyncManifest( + user_id="alice", + machine_id="macbook", + project_path="/Users/alice/notes", + project_encoded="-Users-alice-notes", + session_count=0, + sessions=[], + project_name="notes", + ) + data = m.model_dump() + assert data["project_name"] == "notes" + + def test_manifest_project_name_optional(self): + from karma.manifest import SyncManifest + + m = SyncManifest( + user_id="alice", + machine_id="macbook", + project_path="/Users/alice/notes", + project_encoded="-Users-alice-notes", + session_count=0, + sessions=[], + ) + data = m.model_dump() + assert data["project_name"] is None + + def test_manifest_roundtrip_with_project_name(self): + from karma.manifest import SyncManifest + + m = SyncManifest( + user_id="alice", + machine_id="macbook", + project_path="/Users/alice/notes", + project_encoded="-Users-alice-notes", + session_count=0, + sessions=[], + project_name="my-design-notes", + git_identity=None, + ) + json_str = json.dumps(m.model_dump()) + data = json.loads(json_str) + m2 = SyncManifest(**data) + assert m2.project_name == "my-design-notes" + assert m2.git_identity is None diff --git a/cli/tests/test_packager.py b/cli/tests/test_packager.py new file mode 100644 index 00000000..71add045 --- /dev/null +++ b/cli/tests/test_packager.py @@ -0,0 +1,836 @@ +"""Tests for session packager.""" + +import json +from pathlib import Path + +import pytest + +from karma.packager import SessionPackager + + +@pytest.fixture +def mock_claude_project(tmp_path: Path) -> Path: + """Create a fake ~/.claude/projects/-My-project/ directory.""" + project_dir = tmp_path / ".claude" / "projects" / "-My-project" + project_dir.mkdir(parents=True) + + # Session 1: simple JSONL + s1 = project_dir / "session-uuid-001.jsonl" + s1.write_text('{"type":"user","message":{"role":"user","content":"hello"}}\n') + + # Session 2: with subagents directory + s2 = project_dir / "session-uuid-002.jsonl" + s2.write_text('{"type":"user","message":{"role":"user","content":"build X"}}\n') + sub_dir = project_dir / "session-uuid-002" / "subagents" + sub_dir.mkdir(parents=True) + (sub_dir / "agent-abc.jsonl").write_text('{"type":"agent"}\n') + + # Tool results + tr_dir = project_dir / "session-uuid-002" / "tool-results" + tr_dir.mkdir(parents=True) + (tr_dir / "toolu_123.txt").write_text("tool output here") + + return project_dir + + +class TestSessionPackager: + def test_discover_sessions(self, mock_claude_project): + packager = SessionPackager( + project_dir=mock_claude_project, + user_id="alice", + machine_id="test-mac", + ) + sessions = packager.discover_sessions() + assert len(sessions) == 2 + uuids = {s.uuid for s in sessions} + assert "session-uuid-001" in uuids + assert "session-uuid-002" in uuids + + def test_package_creates_staging_dir(self, mock_claude_project, tmp_path): + staging = tmp_path / "staging" + packager = SessionPackager( + project_dir=mock_claude_project, + user_id="alice", + machine_id="test-mac", + ) + packager.package(staging_dir=staging) + + assert staging.exists() + assert (staging / "manifest.json").exists() + assert (staging / "sessions" / "session-uuid-001.jsonl").exists() + assert (staging / "sessions" / "session-uuid-002.jsonl").exists() + assert (staging / "sessions" / "session-uuid-002" / "subagents" / "agent-abc.jsonl").exists() + assert (staging / "sessions" / "session-uuid-002" / "tool-results" / "toolu_123.txt").exists() + + def test_manifest_content(self, mock_claude_project, tmp_path): + staging = tmp_path / "staging" + packager = SessionPackager( + project_dir=mock_claude_project, + user_id="alice", + machine_id="test-mac", + ) + manifest = packager.package(staging_dir=staging) + + assert manifest.user_id == "alice" + assert manifest.machine_id == "test-mac" + assert manifest.session_count == 2 + assert manifest.version == 1 + assert len(manifest.sessions) == 2 + + + +class TestSessionEntryMetadata: + def test_session_entry_default_no_worktree(self): + from karma.manifest import SessionEntry + entry = SessionEntry(uuid="abc", mtime="2026-01-01T00:00:00Z", size_bytes=100) + assert entry.worktree_name is None + assert entry.git_branch is None + + def test_session_entry_with_worktree(self): + from karma.manifest import SessionEntry + entry = SessionEntry( + uuid="abc", + mtime="2026-01-01T00:00:00Z", + size_bytes=100, + worktree_name="syncthing-sync-design", + git_branch="worktree-syncthing-sync-design", + ) + assert entry.worktree_name == "syncthing-sync-design" + assert entry.git_branch == "worktree-syncthing-sync-design" + + def test_session_entry_worktree_in_dump(self): + from karma.manifest import SessionEntry + entry = SessionEntry( + uuid="abc", + mtime="2026-01-01T00:00:00Z", + size_bytes=100, + worktree_name="feat-x", + ) + data = entry.model_dump() + assert data["worktree_name"] == "feat-x" + assert data["git_branch"] is None + + +@pytest.fixture +def mock_project_with_worktree(tmp_path: Path) -> dict: + """Create a main project dir + one worktree dir.""" + projects_dir = tmp_path / ".claude" / "projects" + + # Main project + main_dir = projects_dir / "-Users-jay-GitHub-karma" + main_dir.mkdir(parents=True) + (main_dir / "session-main-001.jsonl").write_text( + '{"type":"user","message":{"role":"user","content":"hello"}}\n' + ) + + # Worktree + wt_dir = projects_dir / "-Users-jay-GitHub-karma--claude-worktrees-feat-a" + wt_dir.mkdir(parents=True) + (wt_dir / "session-wt-001.jsonl").write_text( + '{"type":"user","message":{"role":"user","content":"worktree work"}}\n' + ) + # Worktree session with subagent + (wt_dir / "session-wt-002.jsonl").write_text( + '{"type":"user","message":{"role":"user","content":"more work"}}\n' + ) + sub_dir = wt_dir / "session-wt-002" / "subagents" + sub_dir.mkdir(parents=True) + (sub_dir / "agent-x.jsonl").write_text('{"type":"agent"}\n') + + return { + "main_dir": main_dir, + "wt_dir": wt_dir, + "projects_dir": projects_dir, + } + + +class TestPackagerWithWorktrees: + def test_discover_includes_worktree_sessions(self, mock_project_with_worktree): + dirs = mock_project_with_worktree + packager = SessionPackager( + project_dir=dirs["main_dir"], + user_id="jay", + machine_id="mac", + extra_dirs=[dirs["wt_dir"]], + ) + sessions = packager.discover_sessions() + uuids = {s.uuid for s in sessions} + assert "session-main-001" in uuids + assert "session-wt-001" in uuids + assert "session-wt-002" in uuids + assert len(sessions) == 3 + + def test_worktree_sessions_tagged_with_worktree_name(self, mock_project_with_worktree): + dirs = mock_project_with_worktree + packager = SessionPackager( + project_dir=dirs["main_dir"], + user_id="jay", + machine_id="mac", + extra_dirs=[dirs["wt_dir"]], + ) + sessions = packager.discover_sessions() + wt_sessions = [s for s in sessions if s.worktree_name is not None] + assert len(wt_sessions) == 2 + assert all(s.worktree_name == "feat-a" for s in wt_sessions) + + def test_package_copies_worktree_subagents(self, mock_project_with_worktree, tmp_path): + dirs = mock_project_with_worktree + staging = tmp_path / "staging" + packager = SessionPackager( + project_dir=dirs["main_dir"], + user_id="jay", + machine_id="mac", + extra_dirs=[dirs["wt_dir"]], + ) + packager.package(staging_dir=staging) + assert (staging / "sessions" / "session-wt-002" / "subagents" / "agent-x.jsonl").exists() + + def test_manifest_counts_all_sessions(self, mock_project_with_worktree, tmp_path): + dirs = mock_project_with_worktree + staging = tmp_path / "staging" + packager = SessionPackager( + project_dir=dirs["main_dir"], + user_id="jay", + machine_id="mac", + extra_dirs=[dirs["wt_dir"]], + ) + manifest = packager.package(staging_dir=staging) + assert manifest.session_count == 3 + + def test_no_extra_dirs_works_like_before(self, mock_claude_project, tmp_path): + """Backward compat: no extra_dirs = original behavior.""" + staging = tmp_path / "staging" + packager = SessionPackager( + project_dir=mock_claude_project, + user_id="alice", + machine_id="test-mac", + ) + manifest = packager.package(staging_dir=staging) + assert manifest.session_count == 2 + + +class TestIncrementalPackaging: + def test_skip_unchanged_sessions(self, mock_claude_project, tmp_path): + """Second package should skip files that haven't changed.""" + staging = tmp_path / "staging" + packager = SessionPackager( + project_dir=mock_claude_project, + user_id="alice", + machine_id="test-mac", + ) + + # First package + manifest1 = packager.package(staging_dir=staging) + assert manifest1.session_count == 2 + + # Record mtime of a copied file + copied = staging / "sessions" / "session-uuid-001.jsonl" + mtime_after_first = copied.stat().st_mtime + + import time + time.sleep(0.05) # ensure mtime difference is detectable + + # Second package (no source changes) + manifest2 = packager.package(staging_dir=staging) + assert manifest2.session_count == 2 + + # File should NOT have been re-copied (mtime unchanged) + mtime_after_second = copied.stat().st_mtime + assert mtime_after_first == mtime_after_second + + def test_repackage_modified_session(self, mock_claude_project, tmp_path): + """Modified source file should be re-copied.""" + staging = tmp_path / "staging" + packager = SessionPackager( + project_dir=mock_claude_project, + user_id="alice", + machine_id="test-mac", + ) + + packager.package(staging_dir=staging) + copied = staging / "sessions" / "session-uuid-001.jsonl" + mtime_before = copied.stat().st_mtime + + import time + time.sleep(0.05) + + # Modify source + src = mock_claude_project / "session-uuid-001.jsonl" + src.write_text('{"type":"user","message":{"role":"user","content":"updated"}}\n') + + packager.package(staging_dir=staging) + mtime_after = copied.stat().st_mtime + assert mtime_after > mtime_before + + +class TestTaskSyncing: + def test_package_copies_task_files(self, tmp_path): + """Tasks from ~/.claude/tasks/{uuid}/ should be copied.""" + claude_dir = tmp_path / ".claude" + project_dir = claude_dir / "projects" / "-My-project" + project_dir.mkdir(parents=True) + (project_dir / "session-abc.jsonl").write_text( + '{"type":"user","message":{"role":"user","content":"hello"}}\n' + ) + + # Create task dir: .claude/tasks/session-abc/ + tasks_dir = claude_dir / "tasks" / "session-abc" + tasks_dir.mkdir(parents=True) + (tasks_dir / "1.json").write_text( + '{"id":"1","subject":"Fix bug","status":"completed"}\n' + ) + (tasks_dir / "2.json").write_text( + '{"id":"2","subject":"Add test","status":"pending"}\n' + ) + + staging = tmp_path / "staging" + packager = SessionPackager( + project_dir=project_dir, + user_id="alice", + machine_id="mac", + ) + packager.package(staging_dir=staging) + + assert (staging / "tasks" / "session-abc" / "1.json").exists() + assert (staging / "tasks" / "session-abc" / "2.json").exists() + + def test_package_skips_missing_task_dir(self, mock_claude_project, tmp_path): + """Sessions without task dirs should not cause errors.""" + staging = tmp_path / "staging" + packager = SessionPackager( + project_dir=mock_claude_project, + user_id="alice", + machine_id="mac", + ) + manifest = packager.package(staging_dir=staging) + assert manifest.session_count == 2 + # tasks dir should not exist if no tasks + assert not (staging / "tasks").exists() + + def test_package_copies_worktree_tasks(self, tmp_path): + """Tasks for worktree sessions should also be copied.""" + claude_dir = tmp_path / ".claude" + main_dir = claude_dir / "projects" / "-Users-jay-karma" + main_dir.mkdir(parents=True) + (main_dir / "main-s.jsonl").write_text('{"type":"user","message":{"role":"user","content":"hi"}}\n') + + wt_dir = claude_dir / "projects" / "-Users-jay-karma--claude-worktrees-feat" + wt_dir.mkdir(parents=True) + (wt_dir / "wt-s.jsonl").write_text('{"type":"user","message":{"role":"user","content":"hi"}}\n') + + # Task for worktree session + tasks_dir = claude_dir / "tasks" / "wt-s" + tasks_dir.mkdir(parents=True) + (tasks_dir / "1.json").write_text('{"id":"1","subject":"WT task","status":"pending"}\n') + + staging = tmp_path / "staging" + packager = SessionPackager( + project_dir=main_dir, + user_id="jay", + machine_id="mac", + extra_dirs=[wt_dir], + ) + packager.package(staging_dir=staging) + + assert (staging / "tasks" / "wt-s" / "1.json").exists() + + +class TestFileHistorySyncing: + def test_package_copies_file_history(self, tmp_path): + """File-history directories should be copied to staging.""" + claude_dir = tmp_path / ".claude" + project_dir = claude_dir / "projects" / "-Users-test-repo" + project_dir.mkdir(parents=True) + + uuid = "sess-fh-001" + (project_dir / f"{uuid}.jsonl").write_text( + '{"type":"user","message":{"role":"user","content":"hi"}}\n' + ) + + # Create file-history for this session + fh_dir = claude_dir / "file-history" / uuid + fh_dir.mkdir(parents=True) + (fh_dir / "snapshot-1.json").write_text('{"file": "main.py", "content": "print(1)"}') + + staging = tmp_path / "staging" + packager = SessionPackager( + project_dir=project_dir, + user_id="test", + machine_id="test-machine", + ) + packager.package(staging) + + staged_fh = staging / "file-history" / uuid / "snapshot-1.json" + assert staged_fh.exists() + assert staged_fh.read_text() == '{"file": "main.py", "content": "print(1)"}' + + def test_package_skips_missing_file_history(self, mock_claude_project, tmp_path): + """Sessions without file-history should not cause errors.""" + staging = tmp_path / "staging" + packager = SessionPackager( + project_dir=mock_claude_project, + user_id="alice", + machine_id="mac", + ) + manifest = packager.package(staging_dir=staging) + assert manifest.session_count == 2 + assert not (staging / "file-history").exists() + + def test_incremental_package_file_history(self, tmp_path): + """Re-packaging should not fail or duplicate file-history.""" + claude_dir = tmp_path / ".claude" + project_dir = claude_dir / "projects" / "-Users-test-repo" + project_dir.mkdir(parents=True) + + uuid = "sess-fh-002" + (project_dir / f"{uuid}.jsonl").write_text( + '{"type":"user","message":{"role":"user","content":"hi"}}\n' + ) + + fh_dir = claude_dir / "file-history" / uuid + fh_dir.mkdir(parents=True) + (fh_dir / "snapshot.json").write_text('{"file": "main.py"}') + + staging = tmp_path / "staging" + packager = SessionPackager( + project_dir=project_dir, + user_id="test", + machine_id="test-machine", + ) + + # First package + packager.package(staging) + assert (staging / "file-history" / uuid / "snapshot.json").exists() + + # Second package (should not crash) + packager.package(staging) + assert (staging / "file-history" / uuid / "snapshot.json").exists() + + +class TestDebugLogSyncing: + def test_package_copies_debug_logs(self, tmp_path): + """Debug log files should be copied to staging.""" + claude_dir = tmp_path / ".claude" + project_dir = claude_dir / "projects" / "-Users-test-repo" + project_dir.mkdir(parents=True) + + uuid = "sess-debug-001" + (project_dir / f"{uuid}.jsonl").write_text( + '{"type":"user","message":{"role":"user","content":"hi"}}\n' + ) + + debug_dir = claude_dir / "debug" + debug_dir.mkdir(parents=True) + (debug_dir / f"{uuid}.txt").write_text("DEBUG: session started\nDEBUG: tool called") + + staging = tmp_path / "staging" + packager = SessionPackager( + project_dir=project_dir, + user_id="test", + machine_id="test-machine", + ) + packager.package(staging) + + staged_debug = staging / "debug" / f"{uuid}.txt" + assert staged_debug.exists() + assert "DEBUG: session started" in staged_debug.read_text() + + def test_package_skips_missing_debug_logs(self, mock_claude_project, tmp_path): + """Sessions without debug logs should not cause errors.""" + staging = tmp_path / "staging" + packager = SessionPackager( + project_dir=mock_claude_project, + user_id="alice", + machine_id="mac", + ) + manifest = packager.package(staging_dir=staging) + assert manifest.session_count == 2 + assert not (staging / "debug").exists() + + def test_package_copies_worktree_debug_logs(self, tmp_path): + """Debug logs for worktree sessions should also be copied.""" + claude_dir = tmp_path / ".claude" + main_dir = claude_dir / "projects" / "-Users-jay-karma" + main_dir.mkdir(parents=True) + (main_dir / "main-s.jsonl").write_text('{"type":"user","message":{"role":"user","content":"hi"}}\n') + + wt_dir = claude_dir / "projects" / "-Users-jay-karma--claude-worktrees-feat" + wt_dir.mkdir(parents=True) + (wt_dir / "wt-s.jsonl").write_text('{"type":"user","message":{"role":"user","content":"hi"}}\n') + + # Debug log for worktree session + debug_dir = claude_dir / "debug" + debug_dir.mkdir(parents=True) + (debug_dir / "wt-s.txt").write_text("DEBUG: worktree session") + + staging = tmp_path / "staging" + packager = SessionPackager( + project_dir=main_dir, + user_id="jay", + machine_id="mac", + extra_dirs=[wt_dir], + ) + packager.package(staging_dir=staging) + + assert (staging / "debug" / "wt-s.txt").exists() + + +class TestSyncManifest: + def test_manifest_git_identity_in_dump(self): + from karma.manifest import SyncManifest + m = SyncManifest( + user_id="alice", + machine_id="mac", + project_path="/foo", + project_encoded="-foo", + session_count=0, + sessions=[], + ) + data = m.model_dump() + assert data["git_identity"] is None + + +class TestPackagerTitles: + def test_package_creates_titles_json(self, mock_claude_project, tmp_path): + """Verify titles.json is created alongside manifest.json.""" + staging = tmp_path / "staging" + packager = SessionPackager( + project_dir=mock_claude_project, + user_id="alice", + machine_id="test-mac", + ) + packager.package(staging_dir=staging) + + assert (staging / "manifest.json").exists() + assert (staging / "titles.json").exists() + + import json + data = json.loads((staging / "titles.json").read_text()) + assert data["version"] == 1 + assert "titles" in data + assert "updated_at" in data + + def test_package_preserves_existing_titles(self, mock_claude_project, tmp_path): + """Pre-populated titles.json should not be overwritten by packaging.""" + staging = tmp_path / "staging" + staging.mkdir(parents=True) + + # Pre-populate titles.json with an existing title + from karma.titles_io import write_title + titles_path = staging / "titles.json" + write_title(titles_path, "session-uuid-001", "My Title", "haiku") + + # Verify it was written + from karma.titles_io import read_titles + pre_titles = read_titles(titles_path) + assert "session-uuid-001" in pre_titles + assert pre_titles["session-uuid-001"]["title"] == "My Title" + + # Now package — should preserve the existing title + packager = SessionPackager( + project_dir=mock_claude_project, + user_id="alice", + machine_id="test-mac", + ) + packager.package(staging_dir=staging) + + post_titles = read_titles(titles_path) + assert "session-uuid-001" in post_titles + assert post_titles["session-uuid-001"]["title"] == "My Title" + assert post_titles["session-uuid-001"]["source"] == "haiku" + + +class TestLiveSessionExclusion: + """Live (in-progress) sessions should not be packaged for sync.""" + + def test_live_session_excluded_from_discovery(self, mock_claude_project, monkeypatch): + """A session whose UUID appears as LIVE should be excluded.""" + from karma import packager + + # Simulate session-uuid-001 being live + monkeypatch.setattr( + packager, "_get_live_session_uuids", lambda: {"session-uuid-001"} + ) + + p = SessionPackager( + project_dir=mock_claude_project, + user_id="alice", + machine_id="test-mac", + ) + sessions = p.discover_sessions() + uuids = {s.uuid for s in sessions} + assert "session-uuid-001" not in uuids + assert "session-uuid-002" in uuids + assert len(sessions) == 1 + + def test_ended_session_not_excluded(self, mock_claude_project, monkeypatch): + """ENDED sessions should pass through (empty live set).""" + from karma import packager + + monkeypatch.setattr(packager, "_get_live_session_uuids", lambda: set()) + + p = SessionPackager( + project_dir=mock_claude_project, + user_id="alice", + machine_id="test-mac", + ) + sessions = p.discover_sessions() + assert len(sessions) == 2 + + def test_exclude_live_false_skips_filter(self, mock_claude_project, monkeypatch): + """exclude_live=False should bypass the filter entirely.""" + from karma import packager + + monkeypatch.setattr( + packager, + "_get_live_session_uuids", + lambda: {"session-uuid-001", "session-uuid-002"}, + ) + + p = SessionPackager( + project_dir=mock_claude_project, + user_id="alice", + machine_id="test-mac", + ) + sessions = p.discover_sessions(exclude_live=False) + assert len(sessions) == 2 + + def test_live_session_not_packaged(self, mock_claude_project, tmp_path, monkeypatch): + """Live session JSONL should not be copied to staging dir.""" + from karma import packager + + monkeypatch.setattr( + packager, "_get_live_session_uuids", lambda: {"session-uuid-001"} + ) + + staging = tmp_path / "staging" + p = SessionPackager( + project_dir=mock_claude_project, + user_id="alice", + machine_id="test-mac", + ) + manifest = p.package(staging_dir=staging) + + assert manifest.session_count == 1 + assert not (staging / "sessions" / "session-uuid-001.jsonl").exists() + assert (staging / "sessions" / "session-uuid-002.jsonl").exists() + + def test_no_live_sessions_dir_packages_all(self, mock_claude_project, tmp_path, monkeypatch): + """When hooks aren't configured (no live-sessions dir), all sessions are packaged.""" + from karma import packager + + # _get_live_session_uuids returns empty set when dir doesn't exist + monkeypatch.setattr(packager, "_get_live_session_uuids", lambda: set()) + + staging = tmp_path / "staging" + p = SessionPackager( + project_dir=mock_claude_project, + user_id="alice", + machine_id="test-mac", + ) + manifest = p.package(staging_dir=staging) + assert manifest.session_count == 2 + + +class TestGetLiveSessionUuids: + """Unit tests for the _get_live_session_uuids helper.""" + + def test_returns_empty_when_dir_missing(self, monkeypatch): + from karma.packager import _get_live_session_uuids + from karma import config + + # Point KARMA_BASE at a non-existent directory + monkeypatch.setattr(config, "KARMA_BASE", Path("/tmp/nonexistent-karma-test")) + # Re-import to pick up monkeypatched KARMA_BASE + import importlib + from karma import packager + importlib.reload(packager) + from karma.packager import _get_live_session_uuids as reloaded + + result = reloaded() + assert result == set() + + # Restore + importlib.reload(config) + importlib.reload(packager) + + def test_collects_live_uuids(self, tmp_path, monkeypatch): + from karma import packager, config + import importlib + + live_dir = tmp_path / "live-sessions" + live_dir.mkdir(parents=True) + + # LIVE session + (live_dir / "happy-slug.json").write_text(json.dumps({ + "session_id": "uuid-live-1", + "session_ids": ["uuid-live-1", "uuid-old-resumed"], + "state": "LIVE", + })) + # ENDED session (should NOT be collected) + (live_dir / "done-slug.json").write_text(json.dumps({ + "session_id": "uuid-ended", + "session_ids": ["uuid-ended"], + "state": "ENDED", + })) + # WAITING session + (live_dir / "waiting-slug.json").write_text(json.dumps({ + "session_id": "uuid-waiting", + "session_ids": ["uuid-waiting"], + "state": "WAITING", + })) + + monkeypatch.setattr(config, "KARMA_BASE", tmp_path) + importlib.reload(packager) + from karma.packager import _get_live_session_uuids as reloaded + + result = reloaded() + assert "uuid-live-1" in result + assert "uuid-old-resumed" in result + assert "uuid-waiting" in result + assert "uuid-ended" not in result + + importlib.reload(config) + importlib.reload(packager) + + def test_stale_live_session_not_excluded(self, tmp_path, monkeypatch): + """Sessions idle > 30 min are considered crashed — should be packaged.""" + from datetime import datetime, timezone, timedelta + from karma import packager, config + import importlib + + live_dir = tmp_path / "live-sessions" + live_dir.mkdir(parents=True) + + now = datetime.now(timezone.utc) + + # Recent LIVE session (5 min ago) — should be excluded + (live_dir / "recent.json").write_text(json.dumps({ + "session_id": "uuid-recent", + "session_ids": ["uuid-recent"], + "state": "LIVE", + "updated_at": (now - timedelta(minutes=5)).isoformat(), + })) + # Stale LIVE session (2 hours ago) — crashed, should NOT be excluded + (live_dir / "crashed.json").write_text(json.dumps({ + "session_id": "uuid-crashed", + "session_ids": ["uuid-crashed"], + "state": "LIVE", + "updated_at": (now - timedelta(hours=2)).isoformat(), + })) + # Stale WAITING session (45 min ago) — also crashed + (live_dir / "stuck.json").write_text(json.dumps({ + "session_id": "uuid-stuck", + "session_ids": ["uuid-stuck"], + "state": "WAITING", + "updated_at": (now - timedelta(minutes=45)).isoformat(), + })) + + monkeypatch.setattr(config, "KARMA_BASE", tmp_path) + importlib.reload(packager) + from karma.packager import _get_live_session_uuids as reloaded + + result = reloaded() + assert "uuid-recent" in result # recent → still excluded + assert "uuid-crashed" not in result # 2h stale → packaged + assert "uuid-stuck" not in result # 45m stale → packaged + + importlib.reload(config) + importlib.reload(packager) + + def test_skips_corrupt_json(self, tmp_path, monkeypatch): + from karma import packager, config + import importlib + + live_dir = tmp_path / "live-sessions" + live_dir.mkdir(parents=True) + + (live_dir / "corrupt.json").write_text("not valid json {{{{") + (live_dir / "good.json").write_text(json.dumps({ + "session_id": "uuid-good", + "session_ids": ["uuid-good"], + "state": "LIVE", + })) + + monkeypatch.setattr(config, "KARMA_BASE", tmp_path) + importlib.reload(packager) + from karma.packager import _get_live_session_uuids as reloaded + + result = reloaded() + assert "uuid-good" in result + + importlib.reload(config) + importlib.reload(packager) + + +class TestPerDeviceSessionLimit: + """Tests for per-device session limit override via metadata file.""" + + def test_metadata_overrides_team_limit(self, tmp_path, monkeypatch): + """Per-device session_limit in metadata should override team setting.""" + from karma import config, packager + import importlib + + # Create metadata file with per-device override + meta_dir = tmp_path / "metadata-folders" / "acme" / "members" + meta_dir.mkdir(parents=True) + (meta_dir / "jay.jay-mac.json").write_text(json.dumps({ + "member_tag": "jay.jay-mac", + "session_limit": "recent_10", + })) + + monkeypatch.setattr(config, "KARMA_BASE", tmp_path) + importlib.reload(packager) + from karma.packager import get_session_limit as reloaded + + # Team says "all" but device metadata says "recent_10" + result = reloaded("all", tmp_path, team_name="acme", member_tag="jay.jay-mac") + assert result == 10 + + importlib.reload(config) + importlib.reload(packager) + + def test_falls_back_to_team_limit(self, tmp_path, monkeypatch): + """Without metadata file, should use team setting.""" + from karma import config, packager + import importlib + + monkeypatch.setattr(config, "KARMA_BASE", tmp_path) + importlib.reload(packager) + from karma.packager import get_session_limit as reloaded + + result = reloaded("recent_100", tmp_path, team_name="acme", member_tag="jay.jay-mac") + assert result == 100 + + importlib.reload(config) + importlib.reload(packager) + + def test_metadata_all_uses_team_limit(self, tmp_path, monkeypatch): + """If metadata says 'all', use team setting (no override).""" + from karma import config, packager + import importlib + + meta_dir = tmp_path / "metadata-folders" / "acme" / "members" + meta_dir.mkdir(parents=True) + (meta_dir / "jay.jay-mac.json").write_text(json.dumps({ + "member_tag": "jay.jay-mac", + "session_limit": "all", + })) + + monkeypatch.setattr(config, "KARMA_BASE", tmp_path) + importlib.reload(packager) + from karma.packager import get_session_limit as reloaded + + # Metadata says "all", team says "recent_100" — metadata "all" is still valid + result = reloaded("recent_100", tmp_path, team_name="acme", member_tag="jay.jay-mac") + assert result is None # "all" → None (unlimited) + + importlib.reload(config) + importlib.reload(packager) + + def test_no_team_name_skips_metadata(self, tmp_path): + """Without team_name param, should not check metadata.""" + from karma.packager import get_session_limit + + result = get_session_limit("recent_10", tmp_path) + assert result == 10 diff --git a/cli/tests/test_plan_sharing.py b/cli/tests/test_plan_sharing.py new file mode 100644 index 00000000..3525ad38 --- /dev/null +++ b/cli/tests/test_plan_sharing.py @@ -0,0 +1,180 @@ +"""Tests for plan discovery, packaging, and plans-index.json generation.""" + +import json +from pathlib import Path + +import pytest + +from karma.packager import _discover_plan_references + + +class TestDiscoverPlanReferences: + """Test the JSONL-based plan slug discovery.""" + + def _write_jsonl(self, path: Path, lines: list[str]) -> None: + path.write_text("\n".join(lines) + "\n") + + def test_finds_plan_slug_in_jsonl(self, tmp_path): + """A JSONL mentioning plans/my-plan.md should be discovered.""" + jsonl = tmp_path / "session-001.jsonl" + self._write_jsonl(jsonl, [ + '{"type":"assistant","message":{"content":[{"type":"tool_use","name":"Read","input":{"file_path":"/home/user/.claude/plans/cool-plan.md"}}]}}', + ]) + + refs = _discover_plan_references([("session-001", jsonl)]) + assert "cool-plan" in refs + assert refs["cool-plan"]["session-001"] == "read" + + def test_detects_write_operation(self, tmp_path): + """Write tool should map to 'created' operation.""" + jsonl = tmp_path / "session-001.jsonl" + self._write_jsonl(jsonl, [ + '{"type":"assistant","message":{"content":[{"type":"tool_use","name":"Write","input":{"file_path":"/home/user/.claude/plans/new-plan.md"}}]}}', + ]) + + refs = _discover_plan_references([("session-001", jsonl)]) + assert refs["new-plan"]["session-001"] == "created" + + def test_detects_edit_operation(self, tmp_path): + """Edit/StrReplace tool should map to 'edited' operation.""" + jsonl = tmp_path / "session-001.jsonl" + self._write_jsonl(jsonl, [ + '{"type":"assistant","message":{"content":[{"type":"tool_use","name":"Edit","input":{"file_path":"/home/user/.claude/plans/my-plan.md"}}]}}', + ]) + + refs = _discover_plan_references([("session-001", jsonl)]) + assert refs["my-plan"]["session-001"] == "edited" + + def test_write_takes_priority_over_read(self, tmp_path): + """If a session both reads and writes a plan, 'created' wins.""" + jsonl = tmp_path / "session-001.jsonl" + self._write_jsonl(jsonl, [ + '{"type":"assistant","message":{"content":[{"type":"tool_use","name":"Read","input":{"file_path":"/home/user/.claude/plans/mixed-plan.md"}}]}}', + '{"type":"assistant","message":{"content":[{"type":"tool_use","name":"Write","input":{"file_path":"/home/user/.claude/plans/mixed-plan.md"}}]}}', + ]) + + refs = _discover_plan_references([("session-001", jsonl)]) + assert refs["mixed-plan"]["session-001"] == "created" + + def test_no_plans_returns_empty(self, tmp_path): + """JSONL without plan references should return empty dict.""" + jsonl = tmp_path / "session-001.jsonl" + self._write_jsonl(jsonl, [ + '{"type":"user","message":{"role":"user","content":"hello world"}}', + ]) + + refs = _discover_plan_references([("session-001", jsonl)]) + assert refs == {} + + def test_multiple_sessions_multiple_plans(self, tmp_path): + """Multiple sessions referencing different plans.""" + j1 = tmp_path / "s1.jsonl" + j2 = tmp_path / "s2.jsonl" + self._write_jsonl(j1, [ + '{"type":"assistant","message":{"content":[{"type":"tool_use","name":"Write","input":{"file_path":"/home/.claude/plans/plan-a.md"}}]}}', + ]) + self._write_jsonl(j2, [ + '{"type":"assistant","message":{"content":[{"type":"tool_use","name":"Read","input":{"file_path":"/home/.claude/plans/plan-a.md"}}]}}', + '{"type":"assistant","message":{"content":[{"type":"tool_use","name":"Write","input":{"file_path":"/home/.claude/plans/plan-b.md"}}]}}', + ]) + + refs = _discover_plan_references([("s1", j1), ("s2", j2)]) + assert refs["plan-a"]["s1"] == "created" + assert refs["plan-a"]["s2"] == "read" + assert refs["plan-b"]["s2"] == "created" + + def test_skips_missing_files(self, tmp_path): + """Non-existent JSONL paths should be skipped without error.""" + missing = tmp_path / "missing.jsonl" + refs = _discover_plan_references([("s1", missing)]) + assert refs == {} + + def test_ignores_non_plan_md_files(self, tmp_path): + """References to non-plan .md files should be ignored.""" + jsonl = tmp_path / "session-001.jsonl" + self._write_jsonl(jsonl, [ + '{"type":"assistant","message":{"content":[{"type":"tool_use","name":"Read","input":{"file_path":"/home/user/docs/README.md"}}]}}', + ]) + + refs = _discover_plan_references([("session-001", jsonl)]) + assert refs == {} + + +class TestPackagerPlanCopying: + """Integration test: packager copies plan files and writes plans-index.json.""" + + @pytest.fixture + def project_with_plans(self, tmp_path): + """Create a project with sessions that reference plans.""" + project_dir = tmp_path / ".claude" / "projects" / "-My-project" + project_dir.mkdir(parents=True) + + # Create a session that references a plan + s1 = project_dir / "session-001.jsonl" + s1.write_text( + '{"type":"assistant","message":{"content":[{"type":"tool_use","name":"Write","input":{"file_path":"' + + str(tmp_path / ".claude" / "plans" / "test-plan.md") + + '"}}]}}\n' + ) + + # Create the plan file + plans_dir = tmp_path / ".claude" / "plans" + plans_dir.mkdir(parents=True) + (plans_dir / "test-plan.md").write_text("# Test Plan\n\nThis is a test plan.\n") + + return project_dir + + def test_plans_copied_to_staging(self, project_with_plans, tmp_path): + """Plans referenced by sessions should be copied to staging.""" + from karma.packager import SessionPackager + + staging = tmp_path / "staging" + packager = SessionPackager( + project_dir=project_with_plans, + user_id="alice", + machine_id="test-mac", + ) + packager.package(staging_dir=staging) + + plans_dir = staging / "plans" + assert plans_dir.is_dir() + assert (plans_dir / "test-plan.md").is_file() + assert "Test Plan" in (plans_dir / "test-plan.md").read_text() + + def test_plans_index_json_created(self, project_with_plans, tmp_path): + """plans-index.json should map plan slugs to session UUIDs.""" + from karma.packager import SessionPackager + + staging = tmp_path / "staging" + packager = SessionPackager( + project_dir=project_with_plans, + user_id="alice", + machine_id="test-mac", + ) + packager.package(staging_dir=staging) + + index_path = staging / "plans-index.json" + assert index_path.is_file() + + data = json.loads(index_path.read_text()) + assert data["version"] == 1 + assert "test-plan" in data["plans"] + assert "session-001" in data["plans"]["test-plan"]["sessions"] + + def test_unreferenced_plans_not_copied(self, project_with_plans, tmp_path): + """Plans not referenced by any session should NOT be copied.""" + # Add an unreferenced plan + plans_dir = tmp_path / ".claude" / "plans" + (plans_dir / "other-plan.md").write_text("# Other\n") + + from karma.packager import SessionPackager + + staging = tmp_path / "staging" + packager = SessionPackager( + project_dir=project_with_plans, + user_id="alice", + machine_id="test-mac", + ) + packager.package(staging_dir=staging) + + assert not (staging / "plans" / "other-plan.md").exists() diff --git a/cli/tests/test_sync_config_identity.py b/cli/tests/test_sync_config_identity.py new file mode 100644 index 00000000..b6bafe06 --- /dev/null +++ b/cli/tests/test_sync_config_identity.py @@ -0,0 +1,64 @@ +"""Tests for machine_tag and member_tag derivation in SyncConfig.""" + +import pytest + + +def test_machine_tag_from_hostname(): + """machine_tag should be sanitized hostname: lowercase, alphanumeric + hyphens.""" + from karma.config import _sanitize_machine_tag + + assert _sanitize_machine_tag("Jayants-Mac-Mini") == "jayants-mac-mini" + assert _sanitize_machine_tag("MacBook Pro") == "macbook-pro" + assert _sanitize_machine_tag("DESKTOP_PC.local") == "desktop-pc-local" + assert _sanitize_machine_tag("my--weird---host") == "my-weird-host" # collapse multi-hyphens + assert _sanitize_machine_tag("") == "unknown" + + +def test_member_tag_computed(): + """member_tag should be user_id.machine_tag.""" + from karma.config import SyncConfig + + config = SyncConfig(user_id="jayant", machine_id="Jayants-Mac-Mini") + assert config.member_tag == "jayant.jayants-mac-mini" + + +def test_member_tag_with_custom_machine_tag(): + """If machine_tag is explicitly set, it overrides auto-derivation.""" + from karma.config import SyncConfig + + config = SyncConfig(user_id="jayant", machine_id="Jayants-Mac-Mini", machine_tag="mbp") + assert config.member_tag == "jayant.mbp" + + +def test_user_id_cannot_contain_dot(): + """user_id with dots should be rejected (dot is the member_tag separator).""" + from karma.config import SyncConfig + + with pytest.raises(ValueError, match="user_id"): + SyncConfig(user_id="jay.ant", machine_id="test") + + +def test_machine_tag_no_double_dash(): + """machine_tag must not contain -- (folder ID delimiter).""" + from karma.config import _sanitize_machine_tag + + result = _sanitize_machine_tag("my--host") + assert "--" not in result + + +def test_config_roundtrip_with_member_tag(tmp_path): + """Save and load preserves machine_tag and member_tag.""" + import json + + config_path = tmp_path / "sync-config.json" + data = { + "user_id": "jayant", + "machine_id": "Jayants-Mac-Mini", + "machine_tag": "mac-mini", + "syncthing": {"device_id": "ABC", "api_key": "key", "api_url": "http://localhost:8384"}, + } + config_path.write_text(json.dumps(data)) + + from karma.config import SyncConfig + config = SyncConfig(**json.loads(config_path.read_text())) + assert config.member_tag == "jayant.mac-mini" diff --git a/cli/tests/test_sync_diagnostics.py b/cli/tests/test_sync_diagnostics.py new file mode 100644 index 00000000..72336df0 --- /dev/null +++ b/cli/tests/test_sync_diagnostics.py @@ -0,0 +1,73 @@ +"""Diagnostic tests that verify the sync pipeline state. + +These tests use the REAL filesystem (not mocks) to verify the actual +state of the sync pipeline on this machine. They document what IS, +not what SHOULD BE, so they serve as regression tests after fixes. +""" + +import json +from pathlib import Path + +import pytest + + +PROJECTS_DIR = Path.home() / ".claude" / "projects" +KARMA_BASE = Path.home() / ".claude_karma" +MAIN_ENCODED = "-Users-jayantdevkar-Documents-GitHub-claude-karma" + + +@pytest.mark.skipif( + not PROJECTS_DIR.exists(), reason="No ~/.claude/projects/ on this machine" +) +class TestSyncDiagnostics: + def test_cli_worktree_dirs_exist(self): + """CLI worktree dirs should exist in ~/.claude/projects/.""" + from karma.worktree_discovery import find_worktree_dirs + + wt_dirs = find_worktree_dirs(MAIN_ENCODED, PROJECTS_DIR) + # We know there are at least 5 CLI worktree dirs + assert len(wt_dirs) >= 5, ( + f"Expected >=5 CLI worktree dirs, found {len(wt_dirs)}: " + f"{[d.name for d in wt_dirs]}" + ) + + def test_desktop_worktrees_now_discoverable(self): + """After fix: Desktop worktrees should be found by find_desktop_worktree_dirs.""" + from karma.worktree_discovery import find_desktop_worktree_dirs + + desktop_dirs = find_desktop_worktree_dirs( + project_name="claude-karma", + projects_dir=PROJECTS_DIR, + ) + # Should find focused-jepsen and lucid-villani + assert len(desktop_dirs) >= 2, ( + f"Expected >=2 Desktop worktree dirs, found {len(desktop_dirs)}" + ) + + def test_all_worktrees_discovered(self): + """After fix: find_all_worktree_dirs finds both CLI and Desktop worktrees.""" + from karma.worktree_discovery import find_all_worktree_dirs + + all_dirs = find_all_worktree_dirs( + MAIN_ENCODED, + "/Users/jayantdevkar/Documents/GitHub/claude-karma", + PROJECTS_DIR, + ) + # CLI worktrees (>=5) + Desktop worktrees (>=2) + assert len(all_dirs) >= 7, ( + f"Expected >=7 total worktree dirs, found {len(all_dirs)}" + ) + + def test_config_team_name_vs_watch_process(self): + """Config should have a team; watch may be running with wrong name.""" + config_path = KARMA_BASE / "sync-config.json" + if not config_path.exists(): + pytest.skip("No sync config") + + config = json.loads(config_path.read_text()) + teams = list(config.get("teams", {}).keys()) + assert len(teams) >= 1, "Should have at least one team" + # Document: the team is NOT called 'beta' + assert "beta" not in teams, ( + "Team 'beta' should not exist (was renamed)" + ) diff --git a/cli/tests/test_syncthing.py b/cli/tests/test_syncthing.py new file mode 100644 index 00000000..f83828c6 --- /dev/null +++ b/cli/tests/test_syncthing.py @@ -0,0 +1,125 @@ +"""Tests for Syncthing REST API wrapper.""" + +from unittest.mock import patch, MagicMock +import pytest + +from karma.syncthing import SyncthingClient + + +class TestSyncthingClient: + def test_init_defaults(self): + client = SyncthingClient() + assert client.api_url == "http://127.0.0.1:8384" + + def test_init_custom(self): + client = SyncthingClient(api_url="http://localhost:9999", api_key="abc") + assert client.api_url == "http://localhost:9999" + assert client.headers["X-API-Key"] == "abc" + + @patch("karma.syncthing.requests.get") + def test_is_running_true(self, mock_get): + mock_get.return_value = MagicMock(status_code=200, json=lambda: {"myID": "XXXX"}) + client = SyncthingClient() + assert client.is_running() is True + + @patch("karma.syncthing.requests.get") + def test_is_running_false_connection_error(self, mock_get): + import requests + mock_get.side_effect = requests.ConnectionError() + client = SyncthingClient() + assert client.is_running() is False + + @patch("karma.syncthing.requests.get") + def test_get_device_id(self, mock_get): + mock_get.return_value = MagicMock( + status_code=200, + json=lambda: {"myID": "AAAAAAA-BBBBBBB-CCCCCCC-DDDDDDD"} + ) + client = SyncthingClient(api_key="test") + device_id = client.get_device_id() + assert device_id == "AAAAAAA-BBBBBBB-CCCCCCC-DDDDDDD" + + @patch("karma.syncthing.requests.get") + def test_get_connections(self, mock_get): + mock_get.return_value = MagicMock( + status_code=200, + json=lambda: { + "connections": { + "DEVICE1": {"connected": True}, + "DEVICE2": {"connected": False}, + } + } + ) + client = SyncthingClient(api_key="test") + conns = client.get_connections() + assert "DEVICE1" in conns + assert conns["DEVICE1"]["connected"] is True + + @patch("karma.syncthing.requests.get") + @patch("karma.syncthing.requests.put") + def test_add_device(self, mock_put, mock_get): + mock_get.return_value = MagicMock( + status_code=200, + json=lambda: {"devices": [], "folders": []} + ) + mock_put.return_value = MagicMock(status_code=200) + + client = SyncthingClient(api_key="test") + client.add_device("NEWDEVICE-ID", "alice") + + mock_put.assert_called_once() + put_data = mock_put.call_args[1]["json"] + assert any(d["deviceID"] == "NEWDEVICE-ID" for d in put_data["devices"]) + + @patch("karma.syncthing.requests.get") + @patch("karma.syncthing.requests.put") + def test_add_folder(self, mock_put, mock_get): + mock_get.return_value = MagicMock( + status_code=200, + json=lambda: {"devices": [], "folders": []} + ) + mock_put.return_value = MagicMock(status_code=200) + + client = SyncthingClient(api_key="test") + client.add_folder("karma-out-alice", "/tmp/sync", ["DEVICE1"], folder_type="sendonly") + + mock_put.assert_called_once() + put_data = mock_put.call_args[1]["json"] + folder = put_data["folders"][0] + assert folder["id"] == "karma-out-alice" + assert folder["type"] == "sendonly" + + @patch("karma.syncthing.requests.get") + def test_get_pending_folders(self, mock_get): + pending = { + "karma-team-proj": { + "offeredBy": {"DEVICE-ABC": {"time": "2026-03-05T03:45:06Z"}} + } + } + mock_get.return_value = MagicMock(status_code=200, json=lambda: pending) + client = SyncthingClient(api_key="test") + result = client.get_pending_folders() + assert "karma-team-proj" in result + assert "DEVICE-ABC" in result["karma-team-proj"]["offeredBy"] + + @patch("karma.syncthing.requests.get") + def test_get_pending_folders_empty(self, mock_get): + mock_get.return_value = MagicMock(status_code=200, json=lambda: {}) + client = SyncthingClient(api_key="test") + assert client.get_pending_folders() == {} + + @patch("karma.syncthing.requests.get") + def test_find_folder_by_path(self, mock_get): + mock_get.return_value = MagicMock( + status_code=200, + json=lambda: { + "devices": [], + "folders": [ + {"id": "f1", "path": "/tmp/inbox/alice", "type": "receiveonly"}, + {"id": "f2", "path": "/tmp/outbox/me", "type": "sendonly"}, + ], + }, + ) + client = SyncthingClient(api_key="test") + assert client.find_folder_by_path("/tmp/inbox/alice")["id"] == "f1" + assert client.find_folder_by_path("/nonexistent") is None diff --git a/cli/tests/test_titles_io.py b/cli/tests/test_titles_io.py new file mode 100644 index 00000000..647b33fb --- /dev/null +++ b/cli/tests/test_titles_io.py @@ -0,0 +1,113 @@ +"""Tests for titles_io read/write/merge logic.""" + +import json +from pathlib import Path + +import pytest + +from karma.titles_io import read_titles, write_title, write_titles_bulk + + +class TestReadTitles: + def test_returns_empty_dict_when_file_missing(self, tmp_path): + result = read_titles(tmp_path / "titles.json") + assert result == {} + + def test_returns_empty_dict_when_file_corrupt(self, tmp_path): + path = tmp_path / "titles.json" + path.write_text("not json") + result = read_titles(path) + assert result == {} + + def test_reads_valid_titles(self, tmp_path): + path = tmp_path / "titles.json" + path.write_text(json.dumps({ + "version": 1, + "titles": { + "uuid-1": {"title": "Fix bug", "source": "git", "generated_at": "2026-03-08T12:00:00Z"} + } + })) + result = read_titles(path) + assert "uuid-1" in result + assert result["uuid-1"]["title"] == "Fix bug" + assert result["uuid-1"]["source"] == "git" + + def test_ignores_unknown_version(self, tmp_path): + path = tmp_path / "titles.json" + path.write_text(json.dumps({"version": 99, "titles": {"a": {"title": "x"}}})) + result = read_titles(path) + assert result == {} + + +class TestWriteTitle: + def test_creates_file_if_missing(self, tmp_path): + path = tmp_path / "titles.json" + write_title(path, "uuid-1", "Fix bug", "git") + + data = json.loads(path.read_text()) + assert data["version"] == 1 + assert data["titles"]["uuid-1"]["title"] == "Fix bug" + assert data["titles"]["uuid-1"]["source"] == "git" + assert "generated_at" in data["titles"]["uuid-1"] + assert "updated_at" in data + + def test_merges_with_existing(self, tmp_path): + path = tmp_path / "titles.json" + write_title(path, "uuid-1", "First title", "git") + write_title(path, "uuid-2", "Second title", "haiku") + + data = json.loads(path.read_text()) + assert len(data["titles"]) == 2 + assert data["titles"]["uuid-1"]["title"] == "First title" + assert data["titles"]["uuid-2"]["title"] == "Second title" + + def test_overwrites_existing_uuid(self, tmp_path): + path = tmp_path / "titles.json" + write_title(path, "uuid-1", "Old title", "fallback") + write_title(path, "uuid-1", "New title", "haiku") + + data = json.loads(path.read_text()) + assert data["titles"]["uuid-1"]["title"] == "New title" + assert data["titles"]["uuid-1"]["source"] == "haiku" + + def test_creates_parent_dirs(self, tmp_path): + path = tmp_path / "deep" / "nested" / "titles.json" + write_title(path, "uuid-1", "Test", "git") + assert path.exists() + + +class TestWriteTitlesBulk: + def test_writes_multiple_titles(self, tmp_path): + path = tmp_path / "titles.json" + entries = { + "uuid-1": {"title": "First", "source": "git"}, + "uuid-2": {"title": "Second", "source": "haiku"}, + } + write_titles_bulk(path, entries) + + data = json.loads(path.read_text()) + assert len(data["titles"]) == 2 + + def test_merges_with_existing_preserving_newer(self, tmp_path): + path = tmp_path / "titles.json" + # Write initial + write_title(path, "uuid-1", "Original", "haiku") + + # Bulk write that includes uuid-1 with different title + entries = { + "uuid-1": {"title": "Bulk override", "source": "git"}, + "uuid-2": {"title": "New entry", "source": "haiku"}, + } + write_titles_bulk(path, entries) + + data = json.loads(path.read_text()) + assert len(data["titles"]) == 2 + # Bulk should overwrite + assert data["titles"]["uuid-1"]["title"] == "Bulk override" + + def test_handles_empty_entries(self, tmp_path): + path = tmp_path / "titles.json" + write_titles_bulk(path, {}) + # Should create valid empty file + data = json.loads(path.read_text()) + assert data["titles"] == {} diff --git a/cli/tests/test_watcher.py b/cli/tests/test_watcher.py new file mode 100644 index 00000000..1b532b10 --- /dev/null +++ b/cli/tests/test_watcher.py @@ -0,0 +1,53 @@ +"""Tests for filesystem session watcher.""" + +import time +from pathlib import Path +from unittest.mock import MagicMock + +import pytest + +from karma.watcher import SessionWatcher + + +class TestSessionWatcher: + def test_init(self): + packager_fn = MagicMock() + watcher = SessionWatcher( + watch_dir=Path("/tmp/test"), + package_fn=packager_fn, + debounce_seconds=2, + ) + assert watcher.debounce_seconds == 2 + assert watcher.watch_dir == Path("/tmp/test") + + def test_should_process_jsonl(self): + watcher = SessionWatcher( + watch_dir=Path("/tmp"), + package_fn=MagicMock(), + ) + assert watcher._should_process("/tmp/abc123.jsonl") is True + assert watcher._should_process("/tmp/agent-xyz.jsonl") is False + assert watcher._should_process("/tmp/readme.txt") is False + assert watcher._should_process("/tmp/subdir/file.jsonl") is True + + def test_debounce_calls_package_fn_once(self): + packager_fn = MagicMock() + watcher = SessionWatcher( + watch_dir=Path("/tmp"), + package_fn=packager_fn, + debounce_seconds=0.1, + ) + # Simulate rapid file changes + watcher._schedule_package() + watcher._schedule_package() + watcher._schedule_package() + time.sleep(0.3) + # Should only call once despite 3 triggers + assert packager_fn.call_count == 1 + + def test_is_running_property(self): + watcher = SessionWatcher( + watch_dir=Path("/tmp"), + package_fn=MagicMock(), + ) + assert watcher.is_running is False diff --git a/cli/tests/test_worktree_discovery.py b/cli/tests/test_worktree_discovery.py new file mode 100644 index 00000000..d44b8d51 --- /dev/null +++ b/cli/tests/test_worktree_discovery.py @@ -0,0 +1,253 @@ +"""Tests for worktree discovery.""" + +from pathlib import Path +import pytest +from karma.worktree_discovery import ( + is_worktree_dir, + find_worktree_dirs, + find_desktop_worktree_dirs, + project_name_from_path, + find_all_worktree_dirs, +) + + +class TestIsWorktreeDir: + def test_cli_worktree_pattern(self): + assert is_worktree_dir( + "-Users-jay-GitHub-karma--claude-worktrees-feature-x" + ) is True + + def test_superpowers_worktree_pattern(self): + assert is_worktree_dir( + "-Users-jay-GitHub-karma--worktrees-feature-y" + ) is True + + def test_desktop_worktree_pattern(self): + assert is_worktree_dir( + "-Users-jay--claude-worktrees-karma-focused-jepsen" + ) is True + + def test_normal_project_not_worktree(self): + assert is_worktree_dir( + "-Users-jay-Documents-GitHub-claude-karma" + ) is False + + def test_empty_string(self): + assert is_worktree_dir("") is False + + +class TestFindWorktreeDirs: + def test_finds_cli_worktrees(self, tmp_path): + """CLI worktrees: {project}/.claude/worktrees/{name}""" + projects_dir = tmp_path / "projects" + main = projects_dir / "-Users-jay-GitHub-karma" + wt1 = projects_dir / "-Users-jay-GitHub-karma--claude-worktrees-feat-a" + wt2 = projects_dir / "-Users-jay-GitHub-karma--claude-worktrees-feat-b" + for d in (main, wt1, wt2): + d.mkdir(parents=True) + (d / "session.jsonl").write_text('{"type":"user"}\n') + result = find_worktree_dirs( + "-Users-jay-GitHub-karma", projects_dir + ) + assert len(result) == 2 + assert wt1 in result + assert wt2 in result + + def test_finds_superpowers_worktrees(self, tmp_path): + projects_dir = tmp_path / "projects" + main = projects_dir / "-Users-jay-GitHub-karma" + wt = projects_dir / "-Users-jay-GitHub-karma--worktrees-fix-bug" + for d in (main, wt): + d.mkdir(parents=True) + result = find_worktree_dirs( + "-Users-jay-GitHub-karma", projects_dir + ) + assert wt in result + + def test_ignores_unrelated_projects(self, tmp_path): + projects_dir = tmp_path / "projects" + main = projects_dir / "-Users-jay-GitHub-karma" + unrelated = projects_dir / "-Users-jay-GitHub-other--claude-worktrees-x" + for d in (main, unrelated): + d.mkdir(parents=True) + result = find_worktree_dirs( + "-Users-jay-GitHub-karma", projects_dir + ) + assert len(result) == 0 + + def test_returns_empty_when_no_worktrees(self, tmp_path): + projects_dir = tmp_path / "projects" + main = projects_dir / "-Users-jay-GitHub-karma" + main.mkdir(parents=True) + result = find_worktree_dirs( + "-Users-jay-GitHub-karma", projects_dir + ) + assert result == [] + + def test_returns_empty_when_projects_dir_missing(self, tmp_path): + result = find_worktree_dirs( + "-Users-jay-GitHub-karma", tmp_path / "nonexistent" + ) + assert result == [] + + +class TestProjectNameFromPath: + def test_unix_path(self): + assert project_name_from_path("/Users/jay/GitHub/claude-karma") == "claude-karma" + + def test_nested_path(self): + assert project_name_from_path("/Users/jay/Documents/GitHub/my-project") == "my-project" + + def test_trailing_slash(self): + assert project_name_from_path("/Users/jay/repo/") == "repo" + + def test_windows_path(self): + assert project_name_from_path("C:\\Users\\jay\\repos\\karma") == "karma" + + def test_single_segment(self): + assert project_name_from_path("myproject") == "myproject" + + +class TestFindDesktopWorktreeDirs: + def test_finds_desktop_worktrees_by_project_name(self, tmp_path): + projects_dir = tmp_path / "projects" + worktree_base = tmp_path / ".claude-worktrees" + + main = projects_dir / "-Users-jay-GitHub-claude-karma" + main.mkdir(parents=True) + + wt_actual = worktree_base / "claude-karma" / "focused-jepsen" + wt_actual.mkdir(parents=True) + + wt_encoded = projects_dir / "-Users-jay--claude-worktrees-claude-karma-focused-jepsen" + wt_encoded.mkdir(parents=True) + (wt_encoded / "session.jsonl").write_text('{"type":"user"}\n') + + result = find_desktop_worktree_dirs( + project_name="claude-karma", + projects_dir=projects_dir, + worktree_base=worktree_base, + ) + assert len(result) == 1 + assert result[0] == wt_encoded + + def test_finds_multiple_desktop_worktrees(self, tmp_path): + projects_dir = tmp_path / "projects" + worktree_base = tmp_path / ".claude-worktrees" + + (projects_dir / "-Users-jay-GitHub-karma").mkdir(parents=True) + + for name in ("focused-jepsen", "lucid-villani"): + (worktree_base / "karma" / name).mkdir(parents=True) + wt_enc = projects_dir / f"-Users-jay--claude-worktrees-karma-{name}" + wt_enc.mkdir(parents=True) + (wt_enc / "session.jsonl").write_text('{"type":"user"}\n') + + result = find_desktop_worktree_dirs( + project_name="karma", + projects_dir=projects_dir, + worktree_base=worktree_base, + ) + assert len(result) == 2 + + def test_ignores_other_project_worktrees(self, tmp_path): + projects_dir = tmp_path / "projects" + worktree_base = tmp_path / ".claude-worktrees" + + (projects_dir / "-Users-jay-GitHub-karma").mkdir(parents=True) + + (worktree_base / "hubdata" / "feat-x").mkdir(parents=True) + wt_enc = projects_dir / "-Users-jay--claude-worktrees-hubdata-feat-x" + wt_enc.mkdir(parents=True) + + result = find_desktop_worktree_dirs( + project_name="karma", + projects_dir=projects_dir, + worktree_base=worktree_base, + ) + assert len(result) == 0 + + def test_returns_empty_when_no_worktree_base(self, tmp_path): + projects_dir = tmp_path / "projects" + (projects_dir / "-Users-jay-GitHub-karma").mkdir(parents=True) + + result = find_desktop_worktree_dirs( + project_name="karma", + projects_dir=projects_dir, + worktree_base=tmp_path / "nonexistent", + ) + assert result == [] + + def test_returns_empty_when_project_has_no_desktop_worktrees(self, tmp_path): + projects_dir = tmp_path / "projects" + worktree_base = tmp_path / ".claude-worktrees" + worktree_base.mkdir() + + (projects_dir / "-Users-jay-GitHub-karma").mkdir(parents=True) + + result = find_desktop_worktree_dirs( + project_name="karma", + projects_dir=projects_dir, + worktree_base=worktree_base, + ) + assert result == [] + + def test_handles_cleaned_up_worktree_dirs(self, tmp_path): + projects_dir = tmp_path / "projects" + worktree_base = tmp_path / ".claude-worktrees" + + (projects_dir / "-Users-jay-GitHub-karma").mkdir(parents=True) + (worktree_base / "karma").mkdir(parents=True) + + wt_enc = projects_dir / "-Users-jay--claude-worktrees-karma-old-branch" + wt_enc.mkdir(parents=True) + (wt_enc / "session.jsonl").write_text('{"type":"user"}\n') + + result = find_desktop_worktree_dirs( + project_name="karma", + projects_dir=projects_dir, + worktree_base=worktree_base, + ) + assert len(result) == 1 + + +class TestFindAllWorktreeDirs: + def test_combines_cli_and_desktop_worktrees(self, tmp_path): + projects_dir = tmp_path / "projects" + worktree_base = tmp_path / ".claude-worktrees" + + main = projects_dir / "-Users-jay-GitHub-karma" + main.mkdir(parents=True) + + cli_wt = projects_dir / "-Users-jay-GitHub-karma--claude-worktrees-feat-x" + cli_wt.mkdir(parents=True) + + (worktree_base / "karma" / "focused-jepsen").mkdir(parents=True) + desktop_wt = projects_dir / "-Users-jay--claude-worktrees-karma-focused-jepsen" + desktop_wt.mkdir(parents=True) + + result = find_all_worktree_dirs( + main_encoded_name="-Users-jay-GitHub-karma", + project_path="/Users/jay/GitHub/karma", + projects_dir=projects_dir, + worktree_base=worktree_base, + ) + assert len(result) == 2 + assert cli_wt in result + assert desktop_wt in result + + def test_deduplicates_overlapping_results(self, tmp_path): + projects_dir = tmp_path / "projects" + + main = projects_dir / "-Users-jay-GitHub-karma" + main.mkdir(parents=True) + + wt = projects_dir / "-Users-jay-GitHub-karma--claude-worktrees-feat-x" + wt.mkdir(parents=True) + + result = find_all_worktree_dirs( + main_encoded_name="-Users-jay-GitHub-karma", + project_path="/Users/jay/GitHub/karma", + projects_dir=projects_dir, + ) + assert result.count(wt) == 1 diff --git a/docs/about/api-reference.md b/docs/about/api-reference.md index 051a00da..434e6554 100644 --- a/docs/about/api-reference.md +++ b/docs/about/api-reference.md @@ -2,147 +2,294 @@ Complete reference for the Claude Code Karma REST API. All endpoints are served from `http://localhost:8000`. -The API also provides interactive documentation via FastAPI's built-in Swagger UI at `/docs` and ReDoc at `/redoc`. - ---- +The API also provides interactive documentation: +- Swagger UI: `http://localhost:8000/docs` +- ReDoc: `http://localhost:8000/redoc` ## Projects +List and explore your projects. + | Method | Endpoint | Description | |--------|----------|-------------| -| GET | `/projects` | List all discovered projects with session counts and metadata | -| GET | `/projects/{encoded_name}` | Project details including all sessions, recent activity, and aggregate stats | - -**Path parameter:** `encoded_name` is the path-encoded project directory (e.g., `-Users-me-repo`). - ---- +| GET | `/projects` | List all projects with session counts and metadata | +| GET | `/projects/{encoded_name}` | Project details including all sessions and stats | +| GET | `/projects/{encoded_name}/chains` | Session chains (resumed/related sessions) | +| GET | `/projects/{encoded_name}/branches` | Session branches and history | +| GET | `/projects/{encoded_name}/analytics` | Project analytics (token usage, tools, costs) | +| GET | `/projects/{encoded_name}/memory` | Project memory and metadata | +| GET | `/projects/{encoded_name}/agents` | Agents spawned in this project | +| GET | `/projects/{encoded_name}/skills` | Skills invoked in this project | +| GET | `/projects/{encoded_name}/remote-sessions` | Remote sessions from team members | + +**Path parameter:** `encoded_name` is the path-encoded project directory (e.g., `-Users-me-repo`). Use the value from `/projects` endpoint. ## Sessions +Browse, analyze, and interact with sessions. + | Method | Endpoint | Description | |--------|----------|-------------| -| GET | `/sessions/{uuid}` | Session details: messages, metadata, token counts, duration, model | -| GET | `/sessions/{uuid}/timeline` | Chronological event timeline with messages, tool calls, and subagent events | -| GET | `/sessions/{uuid}/tools` | Tool usage breakdown: call counts, tool names, success/failure | -| GET | `/sessions/{uuid}/file-activity` | File operations performed during the session (read, write, edit, create) | -| GET | `/sessions/{uuid}/subagents` | Subagent (Task agent) activity: spawned agents, prompts, outcomes | +| GET | `/sessions/all` | List all sessions across all projects | +| GET | `/sessions/{uuid}` | Session details: messages, metadata, token counts | +| GET | `/sessions/{uuid}/timeline` | Chronological event timeline | +| GET | `/sessions/{uuid}/tools` | Tool usage breakdown | +| GET | `/sessions/{uuid}/file-activity` | Files changed during the session | +| GET | `/sessions/{uuid}/subagents` | Subagent activity | +| GET | `/sessions/{uuid}/plan` | Plan details (if this was a plan-mode session) | +| GET | `/sessions/{uuid}/chain` | Full session chain (resumed sessions) | +| GET | `/sessions/{uuid}/initial-prompt` | The original user prompt that started the session | +| POST | `/sessions/{uuid}/title` | Update session title manually | **Path parameter:** `uuid` is the session UUID matching the JSONL filename. ---- - ## Analytics +Analyze patterns and usage across projects and sessions. + | Method | Endpoint | Description | |--------|----------|-------------| -| GET | `/analytics/projects/{encoded_name}` | Project-level analytics: token trends, tool distribution, session frequency | +| GET | `/agents` | Agent statistics across all sessions | +| GET | `/skills` | Skill invocation data | +| GET | `/tools` | MCP tool discovery and usage | ---- +## Real-Time Monitoring -## Agents +Watch active sessions as they happen (requires hooks installed). | Method | Endpoint | Description | |--------|----------|-------------| -| GET | `/agents` | List all subagents across sessions with usage statistics | +| GET | `/live-sessions` | Current real-time session states | ---- +Returns session state with: session ID, project, status (STARTING, LIVE, WAITING, STOPPED, STALE, ENDED), timestamps, and latest activity. -## Skills +## Sync — System + +Initialize, detect, and manage your Syncthing sync setup. | Method | Endpoint | Description | |--------|----------|-------------| -| GET | `/skills` | Skill invocation data across all sessions | +| GET | `/sync/detect` | Check if Syncthing is installed and running | +| POST | `/sync/init` | Initialize sync — saves your user ID, detects Syncthing | +| GET | `/sync/status` | Current sync config, member tag, Syncthing status, and team summary | +| POST | `/sync/reconcile` | Manually trigger the 3-phase reconciliation cycle | +| POST | `/sync/reset` | Full teardown — deletes all sync data and optionally uninstalls Syncthing | + +**Example — `/sync/status` response:** ---- +```json +{ + "configured": true, + "user_id": "jayant", + "machine_tag": "macbook", + "member_tag": "jayant.macbook", + "syncthing": { "installed": true, "running": true, "device_id": "ABCDE-FGHIJ-..." }, + "teams": [{ "name": "backend-crew", "status": "active", "member_count": 3 }] +} +``` + +## Sync — Teams & Members -## Live Sessions +Create teams, manage members, and view team details. Only the team leader can modify membership. | Method | Endpoint | Description | |--------|----------|-------------| -| GET | `/live-sessions` | Current real-time session states (requires hooks to be installed) | +| POST | `/sync/teams` | Create a new team (caller becomes leader) | +| GET | `/sync/teams` | List all teams | +| GET | `/sync/teams/{name}` | Team detail — includes members, projects, and subscriptions | +| DELETE | `/sync/teams/{name}` | Dissolve a team (leader only) | +| POST | `/sync/teams/{name}/members` | Add member via pairing code (leader only) | +| DELETE | `/sync/teams/{name}/members/{tag}` | Remove a member (leader only) | +| GET | `/sync/teams/{name}/members` | List team members | +| GET | `/sync/teams/{name}/join-code` | Generate a join code for inviting teammates | +| GET | `/sync/teams/{name}/activity?limit=20` | Recent activity events for the team | +| GET | `/sync/teams/{name}/project-status` | Per-project subscription counts | +| GET | `/sync/teams/{name}/session-stats?days=30` | Per-member stats and subscription counts | + +**Path parameter:** `{tag}` is the member's `member_tag` (e.g., `jayant.macbook`). + +**Example — `/sync/teams/{name}` response:** -Returns session state objects with fields: session ID, project, status (STARTING, LIVE, WAITING, STOPPED, STALE, ENDED), timestamps, and latest activity. +```json +{ + "name": "backend-crew", + "leader_member_tag": "jayant.macbook", + "status": "active", + "created_at": "2026-03-18T10:00:00+00:00", + "members": [ + { "member_tag": "jayant.macbook", "device_id": "ABCDE-...", "user_id": "jayant", "machine_tag": "macbook", "status": "active" } + ], + "projects": [ + { "git_identity": "jayantdevkar/claude-karma", "folder_suffix": "jayantdevkar-claude-karma", "status": "shared" } + ], + "subscriptions": [ + { "member_tag": "jayant.macbook", "project": "jayantdevkar/claude-karma", "status": "accepted", "direction": "both" } + ] +} +``` ---- +## Sync — Projects & Subscriptions -## Plans +Share projects with teams and manage how you receive them. | Method | Endpoint | Description | |--------|----------|-------------| -| GET | `/plans` | Browse plan-mode sessions and their approval status | +| POST | `/sync/teams/{name}/projects` | Share a project with the team (leader only) | +| DELETE | `/sync/teams/{name}/projects/{git_identity}` | Remove a project from the team (leader only) | +| GET | `/sync/teams/{name}/projects` | List shared projects | +| POST | `/sync/subscriptions/{team}/{git_identity}/accept` | Accept a subscription (set direction) | +| POST | `/sync/subscriptions/{team}/{git_identity}/pause` | Pause a subscription | +| POST | `/sync/subscriptions/{team}/{git_identity}/resume` | Resume a paused subscription | +| POST | `/sync/subscriptions/{team}/{git_identity}/decline` | Decline a subscription | +| PATCH | `/sync/subscriptions/{team}/{git_identity}/direction` | Change sync direction | +| GET | `/sync/subscriptions` | List all your subscriptions across teams | + +**Subscription statuses:** `offered` → `accepted` / `declined`. Accepted subscriptions can be `paused` and `resumed`. + +**Sync directions:** `send` (share yours), `receive` (get theirs), `both` (default). ---- +## Sync — Pending Devices & Folders -## Tools +Manage incoming connection requests and folder offers from other Syncthing devices. | Method | Endpoint | Description | |--------|----------|-------------| -| GET | `/tools` | MCP tool discovery and usage data across sessions | +| GET | `/sync/pending-devices` | Devices requesting to connect | +| POST | `/sync/pending-devices/{device_id}/accept` | Accept a pending device into Syncthing | +| DELETE | `/sync/pending-devices/{device_id}` | Dismiss a pending device | +| GET | `/sync/pending` | Folders offered by peers | +| POST | `/sync/pending/accept/{folder_id}` | Accept a pending folder | +| POST | `/sync/pending/reject/{folder_id}` | Reject a pending folder | ---- +## Sync — Pairing -## Hooks +Generate and validate pairing codes for adding teammates. | Method | Endpoint | Description | |--------|----------|-------------| -| GET | `/hooks` | Hook configuration and event data | +| GET | `/sync/pairing/code` | Generate your permanent pairing code | +| POST | `/sync/pairing/validate` | Validate and decode a pairing code | +| GET | `/sync/devices` | List connected Syncthing devices | ---- +## Remote Sessions -## Plugins +Browse sessions synced from team members. | Method | Endpoint | Description | |--------|----------|-------------| -| GET | `/plugins` | Plugin listing with MCP tool details | +| GET | `/users` | List all remote users who synced sessions | +| GET | `/users/{user_id}/projects` | List projects synced by a remote user | +| GET | `/users/{user_id}/projects/{project}/sessions` | Sessions in a remote project | +| GET | `/users/{user_id}/projects/{project}/manifest` | Project manifest with metadata | ---- +**Path parameters:** +- `user_id` — Remote user ID (e.g., `alice`, `bob`) +- `project` — Project encoded name (e.g., `-Users-alice-work-acme-app`) -## History +**Example response — Remote user:** + +```json +{ + "user_id": "alice", + "project_count": 2, + "total_sessions": 12 +} +``` + +**Example response — Remote project:** + +```json +{ + "encoded_name": "-Users-alice-work-acme-app", + "session_count": 5, + "synced_at": "2026-03-03T14:30:00Z", + "machine_id": "alice-macbook-pro" +} +``` + +**Example response — Manifest:** + +```json +{ + "version": 1, + "user_id": "alice", + "machine_id": "alice-macbook-pro", + "project_path": "/Users/alice/work/acme-app", + "synced_at": "2026-03-03T14:30:00Z", + "session_count": 5, + "sync_backend": "syncthing", + "sessions": [ + { + "uuid": "abc-123-def", + "mtime": "2026-03-03T12:00:00Z", + "size_bytes": 45000 + } + ] +} +``` + +## Plans + +Browse plan-mode sessions. | Method | Endpoint | Description | |--------|----------|-------------| -| GET | `/history` | File history across all sessions — which files were touched, when, and by whom | +| GET | `/plans` | List plan-mode sessions | ---- +## Hooks -## Settings +Hook management and event logs. | Method | Endpoint | Description | |--------|----------|-------------| -| GET | `/settings` | User preferences and dashboard configuration | +| GET | `/hooks` | Hook configuration and event data | ---- +## History -## About Docs +File change tracking across all sessions. | Method | Endpoint | Description | |--------|----------|-------------| -| GET | `/docs/about` | About page documentation files (overview, features, architecture, etc.) | +| GET | `/history` | All file changes across sessions | ---- +## Settings -## Health +Dashboard configuration and preferences. | Method | Endpoint | Description | |--------|----------|-------------| -| GET | `/health` | Health check endpoint returning API status | +| GET | `/settings` | User preferences and configuration | ---- +## Plugins & Tools -## Common Response Patterns +Discover available plugins and MCP tools. + +| Method | Endpoint | Description | +|--------|----------|-------------| +| GET | `/plugins` | Plugin listing with MCP tool details | + +## Health + +System status check. + +| Method | Endpoint | Description | +|--------|----------|-------------| +| GET | `/health` | API health check | + +## Response Patterns ### Pagination -List endpoints that return large datasets support query parameters: +List endpoints support pagination: | Parameter | Type | Description | |-----------|------|-------------| -| `limit` | int | Maximum number of items to return | -| `offset` | int | Number of items to skip | +| `limit` | int | Maximum items to return (default: 50) | +| `offset` | int | Items to skip | ### Error Responses -Errors follow standard HTTP status codes with JSON bodies: +Errors follow HTTP status codes with JSON bodies: ```json { @@ -153,16 +300,39 @@ Errors follow standard HTTP status codes with JSON bodies: | Status | Meaning | |--------|---------| | 200 | Success | -| 404 | Resource not found (invalid UUID, unknown project) | +| 201 | Created (team, member, project) | +| 400 | Bad request (invalid name, missing config) | +| 403 | Forbidden (not the team leader) | +| 404 | Resource not found (invalid UUID, unknown project or team) | +| 409 | Conflict (invalid state transition — e.g., dissolving an already dissolved team) | | 422 | Validation error (malformed parameters) | | 500 | Internal server error (JSONL parse failure, filesystem error) | ### Path Encoding -Project endpoints use encoded path names. The encoding converts filesystem paths to URL-safe strings by replacing `/` with `-` and prefixing with `-`: +Project endpoints use encoded path names. The encoding converts filesystem paths to URL-safe strings: ``` -/Users/me/project --> -Users-me-project +/Users/me/project → -Users-me-project ``` Use the value from the `/projects` listing as the `encoded_name` parameter. + +### Input Validation + +Remote session endpoints validate input to prevent path traversal: +- `user_id` and `project` must be alphanumeric, dash, underscore, or dot only +- Values like `.` and `..` are rejected +- Invalid characters result in 400 Bad Request + +## Authentication + +The API does not require authentication. It's designed for local use on your machine. If you expose it to the network, add authentication using a reverse proxy or firewall. + +## Rate Limiting + +No rate limiting. The API is designed for local use. + +## CORS + +CORS is enabled for local development. The API accepts requests from `localhost:*` and other configured origins. diff --git a/docs/about/architecture.md b/docs/about/architecture.md index 27a6f10f..40c15db6 100644 --- a/docs/about/architecture.md +++ b/docs/about/architecture.md @@ -1,190 +1,265 @@ # Architecture -Technical overview of Claude Code Karma's system design, data flow, and key patterns. +Understanding how Claude Code Karma works internally. ---- - -## System Diagram +## Data flow ``` -~/.claude/projects/{encoded-path}/{uuid}.jsonl -~/.claude/projects/{encoded-path}/{uuid}/subagents/agent-*.jsonl -~/.claude/projects/{encoded-path}/{uuid}/tool-results/toolu_*.txt -~/.claude/todos/{uuid}-*.json -~/.claude_karma/live-sessions/{slug}.json - | - v -+---------------------------------------+ -| API (FastAPI, port 8000) | -| | -| models/ — JSONL parsing, Pydantic | -| routers/ — REST endpoints | -| utils.py — path encoding, helpers | -+---------------------------------------+ - | - v (JSON over HTTP) -+---------------------------------------+ -| Frontend (SvelteKit, port 5173) | -| | -| src/routes/ — pages & layouts | -| src/lib/ — components, stores | -| Svelte 5 runes, Tailwind CSS 4 | -+---------------------------------------+ - | - v - Browser (dashboard UI) - -+---------------------------------------+ -| Hooks (Claude Code integration) | -| | -| live_session_tracker.py | -| session_title_generator.py | -| plan_approval.py | -+---------------------------------------+ - | - v - ~/.claude_karma/live-sessions/*.json +Claude Code writes sessions to ~/.claude/projects/ + ↓ +API reads JSONL files from disk + ↓ +API parses with Pydantic models + ↓ +API serves REST endpoints (JSON) + ↓ +Frontend fetches from API + ↓ +Browser displays dashboard + +Hooks fire during Claude Code sessions + ↓ +Hooks write state to ~/.claude_karma/live-sessions/ + ↓ +API reads live session state + ↓ +Dashboard shows real-time status + +CLI watches for new sessions + ↓ +Sessions are packaged locally + ↓ +Syncthing syncs to team members + ↓ +Their dashboards show remote sessions ``` ---- - -## Three Layers - -### 1. Data Parsing Layer (API) - -The API reads Claude Code's local file system and parses raw JSONL into structured Pydantic models. It discovers projects by scanning `~/.claude/projects/`, reads session files lazily, and serves parsed data through REST endpoints. +## System layers -### 2. Visualization Layer (Frontend) +### Data Parsing (API) +The API scans `~/.claude/projects/` for session JSONL files. When you request a session, it reads the file, parses it with Pydantic models, and returns JSON. Messages are loaded on-demand (lazy loading) so the API doesn't run out of memory with huge sessions. -The SvelteKit frontend fetches data from the API and renders interactive dashboards. It uses Svelte 5 runes for reactivity, Tailwind CSS 4 for styling, Chart.js for visualizations, and bits-ui for accessible UI primitives. +### Visualization (Frontend) +The SvelteKit frontend runs in your browser. It fetches data from the API and renders interactive pages. Charts, tables, timelines — all powered by Chart.js and Tailwind CSS. Svelte 5 runes make the UI reactive. -### 3. Real-Time Tracking Layer (Hooks) +### Real-Time Tracking (Hooks) +Claude Code executes hook scripts when sessions start, end, receive input, or run tools. Our hooks write state to `~/.claude_karma/live-sessions/`. The API reads these state files to tell the dashboard what's currently happening. -Claude Code hook scripts fire during session events and write state to `~/.claude_karma/live-sessions/`. The API reads these state files to serve live session data. Hooks run in the Claude Code process and require no separate daemon. +### Session Sync (CLI + Syncthing) +The `karma` CLI watches your projects for new sessions, packages them into a standard format, and tells Syncthing to sync them. Syncthing handles all the network communication. ---- - -## Monorepo Structure +## Repository structure ``` claude-code-karma/ -├── api/ # FastAPI backend (Python) -│ ├── models/ # Pydantic models for JSONL parsing -│ ├── routers/ # FastAPI route handlers -│ ├── tests/ # pytest test suite -│ └── main.py # Application entry point -├── frontend/ # SvelteKit frontend (Svelte 5) -│ ├── src/routes/ # Page routes -│ ├── src/lib/ # Shared components, stores, utils -│ └── static/ # Static assets -├── captain-hook/ # Pydantic hook models library -│ ├── captain_hook/ # Library source -│ └── tests/ # Model tests -├── hooks/ # Production hook scripts +├── api/ # FastAPI backend +│ ├── main.py # Server entry point +│ ├── models/ # Pydantic models for JSONL parsing +│ ├── routers/ # API route handlers +│ ├── db/ # SQLite schema and queries +│ └── tests/ # Pytest tests +├── frontend/ # SvelteKit web app +│ ├── src/routes/ # Pages and routes +│ ├── src/lib/ # Shared components and utilities +│ └── package.json +├── cli/karma/ # Karma CLI package +│ ├── main.py # CLI entry point +│ ├── config.py # Configuration loading +│ ├── syncthing.py # Syncthing API client +│ ├── packager.py # Session packaging +│ ├── watcher.py # File watcher +│ └── tests/ +├── hooks/ # Production hook scripts │ ├── live_session_tracker.py │ ├── session_title_generator.py -│ └── plan_approval.py -└── docs/ # Documentation +│ └── plan_approval.py # Reference only (not production) +├── captain-hook/ # Pydantic models for hooks +│ ├── captain_hook/ # Library source +│ └── tests/ +└── docs/ # Documentation ``` ---- +This is a monorepo — all code is in one git repository. The API, frontend, CLI, and hooks are independent and can be developed/deployed separately. -## Claude Code Storage Locations +## Claude Code storage locations -Claude Code Karma reads from these locations on disk: +The API reads from these locations: | Data | Location | |------|----------| -| Session JSONL | `~/.claude/projects/{encoded-path}/{uuid}.jsonl` | +| Session files | `~/.claude/projects/{encoded-path}/{uuid}.jsonl` | | Subagent sessions | `~/.claude/projects/{encoded-path}/{uuid}/subagents/agent-*.jsonl` | -| Tool result outputs | `~/.claude/projects/{encoded-path}/{uuid}/tool-results/toolu_*.txt` | +| Tool outputs | `~/.claude/projects/{encoded-path}/{uuid}/tool-results/toolu_*.txt` | | Debug logs | `~/.claude/debug/{uuid}.txt` | -| Todo items | `~/.claude/todos/{uuid}-*.json` | | Live session state | `~/.claude_karma/live-sessions/{slug}.json` | +| Remote sessions | `~/.claude_karma/remote-sessions/{user-id}/{encoded-path}/` | +| Sync configuration | `~/.claude_karma/sync-config.json` | +| SQLite metadata | `~/.claude_karma/metadata.db` | ---- +## API model hierarchy -## Path Encoding +All data is structured with Pydantic models. Here's the hierarchy: -Claude Code encodes project paths for use as directory names. The encoding replaces the leading `/` with `-` and all subsequent `/` characters with `-`: +``` +Project +├── Session (one per JSONL file) +│ ├── Messages (UserMessage, AssistantMessage, FileHistorySnapshot, SummaryMessage) +│ ├── Subagents (spawned Task agents) +│ ├── ToolResults (large tool outputs) +│ └── TodoItems +└── Subagents (standalone agent-*.jsonl files) +``` -| Original Path | Encoded | -|---------------|---------| -| `/Users/me/repo` | `-Users-me-repo` | -| `/home/dev/my-project` | `-home-dev-my-project` | +All models are immutable (frozen) once created. This prevents bugs and makes caching safe. -The API decodes these paths when presenting project names to the frontend. +## API endpoints ---- +All endpoints are on the API server at `http://localhost:8000`. -## API Model Hierarchy +**Projects:** +- `GET /projects` — List all projects +- `GET /projects/{name}` — Project details with all sessions -``` -Project (entry point — one per encoded path) -├── Session ({uuid}.jsonl — one per conversation) -│ ├── Message -│ │ ├── UserMessage -│ │ ├── AssistantMessage -│ │ ├── FileHistorySnapshot -│ │ └── SummaryMessage (indicates compaction) -│ ├── Agent (subagents/ — spawned Task agents) -│ ├── ToolResult (tool-results/ — large tool outputs) -│ └── TodoItem (todos/ — task lists) -└── Agent (standalone: agent-{id}.jsonl) -``` +**Sessions:** +- `GET /sessions/{uuid}` — Session details +- `GET /sessions/{uuid}/timeline` — Event timeline +- `GET /sessions/{uuid}/tools` — Tool usage +- `GET /sessions/{uuid}/file-activity` — Files changed +- `GET /sessions/{uuid}/subagents` — Subagent activity -All models are Pydantic v2 with `ConfigDict(frozen=True)` for immutability. +**Analytics:** +- `GET /analytics/projects/{name}` — Project analytics +- `GET /agents` — Agent stats +- `GET /skills` — Skill usage +- `GET /tools` — MCP tool discovery ---- +**Real-Time:** +- `GET /live-sessions` — Current session state (requires hooks) -## Key Patterns +**Sync:** +- `GET /sync/status` — Sync config, member tag, Syncthing status +- `GET /sync/detect` — Check if Syncthing is installed/running +- `POST /sync/init` — Initialize sync setup +- `GET /sync/teams` — List all teams +- `GET /sync/teams/{name}` — Team detail with members, projects, subscriptions +- `POST /sync/teams` — Create a team +- `POST /sync/teams/{name}/members` — Add member via pairing code +- `POST /sync/teams/{name}/projects` — Share a project +- `POST /sync/subscriptions/{team}/{git_identity}/accept` — Accept a subscription +- `GET /sync/pending-devices` — Pending Syncthing device requests +- `GET /sync/pending` — Pending folder offers from peers +- `GET /users` — List remote users +- `GET /users/{user}/projects` — Remote projects -### Lazy Loading +**Misc:** +- `GET /history` — File history across sessions +- `GET /plans` — Plan browsing +- `GET /hooks` — Hook status -Session messages are not loaded into memory at discovery time. The `iter_messages()` generator reads and yields JSONL lines on demand, keeping memory usage constant regardless of session size. +See [API Reference](api-reference.md) for complete documentation. -### Frozen Pydantic Models +## Path encoding -All data models use `frozen=True` configuration. Once parsed, objects are immutable. This prevents accidental mutation and enables safe caching. +Claude Code stores projects in directories with paths like `/Users/me/my-project`. These are encoded as directory names: `-Users-me-my-project`. The encoding: +- Replaces the leading `/` with `-` +- Replaces all other `/` with `-` + +The API decodes these back to readable names in the dashboard. + +## Tech stack details + +### Backend +- **FastAPI** — Async web framework with automatic docs +- **Pydantic 2.x** — Data validation and serialization (all models frozen) +- **aiofiles** — Non-blocking file I/O +- **SQLite** — Session metadata and indexing +- **pytest** — Testing + +### Frontend +- **SvelteKit 2** — Full-stack framework +- **Svelte 5** — UI with runes for reactivity +- **Tailwind CSS 4** — Styling +- **Chart.js 4** — Data visualizations +- **bits-ui** — Accessible UI primitives +- **TypeScript** — Type safety + +### CLI +- **Click** — CLI framework +- **Pydantic** — Config models +- **requests** — HTTP client +- **watchdog** — File watching +- **requests-auth** — Syncthing API authentication + +## Key design patterns + +### Lazy Loading +Session messages aren't loaded all at once. The API uses a generator that reads JSONL lines on-demand. This keeps memory constant no matter how large the session is. + +### Frozen Models +All Pydantic models use `frozen=True`. Once created, they can't be changed. This prevents bugs and makes caching safe. ### Session Chains +When a session is resumed, the new session references the old one. The API detects these chains and links them so you can see the full history of a task. -Related sessions are detected via two mechanisms: -1. **leaf_uuid** — When a session is resumed, the new session references the original via `leaf_uuid` -2. **Slug matching** — Sessions within the same project that share temporal proximity are linked +### Async I/O +The API uses `aiofiles` for non-blocking file reads. This prevents parsing one session from blocking requests for other data. -### Compaction Detection +### SQLite Indexing +Session metadata is indexed in SQLite for fast queries. The API keeps the index in sync with the filesystem via background scanning. -When Claude Code compacts a session's context window, it inserts a `SummaryMessage` containing the compressed history. Claude Code Karma detects these messages and flags the session as compacted in the UI. +## Live session state -### Async File I/O +Hooks write state to `~/.claude_karma/live-sessions/{slug}.json`. Example: -The API uses `aiofiles` for non-blocking file reads. Since all data comes from the local filesystem (not a database), async I/O prevents session parsing from blocking the event loop. +```json +{ + "session_id": "abc-123-def", + "project": "/Users/me/repo", + "status": "LIVE", + "started_at": "2026-03-09T10:00:00Z", + "last_activity": "2026-03-09T10:15:00Z", + "message_count": 5, + "tool_calls": 3 +} +``` ---- +The API reads these files and merges them with historical data to show both current state and history. -## Tech Stack Details +## Session packaging for sync -### Backend +When sessions are synced via Syncthing, they're packaged into this structure: -| Component | Technology | Purpose | -|-----------|-----------|---------| -| Framework | FastAPI | Async web framework with OpenAPI docs | -| Validation | Pydantic 2.x | Data parsing and serialization | -| File I/O | aiofiles | Non-blocking filesystem access | -| Testing | pytest | Unit and integration tests | -| Linting | ruff | Python linting and formatting | -| Runtime | Python 3.9+ | Minimum supported version | +``` +~/.claude_karma/remote-sessions/ +├── alice/ +│ └── -Users-alice-work-acme-app/ +│ ├── manifest.json +│ └── sessions/ +│ ├── uuid1.jsonl +│ ├── uuid1/subagents/agent-*.jsonl +│ ├── uuid1/tool-results/toolu_*.txt +│ └── uuid2.jsonl +``` -### Frontend +The `manifest.json` contains metadata: + +```json +{ + "version": 1, + "user_id": "alice", + "machine_id": "alice-macbook", + "project_path": "/Users/alice/work/acme-app", + "synced_at": "2026-03-09T14:30:00Z", + "session_count": 5, + "sync_backend": "syncthing", + "sessions": [ + { + "uuid": "abc-123-def", + "mtime": "2026-03-09T14:20:00Z", + "size_bytes": 45000 + } + ] +} +``` -| Component | Technology | Purpose | -|-----------|-----------|---------| -| Framework | SvelteKit 2 | Full-stack Svelte framework | -| UI Library | Svelte 5 | Runes-based reactivity ($state, $derived, $effect) | -| Styling | Tailwind CSS 4 | Utility-first CSS | -| Charts | Chart.js 4 | Data visualizations | -| UI Primitives | bits-ui | Accessible component library | -| Icons | lucide-svelte | Icon set | -| Language | TypeScript | Type safety | -| Adapter | adapter-node | Node.js deployment | +The API reads this same format on every machine, regardless of how sessions arrived. diff --git a/docs/about/features.md b/docs/about/features.md index 645e9949..ec4b9a68 100644 --- a/docs/about/features.md +++ b/docs/about/features.md @@ -1,136 +1,113 @@ # Features -A comprehensive overview of everything Claude Code Karma provides. +## Core Features ---- +### Session Browsing +Browse all your Claude Code sessions across all projects. See which sessions ran, how long they took, how many tokens they used, and which model ran them. Search, filter by date or project, and sort by any column. -## Core Monitoring - -### Session Browser - -Browse all Claude Code sessions across every project. Filter by project, date range, session status, and more. Sessions display key metadata: duration, token count, message count, model used, and cost estimate. +### Conversation Playback +Read the full conversation from any session exactly as it happened. See user messages, Claude's responses, tool calls with inputs and outputs, and file modifications in chronological order. ### Timeline View +Chronological event log showing everything that happened in a session. See messages, tool calls (with success/failure status), subagent activity, and file operations step-by-step. -Chronological event stream for any session. Events include user messages, assistant responses, tool calls (with inputs and outputs), subagent spawns, file operations, and system events. Each event is timestamped and categorized. - -### Conversation Viewer - -Full conversation playback showing user and assistant messages in sequence. Supports markdown rendering, code blocks, and tool call visualization inline with the conversation flow. - -### Token Usage and Cost Tracking - -Per-session and per-project token breakdowns: input tokens, output tokens, and cache reads/writes. Cost estimates based on model pricing. Aggregate views across all sessions for trend analysis. - -### File Activity Tracking - -See every file that was read, written, created, or modified during a session. Includes operation type, file path, and timestamp. Useful for understanding the scope of changes made by Claude Code. - ---- +### Token and Cost Tracking +Every session shows token counts: input tokens, output tokens, cache reads, and cache writes. Costs are calculated based on the model. Track per-session costs and see trends across all sessions. -## Real-Time Monitoring +### File Activity +See every file that was touched during a session. Know which files were read, written, created, or modified. Useful for understanding what changed and where. -### Live Session Tracking +### Real-Time Session Monitoring +With hooks installed, watch active sessions as they happen. See current state (STARTING, LIVE, WAITING, STOPPED, ENDED). Know when Claude is actively processing versus waiting for your input. Sessions with no activity for 30 minutes are marked stale. -Real-time session state powered by Claude Code hooks. Sessions transition through a state machine: +### Automatic Session Titles +Sessions get descriptive titles when they end. Titles come from git commits made during the session, or Claude Haiku generates them if no commits were made. Makes sessions easy to find in the browser. -``` -STARTING --> LIVE --> WAITING --> STOPPED --> ENDED - \--> STALE (no heartbeat) -``` +### Subagent Tracking +See subagents (Task agents) spawned during sessions. Track which agents were created, their status, what tools they used, how long they ran, and their outcomes. Browse individual agent conversations. -The live sessions view shows all active sessions with their current state, project, duration, and latest activity. - -### Subagent Monitoring - -Track subagent (Task agent) spawning within sessions. See which agents were created, their prompts, duration, tool usage, and outcomes. Subagent conversations are individually browsable. - -### Session Title Auto-Generation - -Automatic title generation when sessions end. Titles are derived from git commits made during the session, or generated via Claude Haiku when no commits are available. Titles appear in the session browser for quick identification. - ---- - -## Analytics and Insights +## Analytics ### Project Analytics - -Per-project dashboards with charts covering: +Per-project dashboards showing charts of: - Session count and duration over time - Token usage trends -- Tool usage distribution +- Tool usage breakdown +- Cost estimates - Most active files -- Cost breakdown by model ### Global Analytics +Cross-project analytics comparing all projects by activity, cost, tool usage, and other metrics. -Cross-project analytics aggregating data across all projects. Compare projects by activity, cost, and usage patterns. - -### Agent Analytics +### Agent and Skill Analytics +See which subagents are spawned most often and how frequently Claude Code skills are invoked. -Track subagent usage patterns: which agent types are spawned most frequently, their success rates, average duration, and token consumption. - -### Skill Analytics - -Monitor Claude Code skill invocations across sessions. See which skills are used, how often, and in which projects. - -### Tool Usage Analytics - -Detailed breakdown of tool calls: Read, Write, Edit, Bash, Glob, Grep, and all MCP tools. Per-tool metrics include call count, success rate, and average execution time. - -### MCP Tools Tracking - -Discover and track MCP (Model Context Protocol) tool usage. See which MCP servers are configured, which tools are invoked, and their usage patterns across sessions. - ---- +### MCP Tool Tracking +Discover which MCP (Model Context Protocol) tools are configured and actually used, with usage patterns across sessions. ## Dashboard Pages -Claude Code Karma provides 12 dashboard pages: - -| Page | Description | -|------|-------------| -| **Projects** | All Claude Code projects with session counts and recent activity | -| **Sessions** | Session browser with filtering, sorting, and search | -| **Analytics** | Global analytics with charts and trends | -| **Plans** | Browse plan-mode sessions and approval workflows | -| **Skills** | Skill usage tracking across sessions | -| **Agents** | Subagent analytics and browsing | -| **Tools** | MCP tool discovery and usage tracking | -| **Hooks** | Hook configuration and event monitoring | -| **Plugins** | Plugin management and MCP tool details | -| **Settings** | User preferences and configuration | -| **Archived** | Archived and completed sessions | -| **About** | Documentation and guides (this section) | - ---- - -## Advanced Features - -### Session Chains - -Claude Code Karma detects and links related sessions. When a session is resumed or continued, the chain is preserved so you can follow the full history of a task across multiple sessions. Detection uses `leaf_uuid` references and project slug matching. +| Page | What you see | +|------|---| +| **Home** | Overview of recent activity and quick stats | +| **Projects** | All your projects with session counts and recent activity | +| **Sessions** | Global session browser with search and filters | +| **Analytics** | Cross-project charts and trends | +| **Agents** | Subagent statistics and details | +| **Skills** | Skill invocation data | +| **Tools** | MCP tool discovery and usage | +| **Plans** | Plan-mode sessions (read-only browsing) | +| **Team** | Remote sessions synced from team members | +| **Members** | Team members and their sync status | +| **Hooks** | Hook status and event log | +| **History** | All file changes across all sessions | +| **Settings** | Preferences and dashboard configuration | + +## Session Features + +### Session Chaining +Claude Code Karma detects when a session is resumed or related to another. These sessions are linked together so you can follow a task across multiple sessions and see the full chain. ### Compaction Detection +When Claude Code runs out of context, it compacts the session by summarizing old messages. Sessions with compaction are flagged so you know the older part of the conversation has been summarized. -Sessions that undergo context compaction (when conversation history is summarized to free up context window) are detected via the presence of `SummaryMessage` entries. Compacted sessions are flagged in the UI. +### Command Palette +Press Ctrl+K (Cmd+K on Mac) to open the command palette. Quickly jump to any project or session by name. -### Plan Approval Workflow +### URL State +All filters and view settings are saved in the URL. Share a link to give someone the exact view you're looking at with all filters applied. -Integration with Claude Code's plan mode. When Claude Code enters plan mode and requests approval, the `plan_approval.py` hook gates execution. Plans can be reviewed and approved through the dashboard. +## Cross-Team Session Sharing -### Command Palette +### Overview +Share sessions with teammates and freelancers using peer-to-peer sync. Everyone sees relevant sessions in a unified dashboard — no manual copying, no central server. -Press `Ctrl+K` (or `Cmd+K` on macOS) to open the command palette. Quickly navigate to any project, session, or page. Supports fuzzy search. +### How it Works +1. You create a team from the `/team` page +2. Your teammate generates a **join code** from their `/sync` page +3. You paste the code to add them — devices pair automatically via Syncthing +4. You share projects with the team — each member gets a **subscription** +5. Members accept subscriptions and choose their sync direction (send, receive, or both) +6. Sessions flow automatically — new sessions appear within seconds on LAN -### Keyboard Shortcuts +### Subscription Control +Every member controls what they receive. When a project is shared with a team, each member gets an **offered** subscription. They can: +- **Accept** it (and choose send-only, receive-only, or both) +- **Pause** it temporarily +- **Decline** it entirely -Navigate the dashboard efficiently with keyboard shortcuts. Available shortcuts are displayed in the command palette. +This means a team of 5 people sharing 10 projects can each have different preferences — no one-size-fits-all. -### URL State +### Read-Only Remote Sessions +Sessions from teammates show up in your dashboard as read-only. You can browse their conversations, see tool usage, and learn from their approach — but you can't modify their data. -All filters, sort orders, and view states are persisted in the URL query parameters. Copy and share a URL to give someone the exact same view — including active filters, selected project, and page state. +## Syncthing Backend -### SQLite Metadata Index +Uses Syncthing for automatic, encrypted, peer-to-peer file sync. Sessions are packaged locally and synced directly between machines. -An optional SQLite index caches session metadata for fast queries. Instead of re-parsing JSONL files on every request, the index provides instant lookups for session lists, project summaries, and analytics aggregations. +**Why Syncthing?** +- No servers to manage — your data never touches a third party +- Real-time sync — sessions appear within seconds on the same network +- Works anywhere — LAN, VPN, or across the internet via encrypted relays +- End-to-end encrypted — even relay servers can't read your data +- Simple setup — the `/sync` page walks you through everything diff --git a/docs/about/hooks-guide.md b/docs/about/hooks-guide.md index e4ecd909..d51c73ab 100644 --- a/docs/about/hooks-guide.md +++ b/docs/about/hooks-guide.md @@ -1,100 +1,82 @@ # Hooks Guide -How Claude Code hooks work and how Claude Code Karma uses them for live tracking, title generation, and plan approval. +How Claude Code hooks work and how to enable real-time session tracking. ---- +## What are Claude Code hooks? -## What Are Claude Code Hooks? +Hooks are scripts that Claude Code automatically executes when events happen during a session. They run in the Claude Code process and can either observe events or actively block them. -Hooks are scripts that Claude Code executes automatically when specific events occur during a session. They run synchronously in the Claude Code process and can either observe events passively or actively block them (returning `"deny"` to reject an action). +You register hooks in Claude Code's `settings.json`. They can be written in any language. Claude Code Karma's hooks are Python scripts. -Hooks are registered in Claude Code's `settings.json` and can be written in any language. Claude Code Karma's hooks are written in Python. +## The 10 hook types ---- +Claude Code defines 10 hook event types. Here are the main ones: -## The 10 Hook Types +| Hook | Fires When | Can Block? | +|------|-----------|------------| +| **SessionStart** | Session begins | No | +| **SessionEnd** | Session ends | No | +| **UserPromptSubmit** | User submits a message | Yes | +| **PostToolUse** | Tool call completes | No | +| **PreToolUse** | Before tool executes | Yes | +| **Stop** | Main agent stops | No | +| **SubagentStart** | Task agent spawns | No | +| **SubagentStop** | Task agent stops | No | +| **PreCompact** | Before context compaction | No | +| **PermissionRequest** | Permission dialog appears | Yes | -Claude Code defines 10 hook event types. The captain-hook library provides Pydantic models for all of them. +Blocking hooks can return a response that prevents the action. Non-blocking hooks can only observe. -| Hook | Fires When | Can Block? | Common Use | -|------|-----------|------------|------------| -| **PreToolUse** | Before a tool is executed | Yes | Validate or deny tool calls | -| **PostToolUse** | After a tool completes | No | Log tool results, track file changes | -| **UserPromptSubmit** | User submits a message | Yes | Filter prompts, add context | -| **SessionStart** | Session begins | No | Initialize tracking state | -| **SessionEnd** | Session ends | No | Generate titles, finalize state | -| **Stop** | Main agent stops | No | Record completion status | -| **SubagentStop** | A subagent (Task) stops | No | Track subagent outcomes | -| **PreCompact** | Before context compaction | No | Capture pre-compaction state | -| **PermissionRequest** | Permission dialog appears | Yes | Auto-approve or gate actions | -| **Notification** | System notification | No | Forward or log notifications | +## Production Hooks in Claude Code Karma -**Blocking hooks** (PreToolUse, UserPromptSubmit, PermissionRequest) can return a response that prevents the action from proceeding. Non-blocking hooks can only observe. - ---- - -## Claude Code Karma's Production Hooks - -Claude Code Karma ships three hook scripts in the `hooks/` directory. +Claude Code Karma ships two production hooks: ### 1. live_session_tracker.py -**Purpose:** Tracks session state in real time across 8 hook events. +**Purpose:** Track session state in real time. **Events handled:** SessionStart, SessionEnd, Stop, SubagentStart, SubagentStop, PostToolUse, UserPromptSubmit, Notification -**State machine:** - -``` -STARTING ──> LIVE ──> WAITING ──> STOPPED ──> ENDED - \ | - \──> STALE / - (no heartbeat) / - \──────────────/ -``` +**What it does:** +- Tracks the session state machine (STARTING → LIVE → WAITING → STOPPED → ENDED) +- Writes state to `~/.claude_karma/live-sessions/{slug}.json` +- API reads this to show live session status in the dashboard +**State machine:** - **STARTING** — Session has begun, no user message yet - **LIVE** — Actively processing (tool calls, responses) - **WAITING** — Waiting for user input - **STOPPED** — Main agent has stopped -- **STALE** — No heartbeat received within timeout -- **ENDED** — Session has formally ended - -State is written to `~/.claude_karma/live-sessions/{slug}.json`. The API reads these files to serve the `/live-sessions` endpoint. +- **STALE** — No heartbeat for 30+ minutes +- **ENDED** — Session formally ended ### 2. session_title_generator.py -**Purpose:** Automatically generates a descriptive title when a session ends. +**Purpose:** Generate descriptive titles for sessions. **Event handled:** SessionEnd -**Title generation strategy:** -1. Check for git commits made during the session -2. If commits found, derive the title from commit messages -3. If no commits, call Claude Haiku to generate a title from the session summary - -Titles are stored in session metadata and displayed in the session browser. +**How it works:** +1. Checks for git commits made during the session +2. If commits exist, derives the title from commit messages +3. If no commits, calls Claude Haiku to generate a title from the session summary -### 3. plan_approval.py +Titles appear in the session browser and dashboard so you can quickly find sessions. -**Purpose:** Gates plan execution by intercepting ExitPlanMode permission requests. +### 3. plan_approval.py (Reference Only) -**Event handled:** PermissionRequest (specifically `ExitPlanMode`) +This script is kept as a reference implementation but is **not production-ready**. It requires API endpoints for plan approval that haven't been implemented yet. Do not register this hook — it will block all ExitPlanMode calls. We'll document it when the approval feature is built. -When Claude Code enters plan mode and produces a plan, it fires a PermissionRequest before proceeding. This hook intercepts that request and can approve or deny execution based on configured rules or user preferences. +## Captain-Hook Library ---- +The `captain-hook/` directory contains a standalone Python library with type-safe Pydantic models for all 10 hook types. -## captain-hook Library - -The `captain-hook/` directory contains a standalone Python library providing type-safe Pydantic models for all 10 hook types. - -### Usage +**Use it to parse hook events:** ```python -from captain_hook import parse_hook_event, PreToolUseHook, SessionStartHook +from captain_hook import parse_hook_event, PreToolUseHook -# Parse any hook event from JSON +# Parse any hook event hook = parse_hook_event(json_data) # Type-narrowed access @@ -103,31 +85,22 @@ if isinstance(hook, PreToolUseHook): tool_input = hook.tool_input ``` -### Model Structure - -Each hook model inherits from a base and includes: -- `session_id` — UUID of the active session -- `project_path` — Encoded project path -- Hook-specific fields (tool name, message content, etc.) - -The library validates all fields at parse time and raises clear errors for malformed hook data. - ---- +See the captain-hook README for the full API reference. ## Installing Hooks -### 1. Copy or Symlink Scripts +### Step 1: Symlink the Hook Scripts ```bash -# Symlink (recommended — stays in sync with repo) ln -s /path/to/claude-karma/hooks/live_session_tracker.py ~/.claude/hooks/ ln -s /path/to/claude-karma/hooks/session_title_generator.py ~/.claude/hooks/ -ln -s /path/to/claude-karma/hooks/plan_approval.py ~/.claude/hooks/ ``` -### 2. Register in settings.json +(Symlinks are recommended — they stay in sync with the repo.) + +### Step 2: Register in settings.json -Add hook registrations to your Claude Code settings file (`~/.claude/settings.json`): +Add hook registrations to `~/.claude/settings.json`. The hooks need to be registered for specific events: ```json { @@ -165,7 +138,7 @@ Add hook registrations to your Claude Code settings file (`~/.claude/settings.js ] } ], - "Notification": [ + "Stop": [ { "hooks": [ { @@ -176,7 +149,7 @@ Add hook registrations to your Claude Code settings file (`~/.claude/settings.js ] } ], - "Stop": [ + "SubagentStart": [ { "hooks": [ { @@ -187,7 +160,7 @@ Add hook registrations to your Claude Code settings file (`~/.claude/settings.js ] } ], - "SubagentStart": [ + "SubagentStop": [ { "hooks": [ { @@ -198,7 +171,7 @@ Add hook registrations to your Claude Code settings file (`~/.claude/settings.js ] } ], - "SubagentStop": [ + "Notification": [ { "hooks": [ { @@ -228,31 +201,18 @@ Add hook registrations to your Claude Code settings file (`~/.claude/settings.js } ] } - ], - "PermissionRequest": [ - { - "hooks": [ - { - "type": "command", - "command": "python3 ~/.claude/hooks/plan_approval.py", - "timeout": 10000 - } - ] - } ] } } ``` -The `timeout` value is in milliseconds. If a hook exceeds its timeout, Claude Code kills the process and continues without it. - ---- +The `timeout` value is in milliseconds. If a hook exceeds its timeout, Claude Code kills it and continues. ## Writing Custom Hooks Hooks receive event data as JSON on stdin and can optionally write a JSON response to stdout. -**Basic structure (Python):** +**Basic structure:** ```python import sys @@ -272,10 +232,11 @@ if __name__ == "__main__": main() ``` -**With captain-hook:** +**Using captain-hook for type safety:** ```python import sys +import json from captain_hook import parse_hook_event, PreToolUseHook def main(): @@ -289,4 +250,8 @@ if __name__ == "__main__": main() ``` -See the captain-hook README in the `captain-hook/` directory for the full API reference. +## Verification + +After installation, verify hooks are working by checking the **Hooks** page in the dashboard. You should see hook execution logs and recent events. + +Also check the live sessions page — if hooks are working, you should see real-time session state for active sessions. diff --git a/docs/about/overview.md b/docs/about/overview.md index 31c31769..e385f4c6 100644 --- a/docs/about/overview.md +++ b/docs/about/overview.md @@ -1,67 +1,70 @@ -# Claude Code Karma — Overview +# Claude Code Karma -## What is Claude Code Karma? +Claude Code Karma is a dashboard for understanding what Claude Code has done on your machine. It reads the session files Claude Code stores locally and shows you everything in a web dashboard. -Claude Code Karma is a full-stack monitoring and analytics dashboard for [Claude Code](https://docs.anthropic.com/en/docs/claude-code) sessions. It parses Claude Code's local storage (`~/.claude/`), extracts structured data from raw JSONL session files, and presents it through an interactive web dashboard. +## The problem -## The Problem +Claude Code creates JSONL files with all your session data in `~/.claude/projects/`. These files contain everything — conversations, tool calls, files modified, tokens used — but Claude Code itself doesn't show them to you. -Claude Code stores all session data locally as raw JSONL files scattered across `~/.claude/projects/`. These files contain rich information — conversations, tool calls, token usage, subagent activity, file operations — but are effectively invisible to the user. There is no built-in way to: +Karma makes this visible. You can browse sessions, see token usage, watch tools being called, replay conversations, and more. If you work in a team, you can also share sessions with freelancers across machines. -- Browse past sessions across projects -- Track token usage and costs over time -- Monitor live sessions in real time -- Analyze tool usage patterns or agent behavior -- Replay conversations or inspect timelines +## What you can do + +**Browse your work:** +- See all sessions across all projects +- Search and filter by project, date, or keywords +- Understand how long sessions took and how many tokens they used -Claude Code Karma makes all of this accessible through a single dashboard. +**Analyze patterns:** +- Track token usage and costs over time +- See which tools Claude Code uses most +- Find which files change most frequently -## Who Is It For? +**Watch sessions happen:** +- With hooks installed, see live session state (waiting, processing, done) +- Get automatic titles for sessions based on git commits or AI generation -- **Claude Code power users** who run dozens of sessions daily and want visibility into their usage -- **Developers** who want to understand how Claude Code interacts with their codebase -- **Teams** evaluating Claude Code adoption and needing usage analytics -- **Hook developers** building on Claude Code's extensibility layer +**Share with your team:** +- Add freelancers to teams +- They sync their sessions via Syncthing (peer-to-peer) +- You see everything in one unified dashboard +- Leave feedback on work that syncs back to them -## Key Capabilities +## Who is this for -- **Session Browser** — Browse, search, and filter all sessions across every project -- **Timeline View** — Chronological event stream with messages, tool calls, and subagent activity -- **Conversation Playback** — Full conversation viewer with user and assistant messages -- **Token and Cost Tracking** — Per-session and aggregate token usage with cost estimates -- **File Activity Tracking** — See which files were read, written, or modified -- **Live Session Monitoring** — Real-time session state via Claude Code hooks -- **Analytics Dashboards** — Project-level and global analytics with charts -- **Agent and Skill Analytics** — Track subagent spawning patterns and skill usage -- **MCP Tool Tracking** — Monitor MCP tool discovery and invocation -- **Session Chains** — Detect and link related or resumed sessions -- **Command Palette** — Quick navigation with Ctrl+K +- Power users who run Claude Code every day and want visibility into what happened +- Teams evaluating Claude Code and needing usage metrics +- Project owners managing freelancers on multiple machines +- Anyone building custom Claude Code hooks -## Tech Stack +## Tech stack -| Layer | Technology | -|-------|-----------| -| Backend | Python 3.9+, FastAPI, Pydantic 2.x, aiofiles | -| Frontend | SvelteKit 2, Svelte 5 (runes), Tailwind CSS 4, Chart.js 4, bits-ui | -| Hooks | captain-hook (Pydantic models for Claude Code's 10 hook types) | -| Tooling | ruff (Python), eslint/prettier (JS), pytest, vitest | +| Component | Tech | +|-----------|------| +| Backend | Python 3.9+, FastAPI, Pydantic | +| Frontend | SvelteKit, Svelte 5, Tailwind CSS, Chart.js | +| CLI | Python with Click | +| Hooks | Python scripts | +| Sync | Syncthing (peer-to-peer file sync) | -## Architecture +## Architecture at a glance -Claude Code Karma is a monorepo with all components in a single repository: +This is one repository with four parts: -| Directory | Description | Port | -|-----------|-------------|------| -| `api/` | FastAPI backend — parses JSONL, serves REST endpoints | 8000 | -| `frontend/` | SvelteKit dashboard — visualizes session data | 5173 | -| `captain-hook/` | Pydantic library — type-safe models for Claude Code hooks | — | +| Part | Purpose | Port | +|------|---------|------| +| `api/` | Reads JSONL files and serves REST API | 8000 | +| `frontend/` | Web dashboard | 5173 | +| `cli/karma/` | Command-line tool for managing sync | — | +| `hooks/` | Scripts for real-time tracking | — | -A `hooks/` directory contains production hook scripts that integrate with Claude Code for live tracking and automation. +Claude Code writes sessions to `~/.claude/projects/`. The API reads them and serves JSON. The frontend fetches from the API and displays everything. If you enable sync, the CLI watches for new sessions and packages them for Syncthing. -## Learn More +## Quick navigation -- [Quick Start](quick-start.md) — Get up and running in 5 minutes -- [Features](features.md) — Full feature showcase -- [Architecture](architecture.md) — Technical deep dive -- [Hooks Guide](hooks-guide.md) — Claude Code hooks and how Claude Code Karma uses them -- [API Reference](api-reference.md) — Complete endpoint documentation +- **[Quick Start](quick-start.md)** — Get running in 5 minutes +- **[Features](features.md)** — See all the capabilities +- **[Architecture](architecture.md)** — How it works internally +- **[Hooks Guide](hooks-guide.md)** — Enable real-time tracking +- **[Syncing Sessions](syncing-sessions.md)** — Share sessions with your team +- **[API Reference](api-reference.md)** — For developers diff --git a/docs/about/quick-start.md b/docs/about/quick-start.md index 2dcd4c17..328d12c1 100644 --- a/docs/about/quick-start.md +++ b/docs/about/quick-start.md @@ -1,19 +1,16 @@ # Quick Start -Get Claude Code Karma running in under 5 minutes. +Get Claude Code Karma running in 5 minutes. ## Prerequisites -| Requirement | Minimum Version | -|-------------|----------------| -| Python | 3.9+ | -| Node.js | 18+ | -| npm | 7+ | -| Git | 2.x | +- Python 3.9+ +- Node.js 18+ +- npm 7+ +- Git 2.x +- Claude Code installed with existing sessions in `~/.claude/projects/` -You must also have Claude Code installed and have existing sessions in `~/.claude/projects/`. - -## 1. Clone the Repository +## 1. Clone ```bash git clone https://github.com/JayantDevkar/claude-code-karma.git @@ -22,15 +19,17 @@ cd claude-code-karma ## 2. Start the API +In terminal 1: + ```bash cd api pip install -e ".[dev]" && pip install -r requirements.txt uvicorn main:app --reload --port 8000 ``` -The API server starts at `http://localhost:8000`. It automatically discovers and parses session files from `~/.claude/projects/`. +The API server starts at `http://localhost:8000`. It automatically discovers sessions from `~/.claude/projects/`. -Verify the API is running: +Verify it's running: ```bash curl http://localhost:8000/health @@ -38,7 +37,7 @@ curl http://localhost:8000/health ## 3. Start the Frontend -In a separate terminal: +In terminal 2: ```bash cd frontend @@ -46,25 +45,61 @@ npm install npm run dev ``` -The dashboard opens at `http://localhost:5173`. +The dashboard opens at `http://localhost:5173`. You should see your Claude Code projects listed with their sessions. + +That's it. You're done. + +## Optional: Enable Real-Time Session Tracking -## 4. Verify +To watch active sessions as they happen, you need to install hooks. + +```bash +# Copy or symlink the hook scripts +ln -s /path/to/claude-karma/hooks/live_session_tracker.py ~/.claude/hooks/ +ln -s /path/to/claude-karma/hooks/session_title_generator.py ~/.claude/hooks/ + +# Register them in ~/.claude/settings.json +# See Hooks Guide for the full settings.json structure +``` -Open [http://localhost:5173](http://localhost:5173) in your browser. You should see your Claude Code projects listed with their sessions. +This enables: +- Real-time session state (STARTING, LIVE, WAITING, STOPPED, ENDED) +- Automatic session titles based on git commits or AI generation -## Optional: Enable Live Session Tracking +See [Hooks Guide](hooks-guide.md) for detailed setup. -Claude Code Karma includes hook scripts that track sessions in real time. To enable live tracking: +## Optional: Enable Session Sync with Syncthing -1. Copy or symlink the hook scripts from `hooks/` to `~/.claude/hooks/` -2. Register them in your Claude Code `settings.json` +Share sessions with your team — no cloud, no accounts, fully peer-to-peer. + +```bash +# 1. Install Syncthing on each machine +# macOS: brew install syncthing && brew services start syncthing +# Linux: sudo apt install syncthing && systemctl --user enable --now syncthing + +# 2. Open the Karma dashboard and go to /sync +# The setup wizard walks you through picking your user ID +# and detecting Syncthing automatically. + +# 3. Create a team on the /team page +# Click "Create Team" and give it a name like "alpha" + +# 4. Add teammates via join codes +# Your teammate generates a join code from their /sync page. +# You paste it on the Team page to add them. + +# 5. Share projects +# Pick which projects to share with the team. +# Each member gets a subscription they can accept, pause, or decline. +``` -Live tracking provides real-time session state (STARTING, LIVE, WAITING, STOPPED, ENDED) and automatic session title generation. +Sessions are packaged and synced automatically. Teammates' sessions appear in your dashboard within seconds on LAN, or a few minutes over the internet. -See the [Hooks Guide](hooks-guide.md) for detailed setup instructions. +See [Syncing Sessions](syncing-sessions.md) for the full walkthrough. ## Next Steps -- [Features](features.md) — Explore the full feature set -- [Architecture](architecture.md) — Understand how Claude Code Karma works -- [API Reference](api-reference.md) — Browse all API endpoints +- [Features](features.md) — See what you can do +- [Architecture](architecture.md) — Understand how it works +- [Hooks Guide](hooks-guide.md) — Set up real-time tracking +- [Syncing Sessions](syncing-sessions.md) — Share with your team diff --git a/docs/about/syncing-sessions.md b/docs/about/syncing-sessions.md new file mode 100644 index 00000000..7edb7703 --- /dev/null +++ b/docs/about/syncing-sessions.md @@ -0,0 +1,268 @@ +# Syncing Sessions + +Share Claude Code sessions across your machines and with your team — no cloud, no accounts, no servers. + +## The problem + +Claude Code Karma reads from `~/.claude/` on your local machine. That's great for solo use, but the moment you have two machines or a teammate, each person's sessions are invisible to everyone else. + +You lose context. You duplicate work. You can't learn from how your teammates use Claude. + +## The solution: peer-to-peer sync + +We use **Syncthing** — an open-source, encrypted, peer-to-peer file sync tool. There's no central server. Sessions travel directly from one machine to another. Your data stays entirely under your control. + +Think of it like AirDrop for Claude sessions, but it works across the internet too. + +## Four concepts you need to know + +Everything in Karma sync is built on four ideas: **you**, **teams**, **projects**, and **subscriptions**. + +### 1. You (the Member) + +Every person + machine combination is a unique **member**. Your identity looks like this: + +``` +jayant.macbook + ↑ ↑ + you your machine +``` + +Why per-machine? Because your sessions are machine-specific. If you're "jayant" on a MacBook and also "jayant" on a desktop, those are two separate members with separate session outboxes. Same person, different machines, different sessions. + +You choose your `user_id` once (your name, no dots). The `machine_tag` is auto-detected from your hostname. + +### 2. Teams (who can see your stuff) + +A **team** is a group of members who can see each other's sessions. That's all it is — an access control list. + +``` +Team "backend-crew" (status: active) +├── jayant.macbook (leader — created the team) +├── ayush.laptop (active) +└── priya.desktop (active) +``` + +Teams don't own data. They don't store anything. They just answer the question: "who should get a copy of my sessions?" + +You can be in multiple teams. A freelancer might be in a team with Client A and a separate team with Client B. Sessions shared with Team A are invisible to Team B. + +**Leader privilege:** only the team leader (the person who created it) can add members, remove members, share projects, and dissolve the team. This keeps things tidy and prevents accidental changes. + +Teams have a simple lifecycle: they're **active** until the leader **dissolves** them. Once dissolved, all Syncthing folders are cleaned up and members are notified automatically. + +### 3. Projects (what gets shared) + +You choose which **projects** to share with each team. A project is identified by its **git identity** — that's the git remote URL like `jayantdevkar/claude-karma`. This is how Karma knows "your claude-karma" and "my claude-karma" are the same project, even if they live in different directories on different machines. + +``` +Team "backend-crew" shares: +├── claude-karma (git_identity: jayantdevkar/claude-karma) +└── api-gateway (git_identity: acme/api-gateway) +``` + +Sharing is per-project, per-team. You might share `claude-karma` with your team but keep `personal-notes` private. You're always in control of what gets shared. + +### 4. Subscriptions (how you receive) + +When the leader shares a project with a team, every member gets a **subscription** for that project. Think of it like an email subscription — you're automatically signed up, but you decide what to do with it. + +Each subscription has a **status** and a **direction**: + +| Status | What it means | +|--------|--------------| +| **Offered** | The project was just shared. You haven't responded yet. | +| **Accepted** | You want this project's sessions. They'll start syncing. | +| **Paused** | Temporarily stopped. Easy to resume later. | +| **Declined** | You don't want this project. No sessions will sync. | + +| Direction | What syncs | +|-----------|-----------| +| **Both** | You send your sessions AND receive theirs | +| **Send** | You share your sessions, but don't receive others' | +| **Receive** | You get their sessions, but don't share yours | + +This means you have fine-grained control. Maybe you want to receive the `api-gateway` project but only send on `claude-karma`. Or maybe you want to pause everything for a week while you're on vacation. It's all up to you. + +## How sessions flow + +Here's what happens when you use Claude Code with sync enabled: + +``` + YOUR MACHINE TEAMMATE'S MACHINE + ┌─────────────────────┐ ┌─────────────────────┐ + │ │ │ │ + │ You use Claude │ │ │ + │ Code on a project │ │ │ + │ │ │ │ │ + │ ▼ │ │ │ + │ Session saved to │ │ │ + │ ~/.claude/ │ │ │ + │ │ │ │ │ + │ ▼ │ │ │ + │ Watcher detects │ │ │ + │ the new session │ │ │ + │ │ │ │ │ + │ ▼ │ Syncthing P2P │ │ + │ Packaged into │ (encrypted, │ Session appears │ + │ YOUR OUTBOX ───┼──── automatic) ──────────┼──► in THEIR INBOX │ + │ │ │ │ │ + │ │ │ ▼ │ + │ │ │ Shows up in their │ + │ │ │ Karma dashboard │ + │ │ │ │ + │ Their session │ Syncthing P2P │ They use Claude │ + │ appears in ◄───┼──── (encrypted, ◄───────┼── Code too, session │ + │ YOUR INBOX │ automatic) │ goes to THEIR │ + │ │ │ │ OUTBOX │ + │ ▼ │ │ │ + │ Shows up in your │ │ │ + │ Karma dashboard │ │ │ + │ │ │ │ + └─────────────────────┘ └─────────────────────┘ +``` + +**Key insight:** your outbox and their inbox are the *same folder*. You create it as "send-only"; they add it as "receive-only". Syncthing handles the rest. No copying, no uploading — files just appear. + +## The folder model + +Karma creates three types of Syncthing folders automatically. You never have to manage these — they're invisible plumbing. + +| Type | What it does | Example | +|------|-------------|---------| +| **Outbox** | Your sessions → teammates (send-only) | `karma-out--jayant.macbook--org-repo` | +| **Inbox** | Teammate's sessions → you (receive-only) | `karma-out--ayush.laptop--org-repo` | +| **Metadata** | Team member list & signals (shared) | `karma-meta--backend-crew` | + +Notice that "outbox" and "inbox" have the same naming pattern (`karma-out--{member_tag}--{folder_suffix}`). That's because they're the same folder seen from different sides. Jayant's outbox IS ayush's inbox for that project. The `folder_suffix` is derived from the git identity (e.g., `jayantdevkar/claude-karma` becomes `jayantdevkar-claude-karma`). + +The **metadata folder** is how members discover each other. Each device writes a small JSON file with its identity. When a new member joins, everyone else picks up their info from the metadata folder automatically — no central coordinator needed. + +## Multiple teams, one outbox + +Here's where it gets clever. If you're in two teams that both share the same project, Karma doesn't create two outboxes. It creates ONE outbox and expands the device list: + +``` +Team A shares "claude-karma": members = {jayant, ayush, priya} +Team B shares "claude-karma": members = {jayant, bob, charlie} + ↓ +Jayant's outbox device list = {ayush, priya, bob, charlie} +``` + +This is the **"project channels" model**. Sessions belong to projects, not teams. Teams just decide who has access. This avoids duplicating session data and keeps things efficient. + +When jayant leaves Team B, only Team B's devices (bob, charlie) are removed from the outbox. Team A's devices stay. No data is lost. + +## What gets synced (and what doesn't) + +**Synced:** +- Session conversations and messages +- Tool usage and token statistics +- Session metadata and timelines +- Subagent activity + +**Never synced:** +- Your source code +- Secrets, credentials, or `.env` files +- Files outside `~/.claude/projects/` +- Anything from projects you haven't explicitly shared + +## The lifecycle + +### Getting started (one-time) + +``` +1. Install Syncthing → brew install syncthing (macOS) +2. Open Karma → /sync → The setup wizard walks you through it +3. Pick your user_id → Your name, like "jayant" +4. Machine tag auto-detects → From your hostname, like "macbook" +``` + +### Creating a team + +``` +1. Create team → Give it a name like "backend-crew" +2. Share projects → Pick which projects the team should sync +3. Get a join code → A short code your teammates can use to join +4. Share the code → Send it via Slack, email, anything +``` + +### Joining a team + +``` +1. Get a join code → Your teammate generates one from their dashboard +2. Leader adds you → They paste your code on the Team page +3. Devices pair → Automatic, encrypted Syncthing handshake +4. Accept subscriptions → Choose which projects you want, and in which direction +5. Sessions start flowing → Within seconds on LAN, minutes over internet +``` + +### Day to day + +Nothing. It just works. Karma's watcher runs in the background, packaging new sessions and syncing them automatically. Sessions from teammates appear in your dashboard. + +## Settings you can tweak + +| Setting | Where to set it | What it does | +|---------|----------------|-------------| +| **Subscription status** | Per project, per member | Accept, pause, resume, or decline any project subscription | +| **Sync direction** | Per subscription | Send only, receive only, or both — per project | +| **Session limit** | Per team | Sync all sessions, recent 100, or recent 10 | + +The most granular control is at the subscription level. You can be in a team of 10 people sharing 5 projects, and fine-tune exactly which projects you send/receive for. + +## Security model + +### In transit +All transfers use **TLS 1.3** with mutual certificate authentication. Only devices you've explicitly paired can connect. Even Syncthing's relay servers (used when devices can't connect directly) see only encrypted blobs. + +### At rest +Session files are stored unencrypted on disk. Protect your `~/.claude_karma/` directory with standard filesystem permissions (mode 0700 by default). + +### Access control +- Only the team **leader** can add/remove members, share/remove projects, and dissolve the team +- Removed members are notified via a removal signal in the metadata folder +- Removed members auto-leave and their data is cleaned up +- You can decline or pause subscriptions to specific projects at any time +- A device shared across multiple teams is only unpaired when removed from ALL teams + +### What Karma manages for you +- Device pairing and folder creation +- Member discovery via metadata folders +- Automatic cleanup when leaving teams +- Folder device lists (who can sync what) + +You never touch Syncthing directly — Karma handles all of it through Syncthing's REST API. + +## Network setup + +### Same network (LAN) +Works out of the box. Syncthing discovers peers automatically. Sync is near-instant. + +### Different networks (internet) +Three options: + +1. **Syncthing relays** (easiest) — Enabled by default. Data is end-to-end encrypted; relays can't read it. Slightly slower. +2. **VPN** (Tailscale, WireGuard) — Put everyone on a VPN. Syncthing discovers peers over the VPN as if they were on the same LAN. +3. **Port forwarding** — Open port 22000. Syncthing connects directly. Fastest, but requires router config. + +## Troubleshooting + +**Sessions not appearing?** +- Check that the watcher is running (`/sync` page shows status) +- Verify both devices are online in Syncthing (`localhost:8384`) +- Make sure the project is shared with the team + +**"Syncthing not detected"?** +- Install Syncthing and start it as a background service +- macOS: `brew install syncthing && brew services start syncthing` +- Linux: `sudo apt install syncthing && systemctl --user enable --now syncthing` + +**Teammate's sessions not syncing?** +- Both machines need the project shared with the same team +- Check pending folders on the `/sync` page — you may need to accept new folders +- Verify network connectivity between machines + +**Want to stop sharing a project?** +- Remove the project from the team on the `/sync` page +- Sessions already synced remain on teammates' machines (they're copies) diff --git a/docs/design/sync-v3-architecture.md b/docs/design/sync-v3-architecture.md new file mode 100644 index 00000000..78cd51fc --- /dev/null +++ b/docs/design/sync-v3-architecture.md @@ -0,0 +1,1322 @@ +# Sync v3 Architecture Design + +> **Date:** 2026-03-13 +> **Status:** Design revision 3 (all critic + architect feedback applied) +> **Scope:** Architecture and design only (no code) +> **Input:** `docs/design/sync-v3-audit-findings.md` (BP-1 through BP-18, EC-1 through EC-7, RC-1 through RC-5) + +--- + +## Context + +### Original Request + +Design the v3 sync architecture for claude-karma's Syncthing P2P sync layer. The v2 layer breaks when members overlap across multiple teams sharing the same projects. Three root causes were identified: + +1. Outbox folder IDs lack team scope (BP-1), causing silent device list merging (BP-2) and destructive cleanup (BP-3, BP-4) +2. Syncthing's introducer mechanism leaks across team boundaries (BP-5), creating phantom team memberships (BP-6) +3. No surgical device removal from folders (BP-7), only folder deletion + +### Research Findings + +The audit document (`docs/design/sync-v3-audit-findings.md`) provides a complete behavioral analysis of v2 with 18 breakpoints, 7 edge cases, 5 race conditions, and 7 verified-correct behaviors. Two candidate architectures were proposed: team-scoped folder IDs (Option A) and project channels (Option B). + +### What Works Correctly (Preserved in v3) + +- OK-1: Atomic metadata writes (tempfile + rename) +- OK-2: SQLite WAL mode with proper locking +- OK-3: Same-user multi-device differentiation (member_tag) +- OK-4: Handshake and metadata folder IDs include team +- OK-5: Device cross-team check on removal +- OK-6: Event loop handling in daemon thread +- OK-7: Removal authority (creator-only) + +--- + +## ADR-1: Folder ID Strategy — Project Channels + +### Decision + +**Choose Option B: Project Channels.** Keep the current folder ID format `karma-out--{member_tag}--{suffix}` (one folder per member per project). Teams become an access control layer, not a data boundary. Device lists are computed as the union of all teams sharing that project for that member. + +### Status + +Accepted. + +### Context + +Two options were evaluated: + +**Option A — Team-Scoped Folder IDs:** +- Format: `karma-out--{member_tag}--{team}--{suffix}` +- Pro: Clean isolation per team. Simple cleanup (just delete team-scoped folders). +- Con: Same session data duplicated N times for N teams sharing the project. Packager must copy to N outbox paths. Folder count multiplied by team count. + +**Option B — Project Channels:** +- Format: `karma-out--{member_tag}--{suffix}` (unchanged from v2) +- Pro: No session duplication. One outbox per (member, project). Packager unchanged. Fewer folders. +- Con: Requires cross-team union queries for device lists. Cleanup requires device subtraction (not folder deletion). More complex bookkeeping. + +### Rationale + +1. **Session data is inherently per-project** (audit section 11.3). A session belongs to `~/.claude/projects/{encoded}/{uuid}.jsonl`. There is no team concept at the session level. Duplicating sessions across team-scoped outboxes adds storage and sync overhead with zero value. + +2. **The packager copies sessions to ONE outbox path** (audit section 10.1). With Option A, the packager would need to copy to N paths. With Option B, no packager changes are needed. + +3. **Folder count matters** (BP-15, EC-7). At scale (10 teams, 20 projects, 10 members), Option A produces ~2000 folders vs ~125 for Option B. Syncthing performance degrades above ~500 folders. + +4. **The complexity is manageable.** The "union device list" computation is a SQL query joining `sync_team_projects` and `sync_members`. The "device subtraction on cleanup" uses `remove_device_from_folder` which already exists (BP-18) but is underused. + +### Consequences + +- **Folder ID format unchanged.** No migration needed for folder IDs themselves. +- **Device list computation changes.** `ensure_outbox_folder` and `ensure_inbox_folders` must compute the union of all teams' devices for a given (member, project) pair. +- **Cleanup changes.** Leaving a team subtracts that team's devices from shared folders, rather than deleting the folder. Folder deletion only happens when refcount reaches 0 (no team claims the folder). +- **`find_team_for_folder` becomes obsolete** for disambiguation. Folder-to-team mapping is now many-to-many. Replaced by direct SQL queries. +- **`sync_rejected_folders` must become team-scoped** (fixes BP-14). + +### Breakpoints Addressed + +- BP-1 (no team scope): Addressed by treating team as access control, not folder boundary +- BP-2 (additive-only): Addressed by ADR-3 (declarative device lists) +- BP-3 (destructive cleanup): Addressed by ADR-4 (device subtraction) +- BP-4 (cross-team inbox removal): Addressed by ADR-4 (refcount check) +- BP-8 (ambiguous team lookup): Addressed by eliminating single-team folder assumption +- BP-14 (rejection not team-scoped): Addressed by team-scoped rejection table +- BP-15 (folder count): Addressed by keeping project-scoped folders (lower count) + +--- + +## ADR-2: Explicit Mesh Pairing (Replacing Introducer) + +### Decision + +**Remove all use of Syncthing's introducer flag.** Replace with explicit device pairing coordinated through the metadata folder. Each device reads the team's metadata folder to discover peer device IDs, then pairs with them directly via the Syncthing REST API. + +### Status + +Accepted. + +### Context + +The introducer mechanism (audit section 6.1, BP-5) is: +- Per-device, global, all-or-nothing (not team-scoped) +- Permanent once set (no code path disables it) +- Re-enforced by `ensure_leader_introducers()` on every poll + +In multi-team setups, a device marked as introducer for Team A propagates ALL devices/folders (including from Teams B, C, D) to any peer that trusts it. This creates phantom team memberships (BP-6) via reconciliation auto-creating teams from introduced artifacts. + +### Rationale + +1. **Syncthing's introducer cannot be scoped to a team** (audit section 6.1). This is a fundamental constraint of Syncthing, not a bug in karma's code. No amount of clever coding around it will prevent cross-team leakage when a device participates in multiple teams. + +2. **The metadata folder already provides the necessary information.** Each member writes their `device_id` to `members/{member_tag}.json`. Reading the metadata folder gives a complete list of all team members and their device IDs. This is sufficient for explicit pairing. + +3. **Explicit pairing is more predictable.** The system pairs exactly the devices it intends to, with no side effects. Debugging "why is device X seeing device Y's data" becomes straightforward: check which teams share a project where both are members. + +### New Join Flow (Explicit Mesh) + +``` +STEP 1: Joiner joins team + Joiner → pair with leader device (from join code) + Joiner → create karma-join--{self}--{team} + Joiner → create karma-meta--{team} (shared with leader) + Joiner → write own member state to metadata folder + NOTE: introducer=False on leader device + +STEP 2: Leader accepts joiner + Leader → auto_accept_pending_peers (as today) + Leader → add joiner device, NO introducer flag + Leader → auto_share_folders (as today) + Leader → update metadata folder device list to include joiner + +STEP 3: Metadata propagation + Metadata folder syncs to all team members (sendreceive) + Each member reads metadata → discovers new member's device_id + +STEP 4: Explicit mesh pairing — existing members (NEW) + Each existing member → reads metadata folder + For each new device_id not yet paired: + proxy.add_device(device_id, member_tag) # NO introducer + Then: compute_and_apply_device_lists() for all project folders (ADR-3) + +STEP 5: Explicit mesh pairing — joiner (NEW) + Joiner receives metadata folder from leader (Step 2) + Joiner → mesh_pair_from_metadata() + Reads metadata → discovers all existing members' device_ids + For each peer not yet paired: + proxy.add_device(device_id, member_tag) # NO introducer + compute_and_apply_device_lists() for all project folders + NOTE: Without this step, the joiner can only sync with the leader + until the next reconciliation cycle discovers peers. +``` + +### What This Replaces + +| v2 Component | v3 Replacement | +|---|---| +| `ensure_leader_introducers()` | Removed entirely | +| `reconcile_introduced_devices()` | Replaced by `mesh_pair_from_metadata()` | +| `reconcile_pending_handshakes()` | Kept (handshake processing is team-scoped, works correctly) | +| `auto_accept_pending_peers()` | Kept (policy gate + identity verification) | +| Introducer flag on `add_device()` | Always `introducer=False` | + +### Explicit Mesh Pairing Function + +New function `mesh_pair_from_metadata(proxy, config, conn)`: + +``` +For each team in list_teams(conn): + meta_dir = KARMA_BASE / "metadata-folders" / team_name + member_states = read_all_member_states(meta_dir) + removal_signals = read_removal_signals(meta_dir) + removed_tags = {r["member_tag"] for r in removal_signals} + + For each member_state: + if member_state.member_tag in removed_tags: skip + if member_state.member_tag == config.member_tag: skip (self) + if member_state.device_id already configured in Syncthing: skip + + # Pair with new device (no introducer) + proxy.add_device(device_id, member_tag) + upsert_member(conn, team_name, ...) + + # Compute and apply device lists for all project folders + compute_and_apply_device_lists(proxy, config, conn, team_name) +``` + +### Migration: Disabling Existing Introducers + +On first v3 startup: + +``` +For each configured device in Syncthing: + if device.introducer == True: + proxy.set_device_introducer(device_id, False) + log_event("introducer_disabled", detail={"device_id": device_id}) +``` + +### Breakpoints Addressed + +- BP-5 (global introducer): Eliminated entirely +- BP-6 (phantom team creation): Eliminated (no introduced artifacts from foreign teams) +- BP-7 (partial): Device pairing is now explicit, so device lists are deterministic + +--- + +## ADR-3: Declarative Device List Management + +### Decision + +Replace the additive-only `update_folder_devices` pattern with a **declarative `set_folder_devices`** approach. For each folder, compute the desired device list from the database, then apply it as the complete list (adding missing devices, removing stale devices). + +### Status + +Accepted. + +### Context + +v2's `update_folder_devices` (BP-2) only adds devices. Once a device leaks into a folder, there is no normal-operation code path to remove it. The only removal mechanism is deleting the entire folder (BP-3, BP-4, BP-7). + +Meanwhile, `remove_device_from_folder` (BP-18) exists and works correctly but is only used in one cleanup path. + +### The Union Query + +For a given folder `karma-out--{member_tag}--{suffix}`, the query must be scoped to teams where the folder OWNER is a member. Without this constraint, a folder would incorrectly include devices from teams the owner does not belong to (e.g., M4's outbox for P2 would include T2 devices even though M4 is NOT in T2). + +```sql +-- All devices that should have access to this folder, +-- scoped to teams where the folder owner is a member. +-- Input: :suffix, :owner_member_tag +SELECT DISTINCT sm.device_id +FROM sync_team_projects stp +JOIN sync_members sm ON sm.team_name = stp.team_name +WHERE stp.folder_suffix = :suffix + AND sm.device_id IS NOT NULL + AND sm.device_id != '' + AND stp.team_name IN ( + SELECT team_name FROM sync_members + WHERE member_tag = :owner_member_tag + ) +``` + +This computes the union of all team members across all teams that (a) share the project identified by `suffix` AND (b) include the folder owner as a member. The `owner_member_tag` parameter is extracted from the folder ID: `karma-out--{owner_member_tag}--{suffix}`. + +### New Function: `compute_and_apply_device_lists` + +``` +def compute_and_apply_device_lists(proxy, config, conn, team_name=None): + """Compute desired device lists for all project folders and apply them. + + If team_name is provided, only recomputes folders for that team's projects. + Otherwise recomputes all folders. + + IMPORTANT: The union query is scoped to teams where the folder OWNER + is a member (see ADR-3 union query). The owner_member_tag is extracted + from the folder ID: karma-out--{owner_member_tag}--{suffix}. + + LOCKING: Must acquire client._config_lock for the full GET-compute-PUT + cycle of each folder (see RC-4 mitigation). + + FOLDER COUNT WARNING: Logs a warning at 200 folders, logs an error + at 500 folders (see BP-15 safeguard). + """ + # 0. Count total folders; warn at 200, error at 500 + # 1. Get all project suffixes (optionally filtered by team) + # 2. For each suffix, for each folder matching the suffix: + # a. Extract owner_member_tag from folder ID + # b. Compute the union device list from DB (scoped to owner's teams) + # c. Get current device list from Syncthing + # d. Compute diff: devices_to_add, devices_to_remove + # e. Acquire client._config_lock, apply: add missing, remove stale + # 3. For folders where device list becomes empty (only self): + # Delete the folder (refcount = 0) +``` + +### Implementation: `set_folder_devices` + +New proxy method that replaces the device list atomically: + +``` +def set_folder_devices(self, folder_id, device_ids): + """Set the folder's device list to exactly these device_ids. + + Uses PUT /rest/config/folders/{id} with the full folder config. + Adds self device_id automatically (Syncthing requires it). + + MUST be called while holding client._config_lock (RLock) for the + full GET-compute-PUT cycle. This prevents interleaving with other + config mutations. Two threads computing DIFFERENT desired states + would NOT produce the same result — the lock prevents corruption. + See existing lock pattern at syncthing_proxy.py:231 and :293. + """ + # Caller must hold client._config_lock + # Get current folder config + # Replace devices list with new list + # PUT the updated config +``` + +This is a combination of the existing `update_folder_devices` (add) and `remove_device_from_folder` (remove) into a single atomic operation. + +### When Device Lists Are Recomputed + +| Event | Scope | +|---|---| +| Member joins team | All folders for that team's projects | +| Member leaves team | All folders for that team's projects | +| Project shared with team | All folders for that project | +| Project removed from team | All folders for that project | +| Device change detected (EC-2) | All folders for all teams the device is in | +| Metadata reconciliation discovers new member | All folders for that team's projects | +| v3 migration startup | All folders | + +### Breakpoints Addressed + +- BP-2 (additive-only): Replaced with declarative set +- BP-7 (no device removal): `set_folder_devices` removes stale devices +- BP-18 (underused remove): `remove_device_from_folder` logic incorporated into `set_folder_devices` + +--- + +## ADR-4: Cross-Team Safe Cleanup + +### Decision + +Cleanup operations use **device subtraction** (remove a team's devices from shared folders) rather than **folder deletion**. A folder is only deleted when its computed device list becomes empty (only self remaining), meaning no team claims it anymore. + +### Status + +Accepted. + +### Context + +v2 cleanup (BP-3, BP-4) removes entire folders without checking cross-team usage. Leaving Team A deletes `karma-out--alice.laptop--P2_suffix` even if Team B also uses that folder. + +### Cleanup Logic: Leave Team + +``` +async def cleanup_for_team_leave(proxy, config, conn, team_name): + """Clean up when leaving a team. Subtracts team's devices from shared folders.""" + + team_members = list_members(conn, team_name) + team_projects = list_team_projects(conn, team_name) + team_device_ids = {m["device_id"] for m in team_members} + + for proj in team_projects: + suffix = _compute_proj_suffix(proj) + + # For each folder related to this project: + # Recompute the desired device list WITHOUT this team + # (union of all OTHER teams sharing this project) + desired_devices = compute_union_devices_excluding_team( + conn, suffix, team_name + ) + + # Apply the new device list + # If desired_devices is empty (no other team claims this folder): + # Delete the folder + # Else: + # set_folder_devices(folder_id, desired_devices) + + # Remove team-specific folders (handshake, metadata) + # These are team-scoped, so always safe to delete + remove_folder(karma-join--{self}--{team_name}) + remove_folder(karma-meta--{team_name}) + + # Remove devices not used by any remaining team + for device_id in team_device_ids: + if not device_in_any_other_team(conn, device_id, team_name): + proxy.remove_device(device_id) +``` + +### Cleanup Logic: Remove Member + +``` +async def cleanup_for_member_removal(proxy, config, conn, team_name, member_device_id): + """Clean up when removing a member from a team.""" + + # Recompute device lists for all project folders in this team + # The removed member's device will no longer appear in the union + # (because they're removed from sync_members for this team) + compute_and_apply_device_lists(proxy, config, conn, team_name) + + # Remove the member's inbox folder ONLY if no other team claims it + member_tag = get_member_tag(conn, member_device_id) + for proj in list_team_projects(conn, team_name): + suffix = _compute_proj_suffix(proj) + inbox_id = build_outbox_id(member_tag, suffix) + desired_devices = compute_union_devices_for_folder(conn, inbox_id) + if not desired_devices or desired_devices == {config.syncthing.device_id}: + proxy.remove_folder(inbox_id) + else: + set_folder_devices(inbox_id, desired_devices) + + # Remove member's handshake folder (team-scoped, always safe) + remove_folder(karma-join--{member_tag}--{team_name}) + + # Remove device if not in any other team + if not device_in_any_other_team(conn, member_device_id, team_name): + proxy.remove_device(member_device_id) +``` + +### Cleanup Logic: Remove Project From Team + +``` +async def cleanup_for_project_removal(proxy, config, conn, team_name, project): + """Clean up when removing a project from a team.""" + + suffix = _compute_proj_suffix(project) + + # Recompute device lists for all folders with this suffix + # Without this team, some devices may no longer need access + desired_devices = compute_union_devices_excluding_team(conn, suffix, team_name) + + # For my outbox + outbox_id = build_outbox_id(config.member_tag, suffix) + if not desired_devices: + proxy.remove_folder(outbox_id) + else: + set_folder_devices(outbox_id, desired_devices) + + # For each peer's inbox + # Same logic: recompute, subtract, delete if empty + + # Filesystem cleanup: remove received session data for this project + cleanup_data_for_project(conn, team_name, project_encoded_name) +``` + +### Breakpoints Addressed + +- BP-3 (destructive team cleanup): Replaced with device subtraction +- BP-4 (cross-team inbox removal): Replaced with refcount check +- RC-2 (partial cleanup): Addressed by making cleanup idempotent (recompute desired state, apply diff) + +--- + +## ADR-5: Edge Case Handling + +### Decision + +Address each edge case with specific mechanisms. + +### BP-9: member_tag Collision Prevention + +**Problem:** Two different users with the same `user_id` and same hostname produce identical `member_tag` values. No validation exists at join/accept time. + +**Solution:** Add collision detection at three points: + +1. **At join time (joiner side):** Before creating the handshake folder, query the metadata folder for existing member states. If any member_state has the same `member_tag` but a different `device_id`, abort the join and prompt the user to choose a different `user_id`. + +2. **At accept time (leader side):** Before `upsert_member`, check: + ```sql + SELECT device_id FROM sync_members + WHERE member_tag = ? AND device_id != ? + ``` + If collision detected, reject the device (dismiss pending, log warning). + +3. **Metadata folder validation:** `reconcile_metadata_folder` checks for multiple member states with the same `member_tag` but different `device_id` values. If found, log a critical warning. + +### BP-12: Folder Acceptance Before Metadata Sync + +**Problem:** `auto_share_folders` reads subscriptions from metadata, but metadata may not have synced yet. All projects are shared regardless of opt-out preferences. + +**Solution:** Two-phase folder sharing with stateless detection: + +1. **Phase 1 (immediate):** Share only the metadata folder with the new member. Do NOT share project folders yet. + +2. **Phase 2 (deferred, stateless detection):** On each reconciliation cycle (60s timer), detect members who need project folders via a stateless check: "member exists in `sync_members` for this team, but their device is not in any of this team's project folders' device lists." When detected, run `compute_and_apply_device_lists` to share project folders with subscription awareness. + +**Detection mechanism:** The reconciliation timer (60s) performs this stateless check on every cycle. No durable timer or timestamp is needed. If metadata has not synced yet (member has no subscription preferences), the default opt-in behavior shares all projects. Once metadata arrives with opt-out preferences, the next reconciliation cycle self-corrects by removing the member from opted-out folders. + +**No fallback timer needed:** The stateless detection runs every 60s and always converges to the correct state. Late-arriving subscription preferences self-correct on the next cycle. + +### BP-13: git_identity Change Creates Orphaned Folders + +**Problem:** Changing a project's git remote URL creates a new folder suffix. Old folders persist. + +**Solution:** + +1. **Store the folder suffix in `sync_team_projects`** as a new column `folder_suffix`. Computed once at share time, immutable afterward. This decouples the folder ID from the current `git_identity`. + +2. **On `git_identity` change detection:** Log a warning event but do NOT change the folder suffix. The old suffix continues working. + +3. **Manual migration:** Provide a CLI command `karma sync migrate-project --team T --project P` that: + - Creates new folders with new suffix + - Waits for sync completion + - Removes old folders + - Updates `sync_team_projects.folder_suffix` + +### BP-14: sync_rejected_folders Not Team-Scoped + +**Problem:** Rejection is stored by `folder_id`. Since folder IDs lack team scope, rejecting a folder in one team rejects it for all teams. + +**Solution:** Change the rejection key to `(folder_id, team_name)`: + +```sql +CREATE TABLE IF NOT EXISTS sync_rejected_folders ( + folder_id TEXT NOT NULL, + team_name TEXT NOT NULL, + rejected_at TEXT DEFAULT (datetime('now')), + PRIMARY KEY (folder_id, team_name) +); +``` + +`is_folder_rejected` checks `WHERE folder_id = ? AND team_name = ?`. A folder can be rejected in Team A but accepted in Team B. + +### EC-1: member_tag Collision (Addressed by BP-9) + +See BP-9 above. Additionally, consider adding a random 4-character suffix to `machine_tag` if the hostname is very common (e.g., "macbook-pro", "localhost"). This reduces collision probability from `P(same user_id AND same hostname)` to `P(same user_id AND same hostname AND same random suffix)`. + +**Decision:** Do NOT add random suffix. The BP-9 collision detection is sufficient. Random suffixes would break the human-readable property of member_tags. + +### EC-2: Device ID Changes (Syncthing Reinstall) + +**Problem:** Old device ID persists in all teams' member lists and folder device lists. No migration path. After Syncthing reinstall, the device has a new device ID, no pairings, and no access to metadata folders. + +**Solution:** + +1. **Detection:** On startup, if `config.syncthing.device_id` differs from the stored device_id in any team's member record where `member_tag == config.member_tag`, flag a device ID change. + +2. **User notification:** Log a warning and surface via the API: "Your Syncthing device ID has changed. You must re-join all teams to restore sync." The device cannot self-heal because it has no pairings and no metadata folder access after a Syncthing reinstall. + +3. **Re-join required:** The user must re-join each team using a new invite code. The old member state in peers' metadata folders will show the stale device_id. Peers will clean up the stale entry via `compute_and_apply_device_lists` (the old device_id won't appear in any union query because the old member record will be replaced by the new one after re-joining). + +4. **Local cleanup:** On device ID change detection, clear local `sync_members` records that reference the old device_id for this member_tag. Do NOT attempt to write to metadata folders (they are inaccessible without pairings). + +**NOTE:** Self-heal via metadata folder is NOT possible in this scenario. The device has no pairings after Syncthing reinstall, so it cannot access any metadata folders to update its member state. + +### EC-6: Folder Rejection + Re-Share + +**Problem:** With team-scoped rejections (BP-14 fix), this is partially addressed. But `auto_share_folders` still doesn't check rejections. + +**Solution:** `compute_and_apply_device_lists` checks `sync_rejected_folders` before including a device in a folder's device list. If the local device has rejected folder X for team T, the local device is excluded from the device list for folder X when computing on behalf of team T. + +In practice: the local device writes a rejection to the metadata folder. Other members read this and exclude the rejecting device from the folder's device list. + +### Breakpoints Addressed + +- BP-9: Collision detection at join/accept +- BP-12: Two-phase folder sharing +- BP-13: Immutable folder suffix +- BP-14: Team-scoped rejection +- EC-1: Covered by BP-9 +- EC-2: Device ID change detection + re-join required +- EC-6: Team-scoped rejection + metadata awareness + +--- + +## ADR-6: Migration Strategy (v2 to v3) + +### Decision + +**Rolling migration with backward compatibility window.** v3 code handles both v2 and v3 folder patterns. Migration runs once per device on first v3 startup. + +### Status + +Accepted. + +### Migration Steps (Per Device, On First v3 Startup) + +``` +STEP 1: Disable all introducer flags + For each configured device: + if device.introducer: set_device_introducer(device_id, False) + +STEP 2: Schema migration (v17 -> v18) + ALTER TABLE sync_team_projects ADD COLUMN folder_suffix TEXT; + ALTER TABLE sync_rejected_folders ADD COLUMN team_name TEXT; + (see Schema Changes section below) + +STEP 3: Backfill folder_suffix + For each row in sync_team_projects: + folder_suffix = _compute_proj_suffix(git_identity, path, encoded_name) + UPDATE sync_team_projects SET folder_suffix = ? WHERE ... + +STEP 4: Migrate rejected folders + For each row in sync_rejected_folders: + If team_name is NULL: + # Try to determine team from folder_id + team = find_team_for_folder(conn, [folder_id]) + UPDATE sync_rejected_folders SET team_name = ? WHERE folder_id = ? + +STEP 5: Recompute all device lists + For each team: + compute_and_apply_device_lists(proxy, config, conn, team_name) + This removes any leaked devices from cross-team contamination. + +STEP 6: Clean up phantom teams + For each team in list_teams(conn): + meta_dir = KARMA_BASE / "metadata-folders" / team_name + If meta_dir does not exist AND team has no local join_code: + # Phantom team created by introducer leak (BP-6) + delete_team(conn, team_name) + +STEP 7: Record migration + INSERT INTO schema_version (version) VALUES (18) +``` + +### Backward Compatibility + +- **Folder IDs unchanged.** v2 and v3 devices share the same folder IDs. No folder recreation needed. +- **Metadata folder format unchanged.** v3 adds optional fields to member state JSON (e.g., `rejections`) but reads v2 format without error. +- **v2 devices continue to work** during migration window (their additive device list updates are harmless; v3 devices will correct the lists on next recompute cycle). +- **Handshake folders unchanged.** Join flow is backward compatible. + +### Known Limitation: v2/v3 Coexistence Oscillation + +During the migration window, v2 and v3 devices may oscillate device lists. v3 removes a leaked device from a folder, then a v2 device adds it back (via its additive-only `update_folder_devices`), then v3 removes it again on the next recompute cycle. + +**Impact:** Harmless. No data corruption or sync failure. Device lists fluctuate but converge once all devices upgrade. Syncthing handles transient device list changes gracefully (folders are not deleted, just temporarily inaccessible to the removed device). + +**Recommendation:** Complete the v3 migration across all devices within 24 hours to minimize oscillation. The reconciliation cycle (60s) will converge device lists within one cycle after the last v2 device upgrades. + +### Risk Mitigation + +- **Step 5 is idempotent.** Can be re-run safely. +- **Step 1 is non-destructive.** Devices remain paired; only the auto-propagation behavior changes. +- **Step 6 requires confirmation.** Phantom team detection checks for missing metadata folder AND missing join code. Teams the user legitimately joined (which have join codes stored) are preserved. + +--- + +## ADR-7: Non-Git Project Handling + +### Decision + +Address gaps in how non-git projects and projects missing from some members are handled across the sync layer. + +### Status + +Accepted. + +### Context + +The v2/v3 sync layer relies heavily on `git_identity` (normalized `owner/repo` from git remote URL) for two purposes: +1. **Folder suffix computation:** `_compute_proj_suffix()` uses `git_identity.replace("/", "-")` as a stable, universal project identifier +2. **Cross-machine project resolution:** `resolve_local_project()` matches received sessions to local Claude project directories via `git_identity` + +For non-git projects (no git repo or no `origin` remote), both mechanisms break down. The directory name fallback (`Path(path).name`) is machine-specific and collision-prone. + +### Gaps Identified + +| Gap | Severity | Description | +|-----|----------|-------------| +| GAP-1 | High | Non-git suffix collision: two different projects with same directory name produce identical folder suffixes, causing session mixing in `compute_union_devices` | +| GAP-2 | Medium | Non-git project resolution impossible: `resolve_local_project()` has no fallback when `git_identity` is `None` — all steps (A0, A, A1, B, C) require it | +| GAP-3 | Low | Non-git suffix instability on re-share: already handled by BP-13 (immutable `folder_suffix`) | +| GAP-4 | None | Empty outbox for missing project: working as designed (EC-4) | +| GAP-5 | Low | Git project resolution without local clone: self-healing once member clones the repo and uses Claude Code on it | +| GAP-6 | High | Non-git + member doesn't have project = permanently unresolved sessions. No self-healing path exists | +| GAP-7 | Medium | Mixed resolution in multi-team: some projects resolve, others silently don't. No UX signal | +| Pre-existing bug | High | CLI/API suffix mismatch: CLI computes suffix from `name` argument, API recomputes from `Path(path).name`. Different values for the same project | + +### Solutions + +**Fix A: Store suffix at share time (GAP-1, pre-existing bug)** + +The CLI `karma project add` now passes `folder_suffix` to `add_team_project()` immediately at share time. The suffix is computed once: +- Git projects: `git_identity.replace("/", "-")` (unchanged) +- Non-git projects: CLI `name` argument (user-chosen, meaningful) + +The `_compute_proj_suffix()` function becomes a legacy fallback only, used during migration for records that lack a stored `folder_suffix`. + +**Fix B: Suffix uniqueness check (GAP-1)** + +Before adding a project, the CLI checks for existing projects in the team with the same `folder_suffix`. If a collision is detected, the user is prompted to use `--suffix` to specify a different one: + +``` +karma project add my-notes --path ~/notes/ --team alpha --suffix my-design-notes +``` + +**Fix C: `project_name` in manifest (GAP-2, GAP-7)** + +The `SyncManifest` model now includes a `project_name` field populated from the project's directory name. Receivers can use this to display meaningful labels for unresolved projects and prompt users to map them. + +**Fix D: Manual project mapping CLI (GAP-2, GAP-6)** + +New CLI command for explicit cross-machine mapping: + +``` +karma project map --team --path +``` + +This is the ONLY correct solution for non-git cross-machine resolution. Without a universal identifier, only the user knows which local directory corresponds to a remote project. The command: +1. Validates the team has a project with the given suffix +2. Updates `sync_team_projects` with the local path and encoded name +3. Registers in the local `projects` table +4. Cleans up stale encoded name records if they differ + +### Gaps NOT Requiring Code Fixes + +- **GAP-3:** Protected by BP-13 (immutable `folder_suffix` stored in DB) +- **GAP-4:** Syncthing handles empty folders correctly (EC-4) +- **GAP-5:** Self-healing — once a member clones the repo and runs Claude Code, `resolve_local_project()` succeeds at Step C + +### Breakpoints Addressed + +- Pre-existing CLI/API suffix mismatch (new) +- GAP-1: Non-git suffix collision prevention +- GAP-2: Non-git project resolution via manual mapping +- GAP-6: Permanent unresolved sessions for non-git projects +- GAP-7: Manifest metadata for dashboard display + +### Consequences + +- Non-git projects require explicit CLI name choice at share time (was already the case but now enforced) +- Cross-machine resolution for non-git projects requires manual `karma project map` (no auto-resolution possible without universal identifier) +- The `--suffix` CLI option provides escape hatch for suffix collisions +- `project_name` in manifest enables future dashboard UX improvements (out of scope for v3) + +--- + +## Data Flow Diagrams + +### Join Team Flow (v3) + +``` +Joiner Leader Peer (existing member) + | | | + |-- pair leader (no introducer)--| | + |-- create handshake folder ---->| | + |-- create metadata folder ----->| | + |-- write member state --------->| | + | | | + | auto_accept_pending_peers() | + | |-- add_device(joiner, False) -->| + | |-- upsert_member() ----------->| + | |-- share metadata folder ------>| + | | (DO NOT share project | + | | folders yet — Phase 1) | + | | | + | [metadata syncs to all members] | + | | | + | | mesh_pair_from_metadata() + | | |-- reads metadata + | | |-- discovers joiner + | | |-- add_device(joiner) + | | |-- compute_and_apply_device_lists() + | | | + | [metadata synced, joiner's state visible] + | | | + | mesh_pair_from_metadata() | | + | (joiner discovers peers) | | + |-- add_device(peer, False) --->| | + |-- compute_and_apply_device_lists() | + | | | + | compute_and_apply_device_lists() | + | | (Phase 2 — project folders | + | | shared with subscription | + | | awareness) | + | | | + |<-- pending project folders ----| | + |-- accept project folders ----->| | +``` + +### Leave Team Flow (v3) + +``` +Leaver Remaining Members + | | + |-- cleanup_for_team_leave() --->| + | For each project folder: | + | compute union WITHOUT team | + | If union empty: | + | remove_folder() | + | Else: | + | set_folder_devices() | + | | + | remove handshake folder | + | remove metadata folder | + | | + | For each team device: | + | If not in other teams: | + | remove_device() | + | | + | delete_team(conn) | + | | + | [metadata folder reflects removal] + | | + | mesh_pair_from_metadata() + | |-- leaver no longer in metadata + | |-- compute_and_apply_device_lists() + | | (leaver's device removed from + | | folders for this team only) +``` + +### Share Project Flow (v3) + +``` +Sharer All Team Members + | | + |-- add_team_project(conn) ----->| + | (stores folder_suffix) | + | | + |-- ensure_outbox_folder() ----->| + | (uses compute union: | + | all devices from all teams | + | sharing this project) | + | | + |-- ensure_inbox_folders() ----->| + | For each member: | + | compute union devices | + | set_folder_devices() | + | | + | [peers receive pending folder offers] + | | + | accept_pending_folders() + | |-- compute_and_apply_device_lists() +``` + +### Remove Project From Team Flow (v3) + +``` +Remover Remaining Members + | | + |-- remove_team_project(conn) -->| + | | + |-- cleanup_for_project_removal()| + | compute union WITHOUT team | + | For each folder with suffix: | + | If union empty: | + | remove_folder() | + | cleanup filesystem | + | Else: | + | set_folder_devices() | + | | + | [metadata/reconciliation cycle] + | | + | compute_and_apply_device_lists() + | | (removed team's devices + | | subtracted from folders) +``` + +### Remove Member Flow (v3) + +``` +Remover (creator) Removed Member Other Members + | | | + |-- remove_member(conn) -------->| | + |-- write_removal_signal() ----->| | + | | | + |-- cleanup_for_member_removal() | | + | compute_and_apply_device_lists() | + | (removed device excluded | | + | from union for this team) | | + | | | + | For member's inbox folders: | | + | compute union | | + | If empty: remove_folder() | | + | Else: set_folder_devices() | | + | | | + | Remove handshake folder | | + | Remove device if no teams | | + | | | + | [metadata syncs removal signal] | + | | | + | is_removed() → True | + | _auto_leave_team() | + | | | + | | mesh_pair_from_metadata() + | | |-- reads removal + | | |-- compute_and_apply() + | | | (removed device + | | | excluded from lists) +``` + +--- + +## Schema Changes (v17 -> v18) — Atomic Migration + +All schema changes are applied in a single atomic v18 migration in Phase 1. Phases 2-4 use the already-migrated schema. This prevents ambiguity about which phase owns the migration. + +### New Columns + +```sql +-- Store computed folder suffix (immutable after creation) +ALTER TABLE sync_team_projects ADD COLUMN folder_suffix TEXT; + +-- Durable leave-in-progress marker (survives restarts) +-- NULL = normal, datetime = cleanup started at this time +ALTER TABLE sync_teams ADD COLUMN pending_leave TEXT; +``` + +### Modified Tables + +```sql +-- sync_rejected_folders: change PK to (folder_id, team_name) +-- SQLite cannot ALTER TABLE to change PK, so drop and recreate +-- NOTE: Unattributable rejections are dropped during migration (see below) +CREATE TABLE sync_rejected_folders ( + folder_id TEXT NOT NULL, + team_name TEXT NOT NULL, + rejected_at TEXT DEFAULT (datetime('now')), + PRIMARY KEY (folder_id, team_name) +); +``` + +### New Index + +```sql +CREATE INDEX IF NOT EXISTS idx_sync_team_projects_suffix + ON sync_team_projects(folder_suffix); +``` + +### Migration SQL + Python + +The migration has both SQL and Python steps, run together in Phase 1: + +```sql +-- v18 migration (SQL portion) + +-- 1. Add folder_suffix column +ALTER TABLE sync_team_projects ADD COLUMN folder_suffix TEXT; + +-- 2. Add pending_leave column for durable cleanup tracking (RC-1, RC-2) +ALTER TABLE sync_teams ADD COLUMN pending_leave TEXT; + +-- 3. Create new sync_rejected_folders table (empty — Python step populates it) +CREATE TABLE sync_rejected_folders_v18 ( + folder_id TEXT NOT NULL, + team_name TEXT NOT NULL, + rejected_at TEXT DEFAULT (datetime('now')), + PRIMARY KEY (folder_id, team_name) +); + +-- 4. New index +CREATE INDEX IF NOT EXISTS idx_sync_team_projects_suffix + ON sync_team_projects(folder_suffix); +``` + +```python +# v18 migration (Python portion, runs between SQL steps 3 and table swap) + +# Step A: Backfill folder_suffix (Python logic for fallback) +for row in cursor.execute("SELECT * FROM sync_team_projects"): + suffix = _compute_proj_suffix(row["git_identity"], row["path"], row["encoded_name"]) + cursor.execute("UPDATE sync_team_projects SET folder_suffix = ? WHERE ...", (suffix,)) + +# Step B: Migrate rejected folders — attribute to teams, drop orphans +for row in cursor.execute("SELECT folder_id, rejected_at FROM sync_rejected_folders"): + team = find_team_for_folder(conn, [row["folder_id"]]) + if team: + # Attributable rejection — migrate to new table + cursor.execute( + "INSERT INTO sync_rejected_folders_v18 (folder_id, team_name, rejected_at) VALUES (?, ?, ?)", + (row["folder_id"], team, row["rejected_at"]) + ) + else: + # Unattributable rejection — folder's project removed from all teams. + # Drop it. If the folder is re-shared later, user can re-reject. + log.info("Dropping orphaned rejection for folder %s (no team claims it)", row["folder_id"]) + +# Step C: Swap tables +cursor.execute("DROP TABLE sync_rejected_folders") +cursor.execute("ALTER TABLE sync_rejected_folders_v18 RENAME TO sync_rejected_folders") + +# Step D: Retry any interrupted cleanups from before migration +for row in cursor.execute("SELECT name FROM sync_teams WHERE pending_leave IS NOT NULL"): + log.warning("Team %s has interrupted cleanup — will retry on next timer cycle", row["name"]) +``` + +```sql +-- Final: Record version +INSERT OR REPLACE INTO schema_version (version) VALUES (18); +``` + +### Summary of v18 Schema Changes + +| Change | Purpose | +|--------|---------| +| `sync_team_projects.folder_suffix` | Decouple folder ID from git_identity changes (BP-13) | +| `sync_teams.pending_leave` | Durable cleanup tracking, survives restarts (RC-1, RC-2) | +| `sync_rejected_folders` recreated | Team-scoped PK `(folder_id, team_name)` (BP-14) | +| Orphaned rejections dropped | Stale rows for folders no team claims (C5) | + +--- + +## Reconciliation Architecture (v3) + +### Reconciliation Phases (Revised) + +The v2 4-phase reconciliation (run on `GET /sync/pending-devices`) is restructured: + +``` +v3 Reconciliation (triggered by GET /sync/pending-devices and 60s timer): + + Phase 1: mesh_pair_from_metadata() + Read all teams' metadata folders + Pair with any undiscovered devices (no introducer) + Upsert member records + + Phase 2: reconcile_pending_handshakes() + Process pending karma-join-* folders from configured devices + Create teams, add members (same as v2, works correctly) + + Phase 3: auto_accept_pending_peers() + Accept pending devices offering karma-* folders + Policy gate (same as v2, works correctly) + + Phase 4: compute_and_apply_device_lists() + For all teams (or changed teams): + Compute union device lists + Apply to all project folders + Remove stale devices, delete empty folders +``` + +**Removed:** `ensure_leader_introducers()` (no longer needed) +**Removed:** `reconcile_introduced_devices()` (replaced by Phase 1) +**Added:** Phase 4 as a dedicated step (was implicit in v2's auto_share_folders) + +### Timer-Driven Reconciliation (60s) + +Same as v2 but adds Phase 4: + +``` +reconcile_all_teams_metadata(config, conn, auto_leave=True) + For each team: + reconcile_metadata_folder() # discover members, detect removals + compute_and_apply_device_lists() # ensure folder device lists are correct +``` + +### Race Condition Mitigation + +**RC-1 (auto-leave vs reinvite):** +- Use the durable `pending_leave` column (see RC-2) to prevent re-creation during cleanup +- `reconcile_pending_handshakes` checks `pending_leave IS NULL` before creating/recreating teams +- Use `sync_removed_members` as the authoritative source: if device_id appears in removed_members for a team, handshake reconciliation skips it (already works in v2) + +**RC-2 (partial cleanup):** +- Make cleanup idempotent: `compute_and_apply_device_lists` can always re-derive the correct state +- Do NOT delete team from DB until Syncthing cleanup succeeds +- Use the `pending_leave` column (added in v18 schema) for durability: + - On cleanup start: `UPDATE sync_teams SET pending_leave = datetime('now') WHERE name = ?` + - On cleanup success: `DELETE FROM sync_teams WHERE name = ?` + - On startup: `SELECT name FROM sync_teams WHERE pending_leave IS NOT NULL` to retry interrupted cleanups +- Retry on every 60s timer cycle. After 5 failed attempts (5 minutes), log an error and surface via the API (`GET /sync/teams` should show teams with `pending_leave` status). No automatic escalation — user must manually resolve. + +**RC-3 (no change needed):** +- Handled gracefully by v2, confirmed in audit. + +**RC-4 (concurrent ensure_outbox_folder):** +- `set_folder_devices` is idempotent (sets to desired state), but two concurrent calls may compute DIFFERENT desired states if the DB changes between reads +- Safety is ensured by `client._config_lock` (RLock in `cli/karma/syncthing.py:59`) which serializes all config mutations +- `set_folder_devices` MUST acquire `client._config_lock` for the full GET-compute-PUT cycle (see existing lock pattern at `syncthing_proxy.py:231` and `:293`) +- This prevents interleaving of concurrent config mutations that would produce inconsistent results + +**RC-5 (SQLite contention):** +- No change needed. WAL mode + single writer connection is sufficient for the single-machine model. + +--- + +## Implementation Phases + +### Phase 1: Declarative Device Lists (Foundation) + +**Depends on:** Nothing (can be deployed independently) + +**Scope:** +- New function `compute_union_devices(conn, suffix)` in `sync_folders.py` +- New function `compute_and_apply_device_lists(proxy, config, conn, team_name)` in `sync_folders.py` +- New proxy method `set_folder_devices(folder_id, device_ids)` in `syncthing_proxy.py` +- Modify `ensure_outbox_folder` and `ensure_inbox_folders` to use `compute_union_devices` +- **Complete v18 schema migration** (atomic, all changes in this phase): + - Add `folder_suffix` column to `sync_team_projects` + - Add `pending_leave` column to `sync_teams` + - Recreate `sync_rejected_folders` with team-scoped PK `(folder_id, team_name)` + - Drop unattributable rejections during migration + - Add index on `sync_team_projects(folder_suffix)` +- Backfill `folder_suffix` values + +**Files modified:** +- `api/services/sync_folders.py` — new functions, modify ensure_* functions +- `api/services/syncthing_proxy.py` — new `set_folder_devices` method +- `api/db/sync_queries.py` — new query `compute_union_devices` +- `api/db/schema.py` — complete v18 migration (all schema changes: folder_suffix, pending_leave, sync_rejected_folders recreation) +- `api/services/sync_identity.py` — modify `_compute_proj_suffix` to store result + +**Breakpoints fixed:** BP-2, BP-7, BP-13 (schema), BP-14 (schema), BP-18 + +**Acceptance criteria:** +- `compute_union_devices` returns correct set for single-team and multi-team cases +- `set_folder_devices` correctly adds and removes devices +- `set_folder_devices` acquires `client._config_lock` for the full GET-compute-PUT cycle +- `ensure_outbox_folder` uses union query with `owner_member_tag` constraint +- `folder_suffix` populated for all existing team projects +- `pending_leave` column exists in `sync_teams` +- `sync_rejected_folders` has `(folder_id, team_name)` PK after migration +- Unattributable rejections are dropped during migration (logged) +- Folder count warning logged at 200 folders, error at 500 +- Existing tests pass + +--- + +### Phase 2: Explicit Mesh Pairing (Replace Introducer) + +**Depends on:** Phase 1 (needs `compute_and_apply_device_lists`) + +**Scope:** +- New function `mesh_pair_from_metadata(proxy, config, conn)` in `sync_reconciliation.py` +- Remove `ensure_leader_introducers()` function +- Remove `reconcile_introduced_devices()` function +- Modify join flow: `introducer=False` on `add_device` +- Migration: disable existing introducer flags on startup + +**Files modified:** +- `api/services/sync_reconciliation.py` — replace reconcile_introduced_devices, remove ensure_leader_introducers +- `api/routers/sync_teams.py` — join flow, remove introducer flag +- `api/routers/sync_devices.py` — update reconciliation phase order + +**Breakpoints fixed:** BP-5, BP-6 + +**Acceptance criteria:** +- No device has `introducer=True` after migration +- Joining a team does NOT propagate foreign teams' devices +- Peers discover each other via metadata folder reading +- `mesh_pair_from_metadata` correctly pairs undiscovered devices + +--- + +### Phase 3: Cross-Team Safe Cleanup + +**Depends on:** Phase 1 (needs `compute_and_apply_device_lists` and `set_folder_devices`) + +**Scope:** +- Rewrite `cleanup_syncthing_for_team` to use device subtraction +- Rewrite `cleanup_syncthing_for_member` to use device subtraction +- New function `cleanup_for_project_removal` +- Make `_auto_leave_team` idempotent (don't delete team if cleanup fails) + +**Files modified:** +- `api/services/sync_folders.py` — rewrite cleanup functions +- `api/services/sync_metadata_reconciler.py` — idempotent auto-leave +- `api/db/sync_queries.py` — helper queries for cross-team checks + +**Breakpoints fixed:** BP-3, BP-4, RC-2 + +**Acceptance criteria:** +- Leaving Team A does NOT remove folders used by Team B +- Removing member from Team A does NOT remove their inbox if shared with Team B +- `_auto_leave_team` retries cleanup on next cycle if it fails +- Cleanup is idempotent (running twice produces same result) + +--- + +### Phase 4: Edge Cases and Hardening + +**Depends on:** Phases 1-3 + +**Scope:** +- BP-9: member_tag collision detection at join/accept +- BP-12: Two-phase folder sharing (metadata first, then projects) +- BP-13: Immutable folder_suffix (store in DB, don't recompute) +- BP-14: Team-scoped rejected folders (query changes; schema already migrated in Phase 1) +- EC-2: Device ID change detection and re-join notification +- EC-6: Team-scoped rejection in `compute_and_apply_device_lists` +- RC-1: `pending_leave` guard in reconciliation (uses durable column from v18 schema) + +**Files modified:** +- `api/services/sync_reconciliation.py` — collision detection, `pending_leave` guard +- `api/services/sync_folders.py` — two-phase sharing, rejection checks +- `api/db/sync_queries.py` — team-scoped rejection queries (using v18 schema from Phase 1) +- `api/services/sync_metadata_reconciler.py` — device ID change detection +- `cli/karma/config.py` — device ID change detection on startup + +**Breakpoints fixed:** BP-9, BP-12, BP-13, BP-14, EC-1, EC-2, EC-6, RC-1 + +**Acceptance criteria:** +- Duplicate member_tag at join time produces clear error +- New member receives metadata folder before project folders +- Changing git remote does NOT create orphaned folders +- Rejecting a folder in Team A does NOT affect Team B +- Reinstalling Syncthing is detected on startup; user is warned to re-join teams +- Auto-leave and reinvite do not race (`pending_leave` column prevents team re-creation during cleanup) + +--- + +## Commit Strategy + +| Phase | Commits | Description | +|---|---|---| +| Phase 1 | 3-4 | Complete v18 schema migration, compute_union_devices, set_folder_devices, integrate into ensure_* | +| Phase 2 | 2-3 | mesh_pair_from_metadata, remove introducer code, migration step | +| Phase 3 | 2-3 | Rewrite cleanup functions, idempotent auto-leave | +| Phase 4 | 4-5 | One commit per edge case fix (BP-9, BP-12, BP-13/14 queries, EC-2, RC-1) | + +Total: ~12-15 commits across 4 phases. + +--- + +## Success Criteria + +### Functional + +1. A device in 4 teams sharing overlapping projects has correct folder device lists (union of all relevant teams, no leaks) +2. Leaving Team A does not break sync for Team B (even if they share projects) +3. Removing member M from Team A does not affect M's membership in Team B +4. No phantom team creation (no introduced artifacts from foreign teams) +5. Folder rejections are team-scoped (rejecting in Team A does not affect Team B) +6. Device ID change (Syncthing reinstall) is detected on startup and user is warned to re-join teams; stale device entries are cleaned up by peers via `compute_and_apply_device_lists` + +### Performance + +7. Total folder count per device stays under 200 for the target scale (10 teams, 20 projects, 10 members) +8. Device list recomputation completes in under 2 seconds for target scale +9. No increase in Syncthing REST API calls during normal operation (recomputation is event-driven, not polling) + +### Migration + +10. v2 to v3 migration is automatic (runs on first startup) +11. v2 and v3 devices can coexist during migration window +12. No data loss during migration (session data, team memberships, settings preserved) + +--- + +## Integration Test Strategy: Multi-Team Overlap + +The audit document's 4-team test setup (section 9) provides the basis for integration tests. The test setup uses 4 machines (M1-M4) across 3 users, with 4 teams sharing overlapping projects: + +| Team | Members | Projects | +|------|---------|----------| +| T1 | M1, M2, M3 | P1, P2 | +| T2 | M1, M2 | P2, P3 | +| T3 | M2, M3, M4 | P1, P3 | +| T4 | M1, M4 | P2 | + +Key test scenarios derived from this setup: + +1. **Union device list correctness:** M1's outbox for P2 should include devices from T1, T2, T4 (all teams where M1 is a member AND P2 is shared). Must NOT include M4's T3 device for P2 (M4 is in T3, but P2 is not in T3). +2. **Leave team — device subtraction:** M1 leaves T2. M1's P2 outbox should still include T1 and T4 devices. M1's P3 outbox should become empty (only T2 claimed P3 for M1) and be deleted. +3. **Remove member — cross-team preservation:** Remove M2 from T1. M2's P1 outbox should still include T3 devices. M2's P2 outbox should still include T2 devices. +4. **Folder rejection — team-scoped:** M3 rejects P1 in T1. M3 should still receive P1 from T3. +5. **Device ID change:** M4 reinstalls Syncthing. M4's stale device_id is cleaned up from T3 and T4 folders by peers on next recompute cycle. +6. **Non-git suffix collision prevention:** Two non-git projects with different paths but same CLI name in the same team should be rejected with a collision error. +7. **Manual project mapping:** After `karma project map`, `resolve_local_project` should return the mapped path. +8. **Manifest project_name:** Packaged manifest.json should include `project_name` field for both git and non-git projects. + +Tests should use mocked Syncthing API responses and in-memory SQLite to validate the SQL queries and reconciliation logic without requiring actual Syncthing instances. + +--- + +## Must Have + +- Declarative device list management (compute desired state, apply diff) +- Explicit mesh pairing (no introducer flags) +- Cross-team safe cleanup (device subtraction, not folder deletion) +- Team-scoped folder rejections +- member_tag collision detection +- Backward-compatible migration from v2 + +## Must NOT Have + +- Team-scoped folder IDs (rejected — causes session duplication) +- Central coordination server (violates P2P constraint) +- Breaking changes to metadata folder format (must be backward compatible) +- Manual migration steps (must be automatic on startup) +- New folder types (outbox/inbox/handshake/metadata is sufficient) + +--- + +## Appendix: Key Query — Union Device List + +The core query that enables the project channel model. All variants include the `owner_member_tag` constraint to scope results to teams where the folder owner is a member (see C1 fix in ADR-3). + +### Variant 1: Base union (for `compute_and_apply_device_lists`) + +```sql +-- Given a folder suffix and owner, compute all devices that should have access +-- across all teams that share a project with that suffix AND include the owner. +-- +-- Input: :suffix (e.g., "jayantdevkar-claude-karma"), :owner_member_tag +-- Output: set of device_ids + +SELECT DISTINCT sm.device_id +FROM sync_team_projects stp +JOIN sync_members sm ON sm.team_name = stp.team_name +WHERE stp.folder_suffix = :suffix + AND sm.device_id IS NOT NULL + AND sm.device_id != '' + AND stp.team_name IN ( + SELECT team_name FROM sync_members + WHERE member_tag = :owner_member_tag + ) +``` + +### Variant 2: For a specific member's outbox (includes owner's own devices) + +```sql +-- Union of team devices for the owner's outbox folder. +-- The owner_member_tag is extracted from the folder ID. +-- Owner's own devices are included automatically because the owner +-- is a member of the teams returned by the subquery. +-- +-- Input: :suffix, :owner_member_tag +SELECT DISTINCT sm.device_id +FROM sync_team_projects stp +JOIN sync_members sm ON sm.team_name = stp.team_name +WHERE stp.folder_suffix = :suffix + AND sm.device_id IS NOT NULL + AND sm.device_id != '' + AND stp.team_name IN ( + SELECT team_name FROM sync_members + WHERE member_tag = :owner_member_tag + ) +``` + +### Variant 3: For cleanup (excluding a specific team) + +```sql +-- Union WITHOUT a specific team, still scoped to owner's teams +-- Used by cleanup_for_team_leave and cleanup_for_project_removal +-- +-- Input: :suffix, :excluded_team, :owner_member_tag +SELECT DISTINCT sm.device_id +FROM sync_team_projects stp +JOIN sync_members sm ON sm.team_name = stp.team_name +WHERE stp.folder_suffix = :suffix + AND stp.team_name != :excluded_team + AND sm.device_id IS NOT NULL + AND sm.device_id != '' + AND stp.team_name IN ( + SELECT team_name FROM sync_members + WHERE member_tag = :owner_member_tag + ) +``` diff --git a/docs/design/sync-v3-audit-findings.md b/docs/design/sync-v3-audit-findings.md new file mode 100644 index 00000000..ca499359 --- /dev/null +++ b/docs/design/sync-v3-audit-findings.md @@ -0,0 +1,1089 @@ +# Sync v2 Audit Findings — Multi-Team Scalability Analysis + +> **Date:** 2026-03-13 +> **Status:** Observations for v3 design input +> **Scope:** Multi-team, multi-member, multi-project overlap behaviors +> **Audience:** Agents and developers designing sync v3 + +--- + +## Table of Contents + +1. [Test Setup](#1-test-setup) +2. [Component Behavior Observations](#2-component-behavior-observations) +3. [Timeline Walkthrough: T4 → T3 → T2 → T1](#3-timeline-walkthrough) +4. [Cross-Team Overlap Matrix](#4-cross-team-overlap-matrix) +5. [Observed Breakpoints (BP-1 through BP-8)](#5-observed-breakpoints) +6. [Syncthing Primitive Behaviors](#6-syncthing-primitive-behaviors) +7. [Reconciliation Loop Observations](#7-reconciliation-loop-observations) +8. [Race Conditions & Timing](#8-race-conditions--timing) +9. [Edge Cases (EC-1 through EC-7)](#9-edge-cases) +10. [Filesystem & Data Flow Observations](#10-filesystem--data-flow-observations) +11. [Scalability Observations](#11-scalability-observations) +12. [Additional Breakpoints (BP-9 through BP-18)](#12-additional-breakpoints-investigated) +13. [Observations That Work Correctly (OK-1 through OK-7)](#13-observations-that-work-correctly) +14. [Open Questions for v3](#14-open-questions-for-v3) + +--- + +## 1. Test Setup + +### Devices + +| Label | User | member_tag | Description | +|-------|------|------------|-------------| +| M1 | Jayant | `jayant.macbook` | Jayant's MacBook | +| M2 | Jayant | `jayant.mac-mini` | Jayant's Mac Mini (same user, different machine) | +| M3 | Alice | `alice.laptop` | Alice's Laptop | +| M4 | Bruce | `bruce.mac-mini` | Bruce's Mac Mini | +| M5 | ? | `?.?` | Additional member | +| M6 | ? | `?.?` | Additional member | + +### Teams (creation order: T4 → T3 → T2 → T1) + +| Team | Leader | Members | Projects | +|------|--------|---------|----------| +| T4 | M4 | M1, M3, M5, M6 | P1, P2, P3 | +| T3 | M2 | M3, M2, M1 | P3 | +| T2 | M3 | M3, M1 | P2 | +| T1 | M1 | M1, M2 | P1 | + +### Assumptions for This Analysis + +- All members already have the shared projects locally +- Leaders share the projects after team creation +- Members join one after another via join code +- Default settings (auto_accept=false, sync_direction=both) + +--- + +## 2. Component Behavior Observations + +### 2.1 Folder ID Format + +**Observed:** Folder IDs use format `karma-out--{member_tag}--{suffix}` where suffix derives from `git_identity` (replace `/` with `-`) or project encoded name. + +**Observation:** The folder ID contains NO team identifier. The same (member_tag, project) pair across multiple teams produces the **identical folder ID**. + +``` +File: api/services/folder_id.py + +karma-out--{member_tag}--{suffix} ← session outbox/inbox +karma-join--{member_tag}--{team_name} ← handshake (HAS team) +karma-meta--{team_name} ← metadata (HAS team) +``` + +Only outbox/inbox folders lack team scoping. + +### 2.2 update_folder_devices Is Additive (Union) + +**Observed in:** `api/services/syncthing_proxy.py` + +`update_folder_devices(folder_id, device_ids)` **adds** devices to the existing folder device list. It never removes devices. It skips duplicates. + +**Implication:** Once a device is added to a folder, there is no code path in `ensure_outbox_folder` or `ensure_inbox_folders` that removes it. The device list is monotonically growing during normal operation. + +### 2.3 Cleanup Removes Entire Folders + +**Observed in:** `api/services/sync_folders.py:355-426` + +`cleanup_syncthing_for_team()` matches outbox folders by `(member_tag in team_members AND suffix in team_project_suffixes)` and calls `proxy.remove_folder()` — removing the **entire folder**, not individual devices. + +**Observation:** There is NO cross-team check before folder removal. The only cross-team check exists for **devices** (line 415-418): +```python +other_count = conn.execute( + "SELECT COUNT(*) FROM sync_members WHERE device_id = ? AND team_name != ?", + (device_id, team_name), +).fetchone()[0] +if other_count == 0: + # only then remove device +``` + +No equivalent query exists for folders: +```python +# THIS DOES NOT EXIST: +# "SELECT COUNT(*) FROM sync_team_projects WHERE project_suffix = ? AND team_name != ?" +``` + +### 2.4 Cleanup for Member Removal + +**Observed in:** `api/services/sync_folders.py:429-487` + +`cleanup_syncthing_for_member()` behavior: +- If folder is MY outbox → removes member's device from the folder (`remove_device_from_folder`) +- If folder is the MEMBER's outbox → removes the **entire inbox folder** (`remove_folder`) + +**Observation:** No cross-team check on inbox removal. If the removed member is in another team sharing the same project, their inbox folder is destroyed for all teams. + +### 2.5 Introducer Flag Behavior + +**Observed in:** `api/routers/sync_teams.py` (join flow) and `api/services/sync_reconciliation.py` + +When a device joins a team: +1. Joiner pairs leader with `introducer=True` +2. `ensure_leader_introducers()` re-enforces this flag on every `GET /sync/pending-devices` poll + +**Observation:** The introducer flag is: +- Set per-device globally in Syncthing (not per-team) +- Permanent once set (no code path disables it after handshake) +- Re-enforced by `ensure_leader_introducers()` which iterates ALL teams' join codes + +### 2.6 Reconciliation Creates Teams From Introduced Artifacts + +**Observed in:** `api/services/sync_reconciliation.py:220-364` + +`reconcile_pending_handshakes()` processes pending `karma-join--*` folders from already-configured devices. If the team doesn't exist locally: +```python +if not team_exists: + create_team(conn, team_name, backend="syncthing") +``` + +**Observation:** This auto-creates teams from ANY handshake folder that arrives, regardless of whether the device was invited to that team. + +### 2.7 Metadata Reconciliation Timer + +**Observed in:** `api/services/watcher_manager.py:118-171` and `api/services/sync_metadata_reconciler.py` + +- Runs every 60 seconds as a daemon thread +- Reads `metadata-folders/{team}/members/*.json` and `removals/*.json` +- Discovers new members and detects removal signals +- `auto_leave=True` triggers `cleanup_syncthing_for_team()` + `delete_team()` on removal detection + +### 2.8 Pending Devices Endpoint Runs All Reconciliation + +**Observed in:** `api/routers/sync_devices.py` + +`GET /sync/pending-devices` runs 4 phases sequentially: +1. `ensure_leader_introducers()` — re-sets introducer flags +2. `reconcile_introduced_devices()` — discovers introduced peers +3. `reconcile_pending_handshakes()` — processes handshake folders +4. `auto_accept_pending_peers()` — accepts pending devices + +**Observation:** This is the primary trigger for reconciliation during active use. The 60s metadata timer is the secondary mechanism. + +--- + +## 3. Timeline Walkthrough + +### Phase 1: T4 Created (Leader M4) + +**M4 creates T4, shares P1, P2, P3:** +``` +M4 Syncthing state: + karma-meta--T4 (sendreceive) + karma-out--bruce.mac-mini--P1_suffix (sendonly) + karma-out--bruce.mac-mini--P2_suffix (sendonly) + karma-out--bruce.mac-mini--P3_suffix (sendonly) + Devices: [self] +``` + +**M1 joins T4 (join code: T4:bruce:DID_M4):** +``` +M1 actions: + Pairs DID_M4 with introducer=True + Creates karma-join--jayant.macbook--T4 (sendonly, shared with DID_M4) + Creates karma-meta--T4 (sendreceive, shared with DID_M4) + +M4 reconciliation (on next GET /sync/pending-devices): + auto_accept_pending_peers → sees DID_M1 offering handshake + Handshake bypass: skips auto_accept policy check + add_device(DID_M1) + upsert_member(T4, jayant.macbook, DID_M1) + auto_share_folders(T4, DID_M1): + karma-out--bruce.mac-mini--P1 → add DID_M1 to device list + karma-out--bruce.mac-mini--P2 → add DID_M1 + karma-out--bruce.mac-mini--P3 → add DID_M1 + Create karma-out--jayant.macbook--P1 (receiveonly, inbox for M1) + Create karma-out--jayant.macbook--P2 (receiveonly) + Create karma-out--jayant.macbook--P3 (receiveonly) + +M1 pending folders appear: + karma-out--bruce.mac-mini--P1/P2/P3 → "Receive from bruce" + karma-out--jayant.macbook--P1/P2/P3 → "Send your sessions for..." + M1 accepts all +``` + +**M3 joins T4:** + +Same flow as M1. M4 accepts, runs auto_share_folders. + +**Introducer propagation observed:** +- M3 set DID_M4 as introducer +- M4 has DID_M1 configured +- Syncthing propagates DID_M1 to M3 automatically +- M3's Syncthing auto-adds DID_M1 + any folders M4 shares with M1 + +**M3's reconcile_introduced_devices:** +- Finds DID_M1 (unknown, introduced by M4) +- Extracts team_name=T4 from folder parsing +- upsert_member(T4, jayant.macbook, DID_M1) +- auto_share_folders(T4, DID_M1) + +**Reverse propagation:** +- M1 has DID_M4 as introducer +- M4 now has DID_M3 → propagates to M1 +- M1 discovers M3, adds as T4 member + +**M5, M6 join:** Same pattern. Full mesh forms via introducer cascades. + +**T4 end state per device: ~17 Syncthing folders** (1 meta + 1 handshake + 3 outboxes + 12 inboxes for 4 peers × 3 projects) + +**Observation:** Single-team operation works correctly. No issues observed. + +--- + +### Phase 2: T3 Created (Leader M2) + +M2 has no prior sync state. Creates T3, shares P3. + +**M3 joins T3:** +``` +M3 pairs DID_M2 with introducer=True ← M3 now trusts M2 as introducer +M3 creates karma-join--alice.laptop--T3 +M3 creates karma-meta--T3 +``` + +M2 accepts M3. auto_share_folders creates P3 outbox/inbox. + +**Introducer observation:** M3 set M2 as introducer. M2 currently only has M3 → no additional devices propagated yet. + +**M1 joins T3:** +``` +M1 pairs DID_M2 with introducer=True ← M1 now trusts M2 as introducer +M1 creates karma-join--jayant.macbook--T3 +``` + +M2 accepts M1. auto_share_folders: +``` +For P3: + ensure_outbox: karma-out--jayant.mac-mini--P3_suffix (M2's outbox) + devices → [DID_M1, DID_M3, DID_M2] + ensure_inbox: karma-out--jayant.macbook--P3_suffix (M1's outbox, receiveonly) +``` + +**Observation — same-user member_tag differentiation works:** +- M1's outbox: `karma-out--jayant.macbook--P3_suffix` +- M2's outbox: `karma-out--jayant.mac-mini--P3_suffix` +- Different member_tags → different folder IDs → no collision for this pair. + +**Introducer propagation from M2:** +- M3 trusts M2 as introducer. M2 now has DID_M1. M3 already has DID_M1 from T4. No new info. +- M1 trusts M2 as introducer. M2 now has DID_M3. M1 already has DID_M3 from T4. No new info. + +**Observation:** No cross-team leakage YET because M2 only has T3 members, which overlap with T4 anyway. + +**HOWEVER — Folder ID Collision Detected:** + +M1's P3 outbox for T4: `karma-out--jayant.macbook--P3_suffix` +M1's P3 outbox for T3: `karma-out--jayant.macbook--P3_suffix` + +**Same folder ID.** When T3 calls `ensure_outbox_folder`, it calls `update_folder_devices` on the EXISTING T4 folder. + +``` +Before T3: karma-out--jayant.macbook--P3 devices = [DID_M3, DID_M4, DID_M5, DID_M6] (T4) +After T3: karma-out--jayant.macbook--P3 devices = [DID_M3, DID_M4, DID_M5, DID_M6, DID_M2] (T4 ∪ T3) +``` + +**Since update_folder_devices is additive, DID_M2 gets ADDED to T4's folder.** M2 can now receive M1's P3 sessions even though M2 is not in T4. + +Same collision for M3's P3 outbox: `karma-out--alice.laptop--P3_suffix` +- T4 devices + T3 device (DID_M2 added) +- M2 receives M3's P3 sessions via T4's folder — M2 is only in T3. + +**Observation:** The additive behavior means cross-team device leakage is silent and cumulative. Devices from team B appear on team A's folder without any explicit sharing decision. + +--- + +### Phase 3: T2 Created (Leader M3) + +M3 creates T2, shares P2. + +**M1 joins T2:** +``` +M1: add_device(DID_M3) → already exists (from T4) +M1: set_device_introducer(DID_M3, True) ← M1 now trusts M3 as introducer +``` + +**Observation — Introducer flag accumulation on M1:** +``` +M1's introducer trust list: + DID_M4 = introducer (from T4 join) + DID_M2 = introducer (from T3 join) + DID_M3 = introducer (from T2 join) ← NEW +``` + +M1 now trusts 3 different devices as introducers. Each will propagate ALL their devices and folders to M1. + +**Folder collision — M3's P2 outbox:** +``` +T4 outbox: karma-out--alice.laptop--P2_suffix devices=[DID_M1, DID_M4, DID_M5, DID_M6] +T2 calls ensure_outbox with devices=[DID_M1] +After: devices=[DID_M1, DID_M4, DID_M5, DID_M6] (additive, M1 already there) +``` + +No NEW devices added in this case because all T2 members (M1) are already in T4's device list. But the system made no conscious decision about this — it's an accident of the additive behavior. + +--- + +### Phase 4: T1 Created (Leader M1) + +M1 creates T1, shares P1. + +**M2 joins T1:** +``` +M2: pair DID_M1 with introducer=True ← M2 now trusts M1 as introducer +``` + +**Observation — Introducer Nuclear Cascade:** + +M1's Syncthing config contains devices from ALL four teams: +``` +DID_M2 (T1, T3), DID_M3 (T4, T2, T3), DID_M4 (T4), DID_M5 (T4), DID_M6 (T4) +``` + +M1's Syncthing config contains folders from ALL four teams: +``` +karma-out--jayant.macbook--P1 (T4+T1), karma-out--jayant.macbook--P2 (T4), +karma-out--jayant.macbook--P3 (T4+T3), karma-out--bruce.mac-mini--P1/P2/P3, +karma-out--alice.laptop--P1/P2/P3, karma-out--jayant.mac-mini--P3, +karma-join--jayant.macbook--T4/T3/T2/T1, +karma-meta--T4/T3/T2/T1, plus all inbox folders... +``` + +**Via introducer, ALL of this propagates to M2.** + +M2 auto-receives: +``` +New devices: DID_M3, DID_M4, DID_M5, DID_M6 (none of which M2 shares a team with) +New folders: karma-join--jayant.macbook--T4 (T4 handshake — M2 is not in T4) + karma-join--jayant.macbook--T2 (T2 handshake — M2 is not in T2) + karma-out--bruce.mac-mini--* (T4 inbox folders) + karma-out--alice.laptop--* (T4/T2 inbox folders) + karma-meta--T4, karma-meta--T2 (metadata for non-joined teams) +``` + +**M2's reconciliation processes these artifacts:** + +`reconcile_pending_handshakes` on M2: +- Sees `karma-join--jayant.macbook--T4` from DID_M1 (configured device) +- Team "T4" doesn't exist in M2's DB +- **Creates T4 locally:** `create_team(conn, "T4", backend="syncthing")` +- Adds M1 as member, adds self as member +- Calls auto_share_folders(T4, DID_M1) + +`reconcile_introduced_devices` on M2: +- Unknown devices: DID_M4, DID_M5, DID_M6 +- Finds karma folders shared with them → extracts team_name=T4 +- upsert_member for each into T4 + +**Result: M2 becomes a phantom member of T4 (and T2) without invitation.** + +**Observation:** This is not a theoretical scenario. Given the test setup, this WILL happen whenever T1 is created with M1 as leader and M2 as joiner, because M1 has cross-team state from T4. + +--- + +## 4. Cross-Team Overlap Matrix + +### Member-Team Overlap + +``` + T4 T3 T2 T1 +M1 x x x x ← in ALL teams (maximum introducer exposure) +M2 x x +M3 x x x +M4 x +M5 x +M6 x +``` + +### Project-Team Overlap + +``` + P1 P2 P3 +T4 x x x +T3 x +T2 x +T1 x +``` + +### Folder ID Collisions (same member + same project + different teams) + +| Member | Project | Teams | Folder ID | Collision? | +|--------|---------|-------|-----------|-----------| +| M1 | P1 | T4, T1 | `karma-out--jayant.macbook--P1_suffix` | **YES** | +| M1 | P3 | T4, T3 | `karma-out--jayant.macbook--P3_suffix` | **YES** | +| M3 | P2 | T4, T2 | `karma-out--alice.laptop--P2_suffix` | **YES** | +| M3 | P3 | T4, T3 | `karma-out--alice.laptop--P3_suffix` | **YES** | +| M2 | P3 | T3 | `karma-out--jayant.mac-mini--P3_suffix` | No (single team) | +| M2 | P1 | T1 | `karma-out--jayant.mac-mini--P1_suffix` | No (single team) | + +**4 collisions** in this 4-team setup. Each collision causes silent cross-team device accumulation. + +### Introducer Leak Paths + +``` +M2 joins T1 → M1 is introducer for M2 + M1 knows [M3, M4, M5, M6] from T4 + → M2 gets T4 devices + folders (LEAK) + +M1 joins T2 → M3 is introducer for M1 + M3 knows [M4, M5, M6] from T4 + → M1 gets T4 devices (already has them, no new leak in this case) + +M3 joins T3 → M2 is introducer for M3 + M2 gains T4 artifacts from M1 later (via T1 join) + → M3 gets T4 artifacts back via M2 (but already has from T4) +``` + +**Observation:** Any device that overlaps teams becomes a bridge. The most dangerous path is always through the device with the highest team count (M1 in this setup). + +--- + +## 5. Observed Breakpoints + +### BP-1: Outbox Folder ID Has No Team Scope + +**Location:** `api/services/folder_id.py:build_outbox_id()` + +**Behavior:** `karma-out--{member_tag}--{suffix}` — no team in the ID. + +**Effect:** Same member sharing same project in N teams = 1 folder serving N teams. Device lists from all N teams merge silently (additive). Cleanup for any one team may destroy the folder for all N teams. + +### BP-2: update_folder_devices Is Additive-Only + +**Location:** `api/services/syncthing_proxy.py:update_folder_devices()` + +**Behavior:** Adds devices, never removes. No "set devices to exactly this list" operation. + +**Effect:** Once a device leaks into a folder via cross-team sharing, there is no code path to remove it during normal operation. The device list can only grow. + +**Paradox with cleanup:** Normal operation can only ADD devices. Cleanup can only REMOVE THE ENTIRE FOLDER. There is no "remove one team's devices from the folder" operation. + +### BP-3: Team Cleanup Has No Cross-Team Folder Guard + +**Location:** `api/services/sync_folders.py:355-426` + +**Behavior:** `cleanup_syncthing_for_team()` removes folders matching `(member_tag in team_members AND suffix in team_projects)`. No check for whether other teams share the same (member, project) pair. + +**Effect:** Leaving T2 (which shares P2) removes `karma-out--alice.laptop--P2_suffix` — the same folder T4 uses for M3's P2 sessions. T4's P2 sync from M3 breaks. + +### BP-4: Member Cleanup Removes Cross-Team Inboxes + +**Location:** `api/services/sync_folders.py:429-487` + +**Behavior:** When removing a member's inbox folder (their outbox), `remove_folder` is called without checking if the member is in another team sharing the same project. + +**Effect:** Removing M3 from T2 would remove `karma-out--alice.laptop--P2_suffix` entirely, breaking T4's inbox for M3's P2 sessions. + +### BP-5: Introducer Flag Is Global, Permanent, and Re-Enforced + +**Location:** Join flow in `sync_teams.py`, `ensure_leader_introducers()` in `sync_reconciliation.py` + +**Behavior:** The introducer flag is: +1. Set at Syncthing level (not team-scoped) +2. Never disabled after handshake +3. Re-enforced on every `GET /sync/pending-devices` poll + +**Effect:** A device marked as introducer for Team A will propagate ALL devices/folders (including from Teams B, C, D) to any device that trusts it. There's no way to limit the scope. + +### BP-6: Reconciliation Auto-Creates Phantom Teams + +**Location:** `api/services/sync_reconciliation.py:reconcile_pending_handshakes()` + +**Behavior:** When a handshake folder (`karma-join--X--TeamY`) arrives from a configured device for a team that doesn't exist locally, the code creates that team. + +**Effect:** Introduced handshake folders from other teams cause phantom team memberships. The device becomes a member of teams it was never invited to. + +### BP-7: No Device Removal From Folders (Only Folder Removal) + +**Location:** `api/services/sync_folders.py` — `ensure_outbox_folder`, `ensure_inbox_folders` + +**Behavior:** These functions only ADD devices. `remove_device_from_folder` exists in proxy but is only called in `cleanup_syncthing_for_member` for the caller's OWN outbox folders. + +**Effect:** When a member leaves a team, there is no operation to "remove just that team's claim" on a shared folder. The choices are: leave all leaked devices in place, or delete the entire folder. + +### BP-8: find_team_for_folder Returns First Match + +**Location:** `api/services/sync_folders.py:find_team_for_folder()` + +**Behavior:** Returns the first team that matches a folder by suffix. When the same project suffix exists in multiple teams, the result is ambiguous. + +**Effect:** Pending folder UI may attribute a folder to the wrong team. Rejection/acceptance decisions may be scoped to the wrong team. + +--- + +## 6. Syncthing Primitive Behaviors + +These are Syncthing (the underlying tool) behaviors that constrain the design: + +### 6.1 Introducer Mechanism + +When device A marks device B as "introducer": +- A auto-accepts ALL devices from B's cluster config +- A auto-accepts ALL folders that B shares with devices B introduces to A +- This is ALL-or-nothing — cannot scope to specific folders or teams +- The flag is per-device, global (not per-folder) + +### 6.2 Folder IDs Are Global + +- A folder ID is unique across the entire Syncthing instance +- Two folders cannot share the same ID (even if different paths) +- Folder IDs are the joining key between sender and receiver + +### 6.3 Device Pairing Is Global + +- Adding a device makes it available for ALL folders +- There is no "add device for folder X only" +- Device trust is binary: paired or not paired + +### 6.4 No Folder Namespacing + +- Syncthing has no concept of groups, teams, or namespaces +- All folders exist in a flat list +- The `karma-` prefix convention is the only isolation mechanism + +### 6.5 Folder Type Semantics + +- `sendonly`: Can only push changes, ignores remote changes +- `receiveonly`: Can only accept changes, local changes reverted +- `sendreceive`: Bidirectional sync (used for metadata folders) + +--- + +## 7. Reconciliation Loop Observations + +### 7.1 Two Independent Reconciliation Paths + +``` +Path A: API-driven (GET /sync/pending-devices) + 1. ensure_leader_introducers() ← re-enforces introducer flags + 2. reconcile_introduced_devices() ← discovers peers from introducer + 3. reconcile_pending_handshakes() ← processes team handshakes + 4. auto_accept_pending_peers() ← accepts pending devices + +Path B: Timer-driven (every 60 seconds) + 1. reconcile_all_teams_metadata() ← reads metadata folder + - Discovers new members from members/*.json + - Detects removal from removals/*.json + - Auto-leaves on removal detection +``` + +**Observation:** These paths are independent. Path A can add members that Path B then removes (if a removal signal exists). Path B can auto-leave a team that Path A tries to add members to. No mutual exclusion between them. + +### 7.2 Reconciliation Ordering Dependency + +Path A runs phases sequentially within a single API call. But across multiple devices, the ordering is non-deterministic: + +``` +Device X: [join T3] → [create handshake] → [create metadata] +Device Y: [poll pending] → [see handshake] → [auto-accept] → [share folders] +Device X: [poll pending] → [see pending folders] → [accept] +``` + +**Observation:** There is no global coordination. Each device runs reconciliation independently based on its local state + what Syncthing has synced so far. + +### 7.3 Removal Detection Latency + +``` +Creator writes removal signal → Syncthing syncs to removed device (seconds to minutes) +→ Metadata timer fires (up to 60 seconds) → is_removed() check → auto_leave() +``` + +**Observation:** Worst case: 60s timer + Syncthing sync delay. During this window, the removed device may still create new folders or accept pending offers. + +--- + +## 8. Race Conditions & Timing + +### RC-1: Auto-Leave vs Reinvite Race + +**Scenario:** +1. Removal signal detected → auto_leave begins +2. Simultaneously, another device sends a new handshake folder +3. reconcile_pending_handshakes recreates the team +4. auto_leave deletes the team +5. Handshake reconciliation fails (team gone) + +**No mutual exclusion exists** between the removal path and the invitation path. + +### RC-2: Partial Cleanup on Auto-Leave + +**Observed in:** `sync_metadata_reconciler.py:_auto_leave_team()` + +```python +try: + cleanup_syncthing_for_team(...) + syncthing_cleaned = True +except Exception: + logger.warning(...) # Continues anyway + +delete_team(conn, team_name) # Runs even if cleanup failed +``` + +**Observation:** If Syncthing cleanup fails but DB delete succeeds → orphaned Syncthing folders persist. No recovery mechanism. + +### RC-3: Metadata Sync Lag on Join + +**Scenario:** Device joins team. Metadata folder is created but hasn't synced yet. Other members' reconciliation reads an empty/partial metadata folder. + +**Observation:** `reconcile_metadata_folder()` handles this gracefully — it reads what's available and catches up on next cycle. But `validate_removal_authority()` has a DB fallback for when `team.json` hasn't synced yet. + +### RC-4: Concurrent ensure_outbox_folder Calls + +**Scenario:** Two async handlers call `ensure_outbox_folder` for the same folder ID simultaneously. + +**Observation:** Both call `update_folder_devices` (additive) → both may succeed but the second call adds no new devices. Not a correctness issue due to additive semantics, but the "try update, fall back to create" pattern could race: both fail update, both try create, one fails. + +### RC-5: Watcher Thread + API Thread SQLite Access + +**Observation:** `MetadataReconciliationTimer` runs in a daemon thread, using `get_writer_db()`. API handlers also use writer connections. SQLite's WAL mode allows concurrent reads but only one writer. If both paths try to write simultaneously, one blocks. + +The code uses `get_writer_db()` which returns a single connection — potential for connection contention under load. + +--- + +## 9. Edge Cases + +### EC-1: member_tag Collision + +**Scenario:** Two different users choose the same `user_id` AND have the same hostname. + +**Observation:** `member_tag = user_id.machine_tag`. If user_id="jay" and both machines are named "macbook-pro", both get `jay.macbook-pro`. The `user_id` validation (`^[a-zA-Z0-9_-]+$`) enforces format but not uniqueness. + +**Impact:** Identical folder IDs, session data mixed between users, removal signals target both. + +### EC-2: Device ID Changes (Syncthing Reinstall) + +**Scenario:** User reinstalls Syncthing → new device ID, same machine. + +**Observation:** The old device ID remains in all teams' member lists and folder device lists. The new device ID is unknown. No migration path exists — user must re-join all teams. + +**Stale state:** Old device entries persist in `sync_members`, `sync_removed_members`, metadata folder member files, and Syncthing folder device lists. + +### EC-3: git_identity Change + +**Scenario:** User changes the git remote URL of a project after folders are created. + +**Observation:** The folder suffix is computed from `git_identity` at share time and stored in `sync_team_projects.git_identity`. If the remote changes: +- Existing folders use old suffix → continue working +- New `share project` calls compute new suffix → create NEW folder +- Old and new folders coexist → session duplication + +No migration or update path for git_identity changes. + +### EC-4: Project Shared With No Sessions + +**Scenario:** Leader shares a project that has 0 local sessions. + +**Observation:** Works correctly — outbox folder is created but empty. Syncthing handles empty folders fine. Sessions will sync when they appear. + +### EC-5: Same Project, Different Local Paths + +**Scenario:** M1 has `~/GitHub/repo` and M3 has `~/code/repo`. Same git_identity. + +**Observation:** `_compute_proj_suffix()` uses `git_identity` when available → same suffix → same folder ID. Cross-machine path differences are handled by the project mapping system in `remote_sessions.py` using git_identity matching. + +### EC-6: Folder Rejection + Re-Share + +**Scenario:** M1 rejects `karma-out--alice.laptop--P2` via `POST /sync/pending/reject`. Later, M3 shares P2 in a new team with M1. + +**Observation:** `sync_rejected_folders` table persists rejection by folder_id. Since the folder ID is the same (no team scope), the rejection applies across teams. M1 would NOT receive M3's P2 sessions in the new team either. + +`unreject_folder()` is called on explicit accept, but automatic re-sharing via `auto_share_folders` does not check/clear rejections. + +### EC-7: Folder Count Scalability + +**Formula per device:** +``` +For each team T that device is in: + 1 metadata folder (karma-meta--T) + 1 handshake folder (karma-join--self--T) + For each project P in T: + 1 outbox (karma-out--self--P) ← shared across teams (collision) + N-1 inboxes (karma-out--peer--P) ← one per peer, shared across teams + +Total unique folders ≈ T_count × (2) + unique_projects × (1 + unique_peers_for_project) +``` + +For this setup (M1 in 4 teams, 3 projects, 5 peers): +``` +M1: 4×2 (meta+handshake) + 3 (outboxes) + 5×3 (inboxes) = 8 + 3 + 15 = 26 folders +``` + +With 10 teams × 5 projects × 20 members: `10×2 + 5 + 19×5 = 20 + 5 + 95 = 120 folders` + +**Observation:** Syncthing has been tested with hundreds of folders, but performance degrades with many small folders due to per-folder file watchers and status tracking. + +--- + +## 10. Filesystem & Data Flow Observations + +### 10.1 Session Packaging (Sender Side) + +**File:** `cli/karma/packager.py` + +``` +Local sessions: ~/.claude/projects/{encoded}/{uuid}.jsonl +Staging: /tmp/sync-staging/{encoded}/sessions/{uuid}.jsonl +Outbox: ~/.syncthing/karma-out--{member_tag}--{suffix}/sessions/{uuid}.jsonl + Also: manifest.json, titles.json, todos/, debug/, plans/ +``` + +**Observation:** The packager copies sessions to ONE outbox path per project. With team-scoped folder IDs, it would need to copy to N outbox paths (one per team sharing the project). + +### 10.2 Session Discovery (Receiver Side) + +**File:** `api/services/remote_sessions.py` + +``` +Inbox: ~/.claude_karma/remote-sessions/{user_dir}/{encoded}/sessions/{uuid}.jsonl +``` + +Scans inbox directories, reads manifest.json for identity, resolves local project via git_identity mapping. + +**Observation on dedup:** No active deduplication. Relies on unique UUIDs per session. If the same session appeared in two different inbox paths (possible with cross-team folder sharing), both would be discovered. The API layer does not dedup by (uuid, remote_user_id). + +### 10.3 Manifest Contains Identity + +Each outbox contains `manifest.json` with: +```json +{ + "user_id": "jayant", + "machine_id": "mac-mini", + "member_tag": "jayant.mac-mini", + "device_id": "...", + "project_path": "...", + "git_identity": "jayantdevkar/claude-karma", + "sessions": [{"uuid": "...", "mtime": "...", "size_bytes": ...}] +} +``` + +**Observation:** `device_id` in manifest enables authoritative identity resolution. If the same physical outbox serves multiple teams, the manifest is the same — no team-specific metadata. + +--- + +## 11. Scalability Observations + +### 11.1 The "Additive-Only + Delete-All" Paradox + +The system has two modes for device lists: +1. **During operation:** Devices accumulate (additive only, no removal) +2. **During cleanup:** Entire folder removed (all or nothing) + +There is no "surgical removal" of specific devices from a folder based on team membership. This creates a fundamental impedance mismatch: +- **Teams are dynamic** (members join/leave frequently) +- **Folder device lists are append-only** (until folder deletion) +- **Folder deletion is cross-team destructive** (affects all teams sharing the folder) + +### 11.2 The "Introducer Scope" Problem + +Syncthing's introducer is per-device, not per-team. In a multi-team setup: +- Every join adds a new introducer trust +- Introducers propagate ALL their state (not just the team's) +- The more teams a device is in, the more it leaks across boundaries + +**Growth pattern:** A device in N teams trusts up to N introducers, each potentially bridging their teams' device lists into the current device. + +### 11.3 Session Data Is Inherently Per-Project + +Sessions are written to `~/.claude/projects/{encoded}/{uuid}.jsonl`. There is no team concept at the session level. A session belongs to a project, not a team. + +**Implication:** The "who gets my sessions" decision should be per-project (union of teams), not per-team (requiring duplication). + +### 11.4 Device List Is the Only Access Control + +Syncthing has no ACL system. The folder's device list IS the access control. Any device in the list receives the folder's content. The only way to revoke access is to remove the device from the list (or delete the folder). + +--- + +## 12. Additional Breakpoints (Investigated) + +### BP-9: member_tag Collision — No Validation + +**Location:** `cli/karma/config.py:20-32`, `api/routers/sync_devices.py:64-75` + +**Observation:** `_sanitize_machine_tag()` sanitizes hostname to `[a-z0-9-]+` but provides NO collision detection. No runtime check exists at pair/accept time. Two different users on machines with the same hostname choosing the same `user_id` produce identical `member_tag` values. + +**Example:** User "alice" on two different physical machines both named "macbook" → both produce `alice.macbook` → identical folder IDs, session data mixed, removal signals target both. + +**Missing code:** +```python +# Nothing like this exists in the accept/join flow: +existing = conn.execute( + "SELECT device_id FROM sync_members WHERE member_tag = ? AND device_id != ?", + (member_tag, new_device_id) +).fetchone() +if existing: + raise HTTPException(409, "member_tag collision") +``` + +### BP-10: Device ID Reuse After Syncthing Reinstall + +**Location:** `api/db/sync_queries.py:110-143` + +**Observation:** `upsert_member()` has deletion logic for same-name, different-device_id: +```python +conn.execute( + "DELETE FROM sync_members WHERE team_name = ? AND name = ? AND device_id != ?", + (team_name, name, device_id), +) +``` + +This works IF the name stays the same. But old entries with the old device_id persist in: +- Syncthing folder device lists (stale device still listed) +- Metadata folder member files (old device_id in JSON) +- `sync_removed_members` table (old device_id blocks re-join) + +No automatic cleanup of orphaned device entries when Syncthing is reinstalled. User must re-join all teams manually. + +### BP-11: No Per-Folder Locking for Concurrent Operations + +**Location:** `api/services/sync_folders.py:69-87` + +**Observation:** `ensure_outbox_folder()` uses try-update, fallback-to-add pattern with no locking: +```python +try: + await run_sync(proxy.update_folder_devices, folder_id, device_ids) +except ValueError: + await run_sync(proxy.add_folder, folder_id, path, all_ids, mode) +``` + +Two concurrent async handlers calling `ensure_outbox_folder` for the same folder_id can both fail the update, both try to create, one fails. Not a data corruption risk (Syncthing rejects duplicate folder creation), but can cause error logs and missed folder setup. + +No `asyncio.Lock()` per folder_id exists anywhere in the codebase. + +### BP-12: Folder Acceptance Before Metadata Sync + +**Location:** `api/services/sync_folders.py:300-312` (`auto_share_folders`) + +**Observation:** `auto_share_folders()` reads `member_subscriptions` from metadata folder: +```python +for state in read_all_member_states(meta_dir): + device = state.get("device_id", "") + subs = state.get("subscriptions", {}) + if device: + member_subscriptions[device] = subs +``` + +If metadata folder hasn't synced yet (common during initial join), `read_all_member_states()` returns empty list → subscriptions dict is empty → all projects are shared regardless of member's opt-out preferences. + +**Ordering dependency:** The system assumes metadata folder syncs before project folders are offered. No explicit check or wait exists. + +### BP-13: git_identity Change Creates Orphaned Folders + +**Location:** `api/services/sync_identity.py:171-175` + +**Observation:** Folder suffix is computed from `git_identity` at share time: +```python +def _compute_proj_suffix(git_identity, path, encoded): + if git_identity: + return git_identity.replace("/", "-") +``` + +If `git_identity` changes (repo transfer, remote rename): +1. Old folders use old suffix → continue working but orphaned +2. New share computes new suffix → creates NEW folder with new ID +3. Both old and new folders coexist → session duplication on receiver +4. No migration, detection, or cleanup path exists for this scenario + +### BP-14: sync_rejected_folders Not Team-Scoped + +**Location:** `api/db/sync_queries.py:reject_folder()` + +**Observation:** Rejection is stored by `folder_id` (which lacks team scope). Rejecting `karma-out--alice.laptop--P2_suffix` in T2 context also rejects it for T4, since both teams produce the identical folder_id. + +`auto_share_folders()` does not check/clear rejections. Only explicit `POST /sync/pending/accept/{folder_id}` calls `unreject_folder()`. + +### BP-15: No Folder Count Safeguard + +**Observation:** No validation exists for total folder count per Syncthing instance. Formula: +``` +Folders per device ≈ T×2 + P×(M×T - 1) +``` + +At scale (10 teams, 20 projects, 10 members): ~2000 folders. Syncthing performance degrades above ~500-1000 folders (file watcher overhead, REST API response times, inode limits). + +No rate limiting, no warning, no hard cap in the codebase. + +### BP-16: Partial Cleanup on Auto-Leave + +**Location:** `api/services/sync_metadata_reconciler.py:169-214` + +**Observation:** `_auto_leave_team()` continues to `delete_team()` even if Syncthing cleanup fails: +```python +try: + cleanup_syncthing_for_team(...) + syncthing_cleaned = True +except Exception: + logger.warning(...) # CONTINUES ANYWAY + +delete_team(conn, team_name) # Runs even if cleanup failed +``` + +Result: Orphaned Syncthing folders persist. No recovery mechanism. Next reconciliation cycle won't find the team (deleted from DB) so won't retry cleanup. + +### BP-17: Auto-Leave vs Reinvite Race + +**Location:** `api/services/sync_metadata_reconciler.py:151-166` + +**Observation:** No mutual exclusion between: +1. Timer-driven `_auto_leave_team()` (detects removal signal) +2. API-driven `reconcile_pending_handshakes()` (processes new join) + +If a device is removed and simultaneously re-invited: +- Timer detects removal → starts cleanup +- API processes new handshake → creates team + member +- Timer finishes → deletes team +- Result: Re-invite silently lost + +### BP-18: remove_device_from_folder Exists But Underused + +**Location:** `api/services/syncthing_proxy.py:231-272` + +**Observation:** `remove_device_from_folder(folder_id, device_id)` exists and works correctly — it removes a single device from a folder's device list without deleting the folder. Uses `PUT /rest/config/folders/{id}` with filtered device list. + +However, it is ONLY used in `cleanup_syncthing_for_member()` for the caller's OWN outbox folders (line 455-456). It is NEVER used in: +- `cleanup_syncthing_for_team()` — which removes entire folders instead +- `ensure_outbox_folder()` / `ensure_inbox_folders()` — which only add devices +- Any cross-team device removal path + +This primitive could enable "surgical" device removal if cleanup logic were redesigned. + +--- + +## 13. Observations That Work Correctly + +For completeness — these areas were investigated and found to be sound: + +### OK-1: Atomic Metadata Writes +`sync_metadata.py` uses `tempfile.mkstemp()` + `rename()` for all JSON writes. POSIX atomic. No partial file corruption risk. Each device writes its own file (`members/{member_tag}.json`), so no cross-device write conflicts. + +### OK-2: SQLite WAL Mode +Writer uses WAL mode with `busy_timeout=5000`. Single writer connection via `_writer_lock`. Read connections are separate. Concurrent reads don't block writes. Solid for the single-machine-per-device model. + +### OK-3: Same-User Multi-Device Differentiation +`member_tag = user_id.machine_tag` correctly differentiates M1 (`jayant.macbook`) from M2 (`jayant.mac-mini`). Folder IDs, metadata files, and DB entries are distinct. The v2 fix for this works. + +### OK-4: Handshake and Metadata Folder IDs Include Team +`karma-join--{member_tag}--{team_name}` and `karma-meta--{team_name}` both include team. These never collide across teams. Only outbox/inbox (`karma-out--`) lacks team scope. + +### OK-5: Device Cross-Team Check on Removal +`cleanup_syncthing_for_team()` and `cleanup_syncthing_for_member()` both check `SELECT COUNT(*) FROM sync_members WHERE device_id = ? AND team_name != ?` before removing a Syncthing device. Devices shared across teams are preserved. (Only folder cleanup lacks this check.) + +### OK-6: Event Loop Handling in Daemon Thread +`_auto_leave_team()` correctly detects it's running in a daemon thread (not async context), creates a new event loop, and runs cleanup. No event loop reuse bugs. + +### OK-7: Removal Authority +Creator-only removal enforced via `validate_removal_authority()` which checks `team.json["created_by"]` with DB fallback for when metadata hasn't synced yet. Sound design. + +--- + +## 14. Open Questions for v3 + +### Design Questions + +1. **Should the outbox be team-scoped or project-scoped?** + - Team-scoped: `karma-out--{member}--{team}--{suffix}` — clean isolation, but session duplication + - Project-scoped: `karma-out--{member}--{suffix}` (current) — no duplication, but requires union device list management + +2. **Should the introducer mechanism be used at all?** + - Alternative: explicit mesh via metadata folder (each device reads member list, pairs explicitly) + - Tradeoff: More API calls vs. guaranteed team isolation + +3. **How should cross-team folder device lists be computed?** + - If project-scoped: union of all teams' members for that project + - If team-scoped: simple (just that team's members) + +4. **How should cleanup handle shared folders?** + - Reference counting: "is this folder needed by another team?" + - Device subtraction: "remove just this team's devices from the folder" + - Needs `set_folder_devices` (replace) not just `update_folder_devices` (add) + +5. **How should removal propagate across overlapping teams?** + - Removing M3 from T4 should not affect M3's T2 membership + - But if the outbox folder is shared, removing M3's inbox for T4 removes it for T2 too + +6. **Should there be a "channel" concept separate from teams?** + - Channel = (member, project) — the physical sync unit + - Team = access control layer — determines which channels a member subscribes to + +### Implementation Questions + +7. **Does Syncthing support `set_folder_devices` (replace entire list)?** + - The REST API supports `PUT /rest/config/folders/{id}` with full config + - The proxy has `update_folder_devices` (additive) and `remove_device_from_folder` (single device) + - A "set exactly these devices" operation would need to diff and remove/add + +8. **What is the maximum practical folder count per Syncthing instance?** + - Need benchmarking with 50-200 folders + - File watcher overhead per folder is the main concern + +9. **How to migrate v2 folder IDs to v3?** + - Rename folders? Syncthing may not support rename + - Create new + delete old? Requires re-sync of all data + - Side-by-side? Both formats active during migration window + +10. **How to handle the introducer-to-explicit-mesh transition?** + - Existing introducer flags need to be disabled + - Devices introduced via old mechanism need explicit pairing + - One-time migration on startup? + +--- + +--- + +## Appendix A: Key Source Files + +| File | Purpose | +|------|---------| +| `api/services/folder_id.py` | Folder ID build/parse. `build_outbox_id`, `parse_member_tag` | +| `api/services/sync_folders.py` | Folder CRUD, cleanup, auto_share_folders | +| `api/services/sync_reconciliation.py` | 4-phase reconciliation (introduced, handshakes, auto-accept, introducer) | +| `api/services/sync_metadata.py` | Metadata folder read/write (member states, removal signals, team info) | +| `api/services/sync_metadata_writer.py` | Convenience wrapper for updating own state in metadata | +| `api/services/sync_metadata_reconciler.py` | Timer-driven metadata reconciliation, auto-leave | +| `api/services/sync_policy.py` | Policy evaluation (auto_accept, sync_direction) | +| `api/services/sync_identity.py` | Identity loading, validation, singletons | +| `api/services/syncthing_proxy.py` | Syncthing REST API wrapper | +| `api/services/remote_sessions.py` | Remote session discovery and indexing | +| `api/services/watcher_manager.py` | Session watcher + metadata reconciliation timer | +| `api/db/sync_queries.py` | All sync DB CRUD operations | +| `api/db/schema.py` | SQLite schema v17 | +| `api/routers/sync_teams.py` | Team lifecycle, join, invite, settings | +| `api/routers/sync_members.py` | Member add/remove, profiles | +| `api/routers/sync_devices.py` | Device pairing, pending device acceptance | +| `api/routers/sync_projects.py` | Project sharing, status | +| `api/routers/sync_pending.py` | Pending folder accept/reject | +| `cli/karma/packager.py` | Session packaging into outbox | +| `cli/karma/config.py` | SyncConfig with member_tag derivation | + +## Appendix B: Database Schema (v17) + +``` +sync_teams(name PK, backend, join_code, sync_session_limit, created_at) +sync_members(team_name+device_id PK, name, machine_id, machine_tag, member_tag, added_at) + FK: team_name → sync_teams ON DELETE CASCADE +sync_team_projects(team_name+project_encoded_name PK, path, git_identity, added_at) + FK: team_name → sync_teams ON DELETE CASCADE + FK: project_encoded_name → projects +sync_events(id PK, event_type, team_name, member_name, project_encoded_name, session_uuid, detail, created_at) + FK: team_name → sync_teams ON DELETE SET NULL +sync_settings(scope+setting_key PK, value, updated_at) + NO FK (orphaned on team delete, explicit cleanup exists) +sync_removed_members(team_name+device_id PK, removed_at) + FK: team_name → sync_teams ON DELETE CASCADE +sync_rejected_folders(folder_id PK, team_name, rejected_at) + NO FK +``` + +## Appendix C: Folder ID Formats + +``` +Outbox/Inbox: karma-out--{member_tag}--{suffix} +Handshake: karma-join--{member_tag}--{team_name} +Metadata: karma-meta--{team_name} +``` + +- `member_tag` = `{user_id}.{machine_tag}` (split on first dot) +- `suffix` = git_identity with `/` → `-`, or last path component, or encoded name +- Delimiter `--` is unambiguous (member_tag, suffix, team_name cannot contain `--`) diff --git a/docs/features/2026-03-19-sync-v4.md b/docs/features/2026-03-19-sync-v4.md new file mode 100644 index 00000000..ee7f9ce2 --- /dev/null +++ b/docs/features/2026-03-19-sync-v4.md @@ -0,0 +1,603 @@ +# Feature Definition: Session Sync (v4) + +## Section 1: Scope & Sub-Features + +### Purpose +Enable Claude Code users to share session data (JSONL, subagents, tool results, plans, todos) across machines and team members without a central server, using Syncthing as P2P transport. + +### Sub-Features +1. **Initialization** — Set up sync identity (user_id, machine_tag) and connect to local Syncthing + - Triggered by: `POST /sync/init` or `karma init` + - Depends on: Syncthing installed and running + +2. **Team Management** — Create/dissolve teams, add/remove members via pairing codes + - Triggered by: Leader creates team, shares pairing code out-of-band + - Depends on: Initialization + +3. **Device Pairing** — Exchange Syncthing device IDs via human-readable codes + - Triggered by: Leader enters member's pairing code + - Depends on: Both devices initialized + +4. **Project Sharing** — Share a project's sessions with team members + - Triggered by: Leader shares project via git identity + - Depends on: Team with active members + +5. **Subscription Management** — Accept/decline/pause project subscriptions with direction control (SEND/RECEIVE/BOTH) + - Triggered by: Member responds to OFFERED subscription (shown in Projects tab of team page) + - Depends on: Project shared, subscription discovered via metadata reconciliation + +6. **Session Packaging** — Bundle local sessions into outbox for Syncthing + - Triggered by: File change in `~/.claude/projects/` (debounced 5s) or initial sync + - Depends on: ACCEPTED subscription with SEND|BOTH direction + +7. **Session Receiving** — Index incoming sessions from Syncthing inbox + - Triggered by: File arrival in inbox folder (watchdog) + - Depends on: ACCEPTED subscription with RECEIVE|BOTH direction + +8. **Reconciliation** — 4-phase pipeline every 60s: team discovery → metadata sync → mesh pair → device lists + - Triggered by: Timer (60s) or manual `POST /sync/reconcile` + - Depends on: At least one team exists + +9. **Member Removal & Auto-Leave** — Clean removal with metadata signals and self-cleanup + - Triggered by: Leader removes member, or member discovers removal signal in metadata + - Depends on: Team membership + +10. **Cross-Team Safety** — Prevent destructive operations in one team from breaking another team's resources + - Triggered by: Any folder cleanup, device unpair, or project removal + - Depends on: Same resource potentially shared across teams + +### Not In Scope +- File-level merge conflict resolution (sessions are append-only JSONL) +- Real-time collaboration (async, 60s cycle) +- Central server or relay — purely P2P +- Session editing/deletion by recipients (receive-only) +- Grouping multiple devices into a single "user" concept (each device = separate member) + +--- + +## Section 2: Actors & Roles + +| Actor | Type | Capabilities | Restrictions | +|-------|------|-------------|-------------| +| **Leader** | human (device) | Create team, add/remove members, share/remove projects, dissolve team, generate join code | Cannot be removed (must dissolve), cannot leave own team | +| **Member** | human (device) | Accept/decline/pause subscriptions, choose direction (SEND/RECEIVE/BOTH), leave team, generate pairing code | Cannot add/remove members, cannot share/remove projects | +| **ReconciliationTimer** | system (60s) | Discover teams (Phase 0), sync metadata (Phase 1), mesh pair devices (Phase 2), manage device lists (Phase 3) | Cannot modify subscriptions, cannot share projects | +| **SessionWatcher** | system (watchdog) | Detect JSONL changes, trigger packaging | Cannot package without ACCEPTED+SEND subscription | +| **RemoteSessionWatcher** | system (watchdog) | Detect incoming files, trigger reindex | Cannot modify sync state | +| **MetadataService** | system | Read/write team.json, member state files, removal signals | Filesystem only, no DB access | +| **Syncthing** | external | Sync files between paired devices, offer pending folders/devices | No awareness of Karma semantics | +| **Frontend** | system | Render sync pages, team detail, subscription cards in Projects tab | Cannot access DB or Syncthing directly | + +**Critical rules:** +- A "member" is a **device**, not a person. One person with 2 machines = 2 members (2 member_tags) +- Leader authority is checked by `device_id` match (`team.is_leader(device_id)`) +- A person's second device has NO special permissions — it's just another member that needs to be added +- Reconciliation runs on EVERY machine independently — each machine has its own SQLite DB + +--- + +## Section 3: Vocabulary + +| Term | Definition | NOT the same as | +|------|-----------|-----------------| +| **member_tag** | `{user_id}.{machine_tag}` — unique device identity in sync | `user_id` (one user can have multiple member_tags) | +| **machine_tag** | Sanitized hostname: lowercase `[a-z0-9-]+`, no `--` | `machine_id` (raw hostname, unsanitized) | +| **user_id** | Human-chosen identifier, **no dots** (dot is the separator in member_tag) | Display name, email, GitHub username | +| **device_id** | Syncthing's 56-char device identifier (opaque) | member_tag (member_tag is human-readable) | +| **encoded_name** | Machine-local path encoded: `/Users/me/repo` → `-Users-me-repo` | git_identity — encoded_name differs per machine | +| **git_identity** | Normalized git remote URL: `owner/repo` (lowercase) — machine-independent | encoded_name (machine-specific), folder_suffix (lossy derivation) | +| **folder_suffix** | Derived from git_identity: `owner-repo` (slashes→hyphens). Used in Syncthing folder IDs | git_identity — `a/b-c` and `a-b/c` would collide | +| **outbox** | Syncthing folder where local sessions are packaged TO (**sendonly**) | inbox — outbox is what I write | +| **inbox** | Syncthing folder where remote sessions arrive FROM a peer (**receiveonly**). Folder ID matches remote's outbox ID | outbox — inbox is what I read from others | +| **metadata folder** | `karma-meta--{team}` (**sendreceive**) — team.json, member states, removal signals | outbox/inbox — metadata is bidirectional | +| **session_packaged** | Event logged when local sessions are bundled into outbox staging dir | "sent" — no network transfer happened; Syncthing handles transport | +| **session_received** | Event logged when remote sessions are indexed into local DB from inbox | "downloaded" — Syncthing synced the files, not HTTP | +| **pairing code** | base64url(`{member_tag}:{device_id}`), grouped in 6-char blocks with dashes | join code (v3 concept, removed) | +| **subscription** | Per-(member, team, project) record tracking acceptance status + direction | membership — subscription is about a project, membership is about the team | +| **direction** | SEND, RECEIVE, or BOTH — controls which Syncthing folders are created | status — direction is orthogonal to accepted/paused | +| **OFFERED** | Subscription created by share_project/metadata discovery. Member hasn't responded yet | ACCEPTED — OFFERED means no Syncthing folders created | +| **ACCEPTED** | Member opted in. Syncthing folders created based on direction | ACTIVE (member status) — member can be ACTIVE with OFFERED subscriptions | +| **ADDED** | Member created in leader's DB but not yet confirmed via metadata | ACTIVE — ADDED means peer hasn't published state file yet | +| **reconciliation cycle** | 4-phase pipeline: discovery → metadata → mesh pair → device lists | manual sync — reconciliation is automatic every 60s | + +--- + +## Section 4: State Models + +### State Model: Team + +| State | Meaning | +|-------|---------| +| ACTIVE | Team is operational | +| DISSOLVED | Team has been dissolved by leader | + +| From | To | Triggered By | Side Effects | Idempotent? | +|------|-----|-------------|-------------|-------------| +| — | ACTIVE | `create_team()` | Create leader member, write metadata, register Syncthing folder | Yes (name is PK) | +| ACTIVE | DISSOLVED | `dissolve_team()` (leader only) | Cleanup all Syncthing folders, CASCADE delete members/projects/subs | No — irreversible | + +### State Model: Member + +| State | Meaning | Who | +|-------|---------|-----| +| ADDED | Created in leader's DB, not yet confirmed | New member before Phase 1 activation | +| ACTIVE | Confirmed via metadata, full participant | All participating members | +| REMOVED | Removed by leader | Former member | + +| From | To | Triggered By | Side Effects | Idempotent? | +|------|-----|-------------|-------------|-------------| +| — | ADDED | `add_member()` (leader) | Pair device, share folders (best-effort), create OFFERED subs | Yes | +| — | ACTIVE | `create_team()` (leader self-adds as ACTIVE) | — | Yes | +| ADDED | ACTIVE | Phase 1 discovers peer state file | **Backfill OFFERED subs** for shared projects missed during ADDED state | Yes | +| ADDED/ACTIVE | REMOVED | `remove_member()` (leader) | Record removal, write removal signal, remove from device lists, unpair if no other teams. **Leader cannot remove themselves — must dissolve instead.** | No | + +**Critical questions answered:** +1. **Initiator state**: Leader stays ACTIVE. Adding a member doesn't change leader's state. +2. **Late joiner**: Member added AFTER project shared → gets OFFERED subs via `add_member()`. Member added BEFORE project shared → `share_project()` creates OFFERED if member is ACTIVE; if ADDED, Phase 1 backfills on activation. +3. **Idempotency**: `add_member()` uses INSERT OR REPLACE. Safe to call twice. +4. **Cross-system sync**: Member status propagates via metadata state files → Phase 1 reads them. +5. **Cascade**: Removing member → removal signal in metadata → target machine's Phase 1 auto-leaves. + +### State Model: SharedProject + +| State | Meaning | +|-------|---------| +| SHARED | Project is actively shared with team | +| REMOVED | Project removed from team | + +| From | To | Triggered By | Side Effects | Idempotent? | +|------|-----|-------------|-------------|-------------| +| — | SHARED | `share_project()` (leader) | Create leader's ACCEPTED sub, OFFERED subs for active members, create outbox, publish metadata | Yes | +| SHARED | REMOVED | `remove_project()` (leader) | Decline all subs, cleanup Syncthing folders (cross-team safe), publish metadata | No | + +### State Model: Subscription + +| State | Meaning | Syncthing Folders | +|-------|---------|-------------------| +| OFFERED | Invitation, member hasn't responded | None | +| ACCEPTED | Opted in with direction | Outbox (SEND/BOTH), Inbox (RECEIVE/BOTH) | +| PAUSED | Temporarily suspended | Folders remain but not actively syncing | +| DECLINED | Opted out | None | + +| From | To | Triggered By | Side Effects | Idempotent? | +|------|-----|-------------|-------------|-------------| +| — | OFFERED | `share_project()`, Phase 1 discovery, or Phase 1 backfill | None (no folders) | Yes | +| OFFERED | ACCEPTED | Member calls `accept_subscription(direction)` | Create outbox (SEND/BOTH) + inboxes (RECEIVE/BOTH), publish metadata | Yes | +| OFFERED | DECLINED | Member calls `decline_subscription()` | Publish metadata | Yes | +| ACCEPTED | PAUSED | Member calls `pause_subscription()` | Publish metadata (folders remain) | Yes | +| PAUSED | ACCEPTED | Member calls `resume_subscription()` | Re-apply direction (create any missing folders), publish metadata | Yes | +| ACCEPTED | DECLINED | Member calls `decline_subscription()` | Publish metadata | Yes | +| ANY | DECLINED | Phase 1 project removal (leader removed project) | Publish metadata | Yes | +| DECLINED | OFFERED | Member calls `reopen_subscription()` | Publish metadata, member can then accept again | Yes | + +**Critical questions answered:** +1. **Initiator state**: Leader gets ACCEPTED/BOTH automatically when sharing. Leader is inside the subscription system. +2. **Late joiner**: Member ADDED after project shared → gets OFFERED via `add_member()`. Member activated after project shared → Phase 1 backfills OFFERED. +3. **Cross-system sync**: Subscription status published to metadata → other machines' Phase 1 reads and updates local records (offered→accepted, any→declined). +4. **Cascade**: Accepting subscription → Phase 3 on other machines adds this device to their folder device lists (within 60s). +5. **Direction change**: Only from ACCEPTED state. Removes outbox if losing SEND, creates outbox if gaining SEND. + +--- + +## Section 5: Workflows + +### Workflow 5.1: Team Creation + +**Trigger**: User clicks "Create Team" in UI +**Preconditions**: Sync initialized (`/sync/init` completed) + +| # | Actor | Action | Data | Can Fail? | Failure Handling | +|---|-------|--------|------|-----------|-----------------| +| 1 | Leader | `POST /sync/teams` | `{name}` | Name collision | 409 Conflict | +| 2 | TeamService | Create Team row (ACTIVE) | team_name, leader_member_tag, leader_device_id | — | — | +| 3 | TeamService | Create Leader as ACTIVE Member | same | — | — | +| 4 | MetadataService | Write team.json + leader state file | team info | Filesystem error | Logged, not fatal | +| 5 | FolderManager | Register `karma-meta--{team}` in Syncthing | team_name | Syncthing API down | Fatal — 500 | +| 6 | EventRepository | Log `team_created` | — | — | — | + +**Postconditions:** +- [ ] Team row exists with status=ACTIVE +- [ ] Leader is ACTIVE member in sync_members +- [ ] Metadata folder exists on filesystem +- [ ] Metadata folder registered in Syncthing (sendreceive) +- [ ] team.json contains leader info (created_by, leader_device_id) +- [ ] Leader's state file exists in members/ subdirectory + +### Workflow 5.2: Add Member (Leader Adds via Pairing Code) + +**Trigger**: Leader enters pairing code in "Add Member" dialog +**Preconditions**: Team exists, leader is authenticated (device_id matches) + +| # | Actor | Action | Data | Can Fail? | Failure Handling | +|---|-------|--------|------|-----------|-----------------| +| 1 | PairingService | Decode pairing code | code → member_tag + device_id | Invalid code | 400 Bad Request | +| 2 | TeamService | Auth check: is_leader(by_device) | leader_device_id | Not leader | 403 Forbidden | +| 3 | TeamService | Check if device was previously removed | device_id | Was removed | 409 Conflict | +| 4 | TeamService | Create Member (status=ADDED) | member_tag, device_id | — | — | +| 5 | DeviceManager | Pair new device in Syncthing | device_id | Syncthing down | **Best-effort** — logged, continues | +| 6 | FolderManager | Add new device to metadata folder's device list | device_id | Syncthing down | Best-effort | +| 7 | FolderManager | Add new device to ALL shared project outbox folders | device_id, all folder_ids | Syncthing down | Best-effort | +| 8 | MetadataService | Update metadata with all members | all members | Filesystem error | Logged | +| 9 | TeamService | Create OFFERED subscription for EACH shared project | projects list | — | — | +| 10 | EventRepository | Log `member_added` | — | — | — | + +**Postconditions:** +- [ ] New member exists with status=ADDED +- [ ] OFFERED subscriptions exist for ALL currently shared projects +- [ ] Syncthing metadata folder shared with new device (best-effort) +- [ ] Leader's outbox folders shared with new device (best-effort) +- [ ] Metadata files updated with new member info + +**What if step 5-7 fail (Syncthing down)?** +- DB operations (steps 4, 9) still succeed +- Reconciliation Phase 2 (mesh pair) and Phase 3 (device lists) will retry on next cycle +- Member will eventually discover team via Phase 0 once Syncthing recovers + +### Workflow 5.3: Joiner Discovers Team (Reconciliation) + +**Trigger**: ReconciliationTimer fires (60s) on new member's machine +**Preconditions**: Syncthing has synced the metadata folder from leader + +| # | Actor | Action | Data | Can Fail? | Failure Handling | +|---|-------|--------|------|-----------|-----------------| +| 1 | Phase 0 | Scan Syncthing config for `karma-meta--*` folders | — | Syncthing down | Skip cycle | +| 2 | Phase 0 | Find new metadata folder, no local Team row | folder_id | — | — | +| 3 | Phase 0 | Read team.json from metadata folder | team_name | File not synced yet | Skip — retry next cycle | +| 4 | Phase 0 | Create Team row locally | leader info from team.json | — | — | +| 5 | Phase 0 | Create self as ACTIVE Member | own member_tag, device_id | — | — | +| 6 | Phase 1 | Read all member state files | — | — | — | +| 7 | Phase 1 | Discover leader as new member → save ACTIVE | leader info | — | — | +| 8 | Phase 1 | Read leader's `projects` list from metadata | — | Key missing | Skip project sync (guard) | +| 9 | Phase 1 | For each project: create SharedProject + OFFERED sub for self | git_identity, folder_suffix | — | — | +| 10 | Phase 2 | Pair with leader's device | leader_device_id | Syncthing down | Retry next cycle | +| 11 | Phase 3 | Compute device lists (no accepted subs yet → empty) | — | — | — | + +**Postconditions:** +- [ ] Team exists locally on joiner's machine +- [ ] Self is ACTIVE member +- [ ] Leader known as ACTIVE member +- [ ] SharedProject rows exist for all shared projects +- [ ] OFFERED subscriptions exist for all shared projects +- [ ] Frontend can now show offered subscriptions in Projects tab + +**Timing**: This happens within 60s of metadata folder syncing. If team.json hasn't synced yet, Phase 0 skips and retries next cycle (another 60s). + +### Workflow 5.4: Member Accepts Subscription + +**Trigger**: Member clicks "Accept" on subscription card in team's Projects tab, choosing direction (SEND/RECEIVE/BOTH) +**Preconditions**: OFFERED subscription exists, member is ACTIVE + +| # | Actor | Action | Data | Can Fail? | Failure Handling | +|---|-------|--------|------|-----------|-----------------| +| 1 | ProjectService | Transition OFFERED → ACCEPTED | direction | Invalid transition | 409 Conflict | +| 2 | ProjectService | `_apply_sync_direction()` | — | — | — | +| 2a | (if SEND/BOTH) | Create outbox: `karma-out--{member_tag}--{suffix}` (sendonly) | — | Syncthing down | Retried by Phase 3 | +| 2b | (if RECEIVE/BOTH) | For each active teammate: create inbox matching their outbox ID (receiveonly) | teammate device_ids | Syncthing down | Retried by Phase 3 | +| 3 | ProjectService | Publish member's subscriptions to metadata | projects + subs | Filesystem error | Best-effort | +| 4 | EventRepository | Log `subscription_accepted` | direction | — | — | + +**Postconditions:** +- [ ] Subscription status = ACCEPTED with chosen direction +- [ ] Outbox folder exists in Syncthing (if SEND/BOTH) +- [ ] Inbox folders exist for each active teammate (if RECEIVE/BOTH) +- [ ] Member's metadata state file updated with subscription status + direction +- [ ] WatcherManager can now package sessions to outbox (if SEND/BOTH) + +**What happens next (on other machines within 60s)?** +- Phase 1 reads this member's metadata → sees subscription = "accepted" +- Updates local subscription record (offered → accepted) +- Phase 3 adds this member's device to outbox folder device lists +- Syncthing starts syncing files + +### Workflow 5.5: Share New Project (Members Already Exist) + +**Trigger**: Leader clicks "Share Project" in team's Projects tab +**Preconditions**: Team has ACTIVE members + +| # | Actor | Action | Data | Can Fail? | Failure Handling | +|---|-------|--------|------|-----------|-----------------| +| 1 | ProjectService | Auth check: leader only | by_device | Not leader | 403 | +| 2 | ProjectService | Create SharedProject (SHARED) | git_identity, folder_suffix | — | — | +| 3 | ProjectService | Create ACCEPTED/BOTH subscription for leader | leader_member_tag | — | — | +| 4 | ProjectService | For each ACTIVE non-leader member: create OFFERED subscription | member list | — | — | +| 5 | ProjectService | **Skip ADDED members** (not active yet) | — | — | Backfilled on activation | +| 6 | FolderManager | Create leader's outbox folder (if encoded_name provided) | — | Syncthing down | Phase 3 retries | +| 7 | MetadataService | Publish leader's updated project list | projects + subs | Best-effort | — | +| 8 | EventRepository | Log `project_shared` | — | — | — | + +**On each member's machine (Phase 1, within 60s):** +- Reads leader's updated projects list from metadata +- Sees new project not in local sync_projects +- Creates SharedProject row + OFFERED subscription for self +- Subscription appears in Projects tab as invitation card + +**Combination: Member was ADDED when project shared:** +- `share_project()` skips ADDED members (line 86: `if member.is_active`) +- When Phase 1 activates this member (ADDED→ACTIVE), backfill creates OFFERED subscription +- Delay: up to 2 reconciliation cycles (activation + next project sync) + +**Combination: Member does NOT have the project locally:** +- Still gets OFFERED subscription +- Can accept and RECEIVE sessions without having the repo cloned +- Sessions indexed as remote sessions under resolved local project + +### Workflow 5.6: Remove Member + +**Trigger**: Leader clicks "Remove" on member in Members tab +**Preconditions**: Team exists, target is not the leader + +| # | Actor | Action | Data | Can Fail? | Failure Handling | +|---|-------|--------|------|-----------|-----------------| +| 1 | TeamService | Auth check: leader only | by_device | Not leader | 403 | +| 2 | TeamService | Transition member → REMOVED | member_tag | Already removed | 409 | +| 3 | MemberRepository | Record removal (prevent re-add from stale metadata) | device_id | — | — | +| 4 | MetadataService | Write removal signal to `removed/{member_tag}.json` | removed_by | — | — | +| 5 | FolderManager | Remove device from ALL team folder device lists | device_id, all suffixes + tags | — | — | +| 6 | DeviceManager | Unpair device **only if not in any other team** | device_id | — | — | +| 7 | EventRepository | Log `member_removed` | — | — | — | + +**On removed member's machine (Phase 1, within 60s):** +- Reads removal signals from metadata +- Finds own member_tag → triggers `_auto_leave()` +- Cleans up all Syncthing folders for this team (cross-team safe) +- Unpairs devices not shared with other teams +- Deletes team from local DB +- Logs `member_auto_left` event + +### Workflow 5.7: Session Packaging & Receiving + +**Trigger**: JSONL file modified in `~/.claude/projects/` (packaging) or file arrives in inbox (receiving) + +**Packaging (outbox):** + +| # | Actor | Action | Data | Can Fail? | Failure Handling | +|---|-------|--------|------|-----------|-----------------| +| 1 | SessionWatcher | Detect file change, debounce 5s | file path | — | — | +| 2 | WatcherManager | **Policy gate**: check ACCEPTED + SEND/BOTH subscription | subscription status | No subscription | Skip packaging | +| 3 | SessionPackager | Discover sessions (exclude live, apply limit) | project dir | — | — | +| 4 | SessionPackager | Copy JSONL + subagents + tool results + plans + todos | session files | Disk full | Force recent_100 if <10GiB | +| 5 | SessionPackager | Build manifest.json (git_identity, sessions, skills) | — | — | — | +| 6 | SessionPackager | Write to outbox staging dir | outbox path from DB | Outbox not found | Fallback to remote-sessions/ | +| 7 | Syncthing | Sync outbox to all devices in folder's device list | — | Network down | Retries automatically | + +**Receiving (inbox):** + +| # | Actor | Action | Data | Can Fail? | Failure Handling | +|---|-------|--------|------|-----------|-----------------| +| 1 | RemoteSessionWatcher | Detect file arrival in inbox | — | — | — | +| 2 | Indexer | Read manifest.json, resolve git_identity to local project | git_identity | No local match | Index under git_identity key | +| 3 | Indexer | Index sessions into local DB | JSONL files | Corrupt file | Skip silently | +| 4 | EventRepository | Log `session_received` | session_uuid, member_tag | — | — | + +--- + +## Section 6: Data Contracts + +### Identity Scope Table + +| Identifier | Scope | Use For | Do NOT Use For | +|-----------|-------|---------|---------------| +| encoded_name | one machine | Local file paths, URL routing, frontend navigation | Cross-machine matching, Syncthing folder IDs | +| git_identity | all machines | Project matching/dedup, subscription PK, metadata | Local navigation (differs per machine) | +| folder_suffix | all machines | Syncthing folder IDs (outbox/inbox naming) | Display to user (lossy derivation from git_identity) | +| member_tag | all machines | Device identification, folder IDs, metadata filenames | Display name (use user_id for display) | +| device_id | Syncthing | Peer addressing, connection status | User identification, display | + +### API → Frontend Contracts + +**GET /sync/teams/{name}** (Team Detail) +| Field | Type | Key? | Notes | +|-------|------|------|-------| +| name | string | PK | Team name | +| leader_member_tag | string | — | Who is leader | +| status | string | — | "active" or "dissolved" | +| members[] | Member[] | member_tag | — | +| projects[] | SharedProject[] | git_identity | — | +| subscriptions[] | Subscription[] | (member_tag, team_name, project_git_identity) | — | + +**GET /sync/teams/{name}/project-status** (Projects Tab) +| Field | Type | Key? | Notes | +|-------|------|------|-------| +| git_identity | string | **List key** | Machine-independent — use as `{#each}` key | +| folder_suffix | string | — | — | +| encoded_name | string | — | Resolved locally — may be null if project not on this machine | +| name | string | — | Human-readable, resolved from encoded_name | +| subscription_counts | object | — | {offered, accepted, paused, declined} | +| local_count | number | — | JSONL files on this machine | +| packaged_count | number | — | Sessions in outbox | +| received_counts | object | — | By remote_user_id | +| gap | number | — | max(0, local - packaged) | + +**GET /sync/subscriptions** (Member's Subscriptions) +| Field | Type | Key? | Notes | +|-------|------|------|-------| +| member_tag | string | PK part | — | +| team_name | string | PK part | — | +| project_git_identity | string | PK part + **list key** | — | +| status | string | — | offered/accepted/paused/declined | +| direction | string | — | send/receive/both | + +**GET /sync/members** (Cross-team Members) +| Field | Type | Key? | Notes | +|-------|------|------|-------| +| name | string | — | user_id extracted from member_tag | +| device_id | string | **List key** | Unique across all members | +| connected | boolean | — | From Syncthing connection status | +| is_you | boolean | — | device_id matches local device | +| team_count | number | — | — | +| teams[] | string[] | — | Team names | + +**GET /sync/status** (Sync Status) +| Field | Type | Notes | +|-------|------|-------| +| configured | boolean | Whether /sync/init has been run | +| user_id | string | — | +| machine_id | string | Raw hostname | +| member_tag | string | user_id.machine_tag | +| device_id | string | Syncthing device ID (may be null if Syncthing down) | +| teams[] | object[] | {name, status, leader_member_tag, member_count} | + +### Frontend Rendering Rules +- **List keys**: Always use `git_identity` for project lists, `device_id` for member lists, `member_tag` for team-scoped member lists +- **SSR**: Fetch data in `+page.server.ts`, NOT in `onMount` or `$effect` (SSR crashes) +- **Polling**: Use `onMount` with interval for live data (connection status, pending devices) +- **Member counts**: Always exclude self (`is_you`) from displayed counts + +### Metadata State File Schema (member state file) +```json +{ + "member_tag": "user.machine", + "device_id": "SYNCTHING_DEVICE_ID", + "user_id": "user", + "machine_tag": "machine", + "status": "active", + "projects": [ + { "git_identity": "owner/repo", "folder_suffix": "owner-repo", "encoded_name": "-Users-..." } + ], + "subscriptions": { + "owner/repo": { "status": "accepted", "direction": "both" } + }, + "updated_at": "2026-03-19T..." +} +``` + +### Syncthing Folder ID Conventions +| Type | Format | Direction | +|------|--------|-----------| +| Outbox | `karma-out--{member_tag}--{folder_suffix}` | sendonly (owner), receiveonly (receivers) | +| Metadata | `karma-meta--{team_name}` | sendreceive (all members) | + +--- + +## Section 7: Cross-Cutting Concerns + +### Identity +- **Within one machine**: `encoded_name` for file paths, `member_tag` for sync identity +- **Across machines**: `git_identity` (git remote URL, normalized) for project matching, `device_id` for Syncthing addressing +- **Divergence**: If a project is renamed or git remote changes, git_identity breaks. No auto-migration — must remove and re-share +- **Machine-specific vs independent**: encoded_name is machine-specific. git_identity, member_tag, device_id, folder_suffix are machine-independent + +### Cleanup & Teardown +| Operation | What's Cleaned Up | Cross-Team Safety | +|-----------|-------------------|-------------------| +| Remove member | Device removed from folder device lists, removal signal written, device unpaired | **Only unpair if no other team membership** | +| Remove project | All subscriptions declined, outbox/inbox folders deleted | **Check if other teams share same folder_suffix before deleting** | +| Dissolve team | Write removal signals for all non-leader members, clean all folders, team CASCADE deleted | Check cross-team folder sharing. Remote members auto-leave via Phase 1 removal signal detection. | +| Leave team | Same as auto-leave: folders cleaned, devices unpaired if exclusive | Check cross-team folder sharing | +| Auto-leave (Phase 1) | Same as leave | Check cross-team folder sharing | + +**Cross-team folder check**: `cleanup_team_folders()` and `cleanup_project_folders()` accept `conn` parameter. Before deleting an outbox folder, they query `sync_subscriptions + sync_projects` to check if any OTHER team has active subscriptions for the same `(member_tag, folder_suffix)`. If so, folder is preserved. + +### Migration (v3 → v4) +- **Schema**: v19 migration drops ALL v3 sync tables, creates v4 tables fresh. **Breaking** — no data migration +- **Code**: v3 service files deleted (`16fec93`). v3 CLI sync code removed (`0d30952`) +- **Frontend**: v3 pending folder UI removed from ProjectsTab (`f34ee7c`). v3 join-team flow removed (`8a958a3`) +- **Fresh install**: v19 migration must DROP IF EXISTS the v4 table names too, because SCHEMA_SQL creates them first (`f3534dd` fix) + +### Timing & Ordering +| Scenario | Max Delay | Acceptable? | +|----------|-----------|-------------| +| Leader adds member → member sees team | 60s (Phase 0) + Syncthing sync time | Yes — pairing code exchange takes longer | +| Leader shares project → member sees offer | 60s (Phase 1) | Yes | +| Member accepts subscription → leader's device lists update | 60s (Phase 1 sub sync) + 60s (Phase 3 device lists) = up to 120s | Marginal — consider manual refresh | +| Session packaged → received on other machine | Depends on Syncthing (typically seconds) | Yes | +| Removal signal → auto-leave | 60s (Phase 1) | Yes | + +**First run vs subsequent**: Phase 0 bootstraps team from metadata folder. If team.json hasn't synced yet, Phase 0 skips and retries next cycle. Worst case: 120s for first discovery. + +**Timer during manual operation**: ReconciliationTimer creates a dedicated SQLite connection per thread. Manual operations use the API connection. No lock contention, but state may be stale by one cycle. + +### Multi-Tenancy / Shared Resources +- **Same project in 2 teams**: folder_suffix is derived from git_identity, so it's identical. `list_accepted_for_suffix()` returns subs from all teams, but **Phase 3 filters by `team.name`** when computing device lists — device lists are team-scoped, NOT cross-team unions. This prevents data leaks between teams. +- **Same device in 2 teams**: Member rows exist in both teams. Unpair only checks `get_by_device()` across all teams — only unpairs if no alive memberships remain. +- **Direction change safety**: `change_direction()` checks if another team's subscription (same member + suffix) still needs the outbox before deleting it. +- **Destructive operation safety**: Every cleanup function checks cross-team ownership before deleting folders or unpairing devices. + +--- + +## Section 8: Verification Matrix + +### 8.1 Team Lifecycle +| # | Assertion | Verify By | Pass? | +|---|-----------|-----------|-------| +| 1 | Team created with leader as ACTIVE member | Query `sync_teams` + `sync_members` | [ ] | +| 2 | Metadata folder registered in Syncthing | `GET /sync/detect` or Syncthing UI | [ ] | +| 3 | team.json exists with correct leader info | Read `~/.claude_karma/metadata-folders/karma-meta--{team}/team.json` | [ ] | +| 4 | Dissolve cleans up ALL Syncthing folders | Check Syncthing config for any `karma-*--{team}` folders | [ ] | +| 5 | Dissolve CASCADE deletes members, projects, subs | Query all sync_* tables | [ ] | + +### 8.2 Member Management +| # | Assertion | Verify By | Pass? | +|---|-----------|-----------|-------| +| 1 | Add member creates ADDED row | Query `sync_members` WHERE status='added' | [ ] | +| 2 | OFFERED subs created for ALL shared projects | Count `sync_subscriptions` for new member_tag | [ ] | +| 3 | Metadata folder shared with new device | Check Syncthing folder config for device_id | [ ] | +| 4 | Non-leader cannot add members | `POST /sync/teams/{name}/members` returns 403 | [ ] | +| 5 | Previously removed device cannot re-join | Check `sync_removed_members` table | [ ] | +| 6 | Remove member writes removal signal | Check `removed/{member_tag}.json` exists | [ ] | +| 7 | Unpair only if no other team membership | Query `sync_members` by device_id across teams | [ ] | + +### 8.3 Joiner Discovery (Reconciliation) +| # | Assertion | Verify By | Pass? | +|---|-----------|-----------|-------| +| 1 | Phase 0 bootstraps team from metadata folder | Query `sync_teams` on joiner's machine | [ ] | +| 2 | Phase 0 creates self as ACTIVE (not ADDED) | Query `sync_members` on joiner's machine | [ ] | +| 3 | Phase 1 discovers leader from state files | Leader appears in joiner's `sync_members` | [ ] | +| 4 | Phase 1 discovers projects from leader's metadata | `sync_projects` populated on joiner's machine | [ ] | +| 5 | Phase 1 creates OFFERED subs for each project | `sync_subscriptions` on joiner's machine | [ ] | +| 6 | Guard: skip project sync if leader hasn't published projects key | No crash, no orphan records | [ ] | +| 7 | Phase 2 pairs joiner ↔ leader devices | Both devices in Syncthing config | [ ] | + +### 8.4 Subscription Flow +| # | Assertion | Verify By | Pass? | +|---|-----------|-----------|-------| +| 1 | Accept creates outbox (SEND/BOTH) | Syncthing folder `karma-out--{member_tag}--{suffix}` exists (sendonly) | [ ] | +| 2 | Accept creates inboxes for each teammate (RECEIVE/BOTH) | Syncthing folder matching teammate's outbox ID exists (receiveonly) | [ ] | +| 3 | Metadata updated with subscription status | Check `members/{member_tag}.json` subscriptions field | [ ] | +| 4 | Phase 1 syncs accepted status to leader's DB | Leader's `sync_subscriptions` shows accepted | [ ] | +| 5 | Phase 3 adds device to outbox device lists | Check Syncthing folder device list | [ ] | +| 6 | Decline removes from future device list computation | Phase 3 skips declined subscriptions | [ ] | +| 7 | Pause keeps folders but no new data | Subscription status=paused, folders remain | [ ] | +| 8 | Direction change creates/removes outbox correctly | Switch BOTH→RECEIVE: outbox removed. RECEIVE→BOTH: outbox created | [ ] | + +### 8.5 Session Sync +| # | Assertion | Verify By | Pass? | +|---|-----------|-----------|-------| +| 1 | Sessions packaged to correct outbox folder | Check outbox dir for manifest.json + JSONL files | [ ] | +| 2 | Policy gate: no packaging without ACCEPTED+SEND sub | Stop watcher, verify no files in outbox | [ ] | +| 3 | manifest.json contains git_identity (not encoded_name) | Read manifest.json | [ ] | +| 4 | Received sessions indexed under correct local project | Query sessions DB for remote sessions | [ ] | +| 5 | Live sessions excluded from packaging | Start a session, verify it's not in outbox | [ ] | +| 6 | Incremental packaging (skip unchanged files) | Package twice, verify mtimes unchanged | [ ] | + +### 8.6 Cross-Team Safety +| # | Assertion | Verify By | Pass? | +|---|-----------|-----------|-------| +| 1 | Same project in 2 teams: remove from Team A preserves for Team B | Delete from A, verify B's folders still exist | [ ] | +| 2 | Same device in 2 teams: remove from Team A doesn't unpair | Remove member from A, verify device still in Syncthing config | [ ] | +| 3 | Device lists merge across teams | Share same project in 2 teams, verify device list is union | [ ] | +| 4 | Leave team doesn't corrupt other team's state | Leave A, verify B's sync_* tables untouched | [ ] | + +### 8.7 Edge Cases +| # | Scenario | Expected Behavior | Pass? | +|---|----------|-------------------|-------| +| E1 | Member added AFTER project shared | Gets OFFERED sub via `add_member()` | [ ] | +| E2 | Member ADDED (not active) when project shared | No sub at share time. Backfilled when Phase 1 activates member | [ ] | +| E3 | Leader shares project, no members exist | Only leader's ACCEPTED sub created. OFFERED subs created when members added | [ ] | +| E4 | Subscription accepted on Machine B, checked from Machine A | Phase 1 syncs status via metadata within 60s | [ ] | +| E5 | team.json not synced yet when Phase 0 runs | Phase 0 skips, retries next cycle (60s) | [ ] | +| E6 | leader hasn't published projects key yet | Phase 1 skips project sync (guard at line 251) | [ ] | +| E7 | Syncthing down during add_member | DB operations succeed, Syncthing ops are best-effort. Reconciliation retries | [ ] | +| E8 | folder_suffix collision (a/b-c vs a-b/c) | Both derive to `a-b-c`. Currently unhandled — same outbox folder used | [ ] | +| E9 | Accept subscription twice | Idempotent — INSERT OR REPLACE | [ ] | +| E10 | Remove already-removed member | 409 Conflict from domain model state transition | [ ] | +| E11 | Fresh install with v19 migration | DROP IF EXISTS sync_projects before CREATE — no collision | [ ] | +| E12 | Person with 2 devices in same team | 2 separate members, 2 separate subscriptions, independent packaging | [ ] | +| E13 | Member leaves team, then leader adds them back | Must use new pairing code. Old removal record checked via `was_removed()` | [ ] | +| E14 | Reconciliation timer fires during manual accept_subscription | Separate SQLite connections — no lock contention | [ ] | +| E15 | Member has no local clone of shared project | Can still RECEIVE sessions — indexed as remote sessions | [ ] | +| E16 | Bob declines subscription, later wants to re-accept | `POST .../reopen` → DECLINED→OFFERED, then accept again | [ ] | +| E17 | Leader tries to remove themselves | `InvalidTransitionError` — must use dissolve instead | [ ] | +| E18 | Team dissolved while members are offline | Removal signals written for all members → Phase 1 auto-leave on next cycle | [ ] | +| E19 | Same project in 2 teams, Phase 3 device lists | Device lists are team-scoped — no cross-team pollution | [ ] | +| E20 | Change direction BOTH→RECEIVE when other team needs outbox | Outbox preserved — cross-team subscription check prevents deletion | [ ] | diff --git a/docs/open-issues/syncthing/README.md b/docs/open-issues/syncthing/README.md new file mode 100644 index 00000000..ca262e61 --- /dev/null +++ b/docs/open-issues/syncthing/README.md @@ -0,0 +1,14 @@ +# Syncthing Sync — Open Issues + +Deferred issues identified during the sync permissions, security, and activity implementation (2026-03-08). These are architectural or structural improvements that were intentionally left for separate PRs to keep the current changeset focused. + +## Issue Index + +| # | Severity | File | Summary | +|---|----------|------|---------| +| 1 | HIGH | [folder-id-ambiguity.md](./folder-id-ambiguity.md) | Hyphen delimiter in folder IDs causes parsing ambiguity | +| 2 | HIGH | [duplicated-cli-api-logic.md](./duplicated-cli-api-logic.md) | Shared logic duplicated between CLI and API | +| 3 | HIGH | [sync-status-god-router.md](./sync-status-god-router.md) | `sync_status.py` is 1,900 lines — needs splitting | +| 4 | HIGH | [fstring-sql-construction.md](./fstring-sql-construction.md) | f-string SQL in `query_events` is fragile | +| 5 | MEDIUM | [packager-permission-errors.md](./packager-permission-errors.md) | Packager doesn't handle file permission errors | +| 6 | MEDIUM | [watcher-logging.md](./watcher-logging.md) | Watcher uses `print()` instead of `logger` | diff --git a/docs/open-issues/syncthing/duplicated-cli-api-logic.md b/docs/open-issues/syncthing/duplicated-cli-api-logic.md new file mode 100644 index 00000000..cecc8fd2 --- /dev/null +++ b/docs/open-issues/syncthing/duplicated-cli-api-logic.md @@ -0,0 +1,18 @@ +# Duplicated Logic Between CLI and API + +**Severity:** HIGH +**Files:** `api/routers/sync_status.py`, `cli/karma/main.py` + +## Status: PARTIALLY RESOLVED + +Folder ID parsing has been consolidated into `api/services/folder_id.py`: +- `parse_karma_folder_id(folder_id, known_names=None)` — replaces 4 prior implementations +- `parse_karma_handshake_id(folder_id, known_teams=None)` — replaces `_parse_handshake_folder` +- `known_names_from_db(conn)` / `known_teams_from_db(conn)` — DB convenience helpers + +Both the API (`api/routers/sync_status.py`) and CLI (`cli/karma/pending.py`) now import from this shared module. + +## Remaining Duplication + +- `_auto_share_folders` — folder sharing logic (API async vs CLI sync) +- Project suffix computation from git identity or path diff --git a/docs/open-issues/syncthing/folder-id-ambiguity.md b/docs/open-issues/syncthing/folder-id-ambiguity.md new file mode 100644 index 00000000..d47b0bda --- /dev/null +++ b/docs/open-issues/syncthing/folder-id-ambiguity.md @@ -0,0 +1,30 @@ +# Folder ID Ambiguity + +**Severity:** HIGH +**Files:** `api/routers/sync_status.py:211`, `cli/karma/main.py:171` + +## Problem + +Syncthing folder IDs use hyphens as delimiters: `karma-out-{member}-{suffix}`. Both member names and project suffixes can contain hyphens, making parsing ambiguous. + +Example: `karma-out-alice-bob-my-app` could be: +- member=`alice`, suffix=`bob-my-app` +- member=`alice-bob`, suffix=`my-app` + +The consolidated parser in `api/services/folder_id.py` (`parse_karma_folder_id`) accepts an optional `known_names` set for DB-backed disambiguation, falling back to shortest-prefix-first when no hints are available. + +## Impact + +- Wrong inbox folder matching during Syncthing cleanup +- Wrong member attribution during auto-accept +- Wrong project detection in `_find_team_for_folder` + +## Possible Fixes + +1. **Change delimiter** to double-dash `--` (e.g., `karma-out--alice-bob--my-app`). Requires migration of existing Syncthing folder configs on all deployed machines. +2. **Enforce no-hyphens-in-usernames** at registration time. Breaks existing users with hyphenated names. +3. **Always use DB lookup** for disambiguation (current CLI approach). Extend to API side. + +## Why Deferred + +Options 1-2 require migration strategy affecting deployed machines. Option 3 is partially done (CLI side). Needs a dedicated PR with proper migration plan. diff --git a/docs/open-issues/syncthing/fstring-sql-construction.md b/docs/open-issues/syncthing/fstring-sql-construction.md new file mode 100644 index 00000000..b0c160f0 --- /dev/null +++ b/docs/open-issues/syncthing/fstring-sql-construction.md @@ -0,0 +1,45 @@ +# f-String SQL Construction in query_events + +**Severity:** HIGH +**File:** `api/db/sync_queries.py:256` + +## Problem + +The `query_events()` function builds WHERE clauses via f-string concatenation: + +```python +where = f"WHERE {' AND '.join(conditions)}" if conditions else "" +rows = conn.execute( + f"SELECT * FROM sync_events {where} ORDER BY created_at DESC LIMIT :limit OFFSET :offset", + params, +).fetchall() +``` + +While the column names are hardcoded (safe) and values use named parameters (also safe), the pattern is fragile. A future developer could accidentally introduce user input into the column name position, creating a SQL injection vulnerability. + +## Current Safety + +- All condition strings are hardcoded: `"team_name = :team_name"`, `"event_type = :event_type"`, etc. +- All user values go through named parameters (`:team_name`, `:event_type`) +- A safety comment documents this: `# conditions list is built from hardcoded column names only` + +## Proposed Fix + +Adopt a query builder pattern or add explicit column allowlisting: + +```python +_ALLOWED_FILTER_COLUMNS = {"team_name", "event_type", "member_name"} + +def query_events(conn, filters: dict, limit=50, offset=0): + conditions = [] + params = {"limit": limit, "offset": offset} + for col, val in filters.items(): + assert col in _ALLOWED_FILTER_COLUMNS, f"Invalid filter column: {col}" + conditions.append(f"{col} = :{col}") + params[col] = val + ... +``` + +## Why Deferred + +The current code is safe as written. The proper fix is adopting a query builder (like SQLAlchemy Core) which is a larger architectural decision affecting all of `sync_queries.py`. diff --git a/docs/open-issues/syncthing/packager-permission-errors.md b/docs/open-issues/syncthing/packager-permission-errors.md new file mode 100644 index 00000000..384b6f31 --- /dev/null +++ b/docs/open-issues/syncthing/packager-permission-errors.md @@ -0,0 +1,28 @@ +# Packager Permission Error Handling + +**Severity:** MEDIUM +**File:** `cli/karma/packager.py:161-179` + +## Problem + +`_discover_from_dir()` calls `stat()` on each JSONL file without catching `PermissionError`. On multi-user machines or when files are actively being written by Claude Code, `stat()` or later `shutil.copy2()` could fail. + +## Impact + +A single unreadable file would crash the entire packaging operation, preventing all other sessions from syncing. + +## Proposed Fix + +Wrap the stat/add logic in try/except to skip unreadable files: + +```python +try: + file_stat = jsonl_path.stat() +except (PermissionError, OSError) as e: + logger.debug("Skipping unreadable file %s: %s", jsonl_path, e) + continue +``` + +## Why Deferred + +Edge case on single-user desktop machines (the primary deployment target). Trivial fix but outside the scope of the current security/permissions changeset. diff --git a/docs/open-issues/syncthing/sync-status-god-router.md b/docs/open-issues/syncthing/sync-status-god-router.md new file mode 100644 index 00000000..4b164fbf --- /dev/null +++ b/docs/open-issues/syncthing/sync-status-god-router.md @@ -0,0 +1,37 @@ +# sync_status.py God Router + +**Severity:** HIGH +**File:** `api/routers/sync_status.py` (~1,900 lines) + +## Problem + +This single file handles: +- Team CRUD (create, join, leave, delete) +- Member management (add, remove, list) +- Project management (add, remove, share) +- Syncthing proxy operations (devices, folders, pending) +- Folder ID parsing and naming conventions +- Auto-accept and auto-share logic +- Watcher management (start, stop, status) +- Pending folder handling +- Activity feeds and event queries +- Team settings (session limit) +- Sync-now packaging trigger +- Full reset flow + +This makes it hard to test individual concerns, review changes, and onboard new contributors. + +## Proposed Split + +| New File | Responsibility | +|----------|---------------| +| `routers/sync_teams.py` | Team/member/project CRUD | +| `routers/sync_devices.py` | Syncthing proxy operations | +| `routers/sync_activity.py` | Events and activity feeds | +| `services/sync_folders.py` | Folder ID parsing, auto-accept, auto-share | + +Shared helpers (`validate_project_name`, `validate_project_path`, `_get_sync_conn`) move to `services/sync_helpers.py`. + +## Why Deferred + +Pure structural refactor with no behavioral changes. Ideal for a separate PR that only moves code, making it easy to review and verify nothing breaks. diff --git a/docs/open-issues/syncthing/watcher-logging.md b/docs/open-issues/syncthing/watcher-logging.md new file mode 100644 index 00000000..a0178757 --- /dev/null +++ b/docs/open-issues/syncthing/watcher-logging.md @@ -0,0 +1,28 @@ +# Watcher Uses print() Instead of logger + +**Severity:** MEDIUM +**File:** `cli/karma/watcher.py:56-59` + +## Problem + +Packaging errors in `SessionWatcher._do_package()` are printed to stderr via `print()`: + +```python +except Exception as e: + print(f"[karma watch] Packaging error: {e}", file=sys.stderr) +``` + +This makes errors invisible in log aggregation systems and doesn't include stack traces. + +## Proposed Fix + +```python +except Exception: + logger.exception("Packaging error during watch") +``` + +Using `logger.exception()` captures the full traceback and routes through the standard logging module. + +## Why Deferred + +Minor robustness improvement with no functional impact for the current CLI-only usage. The watcher is run interactively where stderr is visible. diff --git a/docs/plans/2026-03-03-syncthing-session-sync-design.md b/docs/plans/2026-03-03-syncthing-session-sync-design.md new file mode 100644 index 00000000..2f274374 --- /dev/null +++ b/docs/plans/2026-03-03-syncthing-session-sync-design.md @@ -0,0 +1,445 @@ +# Syncthing Session Sync Design + +**Date:** 2026-03-03 +**Status:** Approved +**Author:** Jayant Devkar + Claude + +## Problem + +Claude Karma is 100% local-machine only. If you hire 4-10 freelancers who each use Claude Code on their own machines (Mac, Windows, Linux), there's no way to see their session activity in your dashboard. Same user on multiple machines also can't unify their sessions. + +An IPFS-based sync design exists (`2026-03-03-ipfs-session-sync-design.md`) but requires running a Kubo daemon and is on-demand only. Syncthing provides an alternative that offers real-time, automatic sync with simpler setup for trusted teams. + +## Goal + +Enable cross-system session sharing using Syncthing as a pluggable sync backend alongside IPFS. Both backends produce the same data format so the dashboard API reads them identically. + +## Requirements + +- Freelancers own their `~/.claude/` — they selectively share specific project sessions +- One user may have multiple machines — sessions should be unified per user identity +- Fully automatic sync after initial setup (no CLI commands needed) +- Bidirectional: owner can push feedback/annotations back to freelancers +- Backend is per-team (a user can use IPFS for one team, Syncthing for another) +- Same data format as IPFS design (manifest.json + sessions/) +- Direct connections by default (no public relays) + +## Architecture + +``` + SYNCTHING MESH + (device ID pairing, TLS encrypted) + + ┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐ + │ Freelancer A │ │ Freelancer B │ │ Project Owner (You) │ + │ Syncthing │ │ Syncthing │ │ Syncthing │ + │ Mac Mini │ │ Windows │ │ Mac Mini │ + └──────┬───────┘ └──────┬───────┘ └──────────┬───────────┘ + │ │ │ + remote-sessions/ remote-sessions/ sync-inbox/ + (auto-packaged) (auto-packaged) (auto-received) + │ │ │ + └────────────┬────┘ │ + │ │ + Syncthing auto-syncs │ + (bidirectional, TLS) │ + │ │ + ┌───────▼─────────┐ ┌───────▼─────────┐ + │ karma watch │ │ Karma Dashboard │ + │ (packages │ │ API reads from │ + │ sessions) │ │ remote-sessions/│ + └─────────────────┘ └─────────────────┘ +``` + +### Components + +1. **`karma` CLI** — extended with `--backend syncthing` support, new `karma watch` command +2. **Syncthing** — each participant runs it. Handles transport + encryption +3. **Device ID pairing** — Syncthing's native trust model (Ed25519 key pairs) +4. **Karma API** — same `/remote/*` endpoints, reads from `~/.claude_karma/remote-sessions/` regardless of backend + +### Key Difference from IPFS + +No IPNS, no CIDs, no Kubo daemon. Syncthing handles discovery, transport, and encryption natively. The `karma` CLI only handles packaging sessions into the shared folder format. + +## Data Model + +### What Gets Synced + +The packaging format is identical to the IPFS design so the API reads both the same way. + +### Syncthing Shared Folders + +``` +~/.claude_karma/ +├── remote-sessions/ # Both backends write here, API reads from here +│ └── {user-id}/ +│ └── {project-encoded-name}/ +│ ├── manifest.json +│ ├── sessions/ +│ │ ├── {uuid1}.jsonl +│ │ ├── {uuid2}.jsonl +│ │ ├── {uuid1}/ +│ │ │ ├── subagents/ +│ │ │ │ └── agent-*.jsonl +│ │ │ └── tool-results/ +│ │ │ └── toolu_*.txt +│ │ └── {uuid2}/ +│ │ └── ... +│ └── todos/ +│ └── {uuid1}-*.json +│ +├── sync-inbox/ # Owner → Freelancer (bidirectional) +│ └── {team}/ +│ └── {owner-id}/ +│ └── {project-encoded-name}/ +│ └── feedback/ +│ ├── {session-uuid}.json # Per-session annotations +│ └── project-notes.json # General project notes +│ +└── sync-config.json +``` + +### Syncthing Folder Type Mapping + +| Syncthing Folder | Path | Freelancer Side | Owner Side | +|---|---|---|---| +| `karma-out-{user-id}` | `remote-sessions/{user-id}/` | `sendonly` | `receiveonly` | +| `karma-in-{owner-id}` | `sync-inbox/{team}/{owner-id}/` | `receiveonly` | `sendonly` | + +### manifest.json + +```json +{ + "version": 1, + "user_id": "freelancer-alice", + "machine_id": "alice-macbook-pro", + "project_path": "/Users/alice/work/acme-app", + "project_encoded": "-Users-alice-work-acme-app", + "synced_at": "2026-03-03T14:30:00Z", + "session_count": 12, + "sync_backend": "syncthing", + "sessions": [ + { + "uuid": "abc123...", + "mtime": "2026-03-03T12:00:00Z", + "size_bytes": 45000 + } + ] +} +``` + +Only addition vs IPFS: `"sync_backend": "syncthing"` field. + +## CLI Design + +### Backend Selection During Init + +```bash +$ karma init + +Detecting available backends... + ✓ Syncthing found (v1.27.0, REST API on :8384) + ✓ Kubo/IPFS found (v0.24.0, API on :5001) + +? Which sync backend do you want to use? + › Syncthing (recommended for small trusted teams, real-time sync) + IPFS (recommended for larger teams, on-demand sync, tamper-evident) +``` + +- If only one backend detected → auto-selects it +- If both detected → asks the user +- If neither detected → prints install instructions and exits +- User can switch later with `karma init --backend syncthing` + +### Commands + +```bash +# First-time setup with Syncthing backend +karma init --backend syncthing +# Checks Syncthing is running (REST API on port 8384) +# Generates user_id, machine_id +# Prints Device ID for sharing with owner + +# Create a team +karma team create alpha --backend syncthing + +# Configure a project for syncing +karma project add acme-app --path /Users/alice/work/acme-app --team alpha + +# Start the background watcher (packages sessions automatically) +karma watch +# Uses watchdog library to monitor ~/.claude/projects/{encoded-path}/ +# On file change → re-packages into remote-sessions/ +# Debounces: waits 5 seconds of no changes before packaging + +# Stop the watcher +karma watch --stop + +# Check sync status +karma status +# Shows: backend, watcher running?, last sync time, pending changes + +# Team management (owner side) +karma team add alice +# Configures Syncthing to share folders with alice's device + +karma team list +# Shows all paired devices + their sync state + +karma team remove alice +# Removes Syncthing folder sharing for alice +``` + +### Backend-Agnostic Command Behavior + +| Command | IPFS behavior | Syncthing behavior | +|---|---|---| +| `karma init` | Checks Kubo, imports swarm key | Checks Syncthing REST API | +| `karma project add` | Stores config | Stores config + creates Syncthing folder | +| `karma sync` | Packages + ipfs add + IPNS publish | Packages into remote-sessions/ (Syncthing handles rest) | +| `karma watch` | N/A (IPFS is on-demand) | Starts filesystem watcher | +| `karma team add` | Stores IPNS key | Pairs Syncthing device + shares folders | +| `karma pull` | Resolves IPNS + ipfs get | N/A (Syncthing auto-syncs) | +| `karma status` | Shows last CID, sync time | Shows Syncthing connection state | + +### Config File + +`~/.claude_karma/sync-config.json`: + +```json +{ + "user_id": "alice", + "machine_id": "alice-macbook-pro", + "teams": { + "alpha": { + "backend": "ipfs", + "owner_ipns_key": "k51...", + "projects": { + "acme-app": { + "path": "/Users/alice/work/acme-app", + "last_sync_cid": "Qm..." + } + } + }, + "beta": { + "backend": "syncthing", + "owner_device_id": "YYYYYYY-...", + "projects": { + "startup-app": { + "path": "/Users/alice/work/startup-app", + "last_package_at": "2026-03-03T14:30:00Z" + } + } + } + }, + "ipfs": { + "api_url": "http://127.0.0.1:5001" + }, + "syncthing": { + "api_url": "http://127.0.0.1:8384", + "api_key": "abc123...", + "device_id": "XXXXXXX-XXXXXXX-XXXXXXX-XXXXXXX-XXXXXXX-XXXXXXX-XXXXXXX-XXXXXXX" + } +} +``` + +## Syncthing Integration Details + +### Python ↔ Syncthing Communication + +Syncthing exposes a REST API on `http://127.0.0.1:8384`. Use `requests`: + +```python +import requests + +class SyncthingClient: + def __init__(self, api_url: str, api_key: str): + self.api_url = api_url + self.headers = {"X-API-Key": api_key} + + def get_device_id(self) -> str: + """Get this device's ID.""" + resp = requests.get(f"{self.api_url}/rest/system/status", headers=self.headers) + return resp.json()["myID"] + + def add_device(self, device_id: str, name: str): + """Pair with a remote device.""" + config = self._get_config() + config["devices"].append({"deviceID": device_id, "name": name}) + self._set_config(config) + + def add_folder(self, folder_id: str, path: str, devices: list[str], folder_type: str = "sendonly"): + """Create a shared folder with specified devices.""" + config = self._get_config() + config["folders"].append({ + "id": folder_id, + "path": path, + "devices": [{"deviceID": d} for d in devices], + "type": folder_type, + }) + self._set_config(config) + + def get_connections(self) -> dict: + """Check which devices are connected.""" + resp = requests.get(f"{self.api_url}/rest/system/connections", headers=self.headers) + return resp.json()["connections"] + + def _get_config(self) -> dict: + resp = requests.get(f"{self.api_url}/rest/config", headers=self.headers) + return resp.json() + + def _set_config(self, config: dict): + requests.put(f"{self.api_url}/rest/config", json=config, headers=self.headers) +``` + +### Watcher Implementation + +```python +from watchdog.observers import Observer +from watchdog.events import FileSystemEventHandler +import threading + +class SessionWatcher(FileSystemEventHandler): + def __init__(self, packager, debounce_seconds=5): + self.packager = packager + self.debounce = debounce_seconds + self._timer = None + + def on_modified(self, event): + if event.src_path.endswith(".jsonl"): + self._debounced_package(event.src_path) + + def _debounced_package(self, path): + if self._timer: + self._timer.cancel() + self._timer = threading.Timer( + self.debounce, self.packager.package_project, args=[path] + ) + self._timer.start() +``` + +The watcher monitors `~/.claude/projects/` for JSONL changes, debounces for 5 seconds, then packages into `remote-sessions/{user-id}/{project}/`. Syncthing picks up the changes automatically. + +### Onboarding Flow + +``` +Freelancer: Owner: + +1. Install Syncthing 1. Install Syncthing +2. karma init --backend syncthing 2. karma init --backend syncthing +3. Share Device ID with owner ──────► 3. karma team add alice + 4. Share own Device ID back ◄────── +5. karma team add owner +6. karma project add acme-app --team beta +7. karma watch + Sessions appear in dashboard! +``` + +## Security & Privacy + +### Transport Security Comparison + +| Layer | IPFS | Syncthing | +|---|---|---| +| Encryption | Swarm key (symmetric) | TLS 1.3 (per-connection) | +| Authentication | Swarm membership | Device ID (Ed25519 key pair) | +| Discovery | DHT within swarm | Local announcements (default) | +| Data at rest | Not encrypted by default | Not encrypted by default | + +### Syncthing Network Configuration + +By default, we configure Syncthing for maximum privacy: + +```json +{ + "options": { + "relaysEnabled": false, + "globalAnnounceEnabled": false, + "localAnnounceEnabled": true + } +} +``` + +For remote freelancers (different networks): +- **Option A:** Open port 22000 (Syncthing's default) +- **Option B:** Use a VPN (Tailscale, WireGuard) — Syncthing discovers over the VPN +- **Option C:** Enable Syncthing relays (data is encrypted, relay can't read it) + +The `karma init` setup asks which network mode to use. + +### Data Privacy + +- **No global `~/.claude/` access** — only explicitly configured project dirs synced +- **Send-only folders** — freelancer controls what they share +- **Session data may contain sensitive code** — direct connections + TLS keeps it private +- Freelancers can `karma project remove ` to stop syncing +- `karma watch --stop` halts all automatic syncing immediately + +### Syncthing vs IPFS Security Trade-offs + +| Concern | IPFS | Syncthing | +|---|---|---| +| Tamper evidence | CID changes if data modified | No built-in (trust the TLS channel) | +| Audit trail | CID chain via `previous_cid` | Syncthing versioning (optional) | +| Data sovereignty | Freelancer publishes on-demand | Freelancer can pause/stop watch | +| Network exposure | Private swarm only | Direct connection + optional relay | + +## Dashboard Integration + +### API Changes + +Since both backends produce the same folder structure in `~/.claude_karma/remote-sessions/`, the existing `/remote/*` endpoints work unchanged. + +New endpoints: + +| Method | Endpoint | Description | +|---|---|---| +| GET | `/sync/status` | Backend type, connection state, last sync time per team | +| GET | `/sync/teams` | List all teams with their backend + members | + +### Frontend Additions + +- **Sync status indicator** — green (connected), yellow (syncing), grey (disconnected) +- **Backend badge** — "IPFS" or "Syncthing" label on each team card +- **Feedback panel** (Syncthing only) — owner can write per-session annotations that sync back + +## Design Decisions Summary + +| Decision | Choice | Rationale | +|---|---|---| +| Approach | Syncthing as pluggable sync backend | Supports both IPFS and Syncthing | +| Sync trigger | Fully automatic (watcher + Syncthing) | Leverages Syncthing's core strength | +| Onboarding | Device ID exchange | Simple, secure, native Syncthing | +| Data format | Same as IPFS (manifest.json + sessions/) | API reads both identically | +| Direction | Bidirectional (send-only/receive-only folders) | Owner can push feedback | +| Multi-team | Backend is per-team | User can use IPFS for one team, Syncthing for another | +| Security | Direct connections, no relays by default | Maximum privacy for trusted teams | + +## Design Update: sync-outbox Removed (2026-03-03) + +The original design used `sync-outbox/{team}/{user-id}/{project}/` as an intermediate directory. This was updated so that both `karma watch` (Syncthing) and `karma pull` (IPFS) write directly to `remote-sessions/{user-id}/{project}/`. The `sync-outbox/` concept is dropped because: + +1. The API reads from `remote-sessions/` — an intermediate directory created a routing gap +2. IPFS already wrote directly to `remote-sessions/` — Syncthing should too +3. The `team` tier in the path was unnecessary — `user_id` already provides namespace isolation +4. Syncthing can watch any directory — changing the path doesn't affect its operation + +Syncthing shared folders now point to `remote-sessions/{user-id}/` instead of `sync-outbox/{team}/{user-id}/`. + +## Future Enhancements (Post-MVP) + +- **Live session streaming** — Syncthing's event API notifies dashboard when new files arrive +- **Automatic `karma watch` via launchd/systemd** — starts on boot +- **Conflict resolution UI** — if both backends deliver data for same user/project +- **Encrypted folders** — Syncthing's "untrusted" mode for cloud relay setups +- **SessionEnd hook integration** — immediate packaging on session end (no debounce) +- **Cost tracking** — aggregate token usage across freelancers for billing + +## References + +- [Syncthing Documentation](https://docs.syncthing.net/) +- [Syncthing REST API](https://docs.syncthing.net/dev/rest.html) +- [Syncthing Security](https://docs.syncthing.net/users/security.html) +- [watchdog (Python filesystem events)](https://github.com/gorakhargosh/watchdog) +- [IPFS Session Sync Design](./2026-03-03-ipfs-session-sync-design.md) diff --git a/docs/plans/2026-03-03-syncthing-session-sync-plan.md b/docs/plans/2026-03-03-syncthing-session-sync-plan.md new file mode 100644 index 00000000..c35709b5 --- /dev/null +++ b/docs/plans/2026-03-03-syncthing-session-sync-plan.md @@ -0,0 +1,1362 @@ +# Syncthing Session Sync Implementation Plan + +> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. + +**Goal:** Add Syncthing as a pluggable sync backend alongside IPFS, enabling real-time automatic session sharing for trusted teams with bidirectional feedback support. + +**Architecture:** Refactor the `karma` CLI config to support per-team backend selection. Add a `SyncthingClient` (REST API wrapper), a `SessionWatcher` (watchdog-based filesystem monitor), and extend the CLI with `karma watch`, `karma team create`, and backend-aware `karma init`. The existing `SessionPackager` and `SyncManifest` are reused with minor extensions. The API gets two new endpoints for sync status. + +**Tech Stack:** Python 3.9+, click (CLI), requests (Syncthing REST API), watchdog (filesystem events), Pydantic 2.x (models), pytest (testing) + +**Design doc:** `docs/plans/2026-03-03-syncthing-session-sync-design.md` + +**Existing code:** The IPFS CLI exists at `cli/` with `config.py`, `ipfs.py`, `sync.py`, `packager.py`, `manifest.py`, and `main.py`. This plan extends that codebase. All file paths are relative to the `cli/` directory unless noted otherwise. + +### Review Fixes Applied (2026-03-03) + +Based on Critic review (verdict: REVISE → fixes applied): + +| # | Finding | Fix | +|---|---------|-----| +| 1 | Task 1 already implemented | Converted to verification-only step | +| 2 | `TeamMember \| TeamMemberSyncthing` union has no discriminator | Split into `ipfs_members` / `syncthing_members` dicts with `members` property | +| 3 | `requests` missing from pyproject.toml | Added `requests>=2.28` to Task 3 dependencies step | +| 4 | `str \| None` requires Python 3.10+ | Changed all to `Optional[str]` for Python 3.9 compat | +| 5 | `project add --team` used in Task 6 tests before defined | Moved `project add --team` implementation to Task 6 Step 1 | +| 6 | API import style doesn't match codebase | Changed to block import pattern | +| 7 | `RemoteManifest` missing `sync_backend` field | Added Step 0 to Task 8 | +| 8 | Watcher silently swallows exceptions | Added stderr error logging | +| 9 | API key in plain text | Acknowledged (mitigated by `chmod 0o600`) | +| 10 | No integration test | Post-MVP (noted in Summary) | + +--- + +## Task 1: Verify SyncManifest `sync_backend` Field (Already Implemented) + +> **Note:** This task was completed during the IPFS sync implementation. The `sync_backend` field and tests already exist. This step is a verification-only checkpoint. + +**Files (already modified):** +- `cli/karma/manifest.py:36-38` — `sync_backend: Optional[str]` field exists +- `cli/tests/test_packager.py` — `TestSyncManifest` class with 3 tests exists + +**Step 1: Verify existing implementation** + +Run: `cd cli && pytest tests/test_packager.py::TestSyncManifest -v` +Expected: PASS — all 3 tests pass (default None, set to "syncthing", in model_dump). + +**Step 2: No commit needed** — already committed. + +--- + +## Task 2: Refactor Config to Support Per-Team Backend Selection + +**Files:** +- Modify: `cli/karma/config.py` +- Create: `cli/tests/test_config_teams.py` + +This is the biggest structural change. The current config has flat `projects` and `team` dicts. We need a `teams` dict where each team has its own backend, projects, and members. + +**Step 1: Write the failing tests** + +Create `cli/tests/test_config_teams.py`: + +```python +"""Tests for per-team config model.""" + +import pytest +from karma.config import ( + SyncConfig, + TeamConfig, + ProjectConfig, + SyncthingSettings, +) + + +class TestTeamConfig: + def test_create_syncthing_team(self): + team = TeamConfig( + backend="syncthing", + owner_device_id="XXXXXXX-XXXXXXX", + projects={ + "acme": ProjectConfig(path="/Users/alice/acme", encoded_name="-Users-alice-acme") + }, + ) + assert team.backend == "syncthing" + assert "acme" in team.projects + + def test_create_ipfs_team(self): + team = TeamConfig( + backend="ipfs", + owner_ipns_key="k51abc", + projects={}, + ) + assert team.backend == "ipfs" + assert team.owner_ipns_key == "k51abc" + + def test_invalid_backend_rejected(self): + with pytest.raises(Exception): + TeamConfig(backend="dropbox", projects={}) + + +class TestSyncthingSettings: + def test_defaults(self): + s = SyncthingSettings() + assert s.api_url == "http://127.0.0.1:8384" + assert s.api_key is None + assert s.device_id is None + + def test_custom_values(self): + s = SyncthingSettings(api_url="http://localhost:9999", api_key="abc123") + assert s.api_url == "http://localhost:9999" + assert s.api_key == "abc123" + + +class TestSyncConfigWithTeams: + def test_config_has_teams(self): + config = SyncConfig(user_id="alice") + assert config.teams == {} + + def test_config_has_syncthing_settings(self): + config = SyncConfig( + user_id="alice", + syncthing=SyncthingSettings(api_key="test"), + ) + assert config.syncthing.api_key == "test" + + def test_backward_compat_projects_still_work(self): + """Old flat projects dict is still accessible for IPFS-only setups.""" + config = SyncConfig( + user_id="alice", + projects={ + "acme": ProjectConfig(path="/foo", encoded_name="-foo") + }, + ) + assert "acme" in config.projects + + def test_team_members_property(self): + """Unified members view combines ipfs_members and syncthing_members.""" + from karma.config import TeamMemberSyncthing + team = TeamConfig( + backend="syncthing", + syncthing_members={"bob": TeamMemberSyncthing(syncthing_device_id="DEVICE123")}, + ) + assert "bob" in team.members + + def test_save_and_load_with_teams(self, tmp_path, monkeypatch): + config_path = tmp_path / "sync-config.json" + monkeypatch.setattr("karma.config.SYNC_CONFIG_PATH", config_path) + monkeypatch.setattr("karma.config.KARMA_BASE", tmp_path) + + config = SyncConfig( + user_id="alice", + machine_id="test-mac", + teams={ + "beta": TeamConfig( + backend="syncthing", + owner_device_id="YYYY", + projects={ + "startup": ProjectConfig(path="/startup", encoded_name="-startup") + }, + ) + }, + syncthing=SyncthingSettings(api_url="http://127.0.0.1:8384", api_key="key123"), + ) + config.save() + + loaded = SyncConfig.load() + assert loaded is not None + assert "beta" in loaded.teams + assert loaded.teams["beta"].backend == "syncthing" + assert loaded.syncthing.api_key == "key123" +``` + +**Step 2: Run tests to verify they fail** + +Run: `cd cli && pytest tests/test_config_teams.py -v` +Expected: FAIL — `TeamConfig`, `SyncthingSettings` don't exist yet. + +**Step 3: Write minimal implementation** + +In `cli/karma/config.py`, add new models and extend `SyncConfig`. + +> **Important:** Use `Optional[str]` (not `str | None`) throughout for Python 3.9 compatibility. +> **Important:** Use separate `ipfs_members` and `syncthing_members` dicts instead of a union type to avoid Pydantic deserialization ambiguity. + +```python +from typing import Literal, Optional +# (keep existing imports) + + +class SyncthingSettings(BaseModel): + """Syncthing connection settings.""" + + model_config = ConfigDict(frozen=True) + + api_url: str = Field(default="http://127.0.0.1:8384", description="Syncthing REST API URL") + api_key: Optional[str] = Field(default=None, description="Syncthing API key") + device_id: Optional[str] = Field(default=None, description="This device's Syncthing ID") + + +class TeamMemberSyncthing(BaseModel): + """A team member identified by Syncthing device ID.""" + + model_config = ConfigDict(frozen=True) + + syncthing_device_id: str = Field(..., description="Syncthing device ID") + + @field_validator("syncthing_device_id") + @classmethod + def validate_device_id(cls, v: str) -> str: + if not v or len(v) > 128: + raise ValueError("Device ID must be non-empty and under 128 chars") + return v + + +class TeamConfig(BaseModel): + """Configuration for a team with its own sync backend.""" + + model_config = ConfigDict(frozen=True) + + backend: Literal["ipfs", "syncthing"] = Field(..., description="Sync backend for this team") + projects: dict[str, ProjectConfig] = Field(default_factory=dict) + ipfs_members: dict[str, TeamMember] = Field(default_factory=dict) + syncthing_members: dict[str, TeamMemberSyncthing] = Field(default_factory=dict) + owner_device_id: Optional[str] = Field(default=None, description="Owner's Syncthing device ID") + owner_ipns_key: Optional[str] = Field(default=None, description="Owner's IPNS key") + + @property + def members(self) -> dict: + """Unified view of all members regardless of backend.""" + result = dict(self.ipfs_members) + result.update(self.syncthing_members) + return result +``` + +Then extend `SyncConfig` to add: + +```python + teams: dict[str, TeamConfig] = Field(default_factory=dict) + syncthing: SyncthingSettings = Field(default_factory=SyncthingSettings) +``` + +> **Backward compatibility note:** Old config files lacking `teams` and `syncthing` keys will load correctly because both fields have `default_factory` defaults. The existing flat `projects` and `team` dicts are preserved for IPFS-only setups. + +**Step 4: Run tests to verify they pass** + +Run: `cd cli && pytest tests/test_config_teams.py -v` +Expected: PASS + +**Step 5: Run existing tests to verify backward compatibility** + +Run: `cd cli && pytest tests/test_config.py -v` +Expected: PASS — existing flat config still works. + +**Step 6: Commit** + +```bash +git add cli/karma/config.py cli/tests/test_config_teams.py +git commit -m "feat: add per-team backend config with Syncthing settings" +``` + +--- + +## Task 3: Create SyncthingClient (REST API Wrapper) + +**Files:** +- Create: `cli/karma/syncthing.py` +- Create: `cli/tests/test_syncthing.py` + +**Step 1: Add `requests` to dependencies** + +In `cli/pyproject.toml`, add `"requests>=2.28"` to the `dependencies` list. + +**Step 2: Write the failing tests** + +Create `cli/tests/test_syncthing.py`: + +```python +"""Tests for Syncthing REST API wrapper.""" + +from unittest.mock import patch, MagicMock +import pytest + +from karma.syncthing import SyncthingClient + + +class TestSyncthingClient: + def test_init_defaults(self): + client = SyncthingClient() + assert client.api_url == "http://127.0.0.1:8384" + + def test_init_custom(self): + client = SyncthingClient(api_url="http://localhost:9999", api_key="abc") + assert client.api_url == "http://localhost:9999" + assert client.headers["X-API-Key"] == "abc" + + @patch("karma.syncthing.requests.get") + def test_is_running_true(self, mock_get): + mock_get.return_value = MagicMock(status_code=200, json=lambda: {"myID": "XXXX"}) + client = SyncthingClient() + assert client.is_running() is True + + @patch("karma.syncthing.requests.get") + def test_is_running_false_connection_error(self, mock_get): + import requests + mock_get.side_effect = requests.ConnectionError() + client = SyncthingClient() + assert client.is_running() is False + + @patch("karma.syncthing.requests.get") + def test_get_device_id(self, mock_get): + mock_get.return_value = MagicMock( + status_code=200, + json=lambda: {"myID": "AAAAAAA-BBBBBBB-CCCCCCC-DDDDDDD"} + ) + client = SyncthingClient(api_key="test") + device_id = client.get_device_id() + assert device_id == "AAAAAAA-BBBBBBB-CCCCCCC-DDDDDDD" + + @patch("karma.syncthing.requests.get") + def test_get_connections(self, mock_get): + mock_get.return_value = MagicMock( + status_code=200, + json=lambda: { + "connections": { + "DEVICE1": {"connected": True}, + "DEVICE2": {"connected": False}, + } + } + ) + client = SyncthingClient(api_key="test") + conns = client.get_connections() + assert "DEVICE1" in conns + assert conns["DEVICE1"]["connected"] is True + + @patch("karma.syncthing.requests.get") + @patch("karma.syncthing.requests.put") + def test_add_device(self, mock_put, mock_get): + mock_get.return_value = MagicMock( + status_code=200, + json=lambda: {"devices": [], "folders": []} + ) + mock_put.return_value = MagicMock(status_code=200) + + client = SyncthingClient(api_key="test") + client.add_device("NEWDEVICE-ID", "alice") + + mock_put.assert_called_once() + put_data = mock_put.call_args[1]["json"] + assert any(d["deviceID"] == "NEWDEVICE-ID" for d in put_data["devices"]) + + @patch("karma.syncthing.requests.get") + @patch("karma.syncthing.requests.put") + def test_add_folder(self, mock_put, mock_get): + mock_get.return_value = MagicMock( + status_code=200, + json=lambda: {"devices": [], "folders": []} + ) + mock_put.return_value = MagicMock(status_code=200) + + client = SyncthingClient(api_key="test") + client.add_folder("karma-out-alice", "/tmp/sync", ["DEVICE1"], folder_type="sendonly") + + mock_put.assert_called_once() + put_data = mock_put.call_args[1]["json"] + folder = put_data["folders"][0] + assert folder["id"] == "karma-out-alice" + assert folder["type"] == "sendonly" +``` + +**Step 3: Run tests to verify they fail** + +Run: `cd cli && pytest tests/test_syncthing.py -v` +Expected: FAIL — `karma.syncthing` module doesn't exist. + +**Step 4: Write minimal implementation** + +Create `cli/karma/syncthing.py`: + +> **Important:** Use `Optional[str]` (not `str | None`) for Python 3.9 compatibility. + +```python +"""Syncthing REST API wrapper.""" + +from typing import Optional + +import requests + + +class SyncthingClient: + """Wraps the Syncthing REST API for device/folder management.""" + + def __init__(self, api_url: str = "http://127.0.0.1:8384", api_key: Optional[str] = None): + self.api_url = api_url.rstrip("/") + self.headers = {} + if api_key: + self.headers["X-API-Key"] = api_key + + def is_running(self) -> bool: + """Check if Syncthing is running and accessible.""" + try: + resp = requests.get( + f"{self.api_url}/rest/system/status", + headers=self.headers, + timeout=5, + ) + return resp.status_code == 200 + except requests.ConnectionError: + return False + + def get_device_id(self) -> str: + """Get this device's Syncthing Device ID.""" + resp = requests.get( + f"{self.api_url}/rest/system/status", + headers=self.headers, + timeout=10, + ) + resp.raise_for_status() + return resp.json()["myID"] + + def get_connections(self) -> dict: + """Check which devices are connected.""" + resp = requests.get( + f"{self.api_url}/rest/system/connections", + headers=self.headers, + timeout=10, + ) + resp.raise_for_status() + return resp.json()["connections"] + + def add_device(self, device_id: str, name: str) -> None: + """Pair with a remote device.""" + config = self._get_config() + config["devices"].append({ + "deviceID": device_id, + "name": name, + "autoAcceptFolders": False, + }) + self._set_config(config) + + def add_folder( + self, + folder_id: str, + path: str, + devices: list[str], + folder_type: str = "sendonly", + ) -> None: + """Create a shared folder with specified devices.""" + config = self._get_config() + config["folders"].append({ + "id": folder_id, + "path": path, + "devices": [{"deviceID": d} for d in devices], + "type": folder_type, + }) + self._set_config(config) + + def remove_device(self, device_id: str) -> None: + """Remove a paired device.""" + config = self._get_config() + config["devices"] = [d for d in config["devices"] if d["deviceID"] != device_id] + self._set_config(config) + + def remove_folder(self, folder_id: str) -> None: + """Remove a shared folder.""" + config = self._get_config() + config["folders"] = [f for f in config["folders"] if f["id"] != folder_id] + self._set_config(config) + + def _get_config(self) -> dict: + resp = requests.get(f"{self.api_url}/rest/config", headers=self.headers, timeout=10) + resp.raise_for_status() + return resp.json() + + def _set_config(self, config: dict) -> None: + resp = requests.put( + f"{self.api_url}/rest/config", + json=config, + headers=self.headers, + timeout=10, + ) + resp.raise_for_status() +``` + +**Step 5: Run tests to verify they pass** + +Run: `cd cli && pytest tests/test_syncthing.py -v` +Expected: PASS + +**Step 6: Commit** + +```bash +git add cli/karma/syncthing.py cli/tests/test_syncthing.py cli/pyproject.toml +git commit -m "feat: add SyncthingClient REST API wrapper" +``` + +--- + +## Task 4: Create SessionWatcher (Filesystem Monitor) + +**Files:** +- Create: `cli/karma/watcher.py` +- Create: `cli/tests/test_watcher.py` + +**Step 1: Add `watchdog` to dependencies** + +In `cli/pyproject.toml`, add `"watchdog>=3.0"` to the `dependencies` list. + +**Step 2: Write the failing tests** + +Create `cli/tests/test_watcher.py`: + +```python +"""Tests for filesystem session watcher.""" + +import time +from pathlib import Path +from unittest.mock import MagicMock, patch + +import pytest + +from karma.watcher import SessionWatcher + + +class TestSessionWatcher: + def test_init(self): + packager_fn = MagicMock() + watcher = SessionWatcher( + watch_dir=Path("/tmp/test"), + package_fn=packager_fn, + debounce_seconds=2, + ) + assert watcher.debounce_seconds == 2 + assert watcher.watch_dir == Path("/tmp/test") + + def test_should_process_jsonl(self): + watcher = SessionWatcher( + watch_dir=Path("/tmp"), + package_fn=MagicMock(), + ) + assert watcher._should_process("/tmp/abc123.jsonl") is True + assert watcher._should_process("/tmp/agent-xyz.jsonl") is False + assert watcher._should_process("/tmp/readme.txt") is False + assert watcher._should_process("/tmp/subdir/file.jsonl") is True + + def test_debounce_calls_package_fn_once(self): + packager_fn = MagicMock() + watcher = SessionWatcher( + watch_dir=Path("/tmp"), + package_fn=packager_fn, + debounce_seconds=0.1, + ) + # Simulate rapid file changes + watcher._schedule_package() + watcher._schedule_package() + watcher._schedule_package() + time.sleep(0.3) + # Should only call once despite 3 triggers + assert packager_fn.call_count == 1 + + def test_is_running_property(self): + watcher = SessionWatcher( + watch_dir=Path("/tmp"), + package_fn=MagicMock(), + ) + assert watcher.is_running is False +``` + +**Step 3: Run tests to verify they fail** + +Run: `cd cli && pytest tests/test_watcher.py -v` +Expected: FAIL — `karma.watcher` module doesn't exist. + +**Step 4: Write minimal implementation** + +Create `cli/karma/watcher.py`: + +```python +"""Filesystem watcher for automatic session packaging.""" + +import threading +from pathlib import Path +from typing import Callable, Optional + +from watchdog.events import FileSystemEventHandler, FileModifiedEvent, FileCreatedEvent +from watchdog.observers import Observer + + +class SessionWatcher(FileSystemEventHandler): + """Watches Claude project dirs for JSONL changes and triggers packaging.""" + + def __init__( + self, + watch_dir: Path, + package_fn: Callable[[], None], + debounce_seconds: float = 5.0, + ): + self.watch_dir = Path(watch_dir) + self.package_fn = package_fn + self.debounce_seconds = debounce_seconds + self._timer: Optional[threading.Timer] = None + self._observer: Optional[Observer] = None + self._lock = threading.Lock() + + @property + def is_running(self) -> bool: + return self._observer is not None and self._observer.is_alive() + + def _should_process(self, path: str) -> bool: + """Only process session JSONL files (not agent files).""" + p = Path(path) + return p.suffix == ".jsonl" and not p.name.startswith("agent-") + + def on_modified(self, event): + if not isinstance(event, (FileModifiedEvent, FileCreatedEvent)): + return + if self._should_process(event.src_path): + self._schedule_package() + + def on_created(self, event): + if self._should_process(event.src_path): + self._schedule_package() + + def _schedule_package(self): + """Debounced packaging — waits for quiet period before running.""" + with self._lock: + if self._timer is not None: + self._timer.cancel() + self._timer = threading.Timer(self.debounce_seconds, self._do_package) + self._timer.daemon = True + self._timer.start() + + def _do_package(self): + """Execute the packaging function.""" + try: + self.package_fn() + except Exception as e: + import sys + print(f"[karma watch] Packaging error: {e}", file=sys.stderr) + + def start(self): + """Start watching the directory.""" + self._observer = Observer() + self._observer.schedule(self, str(self.watch_dir), recursive=True) + self._observer.daemon = True + self._observer.start() + + def stop(self): + """Stop watching.""" + with self._lock: + if self._timer is not None: + self._timer.cancel() + self._timer = None + if self._observer is not None: + self._observer.stop() + self._observer.join(timeout=5) + self._observer = None +``` + +**Step 5: Run tests to verify they pass** + +Run: `cd cli && pytest tests/test_watcher.py -v` +Expected: PASS + +**Step 6: Commit** + +```bash +git add cli/karma/watcher.py cli/tests/test_watcher.py cli/pyproject.toml +git commit -m "feat: add SessionWatcher with debounced filesystem monitoring" +``` + +--- + +## Task 5: Extend CLI with Backend-Aware Init and Team Create + +**Files:** +- Modify: `cli/karma/main.py` +- Create: `cli/tests/test_cli_syncthing.py` + +**Step 1: Write the failing tests** + +Create `cli/tests/test_cli_syncthing.py`: + +```python +"""Tests for Syncthing CLI commands.""" + +from unittest.mock import patch, MagicMock +from click.testing import CliRunner + +import pytest + +from karma.main import cli + + +@pytest.fixture +def runner(): + return CliRunner() + + +@pytest.fixture +def mock_config(tmp_path, monkeypatch): + config_path = tmp_path / "sync-config.json" + monkeypatch.setattr("karma.config.SYNC_CONFIG_PATH", config_path) + monkeypatch.setattr("karma.config.KARMA_BASE", tmp_path) + return config_path + + +class TestInitWithBackend: + def test_init_default_no_backend_flag(self, runner, mock_config): + result = runner.invoke(cli, ["init", "--user-id", "alice"]) + assert result.exit_code == 0 + assert "alice" in result.output + + @patch("karma.main.SyncthingClient") + def test_init_syncthing_backend(self, mock_st_cls, runner, mock_config): + mock_st = MagicMock() + mock_st.is_running.return_value = True + mock_st.get_device_id.return_value = "AAAA-BBBB-CCCC" + mock_st_cls.return_value = mock_st + + result = runner.invoke(cli, ["init", "--user-id", "alice", "--backend", "syncthing"]) + assert result.exit_code == 0 + assert "AAAA-BBBB-CCCC" in result.output + + @patch("karma.main.SyncthingClient") + def test_init_syncthing_not_running(self, mock_st_cls, runner, mock_config): + mock_st = MagicMock() + mock_st.is_running.return_value = False + mock_st_cls.return_value = mock_st + + result = runner.invoke(cli, ["init", "--user-id", "alice", "--backend", "syncthing"]) + assert result.exit_code != 0 + assert "not running" in result.output.lower() or "not running" in str(result.exception).lower() + + +class TestTeamCreate: + def test_team_create_syncthing(self, runner, mock_config): + # First init + runner.invoke(cli, ["init", "--user-id", "alice"]) + # Then create team + result = runner.invoke(cli, ["team", "create", "beta", "--backend", "syncthing"]) + assert result.exit_code == 0 + assert "beta" in result.output + + def test_team_create_ipfs(self, runner, mock_config): + runner.invoke(cli, ["init", "--user-id", "alice"]) + result = runner.invoke(cli, ["team", "create", "alpha", "--backend", "ipfs"]) + assert result.exit_code == 0 + assert "alpha" in result.output + + def test_team_create_requires_init(self, runner, mock_config): + result = runner.invoke(cli, ["team", "create", "beta", "--backend", "syncthing"]) + assert result.exit_code != 0 + + +class TestTeamAddSyncthing: + def test_team_add_device_id(self, runner, mock_config): + runner.invoke(cli, ["init", "--user-id", "alice"]) + runner.invoke(cli, ["team", "create", "beta", "--backend", "syncthing"]) + result = runner.invoke(cli, ["team", "add", "bob", "DEVICEID123", "--team", "beta"]) + assert result.exit_code == 0 + assert "bob" in result.output +``` + +**Step 2: Run tests to verify they fail** + +Run: `cd cli && pytest tests/test_cli_syncthing.py -v` +Expected: FAIL — `--backend` option and `team create` command don't exist. + +**Step 3: Write minimal implementation** + +Modify `cli/karma/main.py`: + +1. Add `--backend` option to `init` command: + +Replace the existing `init` command (keeping existing validation logic) to add `--backend` option: + +```python +@cli.command() +@click.option("--user-id", prompt="Your user ID (e.g., your name)", help="Identity for syncing") +@click.option("--backend", type=click.Choice(["ipfs", "syncthing"]), default=None, help="Sync backend") +def init(user_id: str, backend: Optional[str]): + """Initialize Karma sync on this machine.""" + existing = SyncConfig.load() + if existing: + click.echo(f"Already initialized as '{existing.user_id}' on '{existing.machine_id}'.") + if not click.confirm("Reinitialize?"): + return + + if not _SAFE_NAME.match(user_id): + raise click.ClickException("User ID must be alphanumeric, dash, or underscore only.") + + if backend == "syncthing": + from karma.syncthing import SyncthingClient + st = SyncthingClient() + if not st.is_running(): + raise click.ClickException("Syncthing is not running. Start Syncthing first.") + device_id = st.get_device_id() + config = SyncConfig(user_id=user_id) + config.save() + click.echo(f"Initialized as '{user_id}' on '{config.machine_id}'.") + click.echo(f"Your Syncthing Device ID: {device_id}") + click.echo("Share this Device ID with your project owner.") + else: + config = SyncConfig(user_id=user_id) + config.save() + click.echo(f"Initialized as '{user_id}' on '{config.machine_id}'.") + click.echo(f"Config saved to {SYNC_CONFIG_PATH}") + click.echo("\nNext steps:") + click.echo(" 1. Install Kubo: https://docs.ipfs.tech/install/command-line/") + click.echo(" 2. Start IPFS daemon: ipfs daemon &") + click.echo(" 3. Add a project: karma project add --path /path/to/project") +``` + +> **Note:** Add `from typing import Optional` to the top of `main.py` if not already present. + +2. Add `team create` command: + +```python +@team.command("create") +@click.argument("name") +@click.option("--backend", type=click.Choice(["ipfs", "syncthing"]), required=True, help="Sync backend") +def team_create(name: str, backend: str): + """Create a new team with a specific sync backend.""" + if not _SAFE_NAME.match(name): + raise click.ClickException("Team name must be alphanumeric, dash, or underscore only.") + + config = require_config() + + from karma.config import TeamConfig + team_config = TeamConfig(backend=backend, projects={}) + + teams = dict(config.teams) + teams[name] = team_config + updated = config.model_copy(update={"teams": teams}) + updated.save() + + click.echo(f"Created team '{name}' (backend: {backend})") +``` + +3. Modify `team add` to accept `--team` option and support both IPNS keys and device IDs: + +```python +@team.command("add") +@click.argument("name") +@click.argument("identifier") +@click.option("--team", "team_name", default=None, help="Team to add member to (for per-team config)") +def team_add(name: str, identifier: str, team_name: Optional[str]): + """Add a team member by their IPNS key or Syncthing device ID.""" + if not _SAFE_NAME.match(name): + raise click.ClickException("Team member name must be alphanumeric, dash, or underscore only.") + + config = require_config() + + if team_name and team_name in config.teams: + # Per-team member add + team_cfg = config.teams[team_name] + if team_cfg.backend == "syncthing": + from karma.config import TeamMemberSyncthing + syncthing_members = dict(team_cfg.syncthing_members) + syncthing_members[name] = TeamMemberSyncthing(syncthing_device_id=identifier) + teams = dict(config.teams) + teams[team_name] = team_cfg.model_copy(update={"syncthing_members": syncthing_members}) + else: + ipfs_members = dict(team_cfg.ipfs_members) + ipfs_members[name] = TeamMember(ipns_key=identifier) + teams = dict(config.teams) + teams[team_name] = team_cfg.model_copy(update={"ipfs_members": ipfs_members}) + updated = config.model_copy(update={"teams": teams}) + updated.save() + click.echo(f"Added team member '{name}' to team '{team_name}'") + else: + # Legacy flat team dict (IPFS-only backward compat) + if not identifier or identifier.startswith("-") or len(identifier) > 128: + raise click.ClickException("Invalid IPNS key.") + if not re.match(r"^[a-zA-Z0-9]+$", identifier): + raise click.ClickException("Invalid IPNS key: must be alphanumeric only.") + members = dict(config.team) + members[name] = TeamMember(ipns_key=identifier) + updated = config.model_copy(update={"team": members}) + updated.save() + click.echo(f"Added team member '{name}' ({identifier})") +``` + +**Step 4: Run tests to verify they pass** + +Run: `cd cli && pytest tests/test_cli_syncthing.py -v` +Expected: PASS + +**Step 5: Run all existing tests** + +Run: `cd cli && pytest -v` +Expected: All PASS (existing behavior preserved). + +**Step 6: Commit** + +```bash +git add cli/karma/main.py cli/tests/test_cli_syncthing.py +git commit -m "feat: add --backend flag to init, team create command, Syncthing-aware team add" +``` + +--- + +## Task 6: Add `karma watch` Command and `project add --team` Flag + +**Files:** +- Modify: `cli/karma/main.py` +- Add tests to: `cli/tests/test_cli_syncthing.py` + +**Step 1: First, modify `project add` to accept `--team` option** + +This must be done BEFORE writing the watch tests, since `TestWatchCommand` uses `project add --team`. + +Modify the `project_add` command in `cli/karma/main.py`: + +```python +@project.command("add") +@click.argument("name") +@click.option("--path", required=True, help="Absolute path to the project directory") +@click.option("--team", "team_name", default=None, help="Team to add project to") +def project_add(name: str, path: str, team_name: Optional[str]): + """Add a project for syncing.""" + if not _SAFE_NAME.match(name): + raise click.ClickException("Project name must be alphanumeric, dash, or underscore only.") + + from pathlib import Path as _Path + if not _Path(path).is_absolute(): + raise click.ClickException("Project path must be absolute (e.g., /Users/alice/my-project).") + + config = require_config() + encoded = encode_project_path(path) + project_config = ProjectConfig(path=path, encoded_name=encoded) + + if team_name: + if team_name not in config.teams: + raise click.ClickException(f"Team '{team_name}' not found.") + team_cfg = config.teams[team_name] + projects = dict(team_cfg.projects) + projects[name] = project_config + teams = dict(config.teams) + teams[team_name] = team_cfg.model_copy(update={"projects": projects}) + updated = config.model_copy(update={"teams": teams}) + else: + # Legacy flat projects + projects = dict(config.projects) + projects[name] = project_config + updated = config.model_copy(update={"projects": projects}) + + updated.save() + click.echo(f"Added project '{name}' ({path})") + click.echo(f"Encoded as: {encoded}") +``` + +**Step 2: Write the failing tests** + +Add to `cli/tests/test_cli_syncthing.py`: + +```python +class TestWatchCommand: + def test_watch_requires_init(self, runner, mock_config): + result = runner.invoke(cli, ["watch"]) + assert result.exit_code != 0 + + def test_watch_requires_syncthing_team(self, runner, mock_config): + runner.invoke(cli, ["init", "--user-id", "alice"]) + result = runner.invoke(cli, ["watch", "--team", "nonexistent"]) + assert result.exit_code != 0 + + @patch("karma.main.SessionWatcher") + def test_watch_starts_and_stops_on_interrupt(self, mock_watcher_cls, runner, mock_config): + runner.invoke(cli, ["init", "--user-id", "alice"]) + runner.invoke(cli, ["team", "create", "beta", "--backend", "syncthing"]) + runner.invoke(cli, [ + "project", "add", "app", "--path", "/tmp/test-project", "--team", "beta" + ]) + + mock_watcher = MagicMock() + mock_watcher_cls.return_value = mock_watcher + # Simulate KeyboardInterrupt after start + mock_watcher.start.side_effect = KeyboardInterrupt() + + result = runner.invoke(cli, ["watch", "--team", "beta"]) + # Should handle gracefully + mock_watcher.stop.assert_called() +``` + +**Step 2: Run tests to verify they fail** + +Run: `cd cli && pytest tests/test_cli_syncthing.py::TestWatchCommand -v` +Expected: FAIL — `watch` command doesn't exist yet. + +**Step 3: Write minimal implementation** + +Add to `cli/karma/main.py`: + +```python +@cli.command() +@click.option("--team", "team_name", required=True, help="Team to watch for") +def watch(team_name: str): + """Watch project sessions and auto-package for Syncthing sync.""" + from karma.watcher import SessionWatcher + from karma.packager import SessionPackager + + config = require_config() + + if team_name not in config.teams: + raise click.ClickException(f"Team '{team_name}' not found. Run: karma team create {team_name}") + + team_cfg = config.teams[team_name] + if team_cfg.backend != "syncthing": + raise click.ClickException(f"Team '{team_name}' uses {team_cfg.backend}, not syncthing. Watch is only for Syncthing.") + + if not team_cfg.projects: + raise click.ClickException(f"No projects in team '{team_name}'. Run: karma project add --team {team_name}") + + click.echo(f"Watching {len(team_cfg.projects)} project(s) for team '{team_name}'...") + click.echo("Press Ctrl+C to stop.\n") + + watchers = [] + for proj_name, proj in team_cfg.projects.items(): + claude_dir = Path.home() / ".claude" / "projects" / proj.encoded_name + if not claude_dir.is_dir(): + click.echo(f" Skipping '{proj_name}': Claude dir not found ({claude_dir})") + continue + + # team_name intentionally excluded — user_id provides namespace isolation + outbox = KARMA_BASE / "remote-sessions" / config.user_id / proj.encoded_name + + def make_package_fn(cd=claude_dir, ob=outbox, pn=proj_name): + def package(): + packager = SessionPackager( + project_dir=cd, + user_id=config.user_id, + machine_id=config.machine_id, + project_path=proj.path, + ) + ob.mkdir(parents=True, exist_ok=True) + packager.package(staging_dir=ob) + click.echo(f" Packaged '{pn}' -> {ob}") + return package + + watcher = SessionWatcher( + watch_dir=claude_dir, + package_fn=make_package_fn(), + ) + watcher.start() + watchers.append(watcher) + click.echo(f" Watching: {proj_name} ({claude_dir})") + + try: + import time + while True: + time.sleep(1) + except KeyboardInterrupt: + click.echo("\nStopping watchers...") + finally: + for w in watchers: + w.stop() + click.echo("Done.") +``` + +**Step 4: Run tests to verify they pass** + +Run: `cd cli && pytest tests/test_cli_syncthing.py -v` +Expected: PASS + +**Step 5: Run all tests** + +Run: `cd cli && pytest -v` +Expected: All PASS + +**Step 6: Commit** + +```bash +git add cli/karma/main.py cli/tests/test_cli_syncthing.py +git commit -m "feat: add karma watch command and --team flag for project add" +``` + +--- + +## Task 7: Add `karma status` Command + +**Files:** +- Modify: `cli/karma/main.py` +- Add tests to: `cli/tests/test_cli_syncthing.py` + +**Step 1: Write the failing tests** + +Add to `cli/tests/test_cli_syncthing.py`: + +```python +class TestStatusCommand: + def test_status_no_teams(self, runner, mock_config): + runner.invoke(cli, ["init", "--user-id", "alice"]) + result = runner.invoke(cli, ["status"]) + assert result.exit_code == 0 + assert "No teams" in result.output + + def test_status_shows_teams(self, runner, mock_config): + runner.invoke(cli, ["init", "--user-id", "alice"]) + runner.invoke(cli, ["team", "create", "beta", "--backend", "syncthing"]) + result = runner.invoke(cli, ["status"]) + assert result.exit_code == 0 + assert "beta" in result.output + assert "syncthing" in result.output.lower() +``` + +**Step 2: Run tests to verify they fail** + +Run: `cd cli && pytest tests/test_cli_syncthing.py::TestStatusCommand -v` +Expected: FAIL — `status` command doesn't exist. + +**Step 3: Write minimal implementation** + +Add to `cli/karma/main.py`: + +```python +@cli.command() +def status(): + """Show sync status for all teams.""" + config = require_config() + + click.echo(f"User: {config.user_id} ({config.machine_id})") + + if not config.teams and not config.projects: + click.echo("No teams or projects configured.") + return + + # Legacy flat projects + if config.projects: + click.echo(f"\nLegacy projects (IPFS):") + for name, proj in config.projects.items(): + sync_info = f"last sync: {proj.last_sync_at}" if proj.last_sync_at else "never synced" + click.echo(f" {name}: {proj.path} ({sync_info})") + + # Per-team + for team_name, team_cfg in config.teams.items(): + click.echo(f"\n{team_name} ({team_cfg.backend}):") + if not team_cfg.projects: + click.echo(" No projects") + for proj_name, proj in team_cfg.projects.items(): + last = proj.last_sync_at or "never" + click.echo(f" {proj_name}: {proj.path} (last: {last})") + if team_cfg.members: + click.echo(f" Members: {', '.join(team_cfg.members.keys())}") +``` + +**Step 4: Run tests to verify they pass** + +Run: `cd cli && pytest tests/test_cli_syncthing.py::TestStatusCommand -v` +Expected: PASS + +**Step 5: Commit** + +```bash +git add cli/karma/main.py cli/tests/test_cli_syncthing.py +git commit -m "feat: add karma status command showing teams and sync state" +``` + +--- + +## Task 8: Add API Sync Status Endpoints + Extend RemoteManifest + +**Files:** +- Create: `api/routers/sync_status.py` +- Create: `api/tests/api/test_sync_status.py` +- Modify: `api/main.py` (register router) +- Modify: `api/routers/remote_sessions.py` (add `sync_backend` to `RemoteManifest`) + +**Step 0: Extend RemoteManifest to accept `sync_backend`** + +In `api/routers/remote_sessions.py`, add `sync_backend: Optional[str] = None` to the `RemoteManifest` model so the API does not reject Syncthing-generated manifests that include this field. + +**Step 1: Write the failing tests** + +Create `api/tests/api/test_sync_status.py`: + +```python +"""Tests for sync status API endpoints.""" + +import json +from pathlib import Path +from unittest.mock import patch + +import pytest +from fastapi.testclient import TestClient + +from main import app + +client = TestClient(app) + + +class TestSyncStatus: + def test_sync_status_no_config(self, tmp_path, monkeypatch): + monkeypatch.setattr( + "routers.sync_status.SYNC_CONFIG_PATH", + tmp_path / "nonexistent.json", + ) + resp = client.get("/sync/status") + assert resp.status_code == 200 + data = resp.json() + assert data["configured"] is False + + def test_sync_status_with_config(self, tmp_path, monkeypatch): + config_path = tmp_path / "sync-config.json" + config_path.write_text(json.dumps({ + "user_id": "alice", + "machine_id": "mac", + "teams": { + "beta": { + "backend": "syncthing", + "projects": {"app": {"path": "/app", "encoded_name": "-app"}}, + "members": {}, + } + }, + "projects": {}, + "team": {}, + })) + monkeypatch.setattr("routers.sync_status.SYNC_CONFIG_PATH", config_path) + resp = client.get("/sync/status") + assert resp.status_code == 200 + data = resp.json() + assert data["configured"] is True + assert data["user_id"] == "alice" + assert "beta" in data["teams"] + + def test_sync_teams_endpoint(self, tmp_path, monkeypatch): + config_path = tmp_path / "sync-config.json" + config_path.write_text(json.dumps({ + "user_id": "alice", + "machine_id": "mac", + "teams": { + "alpha": {"backend": "ipfs", "projects": {}, "members": {}}, + "beta": {"backend": "syncthing", "projects": {}, "members": {}}, + }, + "projects": {}, + "team": {}, + })) + monkeypatch.setattr("routers.sync_status.SYNC_CONFIG_PATH", config_path) + resp = client.get("/sync/teams") + assert resp.status_code == 200 + data = resp.json() + assert len(data["teams"]) == 2 +``` + +**Step 2: Run tests to verify they fail** + +Run: `cd api && pytest tests/api/test_sync_status.py -v` +Expected: FAIL — router doesn't exist. + +**Step 3: Write minimal implementation** + +Create `api/routers/sync_status.py`: + +```python +"""Sync status API endpoints.""" + +import json +from pathlib import Path + +from fastapi import APIRouter + +SYNC_CONFIG_PATH = Path.home() / ".claude_karma" / "sync-config.json" + +router = APIRouter(prefix="/sync", tags=["sync"]) + + +def _load_config() -> dict | None: + if not SYNC_CONFIG_PATH.exists(): + return None + return json.loads(SYNC_CONFIG_PATH.read_text()) + + +@router.get("/status") +async def sync_status(): + """Get sync configuration and status.""" + config = _load_config() + if config is None: + return {"configured": False} + + teams = {} + for name, team in config.get("teams", {}).items(): + teams[name] = { + "backend": team["backend"], + "project_count": len(team.get("projects", {})), + "member_count": len(team.get("members", {})), + } + + return { + "configured": True, + "user_id": config.get("user_id"), + "machine_id": config.get("machine_id"), + "teams": teams, + } + + +@router.get("/teams") +async def sync_teams(): + """List all teams with their backend and members.""" + config = _load_config() + if config is None: + return {"teams": []} + + teams = [] + for name, team in config.get("teams", {}).items(): + teams.append({ + "name": name, + "backend": team["backend"], + "projects": list(team.get("projects", {}).keys()), + "members": list(team.get("members", {}).keys()), + }) + + return {"teams": teams} +``` + +In `api/main.py`, add `sync_status` to the existing block import and register the router following the existing pattern: + +```python +# Add to the existing block import: +from routers import ( + ..., + sync_status, +) + +# Add alongside the other router registrations: +app.include_router(sync_status.router) +``` + +**Step 4: Run tests to verify they pass** + +Run: `cd api && pytest tests/api/test_sync_status.py -v` +Expected: PASS + +**Step 5: Run all API tests** + +Run: `cd api && pytest -v` +Expected: All PASS + +**Step 6: Commit** + +```bash +git add api/routers/sync_status.py api/tests/api/test_sync_status.py api/main.py +git commit -m "feat: add /sync/status and /sync/teams API endpoints" +``` + +--- + +## Summary + +| Task | Component | Key Files | Tests | +|------|-----------|-----------|-------| +| 1 | Manifest extension (verify only) | `manifest.py` | `test_packager.py` | +| 2 | Per-team config | `config.py` | `test_config_teams.py` | +| 3 | Syncthing client | `syncthing.py`, `pyproject.toml` | `test_syncthing.py` | +| 4 | Filesystem watcher | `watcher.py`, `pyproject.toml` | `test_watcher.py` | +| 5 | CLI init + team create | `main.py` | `test_cli_syncthing.py` | +| 6 | CLI watch + project add --team | `main.py` | `test_cli_syncthing.py` | +| 7 | CLI status command | `main.py` | `test_cli_syncthing.py` | +| 8 | API sync endpoints + RemoteManifest | `sync_status.py`, `remote_sessions.py`, `main.py` | `test_sync_status.py` | + +**Dependencies:** Task 1 (verify) → Task 2 → Tasks 3, 4 (parallel) → Tasks 5, 6, 7 (sequential) → Task 8 + +**Post-MVP:** Integration test for end-to-end flow (init → team create → project add → watch → outbox), Syncthing API key encryption at rest. diff --git a/docs/plans/2026-03-05-complete-sync-pipeline-plan.md b/docs/plans/2026-03-05-complete-sync-pipeline-plan.md new file mode 100644 index 00000000..0ae1e812 --- /dev/null +++ b/docs/plans/2026-03-05-complete-sync-pipeline-plan.md @@ -0,0 +1,580 @@ +# Complete Sync Pipeline — Implementation Plan + +> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. + +**Goal:** Make remote sessions fully viewable by syncing all data sources (tasks, deep metadata) and indexing them at the same depth as local sessions. + +**Architecture:** Three layers — (1) sync task files alongside sessions/todos in the CLI packager, (2) deep-index remote sessions with full `Session._load_metadata()` instead of lazy first/last-line parsing, (3) route `/sessions/{uuid}` to find remote sessions transparently so the frontend works without changes. + +**Tech Stack:** Python 3.9+, FastAPI, Pydantic 2.x, SQLite, pytest + +**Prior plan:** `docs/plans/2026-03-05-syncthing-worktree-sync-plan.md` (worktree sync — completed) + +**Key insight:** Remote sessions already land on disk via Syncthing at `~/.claude_karma/remote-sessions/{user_id}/{encoded_name}/sessions/{uuid}.jsonl`. The API can serve them through the same `Session.from_path()` used for local sessions — the gap is (a) missing task files, (b) shallow indexing, and (c) no path resolution from `/sessions/{uuid}`. + +--- + +## Task 1: Sync task directories in the CLI packager + +Tasks live in `~/.claude/tasks/{uuid}/` as individual JSON files (`1.json`, `2.json`, etc.). The packager already copies todos — mirror that pattern for tasks. + +**Files:** +- Modify: `cli/karma/packager.py:99-115` (package method) +- Modify: `cli/tests/test_packager.py` + +**Step 1: Write failing tests** + +Add to `cli/tests/test_packager.py`: + +```python +class TestTaskSyncing: + def test_package_copies_task_files(self, tmp_path): + """Tasks from ~/.claude/tasks/{uuid}/ should be copied.""" + # Create project dir structure: .claude/projects/-My-project/ + claude_dir = tmp_path / ".claude" + project_dir = claude_dir / "projects" / "-My-project" + project_dir.mkdir(parents=True) + (project_dir / "session-abc.jsonl").write_text( + '{"type":"user","message":{"role":"user","content":"hello"}}\n' + ) + + # Create task dir: .claude/tasks/session-abc/ + tasks_dir = claude_dir / "tasks" / "session-abc" + tasks_dir.mkdir(parents=True) + (tasks_dir / "1.json").write_text( + '{"id":"1","subject":"Fix bug","status":"completed"}\n' + ) + (tasks_dir / "2.json").write_text( + '{"id":"2","subject":"Add test","status":"pending"}\n' + ) + + staging = tmp_path / "staging" + packager = SessionPackager( + project_dir=project_dir, + user_id="alice", + machine_id="mac", + ) + packager.package(staging_dir=staging) + + assert (staging / "tasks" / "session-abc" / "1.json").exists() + assert (staging / "tasks" / "session-abc" / "2.json").exists() + + def test_package_skips_missing_task_dir(self, mock_claude_project, tmp_path): + """Sessions without task dirs should not cause errors.""" + staging = tmp_path / "staging" + packager = SessionPackager( + project_dir=mock_claude_project, + user_id="alice", + machine_id="mac", + ) + manifest = packager.package(staging_dir=staging) + assert manifest.session_count == 2 + # tasks dir should not exist if no tasks + assert not (staging / "tasks").exists() + + def test_package_copies_worktree_tasks(self, tmp_path): + """Tasks for worktree sessions should also be copied.""" + claude_dir = tmp_path / ".claude" + main_dir = claude_dir / "projects" / "-Users-jay-karma" + main_dir.mkdir(parents=True) + (main_dir / "main-s.jsonl").write_text('{"type":"user"}\n') + + wt_dir = claude_dir / "projects" / "-Users-jay-karma--claude-worktrees-feat" + wt_dir.mkdir(parents=True) + (wt_dir / "wt-s.jsonl").write_text('{"type":"user"}\n') + + # Task for worktree session + tasks_dir = claude_dir / "tasks" / "wt-s" + tasks_dir.mkdir(parents=True) + (tasks_dir / "1.json").write_text('{"id":"1","subject":"WT task","status":"pending"}\n') + + staging = tmp_path / "staging" + packager = SessionPackager( + project_dir=main_dir, + user_id="jay", + machine_id="mac", + extra_dirs=[wt_dir], + ) + packager.package(staging_dir=staging) + + assert (staging / "tasks" / "wt-s" / "1.json").exists() +``` + +**Step 2: Run tests to verify they fail** + +Run: `cd cli && pytest tests/test_packager.py::TestTaskSyncing -v` +Expected: FAIL — task files not copied (no `tasks/` dir in staging) + +**Step 3: Add task copying to `package()` method** + +In `cli/karma/packager.py`, add after the todos block (around line 115): + +```python + # Copy tasks if they exist + tasks_base = self.project_dir.parent.parent / "tasks" + if tasks_base.is_dir(): + tasks_staging = staging_dir / "tasks" + for session_entry in sessions: + task_dir = tasks_base / session_entry.uuid + if task_dir.is_dir(): + tasks_staging.mkdir(exist_ok=True) + shutil.copytree( + task_dir, + tasks_staging / session_entry.uuid, + dirs_exist_ok=True, + ) +``` + +**Step 4: Run tests to verify they pass** + +Run: `cd cli && pytest tests/test_packager.py -v` +Expected: All PASS + +**Step 5: Commit** + +```bash +git add cli/karma/packager.py cli/tests/test_packager.py +git commit -m "feat(cli): sync task directories alongside sessions and todos + +Copies ~/.claude/tasks/{uuid}/ into staging/tasks/{uuid}/ for each +session, including worktree sessions. Mirrors the existing todo pattern." +``` + +--- + +## Task 2: Deep-index remote sessions + +Currently `index_remote_sessions()` (indexer.py:232-315) only reads first/last JSONL lines. Local sessions go through `_index_session()` (indexer.py:318-543) which calls `Session._load_metadata()` and populates session_tools, session_skills, session_commands, subagent_invocations, etc. + +The fix: call `_index_session()` for remote sessions instead of the shallow parsing. + +**Files:** +- Modify: `api/db/indexer.py:232-315` (index_remote_sessions function) +- Modify: `api/tests/test_indexer.py` (or create if missing) + +**Step 1: Write failing test** + +Create `api/tests/test_remote_indexing.py`: + +```python +"""Tests for deep remote session indexing.""" + +import json +import sqlite3 +from pathlib import Path + +import pytest + +from db.indexer import index_remote_sessions, _index_session +from db.schema import init_db + + +@pytest.fixture +def db_conn(tmp_path): + """Create an in-memory SQLite DB with schema.""" + db_path = tmp_path / "test.db" + conn = sqlite3.connect(str(db_path)) + init_db(conn) + return conn + + +@pytest.fixture +def remote_sessions_dir(tmp_path): + """Create fake remote session files with tool usage.""" + remote_base = tmp_path / "remote-sessions" + + # Bob's session with tool usage + bob_sessions = remote_base / "bob" / "-Users-bob-myapp" / "sessions" + bob_sessions.mkdir(parents=True) + + # JSONL with actual tool usage for deep indexing + lines = [ + json.dumps({ + "type": "user", + "message": { + "role": "user", + "content": "fix the bug", + }, + "timestamp": "2026-03-05T10:00:00Z", + "uuid": "msg-001", + }), + json.dumps({ + "type": "assistant", + "message": { + "role": "assistant", + "content": [ + {"type": "tool_use", "id": "toolu_1", "name": "Read", "input": {"file_path": "/foo.py"}}, + {"type": "text", "text": "Let me read the file."}, + ], + }, + "timestamp": "2026-03-05T10:00:05Z", + }), + json.dumps({ + "type": "user", + "message": { + "role": "user", + "content": [ + {"type": "tool_result", "tool_use_id": "toolu_1", "content": "file contents here"}, + ], + }, + "timestamp": "2026-03-05T10:00:06Z", + }), + json.dumps({ + "type": "assistant", + "message": { + "role": "assistant", + "content": [ + {"type": "tool_use", "id": "toolu_2", "name": "Edit", "input": {"file_path": "/foo.py"}}, + ], + }, + "timestamp": "2026-03-05T10:00:10Z", + }), + ] + (bob_sessions / "remote-session-001.jsonl").write_text("\n".join(lines) + "\n") + + # Manifest (needed by some code paths) + manifest = { + "user_id": "bob", + "machine_id": "bob-mac", + "project_path": "/Users/bob/myapp", + "project_encoded": "-Users-bob-myapp", + "session_count": 1, + "sessions": [{"uuid": "remote-session-001", "mtime": "2026-03-05T10:00:00Z", "size_bytes": 500}], + } + manifest_dir = remote_base / "bob" / "-Users-bob-myapp" + (manifest_dir / "manifest.json").write_text(json.dumps(manifest)) + + return remote_base + + +class TestDeepRemoteIndexing: + def test_remote_session_has_tools_indexed(self, db_conn, remote_sessions_dir, tmp_path, monkeypatch): + """Remote sessions should have session_tools populated.""" + monkeypatch.setattr("db.indexer.settings.karma_base", tmp_path) + monkeypatch.setattr("db.indexer._get_local_user_id", lambda: "alice") + + index_remote_sessions(db_conn) + + # Check session was indexed + cursor = db_conn.execute( + "SELECT uuid, source, remote_user_id FROM sessions WHERE uuid = ?", + ("remote-session-001",), + ) + row = cursor.fetchone() + assert row is not None + assert row[1] == "remote" + assert row[2] == "bob" + + # Check tools were deep-indexed + cursor = db_conn.execute( + "SELECT tool_name, count FROM session_tools WHERE session_uuid = ?", + ("remote-session-001",), + ) + tools = {name: count for name, count in cursor.fetchall()} + assert "Read" in tools + assert "Edit" in tools + + def test_remote_session_has_message_count(self, db_conn, remote_sessions_dir, tmp_path, monkeypatch): + """Remote sessions should have accurate message_count from deep indexing.""" + monkeypatch.setattr("db.indexer.settings.karma_base", tmp_path) + monkeypatch.setattr("db.indexer._get_local_user_id", lambda: "alice") + + index_remote_sessions(db_conn) + + cursor = db_conn.execute( + "SELECT message_count FROM sessions WHERE uuid = ?", + ("remote-session-001",), + ) + row = cursor.fetchone() + assert row is not None + assert row[0] >= 2 # At least user + assistant messages +``` + +**Step 2: Run tests to verify they fail** + +Run: `cd api && pytest tests/test_remote_indexing.py -v` +Expected: FAIL — session_tools empty for remote sessions (shallow indexing) + +**Step 3: Modify `index_remote_sessions()` to use `_index_session()`** + +In `api/db/indexer.py`, replace the lazy parsing in `index_remote_sessions()` with a call to `_index_session()`. Find the section that does the shallow first/last line parsing and replace it: + +```python +# Replace the shallow parsing block with: +_index_session( + conn=conn, + jsonl_path=jsonl_path, + encoded_name=local_encoded or encoded_name, + mtime=jsonl_path.stat().st_mtime, + size=jsonl_path.stat().st_size, + source="remote", + remote_user_id=user_id, + remote_machine_id=user_id, + source_encoded_name=encoded_name, +) +stats["indexed"] += 1 +``` + +**Step 4: Run tests** + +Run: `cd api && pytest tests/test_remote_indexing.py -v` +Expected: All PASS + +**Step 5: Verify no regressions** + +Run: `cd api && pytest tests/ -v --timeout=30` +Expected: All PASS + +**Step 6: Commit** + +```bash +git add api/db/indexer.py api/tests/test_remote_indexing.py +git commit -m "feat(api): deep-index remote sessions with full metadata + +Remote sessions now go through _index_session() instead of lazy +first/last-line parsing. This populates session_tools, session_skills, +session_commands, and subagent_invocations — matching local sessions." +``` + +--- + +## Task 3: Route `/sessions/{uuid}` to find remote sessions + +The main session endpoint currently only looks in `~/.claude/projects/`. It needs to fall back to `find_remote_session()` when a UUID isn't found locally. + +**Files:** +- Modify: `api/routers/sessions.py` (get_session endpoint) +- Modify: `api/tests/` (add test) + +**Step 1: Identify the current session resolution** + +The endpoint at `GET /sessions/{uuid}` resolves sessions via the SQLite index. Check how `get_session()` finds the JSONL path. It likely queries the `sessions` table for the UUID, gets the `project_encoded_name`, then constructs the path. + +Read `api/routers/sessions.py` to find the `get_session` function and understand the path resolution logic. The key change: when local lookup fails, try `find_remote_session(uuid)`. + +**Step 2: Write failing test** + +```python +# Add to api/tests/test_remote_session_endpoint.py + +def test_session_endpoint_finds_remote_session(client, tmp_path, monkeypatch): + """GET /sessions/{uuid} should find remote sessions.""" + import json + + # Create remote session file + remote_base = tmp_path / "remote-sessions" / "bob" / "-Users-bob-app" / "sessions" + remote_base.mkdir(parents=True) + lines = [ + json.dumps({"type": "user", "message": {"role": "user", "content": "hello"}, "timestamp": "2026-03-05T10:00:00Z"}), + json.dumps({"type": "assistant", "message": {"role": "assistant", "content": [{"type": "text", "text": "hi"}]}, "timestamp": "2026-03-05T10:00:05Z"}), + ] + (remote_base / "remote-uuid-001.jsonl").write_text("\n".join(lines) + "\n") + + monkeypatch.setattr("config.settings.karma_base", tmp_path) + + response = client.get("/sessions/remote-uuid-001") + # Should find it via remote session fallback + assert response.status_code == 200 +``` + +**Step 3: Add remote fallback to session endpoint** + +In the `get_session()` function, after the local session lookup fails (404), add: + +```python +from services.remote_sessions import find_remote_session + +# ... existing local lookup ... +if session is None: + remote_result = find_remote_session(uuid) + if remote_result: + session = remote_result.session +``` + +**Step 4: Run tests** + +Run: `cd api && pytest tests/test_remote_session_endpoint.py -v` +Expected: PASS + +**Step 5: Commit** + +```bash +git add api/routers/sessions.py api/tests/test_remote_session_endpoint.py +git commit -m "feat(api): /sessions/{uuid} falls back to remote sessions + +When a session UUID is not found locally, the endpoint now searches +remote-sessions/ directories. This makes remote sessions accessible +through the same endpoints as local sessions — no frontend changes needed." +``` + +--- + +## Task 4: Serve remote session subagents and tool results + +Remote session subagent and tool-result files live alongside the JSONL in the Syncthing outbox. The session detail endpoints (`/sessions/{uuid}/subagents`, `/sessions/{uuid}/tools`, `/sessions/{uuid}/file-activity`, `/sessions/{uuid}/timeline`) need the correct base directory to find associated files. + +**Files:** +- Modify: `api/routers/sessions.py` (subagent/timeline/file-activity endpoints) +- Test: Extend the remote session test + +**Step 1: Verify the problem** + +When `Session.from_path(jsonl_path)` is called with a remote JSONL, the session's `project_dir` points to the remote outbox directory. Subagent files are at `{outbox}/sessions/{uuid}/subagents/`. Check if `session.list_subagents()` uses `session.project_dir / uuid / "subagents"` — if so, it should already work since the packager copies the directory structure. + +Read the relevant code in `api/models/session.py` to verify. If it works already, this task becomes a verification-only task. + +**Step 2: Write test to verify** + +```python +def test_remote_session_subagents_accessible(tmp_path, monkeypatch): + """Subagent files should be loadable from remote session directories.""" + import json + from models.session import Session + + # Create remote session with subagent + sessions_dir = tmp_path / "sessions" + sessions_dir.mkdir() + (sessions_dir / "remote-s.jsonl").write_text('{"type":"user"}\n') + sub_dir = sessions_dir / "remote-s" / "subagents" + sub_dir.mkdir(parents=True) + (sub_dir / "agent-a1.jsonl").write_text( + json.dumps({"type": "user", "message": {"role": "user", "content": "sub task"}}) + "\n" + ) + + session = Session.from_path(sessions_dir / "remote-s.jsonl") + agents = session.list_subagents() + assert len(agents) >= 1 +``` + +**Step 3: Run test** + +Run: `cd api && pytest tests/test_remote_session_endpoint.py::test_remote_session_subagents_accessible -v` +Expected: PASS (if packager directory structure matches what Session expects) + +If it fails, the fix will be adjusting `Session.list_subagents()` to look in the right directory relative to the JSONL path. + +**Step 4: Commit (if changes needed)** + +```bash +git add api/ +git commit -m "feat(api): remote session subagents and tool results accessible + +Verified that Session.from_path() with remote JSONL paths correctly +resolves subagent and tool-result directories." +``` + +--- + +## Task 5: Add project mapping for remote sessions + +Remote sessions arrive with their original machine's encoded name (e.g., `-Users-bob-myapp`). The indexer needs to map this to the local project so remote sessions appear in the right project view. + +**Files:** +- Check: `api/db/indexer.py` — `get_project_mapping()` function +- Modify if needed: The mapping logic + +**Step 1: Understand current mapping** + +Read `api/db/indexer.py` to find `get_project_mapping()`. It likely uses the sync-config.json to map `(user_id, encoded_name)` to a local project. Check if this already works correctly. + +**Step 2: Write test** + +```python +def test_remote_sessions_appear_in_local_project(db_conn, remote_sessions_dir, tmp_path, monkeypatch): + """Remote sessions should be indexed under the local project name.""" + monkeypatch.setattr("db.indexer.settings.karma_base", tmp_path) + monkeypatch.setattr("db.indexer._get_local_user_id", lambda: "alice") + + # Create project mapping in sync config + sync_config = { + "user_id": "alice", + "machine_id": "alice-mac", + "teams": { + "team1": { + "backend": "syncthing", + "projects": { + "myapp": { + "path": "/Users/alice/myapp", + "encoded_name": "-Users-alice-myapp", + } + }, + "syncthing_members": { + "bob": {"syncthing_device_id": "BOB-DEVICE"} + }, + } + }, + } + import json + (tmp_path / "sync-config.json").write_text(json.dumps(sync_config)) + + index_remote_sessions(db_conn) + + # Session should be indexed under local project name + cursor = db_conn.execute( + "SELECT project_encoded_name, source_encoded_name FROM sessions WHERE uuid = ?", + ("remote-session-001",), + ) + row = cursor.fetchone() + assert row is not None + # project_encoded_name should be the LOCAL project's encoded name + # source_encoded_name should be the REMOTE machine's encoded name + assert row[1] == "-Users-bob-myapp" # original source +``` + +**Step 3: Verify or fix mapping** + +If the test passes, the mapping already works. If not, update `get_project_mapping()` to use sync-config.json team projects to build the mapping. + +**Step 4: Commit** + +```bash +git add api/db/indexer.py api/tests/test_remote_indexing.py +git commit -m "test(api): verify remote session project mapping + +Confirmed that remote sessions are indexed under the correct local +project name via sync-config.json project mapping." +``` + +--- + +## Task 6: Full test suite verification + +**Step 1: Run all CLI tests** + +Run: `cd cli && pytest -v` +Expected: All PASS + +**Step 2: Run all API tests** + +Run: `cd api && pytest tests/ -v --timeout=30` +Expected: All PASS + +**Step 3: Manual smoke test** + +1. Start the API: `cd api && uvicorn main:app --reload --port 8000` +2. Start the frontend: `cd frontend && npm run dev` +3. If you have remote sessions synced, navigate to a remote session and verify: + - Timeline shows events + - File activity shows operations + - Subagents are listed + - Tasks/todos appear + +--- + +## Summary + +| Task | What | Files Changed | Priority | +|------|------|---------------|----------| +| 1 | Sync task directories | `packager.py`, `test_packager.py` | High | +| 2 | Deep-index remote sessions | `indexer.py`, `test_remote_indexing.py` | High | +| 3 | `/sessions/{uuid}` remote fallback | `sessions.py` router | High | +| 4 | Verify subagent/tool-result access | Tests only (likely) | Medium | +| 5 | Project mapping for remote sessions | `indexer.py` (verify/fix) | Medium | +| 6 | Full suite verification | — | Required | + +**Not in scope (future work):** +- Frontend changes for remote session indicators (badges, user labels) +- Conflict resolution for duplicate session UUIDs across users +- Bandwidth optimization (delta sync, compression) +- `history.jsonl` syncing (global file, privacy concerns) +- Live session state syncing (ephemeral, local-only by design) diff --git a/docs/plans/2026-03-05-remote-session-parity-plan.md b/docs/plans/2026-03-05-remote-session-parity-plan.md new file mode 100644 index 00000000..47e51622 --- /dev/null +++ b/docs/plans/2026-03-05-remote-session-parity-plan.md @@ -0,0 +1,1126 @@ +# Remote Session Feature Parity Implementation Plan + +> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. + +**Goal:** Make remote (synced) sessions fully feature-complete with local sessions across CLI packaging and API endpoints — so every piece of data visible for a local session is also available for a remote session. + +**Architecture:** The system has two path anchors per session: `session_dir` (relative to JSONL, handles subagents/tool-results) and `claude_base_dir` (handles todos/tasks/file-history/debug/plans). For local sessions `claude_base_dir` defaults to `~/.claude`. For remote sessions accessed via `find_remote_session()`, it's set to `~/.claude_karma/remote-sessions/{user}/{encoded}/`. The CLI packager must place files at the right relative paths under the staging directory so the API resolves them correctly. + +**Tech Stack:** Python 3.9+, FastAPI, Pydantic 2.x, pytest, shutil, pathlib + +**Current State:** +- JSONL, subagents, tool-results: Packaged + accessible (verified) +- Todos: Packaged, path SHOULD resolve but unverified +- Tasks: Packaged, path SHOULD resolve but unverified +- File-history: NOT packaged +- Debug logs: NOT packaged +- Plans: NOT packaged (and endpoint may hardcode path) + +**Roles:** +- **Role A (Test Engineer):** Writes verification tests proving current state and catching regressions +- **Role B (CLI Engineer):** Extends packager to sync missing resource types +- **Role C (Backend Engineer):** Fixes API path resolution and endpoint gaps + +--- + +## Phase 1: Verify What Already Works (Role A — Test Engineer) + +### Task 1: Test todos resolve for remote sessions + +**Files:** +- Modify: `api/tests/test_remote_sessions.py` + +**Step 1: Write the test** + +Add to `TestRemoteSessionSubagentAccess` class (or create new class `TestRemoteSessionTodos`): + +```python +class TestRemoteSessionTodos: + def test_todos_resolve_for_remote_session(self, karma_base): + """Todos packaged into remote staging dir should be loadable.""" + encoded = "-Users-jayant-acme" + alice_dir = karma_base / "remote-sessions" / "alice" / encoded + + # Create session JSONL + sessions_dir = alice_dir / "sessions" + sessions_dir.mkdir(parents=True, exist_ok=True) + (sessions_dir / "sess-todo-001.jsonl").write_text( + json.dumps({ + "type": "user", + "message": {"role": "user", "content": "hello"}, + "timestamp": "2026-03-03T12:00:00Z", + }) + "\n" + ) + + # Create todo file in staging structure (mirrors packager output) + todos_dir = alice_dir / "todos" + todos_dir.mkdir(parents=True, exist_ok=True) + (todos_dir / "sess-todo-001-task1.json").write_text( + json.dumps([{ + "content": "Fix the bug", + "status": "in_progress", + }]) + ) + + with patch("services.remote_sessions.settings") as mock_settings: + mock_settings.karma_base = karma_base + result = find_remote_session("sess-todo-001") + + assert result is not None + session = result.session + + # Verify todos_dir points to correct location + assert session.todos_dir == todos_dir + assert session.todos_dir.exists() + + # Verify todos are loadable + todos = session.list_todos() + assert len(todos) >= 1 + assert todos[0].content == "Fix the bug" +``` + +**Step 2: Run test to verify** + +Run: `cd api && pytest tests/test_remote_sessions.py::TestRemoteSessionTodos -v` +Expected: PASS (if path resolution works) or FAIL (revealing the gap) + +**Step 3: If test fails, fix path resolution** + +The issue would be in `api/services/remote_sessions.py:196` where `claude_base_dir=encoded_dir`. Verify `encoded_dir` is the parent of `sessions/` (the project-level dir), not the `sessions/` dir itself. + +Check: `encoded_dir` = `~/.claude_karma/remote-sessions/alice/-Users-jayant-acme/` +Then: `session.todos_dir` = `encoded_dir / "todos"` = `.../alice/-Users-jayant-acme/todos/` — should match packager output. + +**Step 4: Commit** + +```bash +git add api/tests/test_remote_sessions.py +git commit -m "test: verify todos resolve for remote sessions" +``` + +--- + +### Task 2: Test tasks resolve for remote sessions + +**Files:** +- Modify: `api/tests/test_remote_sessions.py` + +**Step 1: Write the test** + +```python +class TestRemoteSessionTasks: + def test_tasks_resolve_for_remote_session(self, karma_base): + """Tasks packaged into remote staging dir should be loadable.""" + encoded = "-Users-jayant-acme" + alice_dir = karma_base / "remote-sessions" / "alice" / encoded + + # Create session JSONL + sessions_dir = alice_dir / "sessions" + sessions_dir.mkdir(parents=True, exist_ok=True) + (sessions_dir / "sess-task-001.jsonl").write_text( + json.dumps({ + "type": "user", + "message": {"role": "user", "content": "hello"}, + "timestamp": "2026-03-03T12:00:00Z", + }) + "\n" + ) + + # Create task files in staging structure (mirrors packager output) + task_dir = alice_dir / "tasks" / "sess-task-001" + task_dir.mkdir(parents=True, exist_ok=True) + (task_dir / "1.json").write_text( + json.dumps({ + "id": "1", + "subject": "Implement feature", + "description": "Build the thing", + "status": "in_progress", + }) + ) + + with patch("services.remote_sessions.settings") as mock_settings: + mock_settings.karma_base = karma_base + result = find_remote_session("sess-task-001") + + assert result is not None + session = result.session + + # Verify tasks_dir points to correct location + assert session.tasks_dir == task_dir + assert session.tasks_dir.exists() + + # Verify tasks are loadable + tasks = session.list_tasks() + assert len(tasks) >= 1 +``` + +**Step 2: Run test** + +Run: `cd api && pytest tests/test_remote_sessions.py::TestRemoteSessionTasks -v` + +**Step 3: Commit** + +```bash +git add api/tests/test_remote_sessions.py +git commit -m "test: verify tasks resolve for remote sessions" +``` + +--- + +### Task 3: Test tool-results resolve for remote sessions + +**Files:** +- Modify: `api/tests/test_remote_sessions.py` + +**Step 1: Write the test** + +```python +class TestRemoteSessionToolResults: + def test_tool_results_resolve_for_remote_session(self, karma_base): + """Tool result files packaged alongside JSONL should be accessible.""" + encoded = "-Users-jayant-acme" + alice_sessions = ( + karma_base / "remote-sessions" / "alice" / encoded / "sessions" + ) + alice_sessions.mkdir(parents=True, exist_ok=True) + + # Create session JSONL + (alice_sessions / "sess-tr-001.jsonl").write_text( + json.dumps({ + "type": "user", + "message": {"role": "user", "content": "hello"}, + "timestamp": "2026-03-03T12:00:00Z", + }) + "\n" + ) + + # Create tool-results directory + tr_dir = alice_sessions / "sess-tr-001" / "tool-results" + tr_dir.mkdir(parents=True) + (tr_dir / "toolu_abc123.txt").write_text("Tool output here") + + with patch("services.remote_sessions.settings") as mock_settings: + mock_settings.karma_base = karma_base + result = find_remote_session("sess-tr-001") + + assert result is not None + session = result.session + assert session.tool_results_dir == tr_dir + assert session.tool_results_dir.exists() + + tool_results = session.list_tool_results() + assert len(tool_results) >= 1 +``` + +**Step 2: Run and commit** + +Run: `cd api && pytest tests/test_remote_sessions.py::TestRemoteSessionToolResults -v` + +```bash +git add api/tests/test_remote_sessions.py +git commit -m "test: verify tool-results resolve for remote sessions" +``` + +--- + +## Phase 2: Package Missing Resources (Role B — CLI Engineer) + +### Task 4: Package file-history in CLI packager + +**Files:** +- Modify: `cli/karma/packager.py:134` (after tasks copying block) +- Test: `cli/tests/test_packager.py` + +**Context:** File-history lives at `~/.claude/file-history/{uuid}/` and contains per-file snapshots. The Session model resolves it via `claude_base_dir / "file-history" / {uuid}`. We need to copy it into staging so remote sessions can access it. + +**Step 1: Write the failing test** + +```python +def test_package_copies_file_history(tmp_path): + """File-history directories should be copied to staging.""" + # Setup: create project dir structure + claude_dir = tmp_path / ".claude" + project_dir = claude_dir / "projects" / "-Users-test-repo" + project_dir.mkdir(parents=True) + + uuid = "sess-fh-001" + (project_dir / f"{uuid}.jsonl").write_text( + '{"type":"user","message":{"role":"user","content":"hi"},"timestamp":"2026-01-01T00:00:00Z"}\n' + ) + + # Create file-history for this session + fh_dir = claude_dir / "file-history" / uuid + fh_dir.mkdir(parents=True) + (fh_dir / "snapshot-1.json").write_text('{"file": "main.py", "content": "print(1)"}') + + staging = tmp_path / "staging" + packager = SessionPackager( + project_dir=project_dir, + user_id="test", + machine_id="test-machine", + project_path="/Users/test/repo", + ) + packager.package(staging) + + # Verify file-history was copied + staged_fh = staging / "file-history" / uuid / "snapshot-1.json" + assert staged_fh.exists() + assert staged_fh.read_text() == '{"file": "main.py", "content": "print(1)"}' +``` + +**Step 2: Run test to verify it fails** + +Run: `cd cli && pytest tests/test_packager.py::test_package_copies_file_history -v` +Expected: FAIL — `staged_fh` does not exist + +**Step 3: Implement file-history copying** + +Add after the tasks block in `cli/karma/packager.py` (after line 134): + +```python + # Copy file-history if it exists + file_history_base = self.project_dir.parent.parent / "file-history" + if file_history_base.is_dir(): + fh_staging = staging_dir / "file-history" + for session_entry in sessions: + fh_dir = file_history_base / session_entry.uuid + if fh_dir.is_dir(): + fh_staging.mkdir(exist_ok=True) + shutil.copytree( + fh_dir, + fh_staging / session_entry.uuid, + dirs_exist_ok=True, + ) +``` + +**Step 4: Run test to verify it passes** + +Run: `cd cli && pytest tests/test_packager.py::test_package_copies_file_history -v` +Expected: PASS + +**Step 5: Commit** + +```bash +git add cli/karma/packager.py cli/tests/test_packager.py +git commit -m "feat(cli): package file-history directories for sync" +``` + +--- + +### Task 5: Package debug logs in CLI packager + +**Files:** +- Modify: `cli/karma/packager.py` (after file-history block) +- Test: `cli/tests/test_packager.py` + +**Step 1: Write the failing test** + +```python +def test_package_copies_debug_logs(tmp_path): + """Debug log files should be copied to staging.""" + claude_dir = tmp_path / ".claude" + project_dir = claude_dir / "projects" / "-Users-test-repo" + project_dir.mkdir(parents=True) + + uuid = "sess-debug-001" + (project_dir / f"{uuid}.jsonl").write_text( + '{"type":"user","message":{"role":"user","content":"hi"},"timestamp":"2026-01-01T00:00:00Z"}\n' + ) + + # Create debug log + debug_dir = claude_dir / "debug" + debug_dir.mkdir(parents=True) + (debug_dir / f"{uuid}.txt").write_text("DEBUG: session started\nDEBUG: tool called") + + staging = tmp_path / "staging" + packager = SessionPackager( + project_dir=project_dir, + user_id="test", + machine_id="test-machine", + project_path="/Users/test/repo", + ) + packager.package(staging) + + staged_debug = staging / "debug" / f"{uuid}.txt" + assert staged_debug.exists() + assert "DEBUG: session started" in staged_debug.read_text() +``` + +**Step 2: Run to fail** + +Run: `cd cli && pytest tests/test_packager.py::test_package_copies_debug_logs -v` + +**Step 3: Implement debug log copying** + +Add after file-history block in `cli/karma/packager.py`: + +```python + # Copy debug logs if they exist + debug_base = self.project_dir.parent.parent / "debug" + if debug_base.is_dir(): + debug_staging = staging_dir / "debug" + for session_entry in sessions: + debug_file = debug_base / f"{session_entry.uuid}.txt" + if debug_file.is_file(): + debug_staging.mkdir(exist_ok=True) + shutil.copy2(debug_file, debug_staging / debug_file.name) +``` + +**Step 4: Run to pass, commit** + +```bash +git add cli/karma/packager.py cli/tests/test_packager.py +git commit -m "feat(cli): package debug logs for sync" +``` + +--- + +## Phase 3: API Path Resolution for New Resources (Role C — Backend Engineer) + +### Task 6: Test file-history resolves for remote sessions + +**Files:** +- Modify: `api/tests/test_remote_sessions.py` + +**Step 1: Write the test** + +```python +class TestRemoteSessionFileHistory: + def test_file_history_resolves_for_remote_session(self, karma_base): + """File-history packaged into remote staging should be accessible.""" + encoded = "-Users-jayant-acme" + alice_dir = karma_base / "remote-sessions" / "alice" / encoded + + sessions_dir = alice_dir / "sessions" + sessions_dir.mkdir(parents=True, exist_ok=True) + (sessions_dir / "sess-fh-001.jsonl").write_text( + json.dumps({ + "type": "user", + "message": {"role": "user", "content": "hello"}, + "timestamp": "2026-03-03T12:00:00Z", + }) + "\n" + ) + + # Create file-history in staging structure + fh_dir = alice_dir / "file-history" / "sess-fh-001" + fh_dir.mkdir(parents=True) + (fh_dir / "snapshot.json").write_text('{"file": "main.py"}') + + with patch("services.remote_sessions.settings") as mock_settings: + mock_settings.karma_base = karma_base + result = find_remote_session("sess-fh-001") + + assert result is not None + session = result.session + assert session.file_history_dir == fh_dir + assert session.has_file_history is True +``` + +**Step 2: Run test** + +Run: `cd api && pytest tests/test_remote_sessions.py::TestRemoteSessionFileHistory -v` +Expected: PASS (path resolves via `claude_base_dir / "file-history" / uuid`) + +**Step 3: Commit** + +```bash +git add api/tests/test_remote_sessions.py +git commit -m "test: verify file-history resolves for remote sessions" +``` + +--- + +### Task 7: Test debug log resolves for remote sessions + +**Files:** +- Modify: `api/tests/test_remote_sessions.py` + +**Step 1: Write the test** + +```python +class TestRemoteSessionDebugLog: + def test_debug_log_resolves_for_remote_session(self, karma_base): + """Debug logs packaged into remote staging should be readable.""" + encoded = "-Users-jayant-acme" + alice_dir = karma_base / "remote-sessions" / "alice" / encoded + + sessions_dir = alice_dir / "sessions" + sessions_dir.mkdir(parents=True, exist_ok=True) + (sessions_dir / "sess-dbg-001.jsonl").write_text( + json.dumps({ + "type": "user", + "message": {"role": "user", "content": "hello"}, + "timestamp": "2026-03-03T12:00:00Z", + }) + "\n" + ) + + debug_dir = alice_dir / "debug" + debug_dir.mkdir(parents=True) + (debug_dir / "sess-dbg-001.txt").write_text("DEBUG: started") + + with patch("services.remote_sessions.settings") as mock_settings: + mock_settings.karma_base = karma_base + result = find_remote_session("sess-dbg-001") + + assert result is not None + session = result.session + assert session.has_debug_log is True + assert session.read_debug_log() == "DEBUG: started" +``` + +**Step 2: Run and commit** + +```bash +cd api && pytest tests/test_remote_sessions.py::TestRemoteSessionDebugLog -v +git add api/tests/test_remote_sessions.py +git commit -m "test: verify debug logs resolve for remote sessions" +``` + +--- + +### Task 8: Verify session detail endpoint returns full data for remote sessions + +**Files:** +- Modify: `api/tests/api/test_remote_sessions.py` + +**Context:** The `/sessions/{uuid}` endpoint uses `find_session_with_project()` which falls back to `find_remote_session()` at `api/services/session_lookup.py:82-90`. We need an integration test proving the full detail response includes todos, tasks, and subagent counts for a remote session. + +**Step 1: Write the integration test** + +```python +class TestRemoteSessionDetailEndpoint: + """Integration test: GET /sessions/{uuid} for remote sessions.""" + + def test_detail_endpoint_returns_remote_session_data( + self, client, karma_base + ): + """Full session detail should work for remote sessions via fallback.""" + encoded = "-Users-jayant-acme" + alice_dir = karma_base / "remote-sessions" / "alice" / encoded + + # Create JSONL with a user message and assistant response + sessions_dir = alice_dir / "sessions" + sessions_dir.mkdir(parents=True, exist_ok=True) + jsonl_content = ( + json.dumps({ + "type": "user", + "message": {"role": "user", "content": "Build a CLI tool"}, + "timestamp": "2026-03-03T12:00:00Z", + "sessionId": "remote-test-slug", + }) + "\n" + + json.dumps({ + "type": "assistant", + "message": { + "role": "assistant", + "content": [{"type": "text", "text": "I'll help build that."}], + "model": "claude-sonnet-4-20250514", + "usage": {"input_tokens": 100, "output_tokens": 50}, + }, + "timestamp": "2026-03-03T12:00:05Z", + }) + "\n" + ) + (sessions_dir / "sess-remote-detail.jsonl").write_text(jsonl_content) + + # Create todos + todos_dir = alice_dir / "todos" + todos_dir.mkdir(parents=True, exist_ok=True) + (todos_dir / "sess-remote-detail-task1.json").write_text( + json.dumps([{"content": "Build parser", "status": "in_progress"}]) + ) + + # Create tasks + task_dir = alice_dir / "tasks" / "sess-remote-detail" + task_dir.mkdir(parents=True, exist_ok=True) + (task_dir / "1.json").write_text( + json.dumps({"id": "1", "subject": "Parse args", "status": "pending"}) + ) + + # Create subagent + sub_dir = alice_dir / "sessions" / "sess-remote-detail" / "subagents" + sub_dir.mkdir(parents=True) + (sub_dir / "agent-abc.jsonl").write_text( + json.dumps({ + "type": "user", + "message": {"role": "user", "content": "sub task"}, + "timestamp": "2026-03-03T12:01:00Z", + }) + "\n" + ) + + with patch("services.remote_sessions.settings") as mock_settings, \ + patch("services.session_lookup.settings") as mock_lookup_settings: + mock_settings.karma_base = karma_base + # Make local project search find nothing (force remote fallback) + mock_lookup_settings.projects_dir = karma_base / "nonexistent" + + response = client.get("/sessions/sess-remote-detail") + + assert response.status_code == 200 + data = response.json() + assert data["uuid"] == "sess-remote-detail" + assert data["message_count"] >= 2 + assert data["todo_count"] >= 1 + assert data["task_count"] >= 1 + assert data["subagent_count"] >= 1 +``` + +**Step 2: Run test** + +Run: `cd api && pytest tests/api/test_remote_sessions.py::TestRemoteSessionDetailEndpoint -v` + +This test may reveal issues with how the router accesses todos/tasks for remote sessions. If it fails, the fix is in the session detail endpoint. + +**Step 3: Fix any failures, commit** + +```bash +git add api/tests/api/test_remote_sessions.py +git commit -m "test: integration test for remote session detail endpoint" +``` + +--- + +## Phase 4: Endpoint-Level Fixes (Role C — Backend Engineer) + +### Task 9: Ensure `/sessions/{uuid}/todos` works for remote sessions + +**Files:** +- Modify: `api/routers/sessions.py` (the todos endpoint) +- Test: `api/tests/api/test_remote_sessions.py` + +**Context:** The `/sessions/{uuid}/todos` endpoint calls `find_session(uuid)` which returns a Session. For remote sessions, this goes through `find_remote_session()` which sets `claude_base_dir` correctly. The endpoint should work without code changes — this task verifies it. + +**Step 1: Write the test** + +```python +def test_todos_endpoint_for_remote_session(self, client, karma_base): + """GET /sessions/{uuid}/todos should return remote session todos.""" + encoded = "-Users-jayant-acme" + alice_dir = karma_base / "remote-sessions" / "alice" / encoded + + sessions_dir = alice_dir / "sessions" + sessions_dir.mkdir(parents=True, exist_ok=True) + (sessions_dir / "sess-rtodos.jsonl").write_text( + json.dumps({ + "type": "user", + "message": {"role": "user", "content": "hello"}, + "timestamp": "2026-03-03T12:00:00Z", + }) + "\n" + ) + + todos_dir = alice_dir / "todos" + todos_dir.mkdir(parents=True, exist_ok=True) + (todos_dir / "sess-rtodos-item.json").write_text( + json.dumps([{"content": "Remote todo", "status": "pending"}]) + ) + + with patch("services.remote_sessions.settings") as mock_settings, \ + patch("services.session_lookup.settings") as mock_lookup: + mock_settings.karma_base = karma_base + mock_lookup.projects_dir = karma_base / "nonexistent" + + response = client.get("/sessions/sess-rtodos/todos") + + assert response.status_code == 200 + todos = response.json() + assert len(todos) >= 1 + assert todos[0]["content"] == "Remote todo" +``` + +**Step 2: Run, fix if needed, commit** + +If the endpoint's `find_session()` call doesn't fall through to `find_remote_session()`, update `session_lookup.py:find_session()` to ensure the remote fallback works (it should — line 108 delegates to `find_session_with_project()` which has the fallback at line 82-90). + +```bash +git commit -m "test: verify /sessions/{uuid}/todos for remote sessions" +``` + +--- + +### Task 10: Ensure `/sessions/{uuid}/tasks` works for remote sessions + +**Files:** +- Test: `api/tests/api/test_remote_sessions.py` + +**Step 1: Write and run the test** (same pattern as Task 9 but for tasks endpoint) + +```python +def test_tasks_endpoint_for_remote_session(self, client, karma_base): + """GET /sessions/{uuid}/tasks should return remote session tasks.""" + # ... (same setup as Task 9 but with tasks dir instead of todos) + response = client.get("/sessions/sess-rtasks/tasks") + assert response.status_code == 200 + tasks = response.json() + assert len(tasks) >= 1 +``` + +**Step 2: Commit** + +```bash +git commit -m "test: verify /sessions/{uuid}/tasks for remote sessions" +``` + +--- + +### Task 11: Ensure `/sessions/{uuid}/file-activity` works for remote sessions + +**Files:** +- Test: `api/tests/api/test_remote_sessions.py` + +**Context:** File activity is extracted from JSONL tool-use blocks (Read, Write, etc.) and optionally from tool-result files. The JSONL parsing works regardless of location. Tool-results resolve via `session_dir` (relative to JSONL). This should work. + +**Step 1: Write test with a JSONL containing a tool-use block** + +```python +def test_file_activity_endpoint_for_remote_session(self, client, karma_base): + """GET /sessions/{uuid}/file-activity should work for remote sessions.""" + encoded = "-Users-jayant-acme" + alice_dir = karma_base / "remote-sessions" / "alice" / encoded + sessions_dir = alice_dir / "sessions" + sessions_dir.mkdir(parents=True, exist_ok=True) + + # JSONL with a tool-use block (Read tool) + jsonl_lines = [ + json.dumps({ + "type": "user", + "message": {"role": "user", "content": "read main.py"}, + "timestamp": "2026-03-03T12:00:00Z", + }), + json.dumps({ + "type": "assistant", + "message": { + "role": "assistant", + "content": [{ + "type": "tool_use", + "id": "toolu_001", + "name": "Read", + "input": {"file_path": "/Users/jayant/acme/main.py"}, + }], + "model": "claude-sonnet-4-20250514", + }, + "timestamp": "2026-03-03T12:00:02Z", + }), + ] + (sessions_dir / "sess-rfa.jsonl").write_text("\n".join(jsonl_lines) + "\n") + + with patch("services.remote_sessions.settings") as mock_settings, \ + patch("services.session_lookup.settings") as mock_lookup: + mock_settings.karma_base = karma_base + mock_lookup.projects_dir = karma_base / "nonexistent" + + response = client.get("/sessions/sess-rfa/file-activity") + + assert response.status_code == 200 + activities = response.json() + assert len(activities) >= 1 +``` + +**Step 2: Commit** + +```bash +git commit -m "test: verify /sessions/{uuid}/file-activity for remote sessions" +``` + +--- + +### Task 12: Ensure `/sessions/{uuid}/subagents` works for remote sessions + +**Files:** +- Test: `api/tests/api/test_remote_sessions.py` + +**Context:** Subagent files sit in `session_dir / "subagents"` which is relative to the JSONL path. Already verified in unit test `TestRemoteSessionSubagentAccess`. This task adds an endpoint-level integration test. + +**Step 1: Write test, run, commit** + +```python +def test_subagents_endpoint_for_remote_session(self, client, karma_base): + """GET /sessions/{uuid}/subagents should work for remote sessions.""" + # Create JSONL + subagent file (same structure as TestRemoteSessionSubagentAccess) + # ... setup ... + response = client.get("/sessions/sess-rsub/subagents") + assert response.status_code == 200 +``` + +```bash +git commit -m "test: verify /sessions/{uuid}/subagents for remote sessions" +``` + +--- + +### Task 13: Ensure `/sessions/{uuid}/timeline` works for remote sessions + +**Files:** +- Test: `api/tests/api/test_remote_sessions.py` + +**Context:** Timeline builds events from JSONL messages + tool results. Both should resolve correctly for remote sessions. + +**Step 1: Write test, run, commit** + +```bash +git commit -m "test: verify /sessions/{uuid}/timeline for remote sessions" +``` + +--- + +## Phase 5: Edge Cases and Robustness (Role A + C) + +### Task 14: Handle missing resource dirs gracefully for remote sessions + +**Files:** +- Modify: `api/models/session.py` (if needed) +- Test: `api/tests/test_remote_sessions.py` + +**Context:** A remote session may have JSONL but NOT todos/tasks/file-history (packager didn't find any). The API must return empty lists, not crash. + +**Step 1: Write the test** + +```python +class TestRemoteSessionMissingResources: + def test_missing_todos_returns_empty(self, karma_base): + """Remote session without todos dir should return empty list.""" + encoded = "-Users-jayant-acme" + alice_dir = karma_base / "remote-sessions" / "alice" / encoded + sessions_dir = alice_dir / "sessions" + sessions_dir.mkdir(parents=True, exist_ok=True) + (sessions_dir / "sess-empty-001.jsonl").write_text( + json.dumps({ + "type": "user", + "message": {"role": "user", "content": "hello"}, + "timestamp": "2026-03-03T12:00:00Z", + }) + "\n" + ) + # NO todos, tasks, file-history, debug dirs created + + with patch("services.remote_sessions.settings") as mock_settings: + mock_settings.karma_base = karma_base + result = find_remote_session("sess-empty-001") + + session = result.session + assert session.list_todos() == [] + assert session.list_tasks() == [] + assert session.has_file_history is False + assert session.has_debug_log is False +``` + +**Step 2: Run test — should pass since Session already handles missing dirs** + +Run: `cd api && pytest tests/test_remote_sessions.py::TestRemoteSessionMissingResources -v` + +**Step 3: Commit** + +```bash +git commit -m "test: verify graceful handling of missing resources in remote sessions" +``` + +--- + +### Task 15: Verify incremental packaging skips unchanged file-history and debug + +**Files:** +- Test: `cli/tests/test_packager.py` + +**Context:** The packager uses mtime comparison for JSONL files (`packager.py:101`). The new file-history and debug copying should also not re-copy unchanged data (copytree with `dirs_exist_ok=True` handles this implicitly). + +**Step 1: Write test verifying idempotent packaging** + +```python +def test_incremental_package_skips_unchanged_file_history(tmp_path): + """Re-packaging should not fail or duplicate file-history.""" + # Setup + first package + # ... (same as Task 4 setup) + packager.package(staging) + first_mtime = (staging / "file-history" / uuid / "snapshot-1.json").stat().st_mtime + + # Package again without changes + packager.package(staging) + second_mtime = (staging / "file-history" / uuid / "snapshot-1.json").stat().st_mtime + + # copytree with dirs_exist_ok replaces files, so mtime may change + # Just verify it didn't crash and file still exists + assert (staging / "file-history" / uuid / "snapshot-1.json").exists() +``` + +**Step 2: Run and commit** + +```bash +git commit -m "test: verify incremental packaging for file-history and debug logs" +``` + +--- + +## Phase 6: Indexer Alignment (Role C — Backend Engineer) + +### Task 16: Pass `claude_base_dir` to `_index_session()` for remote sessions + +**Files:** +- Modify: `api/db/indexer.py:351-359` (the `_index_session()` call in `index_remote_sessions()`) +- Modify: `api/db/indexer.py:370-397` (the `_index_session()` signature and `Session.from_path()` call) +- Test: `api/tests/test_remote_sessions.py` + +**Context:** Currently `_index_session()` at line 404 calls `Session.from_path(jsonl_path)` without `claude_base_dir`. For remote sessions this means `claude_base_dir` defaults to `~/.claude`, so todo/task/file-history existence checks during indexing point to the wrong place. While the indexer doesn't currently use these resources, future schema additions (e.g., `todo_count`, `has_file_history` columns) would be incorrect. + +**Step 1: Add `claude_base_dir` parameter to `_index_session()`** + +In `api/db/indexer.py`, modify `_index_session()` signature (line 370): + +```python +def _index_session( + conn: sqlite3.Connection, + jsonl_path: Path, + encoded_name: str, + mtime: float, + size: int, + project_path_override: Optional[str] = None, + session_source: Optional[str] = None, + source_encoded_name: Optional[str] = None, + source: Optional[str] = None, + remote_user_id: Optional[str] = None, + remote_machine_id: Optional[str] = None, + claude_base_dir: Optional[Path] = None, # NEW +) -> None: +``` + +And update the `Session.from_path()` call (line 404): + +```python + session = Session.from_path(jsonl_path, claude_base_dir=claude_base_dir) +``` + +**Step 2: Pass `claude_base_dir` from `index_remote_sessions()`** + +In `api/db/indexer.py`, update the call at line 351: + +```python + _index_session( + conn, + jsonl_path, + local_encoded, + current_mtime, + current_size, + source="remote", + remote_user_id=user_id, + remote_machine_id=user_id, + claude_base_dir=encoded_dir, # NEW + ) +``` + +Where `encoded_dir` is the project-level directory (parent of `sessions/`). + +**Step 3: Run all tests** + +Run: `cd api && pytest tests/ -v` +Expected: All pass (existing behavior unchanged for local sessions since `claude_base_dir=None` preserves default) + +**Step 4: Commit** + +```bash +git add api/db/indexer.py +git commit -m "fix: pass claude_base_dir to indexer for remote sessions" +``` + +--- + +## Phase 7: End-to-End Verification (All Roles) + +### Task 17: Full round-trip test: package → land → index → serve + +**Files:** +- Create: `api/tests/test_remote_roundtrip.py` + +**Context:** This is the capstone test. It simulates the full pipeline: CLI packages a local session with all resources → files land in remote-sessions dir → indexer picks them up → API serves complete data. + +**Step 1: Write the end-to-end test** + +```python +""" +End-to-end test: package local session → simulate sync landing → +index into SQLite → serve via API endpoints. +""" +import json +import shutil +import sqlite3 +from pathlib import Path +from unittest.mock import patch + +import pytest + +from db.indexer import index_remote_sessions +from db.schema import ensure_schema +from services.remote_sessions import find_remote_session + + +@pytest.fixture +def full_roundtrip_env(tmp_path): + """Create a complete roundtrip environment.""" + karma_base = tmp_path / ".claude_karma" + karma_base.mkdir() + + # Simulate remote session landing (as if packager + sync already ran) + user_id = "alice" + encoded = "-Users-alice-acme" + uuid = "roundtrip-001" + + alice_dir = karma_base / "remote-sessions" / user_id / encoded + sessions_dir = alice_dir / "sessions" + sessions_dir.mkdir(parents=True) + + # JSONL with user + assistant messages + jsonl = ( + json.dumps({ + "type": "user", + "message": {"role": "user", "content": "Build feature X"}, + "timestamp": "2026-03-03T12:00:00Z", + "sessionId": "roundtrip-slug", + }) + "\n" + + json.dumps({ + "type": "assistant", + "message": { + "role": "assistant", + "content": [{"type": "text", "text": "On it."}], + "model": "claude-sonnet-4-20250514", + "usage": {"input_tokens": 100, "output_tokens": 50}, + }, + "timestamp": "2026-03-03T12:00:05Z", + }) + "\n" + ) + (sessions_dir / f"{uuid}.jsonl").write_text(jsonl) + + # Subagent + sub_dir = sessions_dir / uuid / "subagents" + sub_dir.mkdir(parents=True) + (sub_dir / "agent-aaa.jsonl").write_text( + json.dumps({ + "type": "user", + "message": {"role": "user", "content": "sub task"}, + "timestamp": "2026-03-03T12:01:00Z", + }) + "\n" + ) + + # Tool result + tr_dir = sessions_dir / uuid / "tool-results" + tr_dir.mkdir(parents=True) + (tr_dir / "toolu_xyz.txt").write_text("file content here") + + # Todos + todos_dir = alice_dir / "todos" + todos_dir.mkdir() + (todos_dir / f"{uuid}-item.json").write_text( + json.dumps([{"content": "Fix bug", "status": "pending"}]) + ) + + # Tasks + task_dir = alice_dir / "tasks" / uuid + task_dir.mkdir(parents=True) + (task_dir / "1.json").write_text( + json.dumps({"id": "1", "subject": "Parse CLI args", "status": "in_progress"}) + ) + + # File-history + fh_dir = alice_dir / "file-history" / uuid + fh_dir.mkdir(parents=True) + (fh_dir / "snapshot.json").write_text('{"file": "main.py"}') + + # Debug log + debug_dir = alice_dir / "debug" + debug_dir.mkdir() + (debug_dir / f"{uuid}.txt").write_text("DEBUG: started") + + # Sync config (identifies local user to skip) + (karma_base / "sync-config.json").write_text( + json.dumps({"user_id": "local-me", "machine_id": "my-mac"}) + ) + + return { + "karma_base": karma_base, + "user_id": user_id, + "encoded": encoded, + "uuid": uuid, + } + + +def test_full_roundtrip(full_roundtrip_env): + """Remote session should be fully accessible after sync landing.""" + env = full_roundtrip_env + + with patch("services.remote_sessions.settings") as mock_settings: + mock_settings.karma_base = env["karma_base"] + + # Step 1: find_remote_session resolves everything + result = find_remote_session(env["uuid"]) + assert result is not None + + session = result.session + assert session.message_count >= 2 + assert result.user_id == "alice" + + # Step 2: All resource types accessible + assert len(session.list_todos()) >= 1 + assert len(session.list_tasks()) >= 1 + assert len(session.list_subagents()) >= 1 + assert len(session.list_tool_results()) >= 1 + assert session.has_file_history is True + assert session.has_debug_log is True + assert "DEBUG: started" in session.read_debug_log() + + # Step 3: Indexer picks it up + conn = sqlite3.connect(":memory:") + conn.row_factory = sqlite3.Row + ensure_schema(conn) + + with patch("db.indexer.settings") as mock_idx_settings, \ + patch("services.remote_sessions.settings") as mock_rs_settings, \ + patch("services.remote_sessions.get_project_mapping", return_value={}): + mock_idx_settings.karma_base = env["karma_base"] + mock_rs_settings.karma_base = env["karma_base"] + + stats = index_remote_sessions(conn) + + assert stats["indexed"] >= 1 + assert stats["errors"] == 0 + + # Verify indexed data + row = conn.execute( + "SELECT * FROM sessions WHERE uuid = ?", (env["uuid"],) + ).fetchone() + assert row is not None + assert row["source"] == "remote" + assert row["remote_user_id"] == "alice" + assert row["message_count"] >= 2 + + conn.close() +``` + +**Step 2: Run the test** + +Run: `cd api && pytest tests/test_remote_roundtrip.py -v` + +**Step 3: Fix any failures discovered** + +**Step 4: Commit** + +```bash +git add api/tests/test_remote_roundtrip.py +git commit -m "test: end-to-end roundtrip test for remote session parity" +``` + +--- + +## Summary: Task Assignment by Role + +| Phase | Task | Role | Description | +|-------|------|------|-------------| +| 1 | 1 | Test Engineer | Verify todos resolve for remote sessions | +| 1 | 2 | Test Engineer | Verify tasks resolve for remote sessions | +| 1 | 3 | Test Engineer | Verify tool-results resolve for remote sessions | +| 2 | 4 | CLI Engineer | Package file-history in packager | +| 2 | 5 | CLI Engineer | Package debug logs in packager | +| 3 | 6 | Backend Engineer | Test file-history resolution | +| 3 | 7 | Backend Engineer | Test debug log resolution | +| 3 | 8 | Backend Engineer | Integration test: session detail endpoint | +| 4 | 9 | Backend Engineer | Verify /todos endpoint for remote | +| 4 | 10 | Backend Engineer | Verify /tasks endpoint for remote | +| 4 | 11 | Backend Engineer | Verify /file-activity endpoint for remote | +| 4 | 12 | Backend Engineer | Verify /subagents endpoint for remote | +| 4 | 13 | Backend Engineer | Verify /timeline endpoint for remote | +| 5 | 14 | Test + Backend | Handle missing resource dirs gracefully | +| 5 | 15 | Test Engineer | Verify incremental packaging | +| 6 | 16 | Backend Engineer | Pass `claude_base_dir` to indexer for remote | +| 7 | 17 | All | Full round-trip end-to-end test | + +**Parallelization:** Phase 1 (Tasks 1-3) and Phase 2 (Tasks 4-5) can run in parallel since they touch different codebases (api/tests vs cli). Phase 3-4 depend on Phase 2 for file-history/debug tests. Phase 5-6 can run in parallel. Phase 7 is the final gate. diff --git a/docs/plans/2026-03-05-sync-page-implementation-plan.md b/docs/plans/2026-03-05-sync-page-implementation-plan.md new file mode 100644 index 00000000..811483b2 --- /dev/null +++ b/docs/plans/2026-03-05-sync-page-implementation-plan.md @@ -0,0 +1,2799 @@ +# Sync Page Implementation Plan + +> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. + +**Goal:** Build a `/sync` page in the dashboard that replaces Syncthing's localhost UI — users can install, initialize, pair devices, toggle project sync, and monitor transfers without ever leaving the Karma dashboard. + +**Architecture:** Backend extends the existing `/sync` router (`api/routers/sync_status.py`) with new endpoints that proxy Syncthing's REST API via the existing `SyncthingClient` class (`cli/karma/syncthing.py`). Frontend adds a tabbed `/sync` route with four tabs (Setup, Devices, Projects, Activity) using the existing `bits-ui` Tabs components and Chart.js for bandwidth visualization. + +**Tech Stack:** Python 3.9+ / FastAPI / Pydantic 2.x (backend), SvelteKit 2 / Svelte 5 / Tailwind CSS 4 / Chart.js / bits-ui (frontend) + +**Design doc:** `docs/plans/2026-03-05-sync-page-ui-design.md` + +--- + +## Architecture Review Amendments + +> **Date:** 2026-03-05 | **Status:** Verified against codebase +> +> The following corrections were identified by cross-referencing the plan against the actual codebase. Apply these changes when implementing each task. + +### Amendment A: SyncthingClient API Corrections (Tasks 1, 2) + +The plan references methods and attributes that don't exist on `SyncthingClient` (`cli/karma/syncthing.py`): + +| Plan references (wrong) | Actual API | +|---|---| +| `client.get_system_status()` | Does NOT exist. Use raw HTTP: `requests.get(f"{client.api_url}/rest/system/status", headers=client.headers)` | +| `client._headers` | `client.headers` (no underscore prefix) | +| `client._session` | Does NOT exist. Client uses `requests.get()`/`requests.put()` directly (no session object) | +| `client.get_connections()` returns per-device dict with `connected` key | Returns raw Syncthing format — `connected` is a field but nested under `connections` key from the API | + +**Fix for `detect()` in SyncthingProxy:** Either add `get_system_status()` to SyncthingClient: +```python +# Add to cli/karma/syncthing.py SyncthingClient class: +def get_system_status(self) -> dict: + resp = requests.get(f"{self.api_url}/rest/system/status", headers=self.headers, timeout=5) + resp.raise_for_status() + return resp.json() +``` +Or use raw requests in the proxy (matching how `get_events()` should work): +```python +resp = requests.get(f"{self._client.api_url}/rest/system/status", headers=self._client.headers, timeout=5) +``` + +### Amendment B: Async Wrapping Required (Tasks 1, 2, 9, 10) + +`SyncthingClient` uses synchronous `requests` library. All FastAPI endpoints calling it MUST use `asyncio.run_in_executor` to avoid blocking the event loop: + +```python +import asyncio +from functools import partial + +async def _run_sync(func, *args, **kwargs): + loop = asyncio.get_running_loop() + return await loop.run_in_executor(None, partial(func, *args, **kwargs)) + +# Example usage in router: +@router.get("/detect") +async def sync_detect(): + proxy = get_proxy() + return await _run_sync(proxy.detect) +``` + +Apply to ALL endpoints: `/detect`, `/devices`, `/devices POST`, `/devices DELETE`, `/projects`, `/activity`, `/init`. + +### Amendment C: CLI Command Corrections (Tasks 9, 10) + +The `karma` CLI uses `click` (not argparse). Actual command signatures differ from the plan: + +| Plan assumes | Actual CLI command | +|---|---| +| `karma init --backend syncthing --machine-name ` | `karma init --user-id --backend syncthing` (no `--machine-name`; machine ID auto-generated from hostname) | +| `karma sync ` | **IPFS-only.** For Syncthing, use `SessionPackager` directly to re-package the outbox. | +| `karma project add ` | `karma project add --path --team ` (requires `--path` and `--team`) | +| `karma project remove ` | `karma project remove --team ` | +| `karma watch` | `karma watch --team ` (requires `--team`) | + +**Fix for `POST /sync/init`:** Update `InitRequest` model: +```python +class InitRequest(BaseModel): + user_id: str # NOT machine_name + backend: str = "syncthing" +``` +And the subprocess call: +```python +run_karma_command(["init", "--user-id", req.user_id, "--backend", req.backend]) +``` + +**Fix for "Sync Now":** Instead of calling `karma sync`, invoke the packager: +```python +@router.post("/projects/{name}/sync-now") +async def sync_project_now(name: str): + name = validate_project_name(name) + # Import and run packager directly instead of karma sync (which is IPFS-only) + result = run_karma_command(["watch", "--team", _get_default_team_name()]) + # Or better: package directly via Python import + return {"success": True} +``` + +### Amendment D: Backend Must Join Folder↔Project Data (Task 7) + +The frontend should NOT guess Syncthing folder naming conventions. The plan's `ProjectsTab.svelte` does: +```typescript +synced: syncedFolders.has(`karma-out-${p.encoded_name}`) // WRONG +``` + +**Fix:** The `GET /sync/projects` endpoint must return already-joined data by reading `sync-config.json` teams→projects and matching against `SyncthingClient.get_folders()` via `find_folder_by_path()`. See the existing `services/remote_sessions.py` for the config reading pattern. + +### Amendment E: Design Token Usage (Tasks 5, 6, 7, 8) + +Replace ALL hardcoded Tailwind colors with CSS custom properties. Complete mapping: + +| Wrong (in plan) | Correct | +|---|---| +| `bg-green-500` | `bg-[var(--success)]` | +| `bg-orange-500` | `bg-[var(--warning)]` | +| `bg-gray-400` | `bg-[var(--text-muted)]` | +| `bg-red-500` | `bg-[var(--error)]` | +| `bg-blue-500` | `bg-[var(--info)]` | +| `text-red-500` | `text-[var(--error)]` | +| `text-purple-500` | `text-[var(--accent)]` | +| `text-blue-500` | `text-[var(--info)]` | +| `bg-orange-500/5`, `bg-green-500/5` | `var(--status-stale-bg)`, `var(--status-active-bg)` | +| `border-orange-500/30`, `border-green-500/30` | `border-[var(--warning)]/30`, `border-[var(--success)]/30` | +| `'#7c3aed'` (chart hex) | `getThemeColors().accent` from `chartConfig.ts` | +| `'#3b82f6'` (chart hex) | Resolve `--info` via `getComputedStyle` | +| `bg-red-50 dark:bg-red-900/20` (error) | `bg-[var(--error-subtle)]` | + +### Amendment F: Test Pattern Corrections (Tasks 1, 2, 9, 10) + +Tests use module-level `TestClient(app)` with `monkeypatch`, NOT `with patch()` context managers: + +```python +# WRONG (plan's pattern): +with patch("routers.sync_status.get_proxy") as mock_get: + ... + +# CORRECT (codebase pattern): +from fastapi.testclient import TestClient +from main import app +client = TestClient(app) + +class TestSyncDetect: + def test_detect_no_syncthing(self, monkeypatch): + mock_proxy = MagicMock() + mock_proxy.detect.return_value = {...} + monkeypatch.setattr("routers.sync_status.get_proxy", lambda: mock_proxy) + resp = client.get("/sync/detect") + assert resp.status_code == 200 +``` + +### Amendment G: Input Validation (Tasks 2, 9, 10) + +Add regex validation following `api/routers/commands.py` pattern: + +```python +import re +from fastapi import HTTPException + +ALLOWED_PROJECT_NAME = re.compile(r"^[a-zA-Z0-9_\-]+$") +ALLOWED_DEVICE_ID = re.compile(r"^[A-Z0-9\-]+$") + +def validate_project_name(name: str) -> str: + if not ALLOWED_PROJECT_NAME.match(name) or len(name) > 128: + raise HTTPException(400, "Invalid project name") + return name + +def validate_device_id(device_id: str) -> str: + if not ALLOWED_DEVICE_ID.match(device_id) or len(device_id) > 72: + raise HTTPException(400, "Invalid device ID") + return device_id +``` + +Apply to: `DELETE /sync/devices/{device_id}`, `POST /sync/projects/{name}/enable`, `/disable`, `/sync-now`. + +### Amendment H: Frontend Pattern Corrections (Tasks 3, 4, 5, 6, 7, 8) + +1. **Tabs API:** `TabsTrigger` has an `icon` prop — use `Setup` instead of wrapping icons in `` children. + +2. **Nav insertion point:** "Sync" goes after Archived (line 161) before Team (line 169) in `Header.svelte`. Same for mobile nav after line 321. + +3. **Skeleton route:** Use `if (path.startsWith('/sync')) return 'settings';` (with `startsWith`, not `===`). + +4. **Centralize polling:** Single 10s interval at page level in `+page.svelte`, pass data to tabs via props. Remove independent `setInterval` calls from `DevicesTab` and `ActivityTab`. + +5. **Error recovery:** Follow settings page pattern — inline `bg-[var(--error-subtle)]` banner with retry button. Add troubleshooting context to error messages. + +6. **Network config:** Mark radio buttons as disabled with "(coming soon)" label. + +7. **Tab badges:** Add count badges to Devices and Projects triggers, activity dot to Activity trigger. + +8. **Accessibility:** Add `aria-label` to all toggle dots, remove buttons, and copy buttons. + +9. **Event data formatting:** Replace `JSON.stringify(event.data).slice(0, 100)` with structured formatters per event type. + +--- + +## Task 1: Backend — Syncthing proxy service + +Create a service layer that wraps `SyncthingClient` for use by the API. The CLI's `SyncthingClient` talks directly to Syncthing's REST API — this service adds error handling, response shaping, and caching suitable for the FastAPI layer. + +**Files:** +- Create: `api/services/syncthing_proxy.py` +- Test: `api/tests/test_syncthing_proxy.py` + +**Step 1: Write the failing test** + +Create `api/tests/test_syncthing_proxy.py`: + +```python +"""Tests for Syncthing proxy service.""" + +import pytest +from unittest.mock import MagicMock, patch + +from services.syncthing_proxy import SyncthingProxy, SyncthingNotRunning + + +class TestSyncthingProxy: + def test_detect_not_installed(self): + """detect() returns not installed when Syncthing unreachable.""" + proxy = SyncthingProxy() + with patch.object(proxy, "_client", None): + result = proxy.detect() + assert result["installed"] is False + assert result["running"] is False + + def test_detect_running(self): + """detect() returns version when Syncthing is running.""" + mock_client = MagicMock() + mock_client.is_running.return_value = True + mock_client.get_system_status.return_value = { + "myID": "DEVICE-ID-123", + "version": "v1.27.0", + "uptime": 3600, + } + + proxy = SyncthingProxy() + proxy._client = mock_client + + result = proxy.detect() + assert result["installed"] is True + assert result["running"] is True + assert result["version"] == "v1.27.0" + assert result["device_id"] == "DEVICE-ID-123" + + def test_get_devices_not_running(self): + """get_devices() raises when Syncthing not running.""" + proxy = SyncthingProxy() + proxy._client = None + + with pytest.raises(SyncthingNotRunning): + proxy.get_devices() + + def test_get_devices_returns_formatted(self): + """get_devices() formats connection + stats data.""" + mock_client = MagicMock() + mock_client.is_running.return_value = True + mock_client.get_connections.return_value = { + "REMOTE-ID": { + "connected": True, + "address": "tcp://192.168.1.42:22000", + "type": "TCP (LAN)", + "crypto": "TLS1.3", + "inBytesTotal": 1000000, + "outBytesTotal": 2000000, + } + } + mock_client._get_config.return_value = { + "devices": [ + {"deviceID": "REMOTE-ID", "name": "my-mac-mini"}, + ], + "folders": [], + } + + proxy = SyncthingProxy() + proxy._client = mock_client + + devices = proxy.get_devices() + assert len(devices) == 1 + assert devices[0]["device_id"] == "REMOTE-ID" + assert devices[0]["name"] == "my-mac-mini" + assert devices[0]["connected"] is True + assert devices[0]["address"] == "tcp://192.168.1.42:22000" + + def test_get_projects_sync_state(self): + """get_projects() returns per-project sync status.""" + mock_client = MagicMock() + mock_client.is_running.return_value = True + mock_client.get_folders.return_value = [ + { + "id": "karma-out-alice", + "path": "/home/alice/.claude_karma/remote-sessions/alice", + "devices": [{"deviceID": "REMOTE-ID"}], + "type": "sendonly", + } + ] + + proxy = SyncthingProxy() + proxy._client = mock_client + + projects = proxy.get_folder_status() + assert len(projects) == 1 + assert projects[0]["folder_id"] == "karma-out-alice" +``` + +**Step 2: Run tests to verify they fail** + +Run: `cd api && python -m pytest tests/test_syncthing_proxy.py -v` +Expected: FAIL — `services.syncthing_proxy` does not exist + +**Step 3: Implement the proxy service** + +Create `api/services/syncthing_proxy.py`: + +```python +"""Syncthing proxy service for the Karma API.""" + +from __future__ import annotations + +import logging +import sys +from pathlib import Path +from typing import Any, Optional + +# Add CLI to path so we can import SyncthingClient +CLI_PATH = Path(__file__).parent.parent.parent / "cli" +if str(CLI_PATH) not in sys.path: + sys.path.insert(0, str(CLI_PATH)) + +try: + from karma.syncthing import SyncthingClient, read_local_api_key +except ImportError: + SyncthingClient = None # type: ignore[misc,assignment] + read_local_api_key = None # type: ignore[assignment] + +logger = logging.getLogger(__name__) + + +class SyncthingNotRunning(Exception): + """Raised when Syncthing daemon is not reachable.""" + + +class SyncthingProxy: + """Wraps SyncthingClient for API use with error handling.""" + + def __init__(self) -> None: + self._client: Optional[Any] = None + self._try_connect() + + def _try_connect(self) -> None: + """Attempt to create a SyncthingClient connection.""" + if SyncthingClient is None: + return + try: + api_key = read_local_api_key() if read_local_api_key else None + client = SyncthingClient( + api_url="http://127.0.0.1:8384", + api_key=api_key, + ) + if client.is_running(): + self._client = client + except Exception: + logger.debug("Syncthing not available", exc_info=True) + + def _require_client(self) -> Any: + """Return client or raise if not available.""" + if self._client is None: + self._try_connect() + if self._client is None: + raise SyncthingNotRunning("Syncthing daemon is not running") + return self._client + + def detect(self) -> dict[str, Any]: + """Check if Syncthing is installed and running.""" + if self._client is None: + self._try_connect() + + if self._client is None: + return { + "installed": SyncthingClient is not None, + "running": False, + "version": None, + "device_id": None, + } + + try: + status = self._client.get_system_status() + return { + "installed": True, + "running": True, + "version": status.get("version"), + "device_id": status.get("myID"), + "uptime": status.get("uptime"), + } + except Exception: + return { + "installed": True, + "running": False, + "version": None, + "device_id": None, + } + + def get_devices(self) -> list[dict[str, Any]]: + """Get all paired devices with connection status.""" + client = self._require_client() + connections = client.get_connections() + config = client._get_config() + config_devices = {d["deviceID"]: d for d in config.get("devices", [])} + + devices = [] + for device_id, dev_config in config_devices.items(): + conn = connections.get(device_id, {}) + devices.append({ + "device_id": device_id, + "name": dev_config.get("name", ""), + "connected": conn.get("connected", False), + "address": conn.get("address", ""), + "type": conn.get("type", ""), + "crypto": conn.get("crypto", ""), + "in_bytes_total": conn.get("inBytesTotal", 0), + "out_bytes_total": conn.get("outBytesTotal", 0), + }) + + return devices + + def add_device(self, device_id: str, name: str) -> dict[str, Any]: + """Pair with a new device.""" + client = self._require_client() + client.add_device(device_id, name) + return {"device_id": device_id, "name": name, "paired": True} + + def remove_device(self, device_id: str) -> dict[str, Any]: + """Remove a paired device.""" + client = self._require_client() + client.remove_device(device_id) + return {"device_id": device_id, "removed": True} + + def get_folder_status(self) -> list[dict[str, Any]]: + """Get all Syncthing folders with sync state.""" + client = self._require_client() + folders = client.get_folders() + return [ + { + "folder_id": f["id"], + "path": f.get("path", ""), + "type": f.get("type", ""), + "devices": [d["deviceID"] for d in f.get("devices", [])], + } + for f in folders + ] + + def get_events(self, since: int = 0, limit: int = 50) -> list[dict[str, Any]]: + """Get recent Syncthing events.""" + client = self._require_client() + try: + resp = client._session.get( + f"{client.api_url}/rest/events", + headers=client._headers, + params={"since": since, "limit": limit}, + timeout=5, + ) + resp.raise_for_status() + return resp.json() + except Exception: + return [] +``` + +**Step 4: Run tests to verify they pass** + +Run: `cd api && python -m pytest tests/test_syncthing_proxy.py -v` +Expected: All PASS + +**Step 5: Commit** + +```bash +git add api/services/syncthing_proxy.py api/tests/test_syncthing_proxy.py +git commit -m "feat(api): add Syncthing proxy service layer + +Wraps CLI's SyncthingClient for API use with error handling, +response shaping, and graceful fallback when Syncthing isn't running." +``` + +--- + +## Task 2: Backend — Expand /sync router with new endpoints + +Extend `api/routers/sync_status.py` with the endpoints needed by the frontend tabs. + +**Files:** +- Modify: `api/routers/sync_status.py` +- Test: `api/tests/api/test_sync_status.py` (extend existing) + +**Step 1: Write failing tests** + +Add to `api/tests/api/test_sync_status.py`: + +```python +from unittest.mock import MagicMock, patch + + +class TestSyncDetect: + def test_detect_no_syncthing(self): + """GET /sync/detect returns not running when Syncthing unavailable.""" + with patch("routers.sync_status.get_proxy") as mock_get: + mock_proxy = MagicMock() + mock_proxy.detect.return_value = { + "installed": False, + "running": False, + "version": None, + "device_id": None, + } + mock_get.return_value = mock_proxy + + resp = client.get("/sync/detect") + assert resp.status_code == 200 + data = resp.json() + assert data["installed"] is False + assert data["running"] is False + + def test_detect_syncthing_running(self): + """GET /sync/detect returns version when Syncthing running.""" + with patch("routers.sync_status.get_proxy") as mock_get: + mock_proxy = MagicMock() + mock_proxy.detect.return_value = { + "installed": True, + "running": True, + "version": "v1.27.0", + "device_id": "DEVICE-123", + } + mock_get.return_value = mock_proxy + + resp = client.get("/sync/detect") + assert resp.status_code == 200 + data = resp.json() + assert data["running"] is True + assert data["version"] == "v1.27.0" + + +class TestSyncDevices: + def test_list_devices(self): + """GET /sync/devices returns paired devices.""" + with patch("routers.sync_status.get_proxy") as mock_get: + mock_proxy = MagicMock() + mock_proxy.get_devices.return_value = [ + { + "device_id": "REMOTE-1", + "name": "mac-mini", + "connected": True, + "address": "tcp://192.168.1.42:22000", + "type": "TCP (LAN)", + "crypto": "TLS1.3", + "in_bytes_total": 1000, + "out_bytes_total": 2000, + } + ] + mock_get.return_value = mock_proxy + + resp = client.get("/sync/devices") + assert resp.status_code == 200 + data = resp.json() + assert len(data["devices"]) == 1 + assert data["devices"][0]["name"] == "mac-mini" + + def test_add_device(self): + """POST /sync/devices pairs a new device.""" + with patch("routers.sync_status.get_proxy") as mock_get: + mock_proxy = MagicMock() + mock_proxy.add_device.return_value = { + "device_id": "NEW-DEV", + "name": "work-pc", + "paired": True, + } + mock_get.return_value = mock_proxy + + resp = client.post( + "/sync/devices", + json={"device_id": "NEW-DEV", "name": "work-pc"}, + ) + assert resp.status_code == 200 + data = resp.json() + assert data["paired"] is True + + def test_remove_device(self): + """DELETE /sync/devices/{id} removes a device.""" + with patch("routers.sync_status.get_proxy") as mock_get: + mock_proxy = MagicMock() + mock_proxy.remove_device.return_value = { + "device_id": "OLD-DEV", + "removed": True, + } + mock_get.return_value = mock_proxy + + resp = client.delete("/sync/devices/OLD-DEV") + assert resp.status_code == 200 + data = resp.json() + assert data["removed"] is True + + +class TestSyncProjects: + def test_list_projects_sync_state(self): + """GET /sync/projects returns folder sync state.""" + with patch("routers.sync_status.get_proxy") as mock_get: + mock_proxy = MagicMock() + mock_proxy.get_folder_status.return_value = [ + { + "folder_id": "karma-out-alice", + "path": "/home/alice/.claude_karma/remote-sessions/alice", + "type": "sendonly", + "devices": ["REMOTE-1"], + } + ] + mock_get.return_value = mock_proxy + + resp = client.get("/sync/projects") + assert resp.status_code == 200 + data = resp.json() + assert len(data["folders"]) == 1 + + +class TestSyncActivity: + def test_get_events(self): + """GET /sync/activity returns recent events.""" + with patch("routers.sync_status.get_proxy") as mock_get: + mock_proxy = MagicMock() + mock_proxy.get_events.return_value = [ + { + "id": 1, + "type": "DeviceConnected", + "time": "2026-03-05T10:00:00Z", + "data": {"id": "REMOTE-1"}, + } + ] + mock_get.return_value = mock_proxy + + resp = client.get("/sync/activity") + assert resp.status_code == 200 + data = resp.json() + assert len(data["events"]) == 1 + assert data["events"][0]["type"] == "DeviceConnected" +``` + +**Step 2: Run tests to verify they fail** + +Run: `cd api && python -m pytest tests/api/test_sync_status.py -v` +Expected: FAIL — new endpoints don't exist yet + +**Step 3: Expand the router** + +Modify `api/routers/sync_status.py` — add new endpoints after existing ones: + +```python +"""Sync status API endpoints.""" + +import json +from pathlib import Path +from typing import Any, Optional + +from fastapi import APIRouter, HTTPException +from pydantic import BaseModel + +from services.syncthing_proxy import SyncthingProxy, SyncthingNotRunning + +SYNC_CONFIG_PATH = Path.home() / ".claude_karma" / "sync-config.json" + +router = APIRouter(prefix="/sync", tags=["sync"]) + +# Singleton proxy instance +_proxy: Optional[SyncthingProxy] = None + + +def get_proxy() -> SyncthingProxy: + """Get or create the Syncthing proxy singleton.""" + global _proxy + if _proxy is None: + _proxy = SyncthingProxy() + return _proxy + + +def _load_config() -> Optional[dict]: + if not SYNC_CONFIG_PATH.exists(): + return None + try: + return json.loads(SYNC_CONFIG_PATH.read_text()) + except (json.JSONDecodeError, OSError): + return None + + +# --- Existing endpoints (unchanged) --- + + +@router.get("/status") +async def sync_status(): + """Get sync configuration and status.""" + config = _load_config() + if config is None: + return {"configured": False} + + teams = {} + for name, team in config.get("teams", {}).items(): + teams[name] = { + "backend": team["backend"], + "project_count": len(team.get("projects", {})), + "member_count": len(team.get("ipfs_members", {})) + + len(team.get("syncthing_members", {})), + } + + return { + "configured": True, + "user_id": config.get("user_id"), + "machine_id": config.get("machine_id"), + "teams": teams, + } + + +@router.get("/teams") +async def sync_teams(): + """List all teams with their backend and members.""" + config = _load_config() + if config is None: + return {"teams": []} + + teams = [] + for name, team in config.get("teams", {}).items(): + teams.append( + { + "name": name, + "backend": team["backend"], + "projects": list(team.get("projects", {}).keys()), + "members": list(team.get("ipfs_members", {}).keys()) + + list(team.get("syncthing_members", {}).keys()), + } + ) + + return {"teams": teams} + + +# --- New endpoints --- + + +@router.get("/detect") +async def sync_detect(): + """Check if Syncthing is installed and running.""" + proxy = get_proxy() + return proxy.detect() + + +class AddDeviceRequest(BaseModel): + device_id: str + name: str + + +@router.get("/devices") +async def list_devices(): + """List all paired devices with connection status.""" + proxy = get_proxy() + try: + devices = proxy.get_devices() + return {"devices": devices} + except SyncthingNotRunning: + raise HTTPException(status_code=503, detail="Syncthing is not running") + + +@router.post("/devices") +async def add_device(req: AddDeviceRequest): + """Pair with a new device.""" + proxy = get_proxy() + try: + return proxy.add_device(req.device_id, req.name) + except SyncthingNotRunning: + raise HTTPException(status_code=503, detail="Syncthing is not running") + + +@router.delete("/devices/{device_id}") +async def remove_device(device_id: str): + """Remove a paired device.""" + proxy = get_proxy() + try: + return proxy.remove_device(device_id) + except SyncthingNotRunning: + raise HTTPException(status_code=503, detail="Syncthing is not running") + + +@router.get("/projects") +async def sync_projects(): + """Get all Syncthing folders with sync state.""" + proxy = get_proxy() + try: + folders = proxy.get_folder_status() + return {"folders": folders} + except SyncthingNotRunning: + raise HTTPException(status_code=503, detail="Syncthing is not running") + + +@router.get("/activity") +async def sync_activity(since: int = 0, limit: int = 50): + """Get recent Syncthing events.""" + proxy = get_proxy() + try: + events = proxy.get_events(since=since, limit=limit) + return {"events": events} + except SyncthingNotRunning: + raise HTTPException(status_code=503, detail="Syncthing is not running") +``` + +**Step 4: Run tests to verify they pass** + +Run: `cd api && python -m pytest tests/api/test_sync_status.py -v` +Expected: All PASS + +**Step 5: Lint** + +Run: `cd api && ruff check routers/sync_status.py services/syncthing_proxy.py && ruff format routers/sync_status.py services/syncthing_proxy.py` + +**Step 6: Commit** + +```bash +git add api/routers/sync_status.py api/tests/api/test_sync_status.py +git commit -m "feat(api): add /sync/detect, devices, projects, activity endpoints + +Expands the sync router with endpoints for the dashboard sync page: +detect, device CRUD, project folder status, and activity event log. +All proxy through SyncthingClient via the new proxy service." +``` + +--- + +## Task 3: Frontend — /sync route shell with tabs + +Create the main sync page with tab structure. Initially all tabs render placeholder content. + +**Files:** +- Create: `frontend/src/routes/sync/+page.svelte` +- Create: `frontend/src/routes/sync/+page.server.ts` + +**Step 1: Create the server load function** + +Create `frontend/src/routes/sync/+page.server.ts`: + +```typescript +import type { PageServerLoad } from './$types'; +import { API_BASE } from '$lib/config'; +import { safeFetch } from '$lib/utils/api-fetch'; + +interface SyncDetect { + installed: boolean; + running: boolean; + version: string | null; + device_id: string | null; + uptime: number | null; +} + +interface SyncStatusResponse { + configured: boolean; + user_id?: string; + machine_id?: string; + teams?: Record; +} + +export const load: PageServerLoad = async ({ fetch, url }) => { + const [detectResult, statusResult] = await Promise.all([ + safeFetch(fetch, `${API_BASE}/sync/detect`), + safeFetch(fetch, `${API_BASE}/sync/status`) + ]); + + const activeTab = url.searchParams.get('tab') || null; + + return { + detect: detectResult.ok ? detectResult.data : null, + status: statusResult.ok ? statusResult.data : null, + activeTab + }; +}; +``` + +**Step 2: Create the page component** + +Create `frontend/src/routes/sync/+page.svelte`: + +```svelte + + + + +
+ +
+ +
+ + + + + + + Setup + {#if data.status?.configured} + + {/if} + + + + + + Devices + + + + + + Projects + + + + + + Activity + + + + + +
+ Setup tab — coming in next task +
+ + + +
+ Devices tab — coming in next task +
+ + + +
+ Projects tab — coming in next task +
+ + + +
+ Activity tab — coming in next task +
+ + +
+``` + +**Step 3: Verify it builds** + +Run: `cd frontend && npm run check` +Expected: No type errors + +**Step 4: Commit** + +```bash +git add frontend/src/routes/sync/+page.svelte frontend/src/routes/sync/+page.server.ts +git commit -m "feat(frontend): add /sync route shell with tabbed layout + +Four tabs (Setup, Devices, Projects, Activity) using bits-ui Tabs. +Default tab is Setup when unconfigured, Devices when configured. +Tab state persisted in URL params." +``` + +--- + +## Task 4: Frontend — Add "Sync" to navigation + +Add the Sync link to the header navigation (desktop + mobile). + +**Files:** +- Modify: `frontend/src/lib/components/Header.svelte` +- Modify: `frontend/src/routes/+layout.svelte` (skeleton) + +**Step 1: Add Sync nav link to Header.svelte** + +In the desktop nav section (after the "Archived" link, before "Team"), add: + +```svelte + + Sync + +``` + +Add the same link in the mobile nav section (same position — after Archived, before Team). + +**Step 2: Add skeleton route in +layout.svelte** + +In the `navigationSkeletonType` derived block, add before `return null`: + +```typescript +if (path === '/sync') return 'settings'; // Reuse settings skeleton for now +``` + +**Step 3: Verify it builds** + +Run: `cd frontend && npm run check` +Expected: No type errors + +**Step 4: Commit** + +```bash +git add frontend/src/lib/components/Header.svelte frontend/src/routes/+layout.svelte +git commit -m "feat(frontend): add Sync to navigation header + +Adds Sync link between Archived and Team in both desktop and mobile +nav. Reuses settings skeleton during navigation loading." +``` + +--- + +## Task 5: Frontend — Setup tab component + +The most complex tab — three states with progressive disclosure. + +**Files:** +- Create: `frontend/src/lib/components/sync/SetupTab.svelte` +- Modify: `frontend/src/routes/sync/+page.svelte` (import SetupTab) + +**Step 1: Create SetupTab.svelte** + +Create `frontend/src/lib/components/sync/SetupTab.svelte`: + +```svelte + + +
+ +
+

Choose Sync Backend

+
+
+
+
+ Syncthing +
+

+ Real-time auto sync between your machines. Simple setup, encrypted. +

+

+ Best for: syncing your own machines +

+
+
+
+
+ IPFS +
+

+ On-demand sync, content-addressed, tamper-evident. +

+

Coming soon

+
+
+
+ + {#if setupState === 'not-installed'} + +
+
+ +

+ Syncthing not detected +

+
+ +
+
+ macOS + brew install syncthing +
+
+ Linux + sudo apt install syncthing +
+
+ Windows + scoop install syncthing +
+ +

+ Then start it: syncthing serve --no-browser +

+
+ +
+ +
+
+ {:else if setupState === 'not-initialized'} + +
+
+ + + Syncthing {detect?.version} running + +
+
+ +
+

Initialize

+ +
+
+ + +

Auto-filled from hostname

+
+ + {#if detect?.device_id} +
+ +
+ + {detect.device_id} + + +
+

+ Share this with your other machine +

+
+ {/if} + + {#if initError} +

{initError}

+ {/if} + + +
+
+ {:else} + +
+
+
+
+ + + {status?.machine_id || 'This Machine'} + +
+

+ Syncthing {detect?.version} running +

+
+ {#if detect?.device_id} + + {/if} +
+
+ + +
+

Paired Devices

+ + {#if isLoadingDevices} +

Loading devices...

+ {:else if devices.length === 0} +

No devices paired yet.

+ {:else} +
+ {#each devices as device} +
+
+
+ + + {device.name} + +
+

+ {device.connected ? device.address : 'Disconnected'} +

+
+ +
+ {/each} +
+ {/if} + + +
+
+ + Add Device +
+
+ + + {#if pairError} +

{pairError}

+ {/if} + +
+
+
+ + +
+

Network

+
+ + + +
+
+ {/if} +
+``` + +**Step 2: Wire it into the sync page** + +Update `frontend/src/routes/sync/+page.svelte` — replace the setup TabsContent placeholder: + +```svelte + +import SetupTab from '$lib/components/sync/SetupTab.svelte'; + + + + + +``` + +**Step 3: Verify it builds** + +Run: `cd frontend && npm run check` +Expected: No type errors + +**Step 4: Commit** + +```bash +git add frontend/src/lib/components/sync/SetupTab.svelte frontend/src/routes/sync/+page.svelte +git commit -m "feat(frontend): implement Setup tab for /sync page + +Three-state progressive flow: detect Syncthing installation, +initialize with machine name, pair devices with Device ID exchange. +Network configuration for LAN/relay/VPN modes." +``` + +--- + +## Task 6: Frontend — Devices tab component + +**Files:** +- Create: `frontend/src/lib/components/sync/DevicesTab.svelte` +- Create: `frontend/src/lib/components/sync/DeviceCard.svelte` +- Modify: `frontend/src/routes/sync/+page.svelte` + +**Step 1: Create DeviceCard.svelte** + +Create `frontend/src/lib/components/sync/DeviceCard.svelte`: + +```svelte + + +
+ + + + + {#if expanded} +
+ +
+

+ Connection +

+
+
+ Address +

+ {device.address || 'N/A'} +

+
+
+ Type +

{device.type || 'N/A'}

+
+
+ Encryption +

+ + {device.crypto || 'N/A'} +

+
+
+ Device ID +

+ {device.device_id.slice(0, 20)}... +

+
+
+
+ + +
+

+ Transfer +

+
+
+ Total Sent +

+ {formatBytes(device.out_bytes_total)} +

+
+
+ Total Received +

+ {formatBytes(device.in_bytes_total)} +

+
+
+
+
+ {/if} +
+``` + +**Step 2: Create DevicesTab.svelte** + +Create `frontend/src/lib/components/sync/DevicesTab.svelte`: + +```svelte + + +
+ {#if !detect?.running} +
+ +

Syncthing is not running. Go to the Setup tab to get started.

+
+ {:else if isLoading} +
+ {#each [1, 2] as _} +
+ {/each} +
+ {:else if error} +
+

{error}

+
+ {:else} + {#each allDevices as device} + + {/each} + {/if} +
+``` + +**Step 3: Wire into sync page** + +Update `frontend/src/routes/sync/+page.svelte` — import and use DevicesTab: + +```svelte +import DevicesTab from '$lib/components/sync/DevicesTab.svelte'; + + + + +``` + +**Step 4: Verify it builds** + +Run: `cd frontend && npm run check` + +**Step 5: Commit** + +```bash +git add frontend/src/lib/components/sync/DeviceCard.svelte frontend/src/lib/components/sync/DevicesTab.svelte frontend/src/routes/sync/+page.svelte +git commit -m "feat(frontend): implement Devices tab with expandable cards + +Shows all paired devices with connection status, transfer stats, +address, encryption, and device ID. Polls every 10s for live updates. +Self-device shown first with 'This Machine' badge." +``` + +--- + +## Task 7: Frontend — Projects tab component + +**Files:** +- Create: `frontend/src/lib/components/sync/ProjectsTab.svelte` +- Create: `frontend/src/lib/components/sync/ProjectRow.svelte` +- Modify: `frontend/src/routes/sync/+page.svelte` + +**Step 1: Create ProjectRow.svelte** + +Create `frontend/src/lib/components/sync/ProjectRow.svelte`: + +```svelte + + +
+ + + + +
+
+ + {project.name} + + + + {statusText} + +
+ {#if project.synced} +

+ Last sync: {formatTimeAgo(project.last_sync_at)} · {project.machine_count} machine{project.machine_count !== 1 ? 's' : ''} +

+ {/if} +
+ + + + {project.local_session_count} sessions + + + + {#if project.synced && project.pending_count > 0} + + {:else if !project.synced} + + {/if} + + + {#if project.synced} + + {#if expanded} + + {:else} + + {/if} + + {/if} + + + + {#if expanded && project.synced} +
+

+ Machine breakdown and file details will load here. +

+
+ {/if} +
+``` + +**Step 2: Create ProjectsTab.svelte** + +Create `frontend/src/lib/components/sync/ProjectsTab.svelte`: + +```svelte + + +
+ {#if isLoading} +
+ {#each [1, 2, 3] as _} +
+ {/each} +
+ {:else if error} +
+

{error}

+
+ {:else if projects.length === 0} +
+ +

No projects found. Start a Claude Code session first.

+
+ {:else} +
+ +
+ +
+ {#each projects as project} + + {/each} +
+ {/if} +
+``` + +**Step 3: Wire into sync page** + +Update `frontend/src/routes/sync/+page.svelte`: + +```svelte +import ProjectsTab from '$lib/components/sync/ProjectsTab.svelte'; + + + + +``` + +**Step 4: Verify it builds** + +Run: `cd frontend && npm run check` + +**Step 5: Commit** + +```bash +git add frontend/src/lib/components/sync/ProjectRow.svelte frontend/src/lib/components/sync/ProjectsTab.svelte frontend/src/routes/sync/+page.svelte +git commit -m "feat(frontend): implement Projects tab with toggle + disclosure + +Per-project rows with sync toggle, status badges, action buttons. +Expandable rows for machine breakdown. Select All for bulk enable." +``` + +--- + +## Task 8: Frontend — Activity tab with bandwidth chart and event log + +**Files:** +- Create: `frontend/src/lib/components/sync/ActivityTab.svelte` +- Create: `frontend/src/lib/components/sync/BandwidthChart.svelte` +- Modify: `frontend/src/routes/sync/+page.svelte` + +**Step 1: Create BandwidthChart.svelte** + +Create `frontend/src/lib/components/sync/BandwidthChart.svelte`: + +```svelte + + +
+ +
+``` + +**Step 2: Create ActivityTab.svelte** + +Create `frontend/src/lib/components/sync/ActivityTab.svelte`: + +```svelte + + +
+ +
+
+

+ Bandwidth +

+
+ + + Upload + + + + Download + +
+
+ +
+ + +
+
+

+ Event Log +

+
+ +
+
+ +
+ {#if isLoading} +
Loading events...
+ {:else if error} +
{error}
+ {:else if filteredEvents.length === 0} +
+ +

No events yet

+
+ {:else} + {#each filteredEvents as event} +
+ +
+
+ + {formatTime(event.time)} + + + {getEventLabel(event.type)} + +
+ {#if event.data} +

+ {JSON.stringify(event.data).slice(0, 100)} +

+ {/if} +
+
+ {/each} + {/if} +
+
+
+``` + +**Step 3: Wire into sync page** + +Update `frontend/src/routes/sync/+page.svelte`: + +```svelte +import ActivityTab from '$lib/components/sync/ActivityTab.svelte'; + + + + +``` + +**Step 4: Verify it builds** + +Run: `cd frontend && npm run check` + +**Step 5: Commit** + +```bash +git add frontend/src/lib/components/sync/BandwidthChart.svelte frontend/src/lib/components/sync/ActivityTab.svelte frontend/src/routes/sync/+page.svelte +git commit -m "feat(frontend): implement Activity tab with bandwidth chart + event log + +Chart.js sparkline for upload/download bandwidth. Filterable event log +with color-coded dots per event type. Polls every 5s for new events." +``` + +--- + +## Task 9: Backend — POST /sync/init endpoint + +The Setup tab needs `POST /sync/init` to run `karma init`. This executes the CLI command via subprocess. + +**Files:** +- Modify: `api/routers/sync_status.py` +- Test: `api/tests/api/test_sync_status.py` + +**Step 1: Write failing test** + +Add to `api/tests/api/test_sync_status.py`: + +```python +class TestSyncInit: + def test_init_success(self): + """POST /sync/init runs karma init.""" + with patch("routers.sync_status.run_karma_command") as mock_run: + mock_run.return_value = {"success": True, "output": "Initialized"} + with patch("routers.sync_status.get_proxy") as mock_get: + mock_proxy = MagicMock() + mock_proxy.detect.return_value = { + "installed": True, + "running": True, + "version": "v1.27.0", + "device_id": "DEVICE-123", + } + mock_get.return_value = mock_proxy + + resp = client.post( + "/sync/init", + json={"machine_name": "my-macbook"}, + ) + assert resp.status_code == 200 + data = resp.json() + assert data["success"] is True +``` + +**Step 2: Run test to verify it fails** + +Run: `cd api && python -m pytest tests/api/test_sync_status.py::TestSyncInit -v` + +**Step 3: Add the endpoint and helper** + +Add to `api/routers/sync_status.py`: + +```python +import subprocess +import shutil + + +class InitRequest(BaseModel): + machine_name: str + + +def run_karma_command(args: list[str]) -> dict[str, Any]: + """Execute a karma CLI command and return result.""" + karma_path = shutil.which("karma") + if not karma_path: + # Try the local CLI directory + cli_path = Path(__file__).parent.parent.parent / "cli" + karma_path = str(cli_path / "karma" / "main.py") + + try: + result = subprocess.run( + ["python", "-m", "karma"] + args if not shutil.which("karma") else ["karma"] + args, + capture_output=True, + text=True, + timeout=30, + cwd=str(Path.home()), + ) + return { + "success": result.returncode == 0, + "output": result.stdout.strip(), + "error": result.stderr.strip() if result.returncode != 0 else None, + } + except subprocess.TimeoutExpired: + return {"success": False, "output": "", "error": "Command timed out"} + except FileNotFoundError: + return {"success": False, "output": "", "error": "karma CLI not found"} + + +@router.post("/init") +async def sync_init(req: InitRequest): + """Initialize sync with karma CLI.""" + result = run_karma_command(["init", "--backend", "syncthing", "--machine-name", req.machine_name]) + if result["success"]: + # Refresh proxy to pick up new config + global _proxy + _proxy = None + + proxy = get_proxy() + detect = proxy.detect() + return { + "success": True, + "device_id": detect.get("device_id"), + "machine_name": req.machine_name, + } + return {"success": False, "error": result.get("error", "Initialization failed")} +``` + +**Step 4: Run tests** + +Run: `cd api && python -m pytest tests/api/test_sync_status.py -v` + +**Step 5: Commit** + +```bash +git add api/routers/sync_status.py api/tests/api/test_sync_status.py +git commit -m "feat(api): add POST /sync/init endpoint for CLI initialization + +Executes karma init via subprocess, returns device ID on success. +Resets proxy singleton to pick up new configuration." +``` + +--- + +## Task 10: Backend — Project enable/disable + sync-now endpoints + +**Files:** +- Modify: `api/routers/sync_status.py` +- Test: `api/tests/api/test_sync_status.py` + +**Step 1: Write failing tests** + +```python +class TestSyncProjectActions: + def test_enable_project_sync(self): + """POST /sync/projects/{name}/enable starts syncing.""" + with patch("routers.sync_status.run_karma_command") as mock_run: + mock_run.return_value = {"success": True, "output": "Enabled"} + resp = client.post("/sync/projects/my-project/enable") + assert resp.status_code == 200 + assert resp.json()["success"] is True + + def test_disable_project_sync(self): + """POST /sync/projects/{name}/disable stops syncing.""" + with patch("routers.sync_status.run_karma_command") as mock_run: + mock_run.return_value = {"success": True, "output": "Disabled"} + resp = client.post("/sync/projects/my-project/disable") + assert resp.status_code == 200 + assert resp.json()["success"] is True + + def test_sync_now(self): + """POST /sync/projects/{name}/sync-now triggers manual sync.""" + with patch("routers.sync_status.run_karma_command") as mock_run: + mock_run.return_value = {"success": True, "output": "Synced 5 sessions"} + resp = client.post("/sync/projects/my-project/sync-now") + assert resp.status_code == 200 + assert resp.json()["success"] is True +``` + +**Step 2: Add endpoints** + +```python +@router.post("/projects/{name}/enable") +async def enable_project_sync(name: str): + """Enable sync for a project.""" + result = run_karma_command(["project", "add", name]) + return {"success": result["success"], "error": result.get("error")} + + +@router.post("/projects/{name}/disable") +async def disable_project_sync(name: str): + """Disable sync for a project.""" + result = run_karma_command(["project", "remove", name]) + return {"success": result["success"], "error": result.get("error")} + + +@router.post("/projects/{name}/sync-now") +async def sync_project_now(name: str): + """Trigger manual sync for a project.""" + result = run_karma_command(["sync", name]) + return {"success": result["success"], "output": result.get("output"), "error": result.get("error")} + + +@router.post("/watcher/restart") +async def restart_watcher(): + """Restart the file watcher.""" + result = run_karma_command(["watch"]) + return {"success": result["success"], "error": result.get("error")} +``` + +**Step 3: Run tests** + +Run: `cd api && python -m pytest tests/api/test_sync_status.py -v` + +**Step 4: Lint** + +Run: `cd api && ruff check routers/sync_status.py && ruff format routers/sync_status.py` + +**Step 5: Commit** + +```bash +git add api/routers/sync_status.py api/tests/api/test_sync_status.py +git commit -m "feat(api): add project enable/disable/sync-now and watcher endpoints + +POST endpoints that execute karma CLI commands for per-project sync +control and manual sync triggers." +``` + +--- + +## Task 11: Full verification + +**Step 1: Run all API tests** + +Run: `cd api && python -m pytest tests/ -v --timeout=30` +Expected: All PASS + +**Step 2: Run frontend type check** + +Run: `cd frontend && npm run check` +Expected: No errors + +**Step 3: Run frontend lint** + +Run: `cd frontend && npm run lint` +Expected: No errors + +**Step 4: Manual smoke test** + +1. Start API: `cd api && uvicorn main:app --reload --port 8000` +2. Start frontend: `cd frontend && npm run dev` +3. Navigate to `http://localhost:5173/sync` +4. Verify: + - Tab bar renders with 4 tabs + - Setup tab shows backend selection + install/detect state + - Devices tab shows loading or "not running" state + - Projects tab lists local projects + - Activity tab shows empty event log with bandwidth chart + - Tab state persists in URL + - "Sync" appears in header nav + +--- + +## Summary + +| Task | What | Files | Priority | +|------|------|-------|----------| +| 1 | Syncthing proxy service | `services/syncthing_proxy.py` | High | +| 2 | Expand /sync router | `routers/sync_status.py` | High | +| 3 | /sync route shell + tabs | `routes/sync/+page.*` | High | +| 4 | Navigation update | `Header.svelte`, `+layout.svelte` | High | +| 5 | Setup tab | `sync/SetupTab.svelte` | High | +| 6 | Devices tab | `sync/DevicesTab.svelte`, `DeviceCard.svelte` | High | +| 7 | Projects tab | `sync/ProjectsTab.svelte`, `ProjectRow.svelte` | High | +| 8 | Activity tab | `sync/ActivityTab.svelte`, `BandwidthChart.svelte` | High | +| 9 | POST /sync/init | `routers/sync_status.py` | High | +| 10 | Project enable/disable/sync-now | `routers/sync_status.py` | High | +| 11 | Full verification | — | Required | + +**Not in scope (future tasks):** +- SSE streaming for real-time events (polling is MVP) +- Conflict resolution UI (detect only in MVP) +- Network mode persistence via `PUT /sync/config` (radio buttons disabled with "coming soon" in MVP) +- Per-file sync status in Projects tab L2 (placeholder in MVP) +- IPFS backend (greyed out) +- QR code for device ID sharing (MVP uses copy/paste) +- `karma sync` for Syncthing (IPFS-only; Syncthing uses packager + auto-sync) + +**Required reading before implementation:** +- Architecture Review Amendments (above) — apply all corrections as you implement each task +- Design Token Mapping in `docs/plans/2026-03-05-sync-page-ui-design.md` +- `cli/karma/main.py` — actual CLI command signatures +- `cli/karma/syncthing.py` — actual SyncthingClient API (no `get_system_status()`, no `_session`, `headers` not `_headers`) diff --git a/docs/plans/2026-03-05-sync-page-ui-design.md b/docs/plans/2026-03-05-sync-page-ui-design.md new file mode 100644 index 00000000..afa0e23f --- /dev/null +++ b/docs/plans/2026-03-05-sync-page-ui-design.md @@ -0,0 +1,587 @@ +# Sync Page UI/UX Design + +**Date:** 2026-03-05 +**Status:** Approved +**Author:** Jayant Devkar + Claude +**Depends on:** [Syncthing Session Sync Design](./2026-03-03-syncthing-session-sync-design.md), [IPFS Sync UI/UX Design](./2026-03-03-ipfs-sync-ui-ux-design.md) + +## Problem + +Users who download Claude Karma and open the `/team` page have zero guidance on what P2P sync means, why they'd want it, how to install prerequisites, or how to monitor it once running. The existing Syncthing and IPFS designs are CLI-first — the dashboard should be the single pane of glass so users never touch Syncthing's web UI or terminal. + +## MVP Persona + +A solo user with 2+ machines running Claude Code. They want to unify their sessions across machines without learning P2P internals. + +**Not in MVP scope:** Team/freelancer management, IPFS backend (UI-ready but greyed out). + +## Design Decisions + +| Decision | Choice | Rationale | +|----------|--------|-----------| +| Primary persona | Solo user, multiple machines | Simplest valuable scenario | +| Dashboard role | Single pane of glass | Users never touch Syncthing UI or terminal | +| Backend execution | SyncthingProxy service wraps SyncthingClient | API calls SyncthingClient directly (HTTP to Syncthing daemon), plus `karma` CLI via subprocess for init/project/team commands | +| Project selection | Toggle per-project with "select all" | Granular control, easy bulk action | +| Navigation | New `/sync` page, keep `/team` separate | Clear separation: infrastructure vs people | +| Page structure | Tabbed single page | Organized by concern, familiar pattern | +| Detail level | Full Syncthing dashboard replacement | Users never need localhost:8384 | +| Visual hierarchy | Scan > Spot > Drill (progressive disclosure) | Don't overwhelm, surface problems first | +| Data refresh | Single 10s poll at page level | Balance between freshness and load; centralized to avoid multiple intervals | + +## Design Token Mapping + +All status colors MUST use CSS custom properties from `app.css` for dark mode support. Never hardcode Tailwind color classes for semantic status. + +| Sync State | Dot Color Token | Card Background Token | Badge Variant | +|---|---|---|---| +| Connected / synced | `var(--success)` | `var(--status-active-bg)` | `success` | +| Syncing in progress | `var(--info)` | `var(--status-waiting-bg)` | `info` | +| Pending / stale | `var(--warning)` | `var(--status-idle-bg)` | `warning` | +| Error / conflict | `var(--error)` | `var(--status-stale-bg)` | `error` | +| Disconnected / stopped | `var(--text-muted)` | `var(--status-stopped-bg)` | `default` | +| Offline / gone | `var(--text-faint)` | `var(--status-ended-bg)` | `slate` | + +**Additional token usage:** +- Error banners: `bg-[var(--error-subtle)] border-[var(--error)]/20 text-[var(--error)]` +- Progress bar track: `bg-[var(--bg-muted)]`, fill: `bg-[var(--success)]` +- Bandwidth chart: Upload = `var(--accent)` (purple), Download = `var(--info)` (blue) — resolved via `getThemeColors()` from `chartConfig.ts` +- Status dots should follow `LiveSessionsSection.svelte` pulse animation pattern for active states +- Use `` from `ui/Badge.svelte` for status badges + +## Route & Navigation + +### Route: `/sync` + +**Nav position:** Between "Archived" and "Team" in the header — grouping infrastructure/collaboration items at the end. + +**Page header:** "Sync" with `RefreshCw` (lucide) icon, purple accent. Breadcrumb: Dashboard > Sync. + +### Tab Bar + +Horizontal tabs below the header: + +1. **Setup** — green checkmark badge once configured +2. **Devices** — count badge (e.g., "2") +3. **Projects** — count badge of syncing projects +4. **Activity** — orange dot when transfers are active + +**Default tab logic:** +- Not configured: Setup tab auto-selected +- Configured: Devices tab auto-selected +- Active transfer in progress: Activity tab gets attention dot + +**URL state:** Tab persisted in URL params (`/sync?tab=devices`) for shareable links. + +**Polling:** `/sync/status` every 10 seconds. "Last updated: 5s ago" timestamp in header. Manual refresh button. + +## Tab 1: Setup + +Three progressive states: Not Installed > Not Initialized > Configured. + +### State 1: Syncthing Not Detected + +``` ++-------------------------------------------------------------+ +| | +| +--- CHOOSE SYNC BACKEND --------------------------------+| +| | || +| | +---------------------+ +---------------------+ || +| | | * Syncthing | | o IPFS | || +| | | | | | || +| | | Real-time auto | | On-demand sync, | || +| | | sync between your | | content-addressed, | || +| | | machines. Simple | | tamper-evident. | || +| | | setup, encrypted. | | | || +| | | | | Best for: larger | || +| | | Best for: syncing | | teams, audit trails| || +| | | your own machines | | [Coming soon] | || +| | +---------------------+ +---------------------+ || +| +---------------------------------------------------------+| +| | +| +--- INSTALL SYNCTHING ----------------------------------+| +| | || +| | * Not detected on this machine || +| | || +| | macOS: brew install syncthing || +| | Linux: sudo apt install syncthing || +| | Windows: scoop install syncthing || +| | || +| | Then start it: syncthing serve --no-browser || +| | || +| | [ Check Again ] || +| +---------------------------------------------------------+| ++-------------------------------------------------------------+ +``` + +- Backend calls Syncthing REST API (`localhost:8384/rest/system/status`) to detect +- "Check Again" button re-polls +- IPFS card greyed out with "Coming soon" +- OS auto-detected, matching install command highlighted + +### State 2: Syncthing Detected, Not Initialized + +``` ++-------------------------------------------------------------+ +| +--- SYNCTHING DETECTED ---------------------------------+| +| | Syncthing v1.27.0 running on port 8384 || +| +---------------------------------------------------------+| +| | +| +--- INITIALIZE -----------------------------------------+| +| | || +| | Machine Name [ alice-macbook-pro ] || +| | (auto-filled from hostname) || +| | || +| | Your Device ID (read-only, from Syncthing): || +| | +--------------------------------------------------+ || +| | | XXXXXXX-XXXXXXX-XXXXXXX-XXXXXXX-XXXXXXX-XXXXXXX | || +| | +--------------------------------------------------+ || +| | [ Copy ] || +| | || +| | Share this Device ID with your other machine, || +| | then paste theirs below. || +| | || +| | [ Initialize ] || +| +---------------------------------------------------------+| ++-------------------------------------------------------------+ +``` + +- Backend calls `karma init --user-id --backend syncthing` on Initialize (user ID is the identity, machine name auto-generated from hostname in config) +- User ID editable (defaults to hostname-derived value) +- Device ID fetched from Syncthing API via `SyncthingClient.get_device_id()`, displayed read-only with copy button +- **Error recovery:** On failure, show contextual error banner with troubleshooting tips (e.g., "Syncthing stopped running", "API key mismatch") and a retry button. Follow settings page error pattern (`bg-[var(--error-subtle)]` banner). + +### State 3: Initialized — Pair Devices + +``` ++-------------------------------------------------------------+ +| +--- THIS MACHINE ---------------------------------------+| +| | alice-macbook-pro || +| | Device ID: XXXXXXX-... [Copy] || +| | Syncthing: v1.27.0 Running || +| +---------------------------------------------------------+| +| | +| +--- PAIRED DEVICES -------------------------------------+| +| | || +| | alice-mac-mini Connected [Remove] || +| | YYYYYYY-... Last seen: 2m ago || +| | || +| | - - - - - - - - - - - - - - - - - - - - - - - - - - || +| | || +| | + Add Device || +| | Paste Device ID: [ ] || +| | Device Name: [ ] || +| | [ Pair Device ] || +| +---------------------------------------------------------+| +| | +| +--- NETWORK CONFIGURATION ------------------------------+| +| | * Local network (devices on same WiFi/LAN) || +| | o Remote (via Syncthing relays, encrypted) || +| | o VPN (Tailscale/WireGuard, direct connection) || +| | || +| | [x] Disable global announce (privacy) || +| | [x] Disable relays (direct connections only) || +| +---------------------------------------------------------+| ++-------------------------------------------------------------+ +``` + +- "Add Device" triggers backend which calls `SyncthingClient.add_device(device_id, name)` directly, then updates sync-config.json via `karma team add --team ` +- Connection status polled from Syncthing `/rest/system/connections` via proxy service +- Network mode: **UI-only in MVP** — radio buttons rendered but disabled with "(coming soon)" label. `PUT /sync/config` deferred to post-MVP. +- Remove button with confirmation dialog, calls `SyncthingClient.remove_device(device_id)` + +## Tab 2: Devices + +Daily monitoring view. All paired machines with full Syncthing detail. + +### Layout + +Each device is a card. "This Machine" card first, then paired devices. + +### Per-Device Card + +``` ++-------------------------------------------------------------+ +| alice-mac-mini [...] | +| Connected | Device ID: YYYYYYY-... | Last seen: now | +| | +| +--- CONNECTION -----------------------------------------+| +| | Address: tcp://192.168.1.42:22000 || +| | Type: Direct (LAN) || +| | Encryption: TLS 1.3 || +| | Connected since: Mar 3, 2:15 PM || +| +---------------------------------------------------------+| +| | +| +--- TRANSFER -------------------------------------------+| +| | Up: 0 B/s Down: 45 KB/s || +| | Total sent: 420 MB Total received: 380 MB || +| | || +| | In Sync ========================-- 92% || +| | Files: 847/920 synced || +| +---------------------------------------------------------+| +| | +| +--- SHARED FOLDERS -------------------------------------+| +| | karma-out-alice remote-sessions/alice/ || +| | Up to date 284 files, 120 MB || +| | || +| | karma-in-alice remote-sessions/alice-mini/ || +| | Syncing... 12 files remaining || +| | ============-------- 62% ~30s left || +| +---------------------------------------------------------+| ++-------------------------------------------------------------+ +``` + +### Status Indicators + +Uses design tokens from `app.css` — see "Design Token Mapping" section above. + +| State | Dot Token | Text | Display | +|-------|-----------|------|---------| +| Connected | `var(--success)` | "Connected" | Active TLS connection | +| Online (self) | `var(--success)` | "Online" | This machine (always) | +| Syncing | `var(--info)` | "Syncing" | Active file transfer, pulse animation | +| Disconnected | `var(--text-muted)` | "Disconnected" | No connection | +| Stale | `var(--warning)` | "Stale" | Disconnected >24h, with help text | + +### [...] Menu Per Device + +- Pause syncing +- Copy Device ID +- Remove device (with confirmation) + +### Data Sources + +| Syncthing API | What it provides | +|---------------|-----------------| +| `/rest/system/connections` | Connection details, bandwidth | +| `/rest/db/completion` | Per-folder sync percentage | +| `/rest/stats/device` | Last seen, total transfer | +| `/rest/system/status` | Local device info, uptime | + +## Tab 3: Projects + +Toggle which projects sync. Progressive disclosure: Scan > Spot > Drill. + +### Default View (Collapsed Rows) + +``` ++--------------------------------------------------------------+ +| PROJECTS [ Select All ] [Refresh] | +| | +| +----------------------------------------------------------+| +| | * claude-karma In sync 42 sessions || +| | Last sync: 5m ago 2 machines || +| |----------------------------------------------------------|| +| | * side-project ! 3 pending 8 sessions || +| | Last sync: 2d ago 1 machine [Sync Now] || +| |----------------------------------------------------------|| +| | o acme-app Not syncing 12 sessions || +| | [Enable Sync] || +| |----------------------------------------------------------|| +| | o personal-site Not syncing 4 sessions || +| | [Enable Sync] || +| +----------------------------------------------------------+| +| | +| ! 1 conflict across projects [View Conflicts] | ++--------------------------------------------------------------+ +``` + +**What you see at a glance:** +- Each project is one row: toggle dot, name, status badge, session count +- Secondary line: last sync time, machine count +- Action buttons only on rows that need them +- Conflicts summarized as a single banner at the bottom + +### Expanded Project (Click Row) — Level 1 + +``` +| * claude-karma In sync 42 sessions | +| Last sync: 5m ago 2 machines | +| | +| +--- Machines ----+ | +| | alice-macbook-pro (this) 24 sessions | +| | alice-mac-mini 18 sessions | +| +-----------------+ | +| | +| > Files (48) > Sync History | +``` + +Machine breakdown as a mini table. "Files" and "Sync History" are chevron links to level 2. + +### Files Expanded — Level 2 + +``` +| v Files (48) | +| +---------------------------------------------------+ +| | Syncing now (2) | +| | --------------------------------------------------| +| | ghi789.jsonl Syncing 72% 89 KB ~5s | +| | ghi789/subagents/ Pending 12 KB | +| | | +| | Recently synced (showing 5 of 46) | +| | --------------------------------------------------| +| | abc123.jsonl Synced 45 KB 5m ago | +| | def456.jsonl Synced 120 KB 5m ago | +| | def456/tool-results Synced 8 KB 5m ago | +| | abc123-task.json Synced 2 KB 5m ago | +| | ... | +| | [ Show all 46 ] | +| +----------------------------------------------------+ +``` + +- Active transfers float to top with progress bars +- Completed files grouped and capped at 5, expandable +- File sizes right-aligned, muted color + +### Hierarchy Summary + +| Level | What's shown | Visible by default | +|-------|-------------|-------------------| +| L0 | Project row: name, status badge, counts, action button | Always | +| L1 | Machine breakdown (mini table) | On row click | +| L2 | Files list (active first, then recent) | On chevron click | +| L2 | Sync history for this project | On chevron click | +| Global | Conflicts banner + detail | Only when conflicts exist | + +### Visual Status Cues + +- `var(--success)` text = everything fine, no action needed +- `var(--warning)` text + action button = needs attention, here's what to do +- `var(--text-muted)` = inactive, opt-in available +- `var(--info)` = something is actively happening + +### Action Buttons + +- **Enable Sync**: backend calls `karma project add --path --team ` via subprocess, then creates Syncthing shared folders via `SyncthingClient.add_folder()` +- **Sync Now**: backend triggers the `SessionPackager` to re-package sessions for the project's outbox directory (Syncthing auto-syncs from there). Note: `karma sync` is IPFS-only — for Syncthing the packager is the sync mechanism. +- **Restart Watcher**: backend calls `karma watch --team ` via subprocess + +### Conflicts Section + +Pulled out to own section below project list. Only visible when conflicts exist. + +``` ++--- CONFLICTS (1) -----------------------------------------------+ +| | +| side-project / sessions / xyz.jsonl | +| Modified on both machines | Mar 3, 2:15 PM | +| Kept: alice-macbook-pro version | +| | +| [ Keep Mine ] [ Keep Other ] [ View Diff ] | ++-------------------------------------------------------------------+ +``` + +## Tab 4: Activity + +Real-time feed of everything happening. The "terminal output" for non-terminal users. + +### Layout: Bandwidth Chart + Filterable Event Log + +``` ++--------------------------------------------------------------+ +| ACTIVITY | +| | +| +--- BANDWIDTH -------- Up: 1.2 MB/s Down: 450 KB/s ----+| +| | || +| | (sparkline chart, ~120px tall, upload/download lines) || +| | || +| | -1h -30m now || +| | [ 1h ] [ 6h ] [ 24h ] [ 7d ] || +| +-----------------------------------------------------------+| +| | +| +--- EVENT LOG --------------------------------------------| +| | || +| | Filter: [ All types ] [ All devices ] [ All projects ] || +| | || +| | * 2:34 PM Transfer complete || +| | claude-karma/sessions/abc123.jsonl || +| | <- alice-mac-mini 45 KB || +| | || +| | * 2:34 PM Transfer started || +| | claude-karma/sessions/ghi789.jsonl || +| | <- alice-mac-mini 89 KB || +| | || +| | * 2:30 PM Device connected || +| | alice-mac-mini || +| | tcp://192.168.1.42:22000 (LAN) || +| | || +| | o 2:15 PM Device disconnected || +| | alice-work-pc || +| | Last seen: 2 days ago || +| | || +| | ! 1:50 PM Conflict detected || +| | side-project/sessions/xyz.jsonl || +| | Both machines modified this file || +| | [Resolve ->] || +| | || +| | * 1:45 PM Watcher packaged || +| | side-project: 3 sessions -> remote-sessions/ || +| | || +| | * 12:00 PM Scan completed || +| | All folders up to date || +| | || +| | [ Load older ] || +| +-----------------------------------------------------------+| ++--------------------------------------------------------------+ +``` + +### Bandwidth Chart + +- Always visible at top, small footprint (~120px tall) +- Two lines: upload (out) and download (in) +- Time range buttons: 1h, 6h, 24h, 7d +- Current rates displayed inline in the section header + +### Event Log + +Reverse chronological. Each entry: +- **Colored dot**: green (success), orange (warning), grey (info/disconnect), blue (in-progress) +- **Timestamp**: left-aligned, muted +- **Event type**: bold, one line +- **Detail line**: file path, device name, size — muted, smaller text +- **Action link**: only on actionable events (conflicts: "Resolve ->") + +### Event Types + +| Event | Dot Token | Syncthing Event Type | Source | +|-------|-----------|---------------------|--------| +| Transfer complete | `var(--success)` | `ItemFinished` | Syncthing events API | +| Transfer started | `var(--info)` | `DownloadProgress` | Syncthing events API | +| Device connected | `var(--success)` | `DeviceConnected` | Syncthing events API | +| Device disconnected | `var(--text-muted)` | `DeviceDisconnected` | Syncthing events API | +| Conflict detected | `var(--warning)` | `LocalChangeDetected` | Syncthing events API | +| Watcher packaged | `var(--success)` | N/A | `karma watch` log | +| Scan completed | `var(--text-muted)` | `FolderSummary` | Syncthing events API | +| Error | `var(--error)` | `FolderErrors` | Any source | + +**Event detail formatting:** Each event type should display structured detail (not raw JSON). For example, `ItemFinished` shows `{item} — {folder}`, `DeviceConnected` shows the address, etc. + +### Filters + +Three dropdowns, all update URL params for bookmarkability: +- Event type: All, Transfers, Connections, Conflicts, Errors +- Device: All devices, or pick one +- Project: All projects, or pick one + +### Data Source + +Syncthing `/rest/events` SSE endpoint proxied through backend. Live-updating without polling. Bandwidth computed from transfer events. `karma watch` packaging events from sync_history SQLite table. + +## API Endpoints (New) + +All endpoints proxy to Syncthing REST API via `SyncthingProxy` service layer (wraps `SyncthingClient` from `cli/karma/syncthing.py`). Init/project/team management calls `karma` CLI via subprocess. **All proxy calls must use `asyncio.run_in_executor`** since `SyncthingClient` uses synchronous `requests`. + +### Setup & Configuration + +| Method | Endpoint | Description | +|--------|----------|-------------| +| GET | `/sync/detect` | Check if Syncthing/IPFS installed, return version | +| POST | `/sync/init` | Run `karma init --user-id --backend syncthing` via subprocess, return device ID | +| PUT | `/sync/config` | Update network mode settings **(post-MVP — not implemented in MVP)** | + +### Device Management + +| Method | Endpoint | Description | +|--------|----------|-------------| +| GET | `/sync/devices` | All devices with connection + transfer stats | +| GET | `/sync/devices/{id}` | Single device detail | +| POST | `/sync/devices` | Pair a new device | +| DELETE | `/sync/devices/{id}` | Remove a device | + +### Project Sync + +| Method | Endpoint | Description | +|--------|----------|-------------| +| GET | `/sync/projects` | All projects with sync state | +| GET | `/sync/projects/{name}/files` | Per-file sync status | +| POST | `/sync/projects/{name}/enable` | Enable sync for a project | +| POST | `/sync/projects/{name}/disable` | Disable sync for a project | +| POST | `/sync/projects/{name}/sync-now` | Trigger manual sync | + +### Activity & Monitoring + +| Method | Endpoint | Description | +|--------|----------|-------------| +| GET | `/sync/activity` | Event log (paginated) | +| GET | `/sync/activity/stream` | SSE event stream | +| GET | `/sync/bandwidth` | Bandwidth time series | +| POST | `/sync/watcher/restart` | Restart the file watcher | +| POST | `/sync/conflicts/{id}/resolve` | Resolve a conflict | + +## Frontend Implementation + +### New Files + +``` +frontend/src/routes/sync/ + +page.svelte # Main sync page with tabs + +page.server.ts # Load sync status + detect state + +frontend/src/lib/components/sync/ + SetupTab.svelte # Backend selection, install, init, pair + DevicesTab.svelte # Device monitoring cards + ProjectsTab.svelte # Project sync toggles + detail + ActivityTab.svelte # Bandwidth chart + event log + DeviceCard.svelte # Per-device expandable card + ProjectRow.svelte # Per-project collapsible row + SyncProgress.svelte # Reusable progress bar + ConflictPanel.svelte # Conflict resolution UI + BandwidthChart.svelte # Chart.js sparkline +``` + +### Navigation Changes + +- Add "Sync" link in Header.svelte (desktop + mobile nav) +- Add skeleton for `/sync` in +layout.svelte + +### Component Patterns + +- **Tabs:** Use existing `bits-ui` Tabs from `$lib/components/ui/` — ``, ``, ``. The `icon` prop accepts Lucide components directly. +- **Progress bars:** `bg-[var(--bg-muted)]` track, `bg-[var(--success)]` fill, Tailwind width utility with CSS transitions +- **Status dots:** Follow `LiveSessionsSection.svelte` pattern — `` with pulse animation for active states +- **Status badges:** Use `` from `$lib/components/ui/Badge.svelte` +- **Expandable rows:** Svelte 5 `$state` for open/closed, CSS transitions +- **Polling:** Single `setInterval` at page level (10s), data distributed to tabs via props. Avoid multiple independent polling intervals. +- **Server load:** Use `safeFetch()` from `$lib/utils/api-fetch.ts` in `+page.server.ts` +- **Client mutations:** Use raw `fetch()` for action buttons (init, pair, enable sync) — matching the settings page pattern +- **Error banners:** `bg-[var(--error-subtle)] border border-[var(--error)]/20 text-[var(--error)]` with retry button — matching `sessions/+page.svelte:1367` pattern +- **Charts:** Resolve colors via `getThemeColors()` from `$lib/components/charts/chartConfig.ts` inside `onMount` — never hardcode hex values + +### Error Recovery + +Every action that can fail must have a recovery path: + +| Action | Failure Mode | Recovery | +|--------|-------------|----------| +| Check Again (detect) | Syncthing not running | Show install instructions, re-poll button | +| Initialize | CLI error / timeout | Show error with troubleshooting tips + retry button | +| Pair Device | Invalid device ID / Syncthing down | Inline error below form, clear on retry | +| Enable Sync | Project path not found | Show error with path, suggest `karma project add --path` | +| Sync Now (package) | Packager failure | Show error, suggest checking outbox directory | + +Error pattern: contextual inline banner with `var(--error-subtle)` background, specific cause text, and a "Try Again" action. Never just show a terse error string. + +### Accessibility + +- All status dots must have adjacent text labels (color alone is insufficient) +- Toggle buttons (project sync dots) must have `aria-label` describing the action: `"Disable sync for {project}"` / `"Enable sync for {project}"` +- Device remove buttons: `aria-label="Remove device {name}"` +- Tab navigation is handled by `bits-ui` Tabs (ARIA tab pattern built-in) +- Copy buttons: announce success via `aria-live="polite"` region +- Respect `prefers-reduced-motion`: disable pulse animations on status dots + +### Input Validation + +Path parameters (`device_id`, `project name`) must be validated before subprocess execution: +- Project names: `^[a-zA-Z0-9_\-]+$`, max 128 chars (matches `_SAFE_NAME` in CLI) +- Device IDs: `^[A-Z0-9\-]+$`, max 72 chars (Syncthing format) +- Follow `api/routers/commands.py` regex allowlist pattern + +## Future Enhancements (Post-MVP) + +- IPFS backend support (un-grey the IPFS card) +- "Invite via link" — generate a pairing URL with device ID embedded +- Sync scheduling — only sync during certain hours +- Bandwidth limits — throttle Syncthing transfers +- Desktop notifications — alert when sync completes or conflicts detected +- Session-level sync status badges in project views diff --git a/docs/plans/2026-03-05-syncthing-worktree-sync-plan.md b/docs/plans/2026-03-05-syncthing-worktree-sync-plan.md new file mode 100644 index 00000000..5e4824ee --- /dev/null +++ b/docs/plans/2026-03-05-syncthing-worktree-sync-plan.md @@ -0,0 +1,1131 @@ +# Syncthing Worktree-Aware Session Sync — Implementation Plan + +> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. + +**Goal:** Make the CLI packager and watcher discover and sync worktree sessions alongside main project sessions, so remote teammates see the complete picture of all work happening on a project. + +**Architecture:** Extract worktree discovery logic from the API's `desktop_sessions.py` into a shared helper in the CLI. The `SessionPackager` accepts multiple source directories. The watcher monitors worktree dirs dynamically. `SessionEntry` gains optional metadata fields (`worktree_name`, `git_branch`) so receivers can understand session context. Incremental packaging avoids redundant copies. + +**Tech Stack:** Python 3.9+, click (CLI), watchdog (filesystem events), Pydantic 2.x (models), pytest (testing) + +**Prior plan:** `docs/plans/2026-03-03-syncthing-session-sync-plan.md` (implements the base Syncthing sync — this plan extends it) + +**Key insight:** The API indexer (`api/db/indexer.py:86-158`) already solves worktree→real project mapping via `api/services/desktop_sessions.py`. The CLI needs a lightweight version of the same logic, without importing the API. + +--- + +## Task 1: Add worktree discovery to the CLI + +The CLI needs `is_worktree_project()` and `find_worktree_dirs()` without depending on the API module. This is a pure-function utility — no API imports, no settings object. + +**Files:** +- Create: `cli/karma/worktree_discovery.py` +- Create: `cli/tests/test_worktree_discovery.py` + +**Step 1: Write failing tests** + +```python +# cli/tests/test_worktree_discovery.py +"""Tests for worktree discovery.""" + +from pathlib import Path +import pytest +from karma.worktree_discovery import is_worktree_dir, find_worktree_dirs + + +class TestIsWorktreeDir: + def test_cli_worktree_pattern(self): + assert is_worktree_dir( + "-Users-jay-GitHub-karma--claude-worktrees-feature-x" + ) is True + + def test_superpowers_worktree_pattern(self): + assert is_worktree_dir( + "-Users-jay-GitHub-karma--worktrees-feature-y" + ) is True + + def test_desktop_worktree_pattern(self): + assert is_worktree_dir( + "-Users-jay--claude-worktrees-karma-focused-jepsen" + ) is True + + def test_normal_project_not_worktree(self): + assert is_worktree_dir( + "-Users-jay-Documents-GitHub-claude-karma" + ) is False + + def test_empty_string(self): + assert is_worktree_dir("") is False + + +class TestFindWorktreeDirs: + def test_finds_cli_worktrees(self, tmp_path): + """CLI worktrees: {project}/.claude/worktrees/{name}""" + projects_dir = tmp_path / "projects" + main = projects_dir / "-Users-jay-GitHub-karma" + wt1 = projects_dir / "-Users-jay-GitHub-karma--claude-worktrees-feat-a" + wt2 = projects_dir / "-Users-jay-GitHub-karma--claude-worktrees-feat-b" + for d in (main, wt1, wt2): + d.mkdir(parents=True) + (d / "session.jsonl").write_text('{"type":"user"}\n') + result = find_worktree_dirs( + "-Users-jay-GitHub-karma", projects_dir + ) + assert len(result) == 2 + assert wt1 in result + assert wt2 in result + + def test_finds_superpowers_worktrees(self, tmp_path): + projects_dir = tmp_path / "projects" + main = projects_dir / "-Users-jay-GitHub-karma" + wt = projects_dir / "-Users-jay-GitHub-karma--worktrees-fix-bug" + for d in (main, wt): + d.mkdir(parents=True) + result = find_worktree_dirs( + "-Users-jay-GitHub-karma", projects_dir + ) + assert wt in result + + def test_ignores_unrelated_projects(self, tmp_path): + projects_dir = tmp_path / "projects" + main = projects_dir / "-Users-jay-GitHub-karma" + unrelated = projects_dir / "-Users-jay-GitHub-other--claude-worktrees-x" + for d in (main, unrelated): + d.mkdir(parents=True) + result = find_worktree_dirs( + "-Users-jay-GitHub-karma", projects_dir + ) + assert len(result) == 0 + + def test_returns_empty_when_no_worktrees(self, tmp_path): + projects_dir = tmp_path / "projects" + main = projects_dir / "-Users-jay-GitHub-karma" + main.mkdir(parents=True) + result = find_worktree_dirs( + "-Users-jay-GitHub-karma", projects_dir + ) + assert result == [] + + def test_returns_empty_when_projects_dir_missing(self, tmp_path): + result = find_worktree_dirs( + "-Users-jay-GitHub-karma", tmp_path / "nonexistent" + ) + assert result == [] +``` + +**Step 2: Run tests to verify they fail** + +Run: `cd cli && pytest tests/test_worktree_discovery.py -v` +Expected: FAIL — `ModuleNotFoundError: No module named 'karma.worktree_discovery'` + +**Step 3: Implement worktree discovery** + +```python +# cli/karma/worktree_discovery.py +"""Worktree directory discovery for CLI packager. + +Detects worktree project directories that belong to a given main project. +This is a lightweight port of the logic in api/services/desktop_sessions.py, +without any API dependencies. + +Worktree patterns (all encoded by Claude Code): + 1. CLI worktrees: {project}/.claude/worktrees/{name} + Encoded: {project_encoded}--claude-worktrees-{name} + 2. Superpowers: {project}/.worktrees/{name} + Encoded: {project_encoded}--worktrees-{name} + 3. Desktop worktrees: ~/.claude-worktrees/{project}/{name} + Encoded: -Users-{user}--claude-worktrees-{project}-{name} + (These DON'T share a prefix with the main project — handled separately) +""" + +from pathlib import Path + +# Markers in encoded names that separate project prefix from worktree suffix. +_WORKTREE_MARKERS = [ + "--claude-worktrees-", + "-.claude-worktrees-", + "--worktrees-", + "-.worktrees-", +] + + +def is_worktree_dir(encoded_name: str) -> bool: + """Check if an encoded project directory name is a worktree.""" + if not encoded_name: + return False + if "-claude-worktrees-" in encoded_name: + return True + if "--worktrees-" in encoded_name or "-.worktrees-" in encoded_name: + return True + return False + + +def _get_worktree_prefix(encoded_name: str) -> str | None: + """Extract the main project prefix from a worktree encoded name. + + Returns the prefix before the worktree marker, or None if not a + prefix-style worktree (e.g., Desktop worktrees don't share a prefix). + """ + for marker in _WORKTREE_MARKERS: + idx = encoded_name.find(marker) + if idx > 0: + prefix = encoded_name[:idx] + if prefix.startswith("-") and len(prefix) > 1: + return prefix + return None + + +def find_worktree_dirs( + main_encoded_name: str, projects_dir: Path +) -> list[Path]: + """Find all worktree directories that belong to a main project. + + Scans projects_dir for directories whose encoded name starts with + the main project's encoded name followed by a worktree marker. + + Args: + main_encoded_name: The main project's encoded directory name + (e.g., "-Users-jay-GitHub-karma"). + projects_dir: Path to ~/.claude/projects/ + + Returns: + List of Path objects for matching worktree directories. + """ + if not projects_dir.is_dir(): + return [] + + matches = [] + for entry in projects_dir.iterdir(): + if not entry.is_dir(): + continue + if entry.name == main_encoded_name: + continue # skip the main project itself + if not is_worktree_dir(entry.name): + continue + # Check if this worktree's prefix matches the main project + prefix = _get_worktree_prefix(entry.name) + if prefix == main_encoded_name: + matches.append(entry) + + return sorted(matches) +``` + +**Step 4: Run tests to verify they pass** + +Run: `cd cli && pytest tests/test_worktree_discovery.py -v` +Expected: All 9 tests PASS + +**Step 5: Commit** + +```bash +git add cli/karma/worktree_discovery.py cli/tests/test_worktree_discovery.py +git commit -m "feat(cli): add worktree directory discovery module + +Lightweight port of API's worktree detection for CLI packager. +Finds CLI, superpowers, and Desktop worktree dirs by encoded name prefix." +``` + +--- + +## Task 2: Extend SessionEntry with worktree metadata + +Add `worktree_name` and `git_branch` to `SessionEntry` so receivers know which worktree/branch a session came from. + +**Files:** +- Modify: `cli/karma/manifest.py:8-14` (SessionEntry class) +- Modify: `cli/tests/test_packager.py` (add tests) + +**Step 1: Write failing tests** + +Add to `cli/tests/test_packager.py`: + +```python +class TestSessionEntryMetadata: + def test_session_entry_default_no_worktree(self): + from karma.manifest import SessionEntry + entry = SessionEntry(uuid="abc", mtime="2026-01-01T00:00:00Z", size_bytes=100) + assert entry.worktree_name is None + assert entry.git_branch is None + + def test_session_entry_with_worktree(self): + from karma.manifest import SessionEntry + entry = SessionEntry( + uuid="abc", + mtime="2026-01-01T00:00:00Z", + size_bytes=100, + worktree_name="syncthing-sync-design", + git_branch="worktree-syncthing-sync-design", + ) + assert entry.worktree_name == "syncthing-sync-design" + assert entry.git_branch == "worktree-syncthing-sync-design" + + def test_session_entry_worktree_in_dump(self): + from karma.manifest import SessionEntry + entry = SessionEntry( + uuid="abc", + mtime="2026-01-01T00:00:00Z", + size_bytes=100, + worktree_name="feat-x", + ) + data = entry.model_dump() + assert data["worktree_name"] == "feat-x" + assert data["git_branch"] is None +``` + +**Step 2: Run tests to verify they fail** + +Run: `cd cli && pytest tests/test_packager.py::TestSessionEntryMetadata -v` +Expected: FAIL — `TypeError: unexpected keyword argument 'worktree_name'` + +**Step 3: Add fields to SessionEntry** + +In `cli/karma/manifest.py`, modify the `SessionEntry` class: + +```python +class SessionEntry(BaseModel): + """Metadata for a single synced session.""" + + model_config = ConfigDict(frozen=True) + + uuid: str + mtime: str = Field(..., description="ISO timestamp of session file modification time") + size_bytes: int + worktree_name: Optional[str] = Field(default=None, description="Worktree name if session is from a worktree") + git_branch: Optional[str] = Field(default=None, description="Git branch the session was on") +``` + +Add `Optional` import at the top of the file if not already present: + +```python +from typing import Optional +``` + +**Step 4: Run tests to verify they pass** + +Run: `cd cli && pytest tests/test_packager.py -v` +Expected: All tests PASS (existing + new) + +**Step 5: Commit** + +```bash +git add cli/karma/manifest.py cli/tests/test_packager.py +git commit -m "feat(cli): add worktree_name and git_branch to SessionEntry + +Allows manifest to carry per-session metadata about which worktree +and branch a session came from, for richer remote viewing." +``` + +--- + +## Task 3: Make SessionPackager accept multiple source directories + +The packager currently only globs one `project_dir`. Extend it to accept additional worktree dirs and tag sessions with their origin. + +**Files:** +- Modify: `cli/karma/packager.py` +- Modify: `cli/tests/test_packager.py` + +**Step 1: Write failing tests** + +Add to `cli/tests/test_packager.py`: + +```python +@pytest.fixture +def mock_project_with_worktree(tmp_path: Path) -> dict: + """Create a main project dir + one worktree dir.""" + projects_dir = tmp_path / ".claude" / "projects" + + # Main project + main_dir = projects_dir / "-Users-jay-GitHub-karma" + main_dir.mkdir(parents=True) + (main_dir / "session-main-001.jsonl").write_text( + '{"type":"user","message":{"role":"user","content":"hello"}}\n' + ) + + # Worktree + wt_dir = projects_dir / "-Users-jay-GitHub-karma--claude-worktrees-feat-a" + wt_dir.mkdir(parents=True) + (wt_dir / "session-wt-001.jsonl").write_text( + '{"type":"user","message":{"role":"user","content":"worktree work"}}\n' + ) + # Worktree session with subagent + (wt_dir / "session-wt-002.jsonl").write_text( + '{"type":"user","message":{"role":"user","content":"more work"}}\n' + ) + sub_dir = wt_dir / "session-wt-002" / "subagents" + sub_dir.mkdir(parents=True) + (sub_dir / "agent-x.jsonl").write_text('{"type":"agent"}\n') + + return { + "main_dir": main_dir, + "wt_dir": wt_dir, + "projects_dir": projects_dir, + } + + +class TestPackagerWithWorktrees: + def test_discover_includes_worktree_sessions(self, mock_project_with_worktree): + dirs = mock_project_with_worktree + packager = SessionPackager( + project_dir=dirs["main_dir"], + user_id="jay", + machine_id="mac", + extra_dirs=[dirs["wt_dir"]], + ) + sessions = packager.discover_sessions() + uuids = {s.uuid for s in sessions} + assert "session-main-001" in uuids + assert "session-wt-001" in uuids + assert "session-wt-002" in uuids + assert len(sessions) == 3 + + def test_worktree_sessions_tagged_with_worktree_name(self, mock_project_with_worktree): + dirs = mock_project_with_worktree + packager = SessionPackager( + project_dir=dirs["main_dir"], + user_id="jay", + machine_id="mac", + extra_dirs=[dirs["wt_dir"]], + ) + sessions = packager.discover_sessions() + wt_sessions = [s for s in sessions if s.worktree_name is not None] + assert len(wt_sessions) == 2 + assert all(s.worktree_name == "feat-a" for s in wt_sessions) + + def test_package_copies_worktree_subagents(self, mock_project_with_worktree, tmp_path): + dirs = mock_project_with_worktree + staging = tmp_path / "staging" + packager = SessionPackager( + project_dir=dirs["main_dir"], + user_id="jay", + machine_id="mac", + extra_dirs=[dirs["wt_dir"]], + ) + packager.package(staging_dir=staging) + assert (staging / "sessions" / "session-wt-002" / "subagents" / "agent-x.jsonl").exists() + + def test_manifest_counts_all_sessions(self, mock_project_with_worktree, tmp_path): + dirs = mock_project_with_worktree + staging = tmp_path / "staging" + packager = SessionPackager( + project_dir=dirs["main_dir"], + user_id="jay", + machine_id="mac", + extra_dirs=[dirs["wt_dir"]], + ) + manifest = packager.package(staging_dir=staging) + assert manifest.session_count == 3 + + def test_no_extra_dirs_works_like_before(self, mock_claude_project, tmp_path): + """Backward compat: no extra_dirs = original behavior.""" + staging = tmp_path / "staging" + packager = SessionPackager( + project_dir=mock_claude_project, + user_id="alice", + machine_id="test-mac", + ) + manifest = packager.package(staging_dir=staging) + assert manifest.session_count == 2 +``` + +**Step 2: Run tests to verify they fail** + +Run: `cd cli && pytest tests/test_packager.py::TestPackagerWithWorktrees -v` +Expected: FAIL — `TypeError: unexpected keyword argument 'extra_dirs'` + +**Step 3: Modify SessionPackager** + +Replace `cli/karma/packager.py` with: + +```python +"""Session packager -- collects project sessions into a staging directory.""" + +import json +import re +import shutil +from datetime import datetime, timezone +from pathlib import Path +from typing import Optional + +from karma.manifest import SessionEntry, SyncManifest + + +def _extract_worktree_name(dir_name: str, main_dir_name: str) -> Optional[str]: + """Extract human-readable worktree name from encoded dir name. + + Given main="-Users-jay-GitHub-karma" and + dir="-Users-jay-GitHub-karma--claude-worktrees-feat-a", + returns "feat-a". + """ + markers = ["--claude-worktrees-", "-.claude-worktrees-", "--worktrees-", "-.worktrees-"] + for marker in markers: + idx = dir_name.find(marker) + if idx > 0: + return dir_name[idx + len(marker):] + return None + + +class SessionPackager: + """Discovers and packages Claude Code sessions for a project.""" + + def __init__( + self, + project_dir: Path, + user_id: str, + machine_id: str, + project_path: str = "", + last_sync_cid: Optional[str] = None, + extra_dirs: Optional[list[Path]] = None, + ): + self.project_dir = Path(project_dir) + self.user_id = user_id + self.machine_id = machine_id + self.project_path = project_path or str(self.project_dir) + self.last_sync_cid = last_sync_cid + self.extra_dirs = [Path(d) for d in (extra_dirs or [])] + + def _discover_from_dir( + self, directory: Path, worktree_name: Optional[str] = None + ) -> list[SessionEntry]: + """Find session JSONL files in a single directory.""" + entries = [] + for jsonl_path in sorted(directory.glob("*.jsonl")): + if jsonl_path.name.startswith("agent-"): + continue + stat = jsonl_path.stat() + if stat.st_size == 0: + continue + entries.append( + SessionEntry( + uuid=jsonl_path.stem, + mtime=datetime.fromtimestamp(stat.st_mtime, tz=timezone.utc).isoformat(), + size_bytes=stat.st_size, + worktree_name=worktree_name, + ) + ) + return entries + + def discover_sessions(self) -> list[SessionEntry]: + """Find all session JSONL files in the project and worktree directories.""" + entries = self._discover_from_dir(self.project_dir) + + for extra_dir in self.extra_dirs: + if not extra_dir.is_dir(): + continue + wt_name = _extract_worktree_name(extra_dir.name, self.project_dir.name) + entries.extend(self._discover_from_dir(extra_dir, worktree_name=wt_name)) + + return entries + + def _source_dir_for_session(self, entry: SessionEntry) -> Path: + """Find the directory containing the session's JSONL file.""" + if (self.project_dir / f"{entry.uuid}.jsonl").exists(): + return self.project_dir + for extra_dir in self.extra_dirs: + if (extra_dir / f"{entry.uuid}.jsonl").exists(): + return extra_dir + return self.project_dir # fallback + + def package(self, staging_dir: Path) -> SyncManifest: + """Copy session files into staging directory and create manifest.""" + sessions = self.discover_sessions() + + sessions_dir = staging_dir / "sessions" + sessions_dir.mkdir(parents=True, exist_ok=True) + + for entry in sessions: + source_dir = self._source_dir_for_session(entry) + + # Copy JSONL file + src_jsonl = source_dir / f"{entry.uuid}.jsonl" + shutil.copy2(src_jsonl, sessions_dir / src_jsonl.name) + + # Copy associated directories (subagents, tool-results) + assoc_dir = source_dir / entry.uuid + if assoc_dir.is_dir(): + shutil.copytree( + assoc_dir, + sessions_dir / entry.uuid, + dirs_exist_ok=True, + ) + + # Copy todos if they exist (from main project dir's parent) + todos_base = self.project_dir.parent.parent / "todos" + if todos_base.is_dir(): + todos_staging = staging_dir / "todos" + for session_entry in sessions: + for todo_file in todos_base.glob(f"{session_entry.uuid}-*.json"): + todos_staging.mkdir(exist_ok=True) + shutil.copy2(todo_file, todos_staging / todo_file.name) + + # Build manifest + manifest = SyncManifest( + user_id=self.user_id, + machine_id=self.machine_id, + project_path=self.project_path, + project_encoded=self.project_dir.name, + session_count=len(sessions), + sessions=sessions, + previous_cid=self.last_sync_cid, + ) + + manifest_path = staging_dir / "manifest.json" + manifest_path.write_text(json.dumps(manifest.model_dump(), indent=2) + "\n") + + return manifest +``` + +**Step 4: Run ALL packager tests** + +Run: `cd cli && pytest tests/test_packager.py -v` +Expected: All tests PASS (existing + new) + +**Step 5: Commit** + +```bash +git add cli/karma/packager.py cli/tests/test_packager.py +git commit -m "feat(cli): packager discovers sessions from worktree dirs + +SessionPackager accepts extra_dirs for worktree directories. +Sessions from worktrees are tagged with worktree_name in the manifest." +``` + +--- + +## Task 4: Wire worktree discovery into `karma watch` + +The `watch` command needs to auto-discover worktree dirs for each project and pass them to the packager. New worktree dirs appearing mid-watch should be picked up. + +**Files:** +- Modify: `cli/karma/main.py` (watch command, ~lines 465-547) +- Modify: `cli/tests/test_cli_syncthing.py` (add watch worktree test) + +**Step 1: Write failing test** + +Add to `cli/tests/test_cli_syncthing.py`: + +```python +from unittest.mock import patch, MagicMock +from pathlib import Path + +def test_watch_discovers_worktree_dirs(tmp_path): + """karma watch should find worktree dirs and pass them to packager.""" + from karma.worktree_discovery import find_worktree_dirs + + projects_dir = tmp_path / ".claude" / "projects" + main = projects_dir / "-Users-jay-GitHub-karma" + wt = projects_dir / "-Users-jay-GitHub-karma--claude-worktrees-feat-a" + main.mkdir(parents=True) + wt.mkdir(parents=True) + (main / "s1.jsonl").write_text('{"type":"user"}\n') + (wt / "s2.jsonl").write_text('{"type":"user"}\n') + + dirs = find_worktree_dirs("-Users-jay-GitHub-karma", projects_dir) + assert len(dirs) == 1 + assert dirs[0] == wt +``` + +**Step 2: Run test to verify it passes** (this tests the discovery itself, which we built in Task 1) + +Run: `cd cli && pytest tests/test_cli_syncthing.py::test_watch_discovers_worktree_dirs -v` +Expected: PASS + +**Step 3: Modify the watch command in `cli/karma/main.py`** + +Replace the watch command's inner loop (lines ~506-536) with worktree-aware logic: + +```python +# In the watch command, replace the watcher setup loop with: + + watchers = [] + for proj_name, proj in team_cfg.projects.items(): + claude_dir = Path.home() / ".claude" / "projects" / proj.encoded_name + if not claude_dir.is_dir(): + click.echo(f" Skipping '{proj_name}': Claude dir not found ({claude_dir})") + continue + + # Discover worktree dirs for this project + from karma.worktree_discovery import find_worktree_dirs + projects_dir = Path.home() / ".claude" / "projects" + wt_dirs = find_worktree_dirs(proj.encoded_name, projects_dir) + if wt_dirs: + click.echo(f" Found {len(wt_dirs)} worktree dir(s) for '{proj_name}'") + + outbox = KARMA_BASE / "remote-sessions" / config.user_id / proj.encoded_name + + def make_package_fn(cd=claude_dir, ob=outbox, pn=proj_name, wd=wt_dirs): + def package(): + # Re-discover worktrees each time (new ones may appear) + current_wt_dirs = find_worktree_dirs(proj.encoded_name, projects_dir) + packager = SessionPackager( + project_dir=cd, + user_id=config.user_id, + machine_id=config.machine_id, + project_path=proj.path, + extra_dirs=current_wt_dirs, + ) + ob.mkdir(parents=True, exist_ok=True) + packager.package(staging_dir=ob) + click.echo(f" Packaged '{pn}' -> {ob} ({len(current_wt_dirs)} worktrees)") + return package + + package_fn = make_package_fn() + + # Watch main project dir + watcher = SessionWatcher( + watch_dir=claude_dir, + package_fn=package_fn, + ) + watcher.start() + watchers.append(watcher) + click.echo(f" Watching: {proj_name} ({claude_dir})") + + # Also watch each worktree dir + for wt_dir in wt_dirs: + wt_watcher = SessionWatcher( + watch_dir=wt_dir, + package_fn=package_fn, + ) + wt_watcher.start() + watchers.append(wt_watcher) + wt_name = wt_dir.name.split("--claude-worktrees-")[-1] if "--claude-worktrees-" in wt_dir.name else wt_dir.name + click.echo(f" Watching worktree: {wt_name} ({wt_dir})") +``` + +**Step 4: Run existing CLI tests to verify no regressions** + +Run: `cd cli && pytest tests/test_cli_syncthing.py -v` +Expected: All PASS + +**Step 5: Commit** + +```bash +git add cli/karma/main.py cli/tests/test_cli_syncthing.py +git commit -m "feat(cli): karma watch discovers and monitors worktree dirs + +Watch command auto-discovers worktree directories for each project +and starts watchers for them. Re-discovers on each package cycle +so new worktrees are picked up dynamically." +``` + +--- + +## Task 5: Add `karma status` sync gap visibility + +Show local vs packaged vs worktree session counts so users can see if they're out of sync. + +**Files:** +- Modify: `cli/karma/main.py` (status command, ~lines 550-580) +- Modify: `cli/tests/test_cli_syncthing.py` + +**Step 1: Write failing test** + +```python +# Add to cli/tests/test_cli_syncthing.py +from click.testing import CliRunner +from karma.main import cli + + +def test_status_shows_worktree_counts(tmp_path, monkeypatch): + """karma status should show worktree session counts.""" + # Create config + config_data = { + "user_id": "jay", + "machine_id": "test-mac", + "projects": {}, + "team": {}, + "ipfs_api": "http://127.0.0.1:5001", + "teams": { + "my-team": { + "backend": "syncthing", + "projects": { + "karma": { + "path": "/Users/jay/karma", + "encoded_name": "-Users-jay-karma", + "last_sync_cid": None, + "last_sync_at": None, + } + }, + "ipfs_members": {}, + "syncthing_members": {"bob": {"syncthing_device_id": "TESTID"}}, + "owner_device_id": None, + "owner_ipns_key": None, + } + }, + "syncthing": {"api_url": "http://127.0.0.1:8384", "api_key": None, "device_id": None}, + } + + import json + config_path = tmp_path / "sync-config.json" + config_path.write_text(json.dumps(config_data)) + monkeypatch.setattr("karma.config.SYNC_CONFIG_PATH", config_path) + + # Create fake project dir with sessions + projects_dir = tmp_path / ".claude" / "projects" + main_dir = projects_dir / "-Users-jay-karma" + main_dir.mkdir(parents=True) + (main_dir / "s1.jsonl").write_text('{"type":"user"}\n') + (main_dir / "s2.jsonl").write_text('{"type":"user"}\n') + + # Create worktree dir + wt_dir = projects_dir / "-Users-jay-karma--claude-worktrees-feat-x" + wt_dir.mkdir(parents=True) + (wt_dir / "s3.jsonl").write_text('{"type":"user"}\n') + + monkeypatch.setattr("karma.main.Path.home", lambda: tmp_path) + + runner = CliRunner() + result = runner.invoke(cli, ["status"]) + assert result.exit_code == 0 + # Should mention worktree count + assert "worktree" in result.output.lower() or "2" in result.output +``` + +**Step 2: Run to verify it fails** + +Run: `cd cli && pytest tests/test_cli_syncthing.py::test_status_shows_worktree_counts -v` +Expected: FAIL (status command doesn't show worktree info yet) + +**Step 3: Enhance the status command** + +In `cli/karma/main.py`, replace the `status` command body with: + +```python +@cli.command() +def status(): + """Show sync status for all teams.""" + from karma.worktree_discovery import find_worktree_dirs + + config = require_config() + + click.echo(f"User: {config.user_id} ({config.machine_id})") + + if not config.teams and not config.projects: + click.echo("No teams or projects configured.") + return + + # Legacy flat projects + if config.projects: + click.echo(f"\nLegacy projects (IPFS):") + for name, proj in config.projects.items(): + sync_info = f"last sync: {proj.last_sync_at}" if proj.last_sync_at else "never synced" + click.echo(f" {name}: {proj.path} ({sync_info})") + + projects_dir = Path.home() / ".claude" / "projects" + + # Per-team + for team_name, team_cfg in config.teams.items(): + click.echo(f"\n{team_name} ({team_cfg.backend}):") + if not team_cfg.projects: + click.echo(" No projects") + for proj_name, proj in team_cfg.projects.items(): + last = proj.last_sync_at or "never" + claude_dir = projects_dir / proj.encoded_name + + # Count local sessions + local_count = 0 + if claude_dir.is_dir(): + local_count = sum( + 1 for f in claude_dir.glob("*.jsonl") + if not f.name.startswith("agent-") and f.stat().st_size > 0 + ) + + # Count worktree sessions + wt_dirs = find_worktree_dirs(proj.encoded_name, projects_dir) + wt_count = 0 + for wd in wt_dirs: + wt_count += sum( + 1 for f in wd.glob("*.jsonl") + if not f.name.startswith("agent-") and f.stat().st_size > 0 + ) + + # Count packaged sessions + outbox = KARMA_BASE / "remote-sessions" / config.user_id / proj.encoded_name / "sessions" + packaged_count = 0 + if outbox.is_dir(): + packaged_count = sum(1 for f in outbox.glob("*.jsonl") if not f.name.startswith("agent-")) + + total_local = local_count + wt_count + gap = total_local - packaged_count + + click.echo(f" {proj_name}: {proj.path} (last: {last})") + click.echo(f" Local: {local_count} sessions + {wt_count} worktree ({len(wt_dirs)} dirs) = {total_local}") + click.echo(f" Packaged: {packaged_count} {'(up to date)' if gap <= 0 else f'({gap} behind)'}") + + if team_cfg.members: + click.echo(f" Members: {', '.join(team_cfg.members.keys())}") +``` + +**Step 4: Run tests** + +Run: `cd cli && pytest tests/test_cli_syncthing.py -v` +Expected: All PASS + +**Step 5: Commit** + +```bash +git add cli/karma/main.py cli/tests/test_cli_syncthing.py +git commit -m "feat(cli): karma status shows worktree counts and sync gap + +Status command now shows local, worktree, and packaged session counts +per project, making it easy to see if the outbox is stale." +``` + +--- + +## Task 6: Incremental packaging (avoid full re-copy) + +Currently `package()` copies all sessions every time. Add mtime tracking to skip unchanged files. + +**Files:** +- Modify: `cli/karma/packager.py` +- Modify: `cli/tests/test_packager.py` + +**Step 1: Write failing test** + +```python +# Add to cli/tests/test_packager.py + +class TestIncrementalPackaging: + def test_skip_unchanged_sessions(self, mock_claude_project, tmp_path): + """Second package should skip files that haven't changed.""" + staging = tmp_path / "staging" + packager = SessionPackager( + project_dir=mock_claude_project, + user_id="alice", + machine_id="test-mac", + ) + + # First package + manifest1 = packager.package(staging_dir=staging) + assert manifest1.session_count == 2 + + # Record mtime of a copied file + copied = staging / "sessions" / "session-uuid-001.jsonl" + mtime_after_first = copied.stat().st_mtime + + import time + time.sleep(0.05) # ensure mtime difference is detectable + + # Second package (no source changes) + manifest2 = packager.package(staging_dir=staging) + assert manifest2.session_count == 2 + + # File should NOT have been re-copied (mtime unchanged) + mtime_after_second = copied.stat().st_mtime + assert mtime_after_first == mtime_after_second + + def test_repackage_modified_session(self, mock_claude_project, tmp_path): + """Modified source file should be re-copied.""" + staging = tmp_path / "staging" + packager = SessionPackager( + project_dir=mock_claude_project, + user_id="alice", + machine_id="test-mac", + ) + + packager.package(staging_dir=staging) + copied = staging / "sessions" / "session-uuid-001.jsonl" + mtime_before = copied.stat().st_mtime + + import time + time.sleep(0.05) + + # Modify source + src = mock_claude_project / "session-uuid-001.jsonl" + src.write_text('{"type":"user","message":{"role":"user","content":"updated"}}\n') + + packager.package(staging_dir=staging) + mtime_after = copied.stat().st_mtime + assert mtime_after > mtime_before +``` + +**Step 2: Run to verify they fail** + +Run: `cd cli && pytest tests/test_packager.py::TestIncrementalPackaging -v` +Expected: FAIL (first test fails because files are always re-copied) + +**Step 3: Add incremental logic to `package()`** + +In `cli/karma/packager.py`, modify the `package()` method's session copy loop: + +```python + def package(self, staging_dir: Path) -> SyncManifest: + """Copy session files into staging directory and create manifest.""" + sessions = self.discover_sessions() + + sessions_dir = staging_dir / "sessions" + sessions_dir.mkdir(parents=True, exist_ok=True) + + for entry in sessions: + source_dir = self._source_dir_for_session(entry) + + # Copy JSONL file (skip if unchanged) + src_jsonl = source_dir / f"{entry.uuid}.jsonl" + dst_jsonl = sessions_dir / src_jsonl.name + if not dst_jsonl.exists() or src_jsonl.stat().st_mtime > dst_jsonl.stat().st_mtime: + shutil.copy2(src_jsonl, dst_jsonl) + + # Copy associated directories (subagents, tool-results) + assoc_dir = source_dir / entry.uuid + if assoc_dir.is_dir(): + dst_assoc = sessions_dir / entry.uuid + # For associated dirs, always sync (copytree with dirs_exist_ok handles updates) + shutil.copytree( + assoc_dir, + dst_assoc, + dirs_exist_ok=True, + ) + + # ... rest unchanged (todos, manifest) +``` + +**Step 4: Run all tests** + +Run: `cd cli && pytest tests/test_packager.py -v` +Expected: All PASS + +**Step 5: Commit** + +```bash +git add cli/karma/packager.py cli/tests/test_packager.py +git commit -m "feat(cli): incremental packaging skips unchanged JSONL files + +Compares source and destination mtimes before copying. Only re-copies +sessions whose source JSONL has been modified since last package." +``` + +--- + +## Task 7: Integration test — end-to-end worktree sync + +Verify the full pipeline: discover worktrees → package → manifest has worktree sessions. + +**Files:** +- Modify: `cli/tests/test_cli_syncthing.py` + +**Step 1: Write integration test** + +```python +# Add to cli/tests/test_cli_syncthing.py + +def test_full_worktree_package_pipeline(tmp_path): + """End-to-end: discover worktrees, package, verify manifest.""" + from karma.packager import SessionPackager + from karma.worktree_discovery import find_worktree_dirs + import json + + projects_dir = tmp_path / "projects" + + # Main project + main = projects_dir / "-Users-jay-karma" + main.mkdir(parents=True) + (main / "main-session.jsonl").write_text( + '{"type":"user","message":{"role":"user","content":"main work"}}\n' + ) + + # Worktree 1 + wt1 = projects_dir / "-Users-jay-karma--claude-worktrees-feat-auth" + wt1.mkdir(parents=True) + (wt1 / "auth-session.jsonl").write_text( + '{"type":"user","message":{"role":"user","content":"auth feature"}}\n' + ) + # With subagent + (wt1 / "auth-session" / "subagents").mkdir(parents=True) + (wt1 / "auth-session" / "subagents" / "agent-a1.jsonl").write_text('{"type":"agent"}\n') + + # Worktree 2 + wt2 = projects_dir / "-Users-jay-karma--claude-worktrees-fix-bug" + wt2.mkdir(parents=True) + (wt2 / "bug-session.jsonl").write_text( + '{"type":"user","message":{"role":"user","content":"bug fix"}}\n' + ) + + # Discover + wt_dirs = find_worktree_dirs("-Users-jay-karma", projects_dir) + assert len(wt_dirs) == 2 + + # Package + staging = tmp_path / "outbox" + packager = SessionPackager( + project_dir=main, + user_id="jay", + machine_id="mac", + extra_dirs=wt_dirs, + ) + manifest = packager.package(staging_dir=staging) + + # Verify manifest + assert manifest.session_count == 3 + uuids = {s.uuid for s in manifest.sessions} + assert uuids == {"main-session", "auth-session", "bug-session"} + + # Verify worktree tagging + by_uuid = {s.uuid: s for s in manifest.sessions} + assert by_uuid["main-session"].worktree_name is None + assert by_uuid["auth-session"].worktree_name == "feat-auth" + assert by_uuid["bug-session"].worktree_name == "fix-bug" + + # Verify files on disk + assert (staging / "sessions" / "auth-session.jsonl").exists() + assert (staging / "sessions" / "auth-session" / "subagents" / "agent-a1.jsonl").exists() + assert (staging / "sessions" / "bug-session.jsonl").exists() + + # Verify manifest JSON + manifest_json = json.loads((staging / "manifest.json").read_text()) + wt_entries = [s for s in manifest_json["sessions"] if s["worktree_name"]] + assert len(wt_entries) == 2 +``` + +**Step 2: Run test** + +Run: `cd cli && pytest tests/test_cli_syncthing.py::test_full_worktree_package_pipeline -v` +Expected: PASS (all prior tasks should make this work) + +**Step 3: Commit** + +```bash +git add cli/tests/test_cli_syncthing.py +git commit -m "test(cli): add end-to-end worktree sync integration test + +Verifies full pipeline: discovery -> packaging -> manifest with +worktree metadata and subagent file copying." +``` + +--- + +## Task 8: Run full test suite and verify + +**Step 1: Run all CLI tests** + +Run: `cd cli && pytest -v` +Expected: All tests PASS + +**Step 2: Run API tests to check no regressions** + +Run: `cd api && pytest tests/ -v --timeout=30` +Expected: All pass (no API changes in this plan) + +**Step 3: Final commit (if any fixups needed)** + +--- + +## Summary + +| Task | What | Files Changed | Tests | +|------|------|---------------|-------| +| 1 | Worktree discovery module | +`worktree_discovery.py`, +`test_worktree_discovery.py` | 9 | +| 2 | SessionEntry metadata fields | `manifest.py`, `test_packager.py` | 3 | +| 3 | Multi-dir SessionPackager | `packager.py`, `test_packager.py` | 5 | +| 4 | Wire into `karma watch` | `main.py`, `test_cli_syncthing.py` | 1 | +| 5 | Status with sync gap | `main.py`, `test_cli_syncthing.py` | 1 | +| 6 | Incremental packaging | `packager.py`, `test_packager.py` | 2 | +| 7 | Integration test | `test_cli_syncthing.py` | 1 | +| 8 | Full suite verification | — | all | + +**Not in scope (future work):** +- Hook-based packaging trigger (SessionEnd hook → `karma watch --once`) +- launchd/systemd for persistent `karma watch` +- Stable project identity (GitHub remote URL) +- Debug log syncing +- Desktop worktree discovery (requires Desktop metadata which the CLI doesn't have) diff --git a/docs/plans/2026-03-06-sync-page-redesign-plan.md b/docs/plans/2026-03-06-sync-page-redesign-plan.md new file mode 100644 index 00000000..178289b6 --- /dev/null +++ b/docs/plans/2026-03-06-sync-page-redesign-plan.md @@ -0,0 +1,1649 @@ +# Sync Page Redesign — Full Web UI Control + +> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. + +**Goal:** Replace the current partial sync page with a complete web UI that gives users full Syncthing control — from setup to team management to live sync — without ever touching the CLI. + +**Architecture:** Three layers of changes: (1) New API endpoints in `api/routers/sync_status.py` and a new `api/services/watcher_manager.py` for in-process watcher management, (2) Updated frontend with onboarding wizard + 4-tab dashboard (Overview, Members, Projects, Activity), (3) New TypeScript types and server load functions. The CLI `karma` commands remain untouched — the web UI calls the same `SyncConfig` / `SyncthingClient` code via new API endpoints. + +**Tech Stack:** Python/FastAPI (API), SvelteKit/Svelte 5 with runes (frontend), Pydantic (config models), existing `SyncthingClient` and `SessionWatcher`/`SessionPackager` from CLI. + +--- + +## Phase 1: API — Team CRUD & Member Management + +New endpoints that wrap the CLI's team/member/project logic into HTTP calls. + +### Task 1: Team CRUD endpoints + +**Files:** +- Modify: `api/routers/sync_status.py` (add new routes) +- Test: `api/tests/test_sync_team_crud.py` (create) + +**Step 1: Write failing tests** + +```python +# api/tests/test_sync_team_crud.py +"""Tests for sync team CRUD endpoints.""" +from __future__ import annotations +import json +from unittest.mock import patch, MagicMock +import pytest +from fastapi.testclient import TestClient + + +@pytest.fixture +def mock_sync_config(tmp_path, monkeypatch): + """Provide a fresh SyncConfig for each test.""" + import sys + cli_path = str(tmp_path / "cli") + # Ensure karma.config is importable with tmp paths + config_path = tmp_path / "sync-config.json" + monkeypatch.setenv("KARMA_SYNC_CONFIG_PATH", str(config_path)) + monkeypatch.setenv("KARMA_BASE", str(tmp_path)) + return config_path + + +class TestCreateTeam: + def test_create_team_success(self, mock_sync_config, tmp_path): + """POST /sync/teams creates a new team in sync-config.json.""" + # Pre-create a valid config + mock_sync_config.write_text(json.dumps({ + "user_id": "jayant", + "machine_id": "mac", + "teams": {}, + "syncthing": {"api_url": "http://127.0.0.1:8384"} + })) + + from main import app + client = TestClient(app) + + resp = client.post("/sync/teams", json={ + "name": "frontend-team", + "backend": "syncthing" + }) + assert resp.status_code == 200 + data = resp.json() + assert data["ok"] is True + assert data["name"] == "frontend-team" + + # Verify persisted + saved = json.loads(mock_sync_config.read_text()) + assert "frontend-team" in saved["teams"] + assert saved["teams"]["frontend-team"]["backend"] == "syncthing" + + def test_create_team_requires_init(self): + """POST /sync/teams returns 400 if not initialized.""" + from main import app + client = TestClient(app) + # With no config file, should fail + resp = client.post("/sync/teams", json={ + "name": "test", "backend": "syncthing" + }) + assert resp.status_code == 400 + + def test_create_team_invalid_name(self, mock_sync_config): + """POST /sync/teams rejects invalid team names.""" + mock_sync_config.write_text(json.dumps({ + "user_id": "jayant", "teams": {}, + "syncthing": {"api_url": "http://127.0.0.1:8384"} + })) + from main import app + client = TestClient(app) + resp = client.post("/sync/teams", json={ + "name": "../evil", "backend": "syncthing" + }) + assert resp.status_code == 400 + + +class TestDeleteTeam: + def test_delete_team_success(self, mock_sync_config): + mock_sync_config.write_text(json.dumps({ + "user_id": "jayant", + "teams": {"old-team": {"backend": "syncthing", "projects": {}}}, + "syncthing": {} + })) + from main import app + client = TestClient(app) + resp = client.delete("/sync/teams/old-team") + assert resp.status_code == 200 + + def test_delete_team_not_found(self, mock_sync_config): + mock_sync_config.write_text(json.dumps({ + "user_id": "jayant", "teams": {}, "syncthing": {} + })) + from main import app + client = TestClient(app) + resp = client.delete("/sync/teams/nope") + assert resp.status_code == 404 +``` + +**Step 2: Run tests to verify they fail** + +Run: `cd api && pytest tests/test_sync_team_crud.py -v` +Expected: FAIL — endpoints don't exist yet + +**Step 3: Implement team CRUD endpoints** + +Add to `api/routers/sync_status.py`: + +```python +class CreateTeamRequest(BaseModel): + name: str + backend: str = "syncthing" + + +@router.post("/teams") +async def sync_create_team(req: CreateTeamRequest) -> Any: + """Create a new sync group.""" + if not ALLOWED_PROJECT_NAME.match(req.name) or len(req.name) > 64: + raise HTTPException(400, "Invalid team name") + if req.backend not in ("syncthing", "ipfs"): + raise HTTPException(400, "Invalid backend") + + config, SyncConfig, _ = await run_sync(_load_sync_config) + if config is None: + raise HTTPException(400, "Not initialized. Set up sync first.") + + if req.name in config.model_dump().get("teams", {}): + raise HTTPException(409, f"Team '{req.name}' already exists") + + from karma.config import TeamConfig + team_cfg = TeamConfig(backend=req.backend, projects={}) + teams = dict(config.teams) + teams[req.name] = team_cfg + updated = config.model_copy(update={"teams": teams}) + await run_sync(updated.save) + + return {"ok": True, "name": req.name, "backend": req.backend} + + +@router.delete("/teams/{team_name}") +async def sync_delete_team(team_name: str) -> Any: + """Delete a sync group.""" + if not ALLOWED_PROJECT_NAME.match(team_name): + raise HTTPException(400, "Invalid team name") + + config, _, _ = await run_sync(_load_sync_config) + if config is None: + raise HTTPException(400, "Not initialized") + + data = config.model_dump() + if team_name not in data.get("teams", {}): + raise HTTPException(404, f"Team '{team_name}' not found") + + teams = dict(config.teams) + del teams[team_name] + updated = config.model_copy(update={"teams": teams}) + await run_sync(updated.save) + + return {"ok": True, "name": team_name} +``` + +**Step 4: Run tests to verify they pass** + +Run: `cd api && pytest tests/test_sync_team_crud.py -v` +Expected: PASS + +**Step 5: Commit** + +```bash +git add api/routers/sync_status.py api/tests/test_sync_team_crud.py +git commit -m "feat(api): add team CRUD endpoints — POST/DELETE /sync/teams" +``` + +--- + +### Task 2: Team member management endpoints + +**Files:** +- Modify: `api/routers/sync_status.py` +- Modify: `api/services/syncthing_proxy.py` (add `auto_share_folders`, `accept_pending_folders`) +- Test: `api/tests/test_sync_members.py` (create) + +**Step 1: Write failing tests** + +```python +# api/tests/test_sync_members.py +"""Tests for sync team member management endpoints.""" +from __future__ import annotations +import json +from unittest.mock import patch, MagicMock +import pytest +from fastapi.testclient import TestClient + + +def _base_config(tmp_path): + return { + "user_id": "jayant", + "machine_id": "mac", + "teams": { + "my-team": { + "backend": "syncthing", + "projects": {}, + "syncthing_members": {}, + "ipfs_members": {}, + } + }, + "syncthing": { + "api_url": "http://127.0.0.1:8384", + "api_key": "test-key", + "device_id": "MY-DEVICE-ID", + }, + } + + +class TestAddMember: + def test_add_member_success(self, tmp_path, monkeypatch): + config_path = tmp_path / "sync-config.json" + config_path.write_text(json.dumps(_base_config(tmp_path))) + monkeypatch.setenv("KARMA_SYNC_CONFIG_PATH", str(config_path)) + + from main import app + client = TestClient(app) + + with patch("services.syncthing_proxy.SyncthingClient") as mock_cls: + mock_st = MagicMock() + mock_st.is_running.return_value = True + mock_st.add_device.return_value = None + mock_st.get_pending_folders.return_value = {} + mock_st._get_config.return_value = {"devices": [], "folders": []} + mock_cls.return_value = mock_st + + resp = client.post("/sync/teams/my-team/members", json={ + "name": "alice", + "device_id": "ALICE-DEVICE-ID-123" + }) + + assert resp.status_code == 200 + data = resp.json() + assert data["ok"] is True + assert data["name"] == "alice" + + # Verify persisted in config + saved = json.loads(config_path.read_text()) + members = saved["teams"]["my-team"]["syncthing_members"] + assert "alice" in members + assert members["alice"]["syncthing_device_id"] == "ALICE-DEVICE-ID-123" + + def test_add_member_team_not_found(self, tmp_path, monkeypatch): + config_path = tmp_path / "sync-config.json" + config_path.write_text(json.dumps(_base_config(tmp_path))) + monkeypatch.setenv("KARMA_SYNC_CONFIG_PATH", str(config_path)) + + from main import app + client = TestClient(app) + resp = client.post("/sync/teams/nope/members", json={ + "name": "alice", "device_id": "AAAA" + }) + assert resp.status_code == 404 + + +class TestRemoveMember: + def test_remove_member_success(self, tmp_path, monkeypatch): + cfg = _base_config(tmp_path) + cfg["teams"]["my-team"]["syncthing_members"]["alice"] = { + "syncthing_device_id": "ALICE-ID" + } + config_path = tmp_path / "sync-config.json" + config_path.write_text(json.dumps(cfg)) + monkeypatch.setenv("KARMA_SYNC_CONFIG_PATH", str(config_path)) + + from main import app + client = TestClient(app) + + with patch("services.syncthing_proxy.SyncthingClient") as mock_cls: + mock_st = MagicMock() + mock_st.is_running.return_value = True + mock_cls.return_value = mock_st + + resp = client.delete("/sync/teams/my-team/members/alice") + + assert resp.status_code == 200 + saved = json.loads(config_path.read_text()) + assert "alice" not in saved["teams"]["my-team"]["syncthing_members"] + + def test_remove_member_not_found(self, tmp_path, monkeypatch): + config_path = tmp_path / "sync-config.json" + config_path.write_text(json.dumps(_base_config(tmp_path))) + monkeypatch.setenv("KARMA_SYNC_CONFIG_PATH", str(config_path)) + + from main import app + client = TestClient(app) + resp = client.delete("/sync/teams/my-team/members/ghost") + assert resp.status_code == 404 +``` + +**Step 2: Run tests — expect FAIL** + +Run: `cd api && pytest tests/test_sync_members.py -v` + +**Step 3: Implement member endpoints** + +Add to `api/routers/sync_status.py`: + +```python +class AddMemberRequest(BaseModel): + name: str + device_id: str + + +@router.post("/teams/{team_name}/members") +async def sync_add_member(team_name: str, req: AddMemberRequest) -> Any: + """Add a member to a sync group. + + This does the full pipeline: + 1. Add to sync-config.json + 2. Pair device in Syncthing + 3. Auto-create shared folders for all team projects + 4. Auto-accept pending folder offers + """ + if not ALLOWED_PROJECT_NAME.match(team_name): + raise HTTPException(400, "Invalid team name") + if not ALLOWED_PROJECT_NAME.match(req.name) or len(req.name) > 64: + raise HTTPException(400, "Invalid member name") + validate_device_id(req.device_id) + + config, _, _ = await run_sync(_load_sync_config) + if config is None: + raise HTTPException(400, "Not initialized") + + data = config.model_dump() + if team_name not in data.get("teams", {}): + raise HTTPException(404, f"Team '{team_name}' not found") + + from karma.config import TeamMemberSyncthing, TeamConfig + + team_cfg = config.teams[team_name] + + # 1. Add member to config + syncthing_members = dict(team_cfg.syncthing_members) + syncthing_members[req.name] = TeamMemberSyncthing( + syncthing_device_id=req.device_id + ) + teams = dict(config.teams) + teams[team_name] = team_cfg.model_copy( + update={"syncthing_members": syncthing_members} + ) + updated = config.model_copy(update={"teams": teams}) + await run_sync(updated.save) + + # 2. Pair device in Syncthing + paired = False + try: + proxy = get_proxy() + await run_sync(proxy.add_device, req.device_id, req.name) + paired = True + except (SyncthingNotRunning, ValueError): + pass + + # 3. Auto-share folders for existing projects + shared_folders = 0 + try: + if paired and team_cfg.projects: + from karma.syncthing import SyncthingClient, read_local_api_key + api_key = config.syncthing.api_key or await run_sync(read_local_api_key) + st = SyncthingClient(api_key=api_key) + if st.is_running(): + from karma.main import _auto_share_folders + await run_sync( + _auto_share_folders, + st, config, team_cfg, teams, team_name, req.device_id + ) + shared_folders = len(team_cfg.projects) + except Exception: + pass + + # 4. Auto-accept pending folder offers + accepted = 0 + try: + from karma.syncthing import SyncthingClient, read_local_api_key + api_key = config.syncthing.api_key or await run_sync(read_local_api_key) + st = SyncthingClient(api_key=api_key) + if st.is_running(): + from karma.main import _accept_pending_folders + accepted = await run_sync(_accept_pending_folders, st, updated) + except Exception: + pass + + return { + "ok": True, + "name": req.name, + "device_id": req.device_id, + "paired": paired, + "shared_folders": shared_folders, + "accepted_folders": accepted, + } + + +@router.delete("/teams/{team_name}/members/{member_name}") +async def sync_remove_member(team_name: str, member_name: str) -> Any: + """Remove a member from a sync group.""" + if not ALLOWED_PROJECT_NAME.match(team_name): + raise HTTPException(400, "Invalid team name") + if not ALLOWED_PROJECT_NAME.match(member_name): + raise HTTPException(400, "Invalid member name") + + config, _, _ = await run_sync(_load_sync_config) + if config is None: + raise HTTPException(400, "Not initialized") + + data = config.model_dump() + if team_name not in data.get("teams", {}): + raise HTTPException(404, f"Team '{team_name}' not found") + + team_cfg = config.teams[team_name] + if member_name not in team_cfg.syncthing_members: + raise HTTPException(404, f"Member '{member_name}' not found") + + device_id = team_cfg.syncthing_members[member_name].syncthing_device_id + + # Remove from config + members = dict(team_cfg.syncthing_members) + del members[member_name] + teams = dict(config.teams) + teams[team_name] = team_cfg.model_copy(update={"syncthing_members": members}) + updated = config.model_copy(update={"teams": teams}) + await run_sync(updated.save) + + # Remove device from Syncthing + try: + proxy = get_proxy() + await run_sync(proxy.remove_device, device_id) + except (SyncthingNotRunning, Exception): + pass + + return {"ok": True, "name": member_name} +``` + +**Step 4: Run tests — expect PASS** + +Run: `cd api && pytest tests/test_sync_members.py -v` + +**Step 5: Commit** + +```bash +git add api/routers/sync_status.py api/tests/test_sync_members.py +git commit -m "feat(api): add team member endpoints — POST/DELETE /sync/teams/{name}/members" +``` + +--- + +### Task 3: Team project management endpoints + +**Files:** +- Modify: `api/routers/sync_status.py` +- Test: `api/tests/test_sync_team_projects.py` (create) + +**Step 1: Write failing tests** + +```python +# api/tests/test_sync_team_projects.py +"""Tests for adding/removing projects to sync groups.""" +from __future__ import annotations +import json +from unittest.mock import patch, MagicMock +import pytest +from fastapi.testclient import TestClient + + +def _base_config(): + return { + "user_id": "jayant", + "machine_id": "mac", + "teams": { + "my-team": { + "backend": "syncthing", + "projects": {}, + "syncthing_members": { + "alice": {"syncthing_device_id": "ALICE-ID"} + }, + "ipfs_members": {}, + } + }, + "syncthing": { + "api_url": "http://127.0.0.1:8384", + "api_key": "test-key", + "device_id": "MY-DEVICE-ID", + }, + } + + +class TestAddProjectToTeam: + def test_add_project_success(self, tmp_path, monkeypatch): + config_path = tmp_path / "sync-config.json" + config_path.write_text(json.dumps(_base_config())) + monkeypatch.setenv("KARMA_SYNC_CONFIG_PATH", str(config_path)) + + from main import app + client = TestClient(app) + + with patch("services.syncthing_proxy.SyncthingClient"): + resp = client.post("/sync/teams/my-team/projects", json={ + "name": "claude-karma", + "path": "/Users/jayant/Documents/GitHub/claude-karma" + }) + + assert resp.status_code == 200 + data = resp.json() + assert data["ok"] is True + assert data["encoded_name"].startswith("-") + + saved = json.loads(config_path.read_text()) + assert "claude-karma" in saved["teams"]["my-team"]["projects"] + + def test_add_project_team_not_found(self, tmp_path, monkeypatch): + config_path = tmp_path / "sync-config.json" + config_path.write_text(json.dumps(_base_config())) + monkeypatch.setenv("KARMA_SYNC_CONFIG_PATH", str(config_path)) + + from main import app + client = TestClient(app) + resp = client.post("/sync/teams/nope/projects", json={ + "name": "x", "path": "/tmp/x" + }) + assert resp.status_code == 404 + + +class TestRemoveProjectFromTeam: + def test_remove_project_success(self, tmp_path, monkeypatch): + cfg = _base_config() + cfg["teams"]["my-team"]["projects"]["claude-karma"] = { + "path": "/Users/jayant/GitHub/claude-karma", + "encoded_name": "-Users-jayant-GitHub-claude-karma", + } + config_path = tmp_path / "sync-config.json" + config_path.write_text(json.dumps(cfg)) + monkeypatch.setenv("KARMA_SYNC_CONFIG_PATH", str(config_path)) + + from main import app + client = TestClient(app) + resp = client.delete("/sync/teams/my-team/projects/claude-karma") + assert resp.status_code == 200 + + saved = json.loads(config_path.read_text()) + assert "claude-karma" not in saved["teams"]["my-team"]["projects"] + + def test_remove_project_not_found(self, tmp_path, monkeypatch): + config_path = tmp_path / "sync-config.json" + config_path.write_text(json.dumps(_base_config())) + monkeypatch.setenv("KARMA_SYNC_CONFIG_PATH", str(config_path)) + + from main import app + client = TestClient(app) + resp = client.delete("/sync/teams/my-team/projects/nope") + assert resp.status_code == 404 +``` + +**Step 2: Run tests — expect FAIL** + +Run: `cd api && pytest tests/test_sync_team_projects.py -v` + +**Step 3: Implement** + +Add to `api/routers/sync_status.py`: + +```python +class AddTeamProjectRequest(BaseModel): + name: str + path: str + + +@router.post("/teams/{team_name}/projects") +async def sync_add_team_project(team_name: str, req: AddTeamProjectRequest) -> Any: + """Add a project to a sync group. + + Creates outbox (sendonly) + inbox per member (receiveonly) in Syncthing. + """ + validate_project_name(req.name) + if not ALLOWED_PROJECT_NAME.match(team_name): + raise HTTPException(400, "Invalid team name") + + config, _, _ = await run_sync(_load_sync_config) + if config is None: + raise HTTPException(400, "Not initialized") + if team_name not in config.teams: + raise HTTPException(404, f"Team '{team_name}' not found") + + from karma.sync import encode_project_path + from karma.config import ProjectConfig, KARMA_BASE + + encoded = encode_project_path(req.path) + project_config = ProjectConfig(path=req.path, encoded_name=encoded) + + team_cfg = config.teams[team_name] + projects = dict(team_cfg.projects) + projects[req.name] = project_config + teams = dict(config.teams) + teams[team_name] = team_cfg.model_copy(update={"projects": projects}) + updated = config.model_copy(update={"teams": teams}) + await run_sync(updated.save) + + # Auto-create Syncthing folders + shared = 0 + try: + if team_cfg.backend == "syncthing" and team_cfg.syncthing_members: + from karma.syncthing import SyncthingClient, read_local_api_key + api_key = config.syncthing.api_key or await run_sync(read_local_api_key) + st = SyncthingClient(api_key=api_key) + if st.is_running(): + from pathlib import Path + # Outbox + outbox_path = str(KARMA_BASE / "remote-sessions" / config.user_id / encoded) + outbox_id = f"karma-out-{config.user_id}-{req.name}" + device_ids = [] + if config.syncthing.device_id: + device_ids.append(config.syncthing.device_id) + for m in team_cfg.syncthing_members.values(): + device_ids.append(m.syncthing_device_id) + Path(outbox_path).mkdir(parents=True, exist_ok=True) + st.add_folder(outbox_id, outbox_path, device_ids, folder_type="sendonly") + shared += 1 + + # Inbox per member + for mname, mcfg in team_cfg.syncthing_members.items(): + inbox_path = str(KARMA_BASE / "remote-sessions" / mname / encoded) + inbox_id = f"karma-out-{mname}-{req.name}" + inbox_devices = [mcfg.syncthing_device_id] + if config.syncthing.device_id: + inbox_devices.append(config.syncthing.device_id) + Path(inbox_path).mkdir(parents=True, exist_ok=True) + st.add_folder(inbox_id, inbox_path, inbox_devices, folder_type="receiveonly") + shared += 1 + except Exception: + pass + + return { + "ok": True, + "name": req.name, + "encoded_name": encoded, + "shared_folders_created": shared, + } + + +@router.delete("/teams/{team_name}/projects/{project_name}") +async def sync_remove_team_project(team_name: str, project_name: str) -> Any: + """Remove a project from a sync group.""" + validate_project_name(project_name) + if not ALLOWED_PROJECT_NAME.match(team_name): + raise HTTPException(400, "Invalid team name") + + config, _, _ = await run_sync(_load_sync_config) + if config is None: + raise HTTPException(400, "Not initialized") + if team_name not in config.teams: + raise HTTPException(404, f"Team '{team_name}' not found") + + team_cfg = config.teams[team_name] + if project_name not in team_cfg.projects: + raise HTTPException(404, f"Project '{project_name}' not found in team") + + projects = dict(team_cfg.projects) + del projects[project_name] + teams = dict(config.teams) + teams[team_name] = team_cfg.model_copy(update={"projects": projects}) + updated = config.model_copy(update={"teams": teams}) + await run_sync(updated.save) + + return {"ok": True, "name": project_name} +``` + +**Step 4: Run tests — expect PASS** + +Run: `cd api && pytest tests/test_sync_team_projects.py -v` + +**Step 5: Commit** + +```bash +git add api/routers/sync_status.py api/tests/test_sync_team_projects.py +git commit -m "feat(api): add team project endpoints — POST/DELETE /sync/teams/{name}/projects" +``` + +--- + +### Task 4: Watcher manager service + endpoints + +**Files:** +- Create: `api/services/watcher_manager.py` +- Modify: `api/routers/sync_status.py` (add watch endpoints) +- Test: `api/tests/test_watcher_manager.py` (create) + +**Step 1: Write failing tests** + +```python +# api/tests/test_watcher_manager.py +"""Tests for the in-process watcher manager.""" +from __future__ import annotations +import json +from unittest.mock import patch, MagicMock +import pytest + + +class TestWatcherManager: + def test_start_creates_watchers(self, tmp_path, monkeypatch): + from services.watcher_manager import WatcherManager + + # Create fake project dirs + projects_dir = tmp_path / ".claude" / "projects" + main_dir = projects_dir / "-Users-jay-karma" + main_dir.mkdir(parents=True) + + config_data = { + "user_id": "jay", + "machine_id": "mac", + "teams": { + "my-team": { + "backend": "syncthing", + "projects": { + "karma": { + "path": "/Users/jay/karma", + "encoded_name": "-Users-jay-karma", + } + }, + "syncthing_members": {}, + "ipfs_members": {}, + } + }, + "syncthing": {}, + } + + with patch("services.watcher_manager.Path.home", return_value=tmp_path): + mgr = WatcherManager() + result = mgr.start("my-team", config_data) + + assert result["running"] is True + assert result["team"] == "my-team" + assert mgr.is_running + + def test_stop_cleans_up(self, tmp_path): + from services.watcher_manager import WatcherManager + + mgr = WatcherManager() + mgr._running = True + mgr._team = "test" + mgr._watchers = [MagicMock(), MagicMock()] + + result = mgr.stop() + assert result["running"] is False + assert not mgr.is_running + for w in mgr._watchers: + w.stop.assert_called_once() + + def test_status_when_not_running(self): + from services.watcher_manager import WatcherManager + mgr = WatcherManager() + status = mgr.status() + assert status["running"] is False + assert status["team"] is None + + def test_cannot_start_twice(self, tmp_path): + from services.watcher_manager import WatcherManager + mgr = WatcherManager() + mgr._running = True + mgr._team = "existing" + + with pytest.raises(ValueError, match="already running"): + mgr.start("another", {}) +``` + +**Step 2: Run tests — expect FAIL** + +Run: `cd api && pytest tests/test_watcher_manager.py -v` + +**Step 3: Implement WatcherManager** + +```python +# api/services/watcher_manager.py +"""In-process session watcher manager. + +Runs the same SessionWatcher + SessionPackager logic as `karma watch`, +but as a background service managed by the API process. +""" +from __future__ import annotations + +import logging +import sys +from datetime import datetime, timezone +from pathlib import Path +from typing import Any, Optional + +logger = logging.getLogger(__name__) + +# Add CLI to path +_CLI_PATH = Path(__file__).parent.parent.parent / "cli" +if str(_CLI_PATH) not in sys.path: + sys.path.insert(0, str(_CLI_PATH)) + + +class WatcherManager: + """Manages SessionWatcher instances for a single team.""" + + def __init__(self) -> None: + self._running = False + self._team: Optional[str] = None + self._watchers: list = [] + self._started_at: Optional[str] = None + self._last_packaged_at: Optional[str] = None + self._projects_watched: list[str] = [] + + @property + def is_running(self) -> bool: + return self._running + + def status(self) -> dict[str, Any]: + return { + "running": self._running, + "team": self._team, + "started_at": self._started_at, + "last_packaged_at": self._last_packaged_at, + "projects_watched": self._projects_watched, + } + + def start(self, team_name: str, config_data: dict) -> dict[str, Any]: + """Start watchers for all projects in the given team.""" + if self._running: + raise ValueError(f"Watcher already running for team '{self._team}'") + + from karma.watcher import SessionWatcher + from karma.packager import SessionPackager + from karma.worktree_discovery import find_worktree_dirs + from karma.config import KARMA_BASE + + team_cfg = config_data.get("teams", {}).get(team_name, {}) + projects = team_cfg.get("projects", {}) + user_id = config_data.get("user_id", "unknown") + machine_id = config_data.get("machine_id", "unknown") + + projects_dir = Path.home() / ".claude" / "projects" + watchers = [] + watched = [] + + for proj_name, proj in projects.items(): + encoded = proj.get("encoded_name", proj_name) + claude_dir = projects_dir / encoded + if not claude_dir.is_dir(): + logger.warning("Skipping %s: dir not found %s", proj_name, claude_dir) + continue + + outbox = KARMA_BASE / "remote-sessions" / user_id / encoded + + def make_package_fn( + cd=claude_dir, ob=outbox, en=encoded, pp=proj.get("path", "") + ): + def package(): + wt_dirs = find_worktree_dirs(en, projects_dir) + packager = SessionPackager( + project_dir=cd, + user_id=user_id, + machine_id=machine_id, + project_path=pp, + extra_dirs=wt_dirs, + ) + ob.mkdir(parents=True, exist_ok=True) + packager.package(staging_dir=ob) + self._last_packaged_at = ( + datetime.now(timezone.utc).isoformat() + ) + return package + + watcher = SessionWatcher( + watch_dir=claude_dir, + package_fn=make_package_fn(), + ) + watcher.start() + watchers.append(watcher) + watched.append(proj_name) + + # Also watch worktree dirs + wt_dirs = find_worktree_dirs(encoded, projects_dir) + for wt_dir in wt_dirs: + wt_watcher = SessionWatcher( + watch_dir=wt_dir, + package_fn=make_package_fn(), + ) + wt_watcher.start() + watchers.append(wt_watcher) + + self._watchers = watchers + self._running = True + self._team = team_name + self._started_at = datetime.now(timezone.utc).isoformat() + self._projects_watched = watched + + logger.info( + "Watcher started: team=%s, projects=%d, watchers=%d", + team_name, len(watched), len(watchers), + ) + return self.status() + + def stop(self) -> dict[str, Any]: + """Stop all watchers.""" + for w in self._watchers: + try: + w.stop() + except Exception as e: + logger.warning("Error stopping watcher: %s", e) + + self._watchers = [] + self._running = False + team = self._team + self._team = None + self._started_at = None + self._projects_watched = [] + + logger.info("Watcher stopped (was team=%s)", team) + return self.status() +``` + +Add watch endpoints to `api/routers/sync_status.py`: + +```python +from services.watcher_manager import WatcherManager + +_watcher: WatcherManager | None = None + +def get_watcher() -> WatcherManager: + global _watcher + if _watcher is None: + _watcher = WatcherManager() + return _watcher + + +@router.get("/watch/status") +async def sync_watch_status() -> Any: + """Get watcher status.""" + return get_watcher().status() + + +@router.post("/watch/start") +async def sync_watch_start(team_name: str | None = None) -> Any: + """Start the session watcher for a team.""" + config, _, _ = await run_sync(_load_sync_config) + if config is None: + raise HTTPException(400, "Not initialized") + + data = config.model_dump() + teams = data.get("teams", {}) + + # Auto-detect team if not specified + if team_name is None: + syncthing_teams = [n for n, t in teams.items() if t.get("backend") == "syncthing"] + if len(syncthing_teams) == 1: + team_name = syncthing_teams[0] + elif len(syncthing_teams) == 0: + raise HTTPException(400, "No syncthing teams configured") + else: + raise HTTPException(400, f"Multiple teams found. Specify team_name: {syncthing_teams}") + + if team_name not in teams: + raise HTTPException(404, f"Team '{team_name}' not found") + + watcher = get_watcher() + if watcher.is_running: + raise HTTPException(409, "Watcher already running. Stop it first.") + + try: + result = await run_sync(watcher.start, team_name, data) + return result + except Exception as e: + raise HTTPException(500, f"Failed to start watcher: {e}") + + +@router.post("/watch/stop") +async def sync_watch_stop() -> Any: + """Stop the session watcher.""" + watcher = get_watcher() + if not watcher.is_running: + return watcher.status() + return await run_sync(watcher.stop) +``` + +**Step 4: Run tests — expect PASS** + +Run: `cd api && pytest tests/test_watcher_manager.py -v` + +**Step 5: Commit** + +```bash +git add api/services/watcher_manager.py api/routers/sync_status.py api/tests/test_watcher_manager.py +git commit -m "feat(api): add watcher manager + /sync/watch endpoints" +``` + +--- + +### Task 5: Pending folders endpoint + +**Files:** +- Modify: `api/routers/sync_status.py` +- Modify: `api/services/syncthing_proxy.py` +- Test: `api/tests/test_sync_pending.py` (create) + +**Step 1: Write failing tests** + +```python +# api/tests/test_sync_pending.py +"""Tests for pending folder endpoints.""" +from __future__ import annotations +from unittest.mock import MagicMock, patch +import pytest +from services.syncthing_proxy import SyncthingNotRunning, SyncthingProxy + + +class TestGetPendingFolders: + def test_returns_pending_from_known_members(self): + mock_client = MagicMock() + mock_client.get_pending_folders.return_value = { + "karma-out-alice-myapp": { + "offeredBy": {"ALICE-DEVICE-ID": {"time": "2026-03-06T00:00:00Z"}} + } + } + + proxy = SyncthingProxy.__new__(SyncthingProxy) + proxy._client = mock_client + + result = proxy.get_pending_folders_for_ui( + known_devices={"ALICE-DEVICE-ID": ("alice", "my-team")} + ) + + assert len(result) == 1 + assert result[0]["folder_id"] == "karma-out-alice-myapp" + assert result[0]["from_member"] == "alice" + + def test_filters_unknown_devices(self): + mock_client = MagicMock() + mock_client.get_pending_folders.return_value = { + "karma-evil": { + "offeredBy": {"UNKNOWN-DEVICE": {"time": "2026-03-06T00:00:00Z"}} + } + } + + proxy = SyncthingProxy.__new__(SyncthingProxy) + proxy._client = mock_client + + result = proxy.get_pending_folders_for_ui(known_devices={}) + assert len(result) == 0 + + def test_filters_non_karma_prefix(self): + mock_client = MagicMock() + mock_client.get_pending_folders.return_value = { + "photos-backup": { + "offeredBy": {"ALICE-ID": {"time": "2026-03-06T00:00:00Z"}} + } + } + + proxy = SyncthingProxy.__new__(SyncthingProxy) + proxy._client = mock_client + + result = proxy.get_pending_folders_for_ui( + known_devices={"ALICE-ID": ("alice", "team")} + ) + assert len(result) == 0 +``` + +**Step 2: Run tests — expect FAIL** + +Run: `cd api && pytest tests/test_sync_pending.py -v` + +**Step 3: Implement** + +Add to `api/services/syncthing_proxy.py`: + +```python +def get_pending_folders_for_ui( + self, known_devices: dict[str, tuple[str, str]] +) -> list[dict]: + """Get pending folder offers filtered for known team members. + + Args: + known_devices: {device_id: (member_name, team_name)} + + Returns: + List of pending offers from known members with karma- prefix only. + """ + client = self._require_client() + pending = client.get_pending_folders() + result = [] + + for folder_id, info in pending.items(): + if not folder_id.startswith("karma-"): + continue + for device_id, offer in info.get("offeredBy", {}).items(): + if device_id not in known_devices: + continue + member_name, team_name = known_devices[device_id] + result.append({ + "folder_id": folder_id, + "from_device": device_id, + "from_member": member_name, + "from_team": team_name, + "offered_at": offer.get("time"), + }) + return result +``` + +Add to `api/routers/sync_status.py`: + +```python +@router.get("/pending") +async def sync_pending() -> Any: + """List pending folder offers from known team members.""" + config, _, _ = await run_sync(_load_sync_config) + if config is None: + return {"pending": []} + + # Build known devices lookup + known: dict[str, tuple[str, str]] = {} + for team_name, team_cfg in config.teams.items(): + for member_name, member_cfg in team_cfg.syncthing_members.items(): + known[member_cfg.syncthing_device_id] = (member_name, team_name) + + if not known: + return {"pending": []} + + proxy = get_proxy() + try: + pending = await run_sync(proxy.get_pending_folders_for_ui, known) + return {"pending": pending} + except SyncthingNotRunning: + return {"pending": []} + + +@router.post("/pending/accept") +async def sync_accept_pending() -> Any: + """Accept all pending folder offers from known team members.""" + config, _, _ = await run_sync(_load_sync_config) + if config is None: + raise HTTPException(400, "Not initialized") + + try: + from karma.syncthing import SyncthingClient, read_local_api_key + api_key = config.syncthing.api_key or await run_sync(read_local_api_key) + st = SyncthingClient(api_key=api_key) + if not st.is_running(): + raise HTTPException(503, "Syncthing is not running") + + from karma.main import _accept_pending_folders + accepted = await run_sync(_accept_pending_folders, st, config) + return {"ok": True, "accepted": accepted} + except SyncthingNotRunning: + raise HTTPException(503, "Syncthing is not running") +``` + +**Step 4: Run tests — expect PASS** + +Run: `cd api && pytest tests/test_sync_pending.py -v` + +**Step 5: Commit** + +```bash +git add api/services/syncthing_proxy.py api/routers/sync_status.py api/tests/test_sync_pending.py +git commit -m "feat(api): add pending folder endpoints — GET /sync/pending, POST /sync/pending/accept" +``` + +--- + +### Task 6: Project status endpoint (local/packaged/received counts) + +**Files:** +- Modify: `api/routers/sync_status.py` +- Test: `api/tests/test_sync_project_status.py` (create) + +**Step 1: Write failing tests** + +```python +# api/tests/test_sync_project_status.py +"""Tests for per-project sync status endpoint.""" +from __future__ import annotations +import json +from unittest.mock import patch +import pytest + + +class TestProjectStatus: + def test_returns_counts(self, tmp_path, monkeypatch): + """GET /sync/teams/{team}/project-status returns local/packaged/received counts.""" + config_path = tmp_path / "sync-config.json" + config_path.write_text(json.dumps({ + "user_id": "jay", + "machine_id": "mac", + "teams": { + "t1": { + "backend": "syncthing", + "projects": { + "karma": { + "path": "/Users/jay/karma", + "encoded_name": "-Users-jay-karma", + } + }, + "syncthing_members": { + "alice": {"syncthing_device_id": "ALICE"} + }, + "ipfs_members": {}, + } + }, + "syncthing": {}, + })) + monkeypatch.setenv("KARMA_SYNC_CONFIG_PATH", str(config_path)) + + # Create fake dirs + projects_dir = tmp_path / ".claude" / "projects" + main_dir = projects_dir / "-Users-jay-karma" + main_dir.mkdir(parents=True) + (main_dir / "s1.jsonl").write_text('{"type":"user"}\n') + (main_dir / "s2.jsonl").write_text('{"type":"user"}\n') + + outbox = tmp_path / "remote-sessions" / "jay" / "-Users-jay-karma" / "sessions" + outbox.mkdir(parents=True) + (outbox / "s1.jsonl").write_text('data') + + inbox = tmp_path / "remote-sessions" / "alice" / "-Users-jay-karma" / "sessions" + inbox.mkdir(parents=True) + (inbox / "a1.jsonl").write_text('data') + (inbox / "a2.jsonl").write_text('data') + + from main import app + from fastapi.testclient import TestClient + client = TestClient(app) + + with patch("karma.main.Path.home", return_value=tmp_path), \ + patch("karma.config.KARMA_BASE", tmp_path): + resp = client.get("/sync/teams/t1/project-status") + + assert resp.status_code == 200 + data = resp.json() + assert len(data["projects"]) == 1 + p = data["projects"][0] + assert p["name"] == "karma" + assert p["local_count"] == 2 + assert p["packaged_count"] == 1 + assert p["received_counts"]["alice"] == 2 +``` + +**Step 2: Run tests — FAIL. Step 3: Implement. Step 4: PASS.** + +Add to `api/routers/sync_status.py`: + +```python +@router.get("/teams/{team_name}/project-status") +async def sync_team_project_status(team_name: str) -> Any: + """Get per-project sync status with local/packaged/received counts.""" + if not ALLOWED_PROJECT_NAME.match(team_name): + raise HTTPException(400, "Invalid team name") + + config, _, _ = await run_sync(_load_sync_config) + if config is None: + raise HTTPException(400, "Not initialized") + if team_name not in config.teams: + raise HTTPException(404, f"Team '{team_name}' not found") + + from pathlib import Path as P + from karma.config import KARMA_BASE + from karma.worktree_discovery import find_worktree_dirs + + team_cfg = config.teams[team_name] + projects_dir = P.home() / ".claude" / "projects" + result = [] + + for proj_name, proj in team_cfg.projects.items(): + encoded = proj.encoded_name + claude_dir = projects_dir / encoded + + # Local sessions + local_count = 0 + if claude_dir.is_dir(): + local_count = sum( + 1 for f in claude_dir.glob("*.jsonl") + if not f.name.startswith("agent-") and f.stat().st_size > 0 + ) + # Worktree sessions + wt_dirs = find_worktree_dirs(encoded, projects_dir) + for wd in wt_dirs: + local_count += sum( + 1 for f in wd.glob("*.jsonl") + if not f.name.startswith("agent-") and f.stat().st_size > 0 + ) + + # Packaged sessions (outbox) + outbox = KARMA_BASE / "remote-sessions" / config.user_id / encoded / "sessions" + packaged_count = 0 + if outbox.is_dir(): + packaged_count = sum( + 1 for f in outbox.glob("*.jsonl") + if not f.name.startswith("agent-") + ) + + # Received per member + received_counts = {} + for mname in team_cfg.syncthing_members: + inbox = KARMA_BASE / "remote-sessions" / mname / encoded / "sessions" + if inbox.is_dir(): + received_counts[mname] = sum( + 1 for f in inbox.glob("*.jsonl") + if not f.name.startswith("agent-") + ) + else: + received_counts[mname] = 0 + + result.append({ + "name": proj_name, + "encoded_name": encoded, + "path": proj.path, + "local_count": local_count, + "packaged_count": packaged_count, + "received_counts": received_counts, + "gap": max(0, local_count - packaged_count), + }) + + return {"projects": result} +``` + +**Step 5: Commit** + +```bash +git add api/routers/sync_status.py api/tests/test_sync_project_status.py +git commit -m "feat(api): add project status endpoint — GET /sync/teams/{name}/project-status" +``` + +--- + +## Phase 2: Frontend — Types & Server Load + +### Task 7: Update TypeScript types + +**Files:** +- Modify: `frontend/src/lib/api-types.ts` + +**Step 1: Add new types** + +Append to the Sync Types section of `frontend/src/lib/api-types.ts`: + +```typescript +// --- New sync types for redesign --- + +export interface SyncTeam { + name: string; + backend: 'syncthing' | 'ipfs'; + projects: SyncTeamProject[]; + members: SyncTeamMember[]; +} + +export interface SyncTeamProject { + name: string; + encoded_name: string; + path: string; + local_count: number; + packaged_count: number; + received_counts: Record; + gap: number; +} + +export interface SyncTeamMember { + name: string; + device_id: string; + connected: boolean; + in_bytes_total: number; + out_bytes_total: number; +} + +export interface SyncWatchStatus { + running: boolean; + team: string | null; + started_at: string | null; + last_packaged_at: string | null; + projects_watched: string[]; +} + +export interface SyncPendingFolder { + folder_id: string; + from_device: string; + from_member: string; + from_team: string; + offered_at: string | null; +} +``` + +**Step 2: Commit** + +```bash +git add frontend/src/lib/api-types.ts +git commit -m "feat(frontend): add TypeScript types for sync redesign" +``` + +--- + +## Phase 3: Frontend — Onboarding Wizard + +### Task 8: Create SetupWizard component + +**Files:** +- Create: `frontend/src/lib/components/sync/SetupWizard.svelte` +- Modify: `frontend/src/routes/sync/+page.svelte` (use wizard when not configured) + +This is a 3-step wizard that replaces the current SetupTab for unconfigured users: + +1. **Install Syncthing** — detect + install instructions (reuse existing SetupTab state 1) +2. **Name This Machine** — user_id + show device ID (reuse SetupTab state 2) +3. **Create/Join Group** — team creation with project selection + +**Step 1: Create SetupWizard.svelte** + +The wizard manages its own step state and calls the API at each transition: +- Step 1→2: Auto-advances when `detect.running` becomes true +- Step 2→3: `POST /sync/init` on "Continue" +- Step 3→done: `POST /sync/teams` + `POST /sync/teams/{name}/projects` (for each selected project) + `POST /sync/watch/start` + +The wizard component accepts `detect`, `status`, and an `ondone` callback. It renders the 3 steps with a progress bar. Each step is self-contained with its own form state. + +Key implementation details: +- Step 3 "Create Group" fetches `GET /projects` to show project list with checkboxes +- Step 3 "Join Existing" just shows the device ID for sharing — no API calls +- Step 3 "Solo Sync" is identical to "Create Group" but with different copy +- On completion, `ondone()` triggers the parent to refresh and switch to dashboard + +**Step 2: Modify +page.svelte to conditionally render wizard vs dashboard** + +Replace the current unconditional tab layout with: + +```svelte +{#if !syncStatus?.configured} + +{:else} + +{/if} +``` + +**Step 3: Commit** + +```bash +git add frontend/src/lib/components/sync/SetupWizard.svelte frontend/src/routes/sync/+page.svelte +git commit -m "feat(frontend): add setup wizard for first-time sync configuration" +``` + +--- + +### Task 9: Create OverviewTab component + +**Files:** +- Create: `frontend/src/lib/components/sync/OverviewTab.svelte` +- Modify: `frontend/src/routes/sync/+page.svelte` (add Overview tab) + +**Key elements:** +1. **Sync Engine banner** — `GET /sync/watch/status` → show running/stopped with start/stop button +2. **Stats row** — members, projects, bandwidth (reuse pattern from current SetupTab state 3) +3. **Machine details** — user_id, device_id (copyable), version +4. **Pending actions** — `GET /sync/pending` → list with Accept/Ignore buttons + +The banner is the most important element. It calls `POST /sync/watch/start` or `POST /sync/watch/stop`. + +Pending actions call `POST /sync/pending/accept` on "Accept All". + +**Step 1: Implement, Step 2: Commit** + +```bash +git add frontend/src/lib/components/sync/OverviewTab.svelte frontend/src/routes/sync/+page.svelte +git commit -m "feat(frontend): add Overview tab with sync engine control + pending actions" +``` + +--- + +### Task 10: Create MembersTab component + +**Files:** +- Create: `frontend/src/lib/components/sync/MembersTab.svelte` +- Modify: `frontend/src/routes/sync/+page.svelte` (replace Devices tab) + +**Key elements:** +1. **Member list** — `GET /sync/teams` to get members, enriched with `GET /sync/devices` for connection status +2. **Add member form** — shows "Your Sync ID" + input for teammate's ID + name → `POST /sync/teams/{team}/members` +3. **Remove member** — confirm dialog → `DELETE /sync/teams/{team}/members/{name}` + +Reuse `DeviceCard.svelte` for display (it already has expand/collapse, status, transfer stats). The key change is that "Add Member" now calls the team member endpoint instead of raw Syncthing device pairing. + +**Step 1: Implement, Step 2: Commit** + +```bash +git add frontend/src/lib/components/sync/MembersTab.svelte frontend/src/routes/sync/+page.svelte +git commit -m "feat(frontend): add Members tab with team member management" +``` + +--- + +### Task 11: Rewrite ProjectsTab for team-scoped projects + +**Files:** +- Modify: `frontend/src/lib/components/sync/ProjectsTab.svelte` +- Modify: `frontend/src/lib/components/sync/ProjectRow.svelte` + +**Key changes:** +1. "Enable Sync" → `POST /sync/teams/{team}/projects` (not flat `config.projects`) +2. "Disable" → `DELETE /sync/teams/{team}/projects/{name}` +3. Expanded row shows local/packaged/received counts from `GET /sync/teams/{team}/project-status` +4. Gap indicator: "3 behind — watcher needs to run" if packaged < local + +**Step 1: Implement, Step 2: Commit** + +```bash +git add frontend/src/lib/components/sync/ProjectsTab.svelte frontend/src/lib/components/sync/ProjectRow.svelte +git commit -m "feat(frontend): rewrite ProjectsTab for team-scoped project management" +``` + +--- + +### Task 12: Update +page.svelte tab layout + +**Files:** +- Modify: `frontend/src/routes/sync/+page.svelte` +- Modify: `frontend/src/routes/sync/+page.server.ts` + +**Key changes:** +1. Replace tabs: Setup → Overview, Devices → Members (keep Projects, Activity) +2. Default tab: `overview` when configured, wizard when not +3. Server load: add `GET /sync/watch/status` and `GET /sync/pending` to initial data +4. Remove old `SetupTab` import (replaced by wizard + overview) + +**Step 1: Implement, Step 2: Commit** + +```bash +git add frontend/src/routes/sync/+page.svelte frontend/src/routes/sync/+page.server.ts +git commit -m "feat(frontend): update sync page layout — wizard + overview/members/projects/activity" +``` + +--- + +## Phase 4: Cleanup & Polish + +### Task 13: Remove dead code + update existing SetupTab + +**Files:** +- Delete or repurpose: `frontend/src/lib/components/sync/SetupTab.svelte` +- Modify: `frontend/src/lib/components/sync/DevicesTab.svelte` (keep as sub-component or remove) + +The old SetupTab and DevicesTab are replaced by SetupWizard, OverviewTab, and MembersTab. Either delete them or keep DevicesTab as a low-level component imported by MembersTab. + +**Step 1: Remove unused imports, Step 2: Commit** + +```bash +git add -A frontend/src/lib/components/sync/ +git commit -m "refactor(frontend): remove old SetupTab, merge DevicesTab into MembersTab" +``` + +--- + +### Task 14: Run full test suite + type check + +**Step 1: API tests** + +```bash +cd api && pytest -v +``` + +Expected: All pass, including new test files. + +**Step 2: Frontend type check** + +```bash +cd frontend && npm run check +``` + +Expected: No errors. + +**Step 3: Frontend lint** + +```bash +cd frontend && npm run lint +``` + +Expected: Clean. + +**Step 4: Final commit** + +```bash +git add -A +git commit -m "chore: fix any remaining type/lint issues from sync redesign" +``` + +--- + +## Dependency Graph + +``` +Task 1 (Team CRUD) ─────────────┐ +Task 2 (Members) ───────────────┤ +Task 3 (Team Projects) ─────────┤──→ Task 7 (TS Types) ──→ Task 8 (Wizard) +Task 4 (Watcher Manager) ───────┤ Task 9 (Overview) +Task 5 (Pending Folders) ───────┤ Task 10 (Members UI) +Task 6 (Project Status) ────────┘ Task 11 (Projects UI) + Task 12 (Page Layout) + Task 13 (Cleanup) + Task 14 (Full Tests) +``` + +Tasks 1-6 are independent of each other (all API-side). Task 7 depends on 1-6 being done. Tasks 8-12 depend on 7. Tasks 13-14 are final cleanup. + +**Parallelizable:** Tasks 1-6 can all run in parallel. Tasks 8-11 can run in parallel after Task 7. + +--- + +## Files Changed Summary + +| File | Action | Task | +|---|---|---| +| `api/routers/sync_status.py` | Modify (add ~200 lines) | 1,2,3,4,5,6 | +| `api/services/watcher_manager.py` | Create (~120 lines) | 4 | +| `api/services/syncthing_proxy.py` | Modify (add ~30 lines) | 5 | +| `api/tests/test_sync_team_crud.py` | Create | 1 | +| `api/tests/test_sync_members.py` | Create | 2 | +| `api/tests/test_sync_team_projects.py` | Create | 3 | +| `api/tests/test_watcher_manager.py` | Create | 4 | +| `api/tests/test_sync_pending.py` | Create | 5 | +| `api/tests/test_sync_project_status.py` | Create | 6 | +| `frontend/src/lib/api-types.ts` | Modify (add types) | 7 | +| `frontend/src/lib/components/sync/SetupWizard.svelte` | Create | 8 | +| `frontend/src/lib/components/sync/OverviewTab.svelte` | Create | 9 | +| `frontend/src/lib/components/sync/MembersTab.svelte` | Create | 10 | +| `frontend/src/lib/components/sync/ProjectsTab.svelte` | Modify (rewrite) | 11 | +| `frontend/src/lib/components/sync/ProjectRow.svelte` | Modify | 11 | +| `frontend/src/routes/sync/+page.svelte` | Modify | 8,9,10,12 | +| `frontend/src/routes/sync/+page.server.ts` | Modify | 12 | +| `frontend/src/lib/components/sync/SetupTab.svelte` | Delete/repurpose | 13 | +| `frontend/src/lib/components/sync/DevicesTab.svelte` | Delete/repurpose | 13 | diff --git a/docs/plans/2026-03-06-sync-page-tabs-implementation.md b/docs/plans/2026-03-06-sync-page-tabs-implementation.md new file mode 100644 index 00000000..cfc541e3 --- /dev/null +++ b/docs/plans/2026-03-06-sync-page-tabs-implementation.md @@ -0,0 +1,741 @@ +# Sync Page Tabs Redesign — Implementation Plan + +> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. + +**Goal:** Restructure the sync page's 4 tabs (Overview, Members, Projects, Activity) to eliminate information duplication, consolidate team management, and translate raw Syncthing events into session-meaningful activity. + +**Architecture:** Rename Members→Team tab and move team-level config into it. Strip Overview down to health-check essentials. Refocus Activity on human-readable session events. Keep Projects mostly as-is but ensure sync health data is fully surfaced. No backend changes needed — all APIs already exist. + +**Tech Stack:** Svelte 5 (runes), Tailwind CSS 4, lucide-svelte icons, existing API endpoints + +--- + +### Task 1: Restructure OverviewTab — strip it down + +**Files:** +- Modify: `frontend/src/lib/components/sync/OverviewTab.svelte` +- Modify: `frontend/src/routes/sync/+page.svelte` (tab label) + +**Context:** The current OverviewTab has 6 sections. We need to remove: team management card (moving to Team tab), getting started guide (moving to Team tab), and "Your Sync ID" from machine details (moving to Team tab). We also refocus the stats row. + +**Step 1: Update tab label in +page.svelte** + +In `frontend/src/routes/sync/+page.svelte`, change the "members" tab trigger: + +```svelte + +Team +``` + +Also update the TabsContent value from "members" to "team": + +```svelte + + + +``` + +Update the import: rename `MembersTab` → `TeamTab` and update the import path to `./TeamTab.svelte`. + +Update the default tab in the `handleCreateTeam` function — it currently sets `activeTab = 'overview'`; leave as-is since team creation still happens via TeamSelector. + +**Step 2: Strip OverviewTab** + +Remove from `OverviewTab.svelte`: + +1. **Team Management section** (lines ~290-336): The entire `
` with heading "Team" that shows active team display and delete team button. This moves to TeamTab. + +2. **Getting Started section** (lines ~371-397): The entire `{#if showGettingStarted}` block with the numbered steps. This moves to TeamTab. + +3. **Sync ID from Machine Details** (lines ~420-441): Remove the `{#if detect?.device_id}` block showing "Sync ID" with copy button inside Machine Details. This moves to TeamTab. Keep the machine details card but without the Sync ID row. + +4. **Remove related state**: `deleteConfirm`, `deletingTeam`, `deleteTeam()`, `showGettingStarted` derived, and the `copiedDeviceId`/`copyDeviceId` function (these move to TeamTab). + +**Step 3: Refocus stats row** + +Change the 4 stat cards from: +- Members / Projects / Synced In / Synced Out + +To: +- Members Online (e.g., "2/3") / Projects Syncing / Sessions Shared / Sessions Received + +This requires fetching device connection data. Add to `loadStats()`: + +```typescript +// Fetch devices to count connected members +const devicesRes = await fetch(`${API_BASE}/sync/devices`).catch(() => null); +let connectedCount = 0; +let totalDeviceCount = 0; +if (devicesRes?.ok) { + const devData = await devicesRes.json(); + const devices = devData.devices ?? []; + // Exclude self device + const remoteDevices = devices.filter((d: { is_self?: boolean }) => !d.is_self); + totalDeviceCount = remoteDevices.length; + connectedCount = remoteDevices.filter((d: { connected?: boolean }) => d.connected).length; +} + +// Fetch project status for session counts +let sessionsShared = 0; +let sessionsReceived = 0; +if (teamName) { + const statusRes = await fetch( + `${API_BASE}/sync/teams/${encodeURIComponent(teamName)}/project-status` + ).catch(() => null); + if (statusRes?.ok) { + const statusData = await statusRes.json(); + const projects = statusData.projects ?? []; + for (const p of projects) { + sessionsShared += p.packaged_count ?? 0; + const received = p.received_counts ?? {}; + for (const count of Object.values(received)) { + sessionsReceived += (count as number) ?? 0; + } + } + } +} +``` + +Update stat card state variables: + +```typescript +let connectedMembers = $state(0); +let totalMembers = $state(0); +let sessionsSharedCount = $state(0); +let sessionsReceivedCount = $state(0); +``` + +Update the stat cards markup: + +```svelte + +
+ +

+ {connectedMembers}/{totalMembers} +

+

Members Online

+
+ + +
+ +

{projectCount}

+

Projects

+
+ + +
+ +

{sessionsSharedCount}

+

Sessions Shared

+
+ + +
+ +

{sessionsReceivedCount}

+

Sessions Received

+
+``` + +**Step 4: Conditionally render Pending Actions** + +Change the Pending Actions section so it only renders when there are pending items. Replace: + +```svelte + +
+``` + +With: + +```svelte +{#if !pendingLoading && pendingFolders.length > 0} +
+ +
+{/if} +``` + +Remove the `{:else if pendingFolders.length === 0}` empty state block entirely (the green checkmark "No pending actions" section). + +**Step 5: Verify and commit** + +Run: `cd frontend && npm run check` +Expected: No type errors + +```bash +git add frontend/src/lib/components/sync/OverviewTab.svelte frontend/src/routes/sync/+page.svelte +git commit -m "refactor: strip Overview tab — move team mgmt, sync ID, getting started to Team tab" +``` + +--- + +### Task 2: Create TeamTab component (rename from MembersTab) + +**Files:** +- Rename: `frontend/src/lib/components/sync/MembersTab.svelte` → `frontend/src/lib/components/sync/TeamTab.svelte` +- Modify: `frontend/src/routes/sync/+page.svelte` (import) + +**Context:** The current MembersTab already has member list, add member form, and "Your Sync ID". We need to add: team header card with delete action, and getting started guide (moved from Overview). + +**Step 1: Rename the file** + +```bash +cd frontend/src/lib/components/sync +mv MembersTab.svelte TeamTab.svelte +``` + +**Step 2: Update import in +page.svelte** + +```typescript +// Change: +import MembersTab from '$lib/components/sync/MembersTab.svelte'; +// To: +import TeamTab from '$lib/components/sync/TeamTab.svelte'; +``` + +**Step 3: Add `onteamchange` prop to TeamTab** + +Add to props: + +```typescript +let { + detect, + active = false, + teamName = null, + onteamchange // NEW +}: { + detect: SyncDetect | null; + active?: boolean; + teamName: string | null; + onteamchange?: () => void; // NEW +} = $props(); +``` + +**Step 4: Add Team Header Card with delete action** + +Add at the top of the `{:else}` block (after `{#if !teamName}` ... `{:else}`), before "Your Sync ID": + +```svelte + +
+
+
+ +
+

{teamName}

+

Syncthing team

+
+
+ {#if deleteConfirm} +
+ Delete team? + + +
+ {:else} + + {/if} +
+
+``` + +Add the state and function for team deletion (moved from OverviewTab): + +```typescript +let deletingTeam = $state(false); +let deleteConfirm = $state(false); + +async function deleteTeam() { + if (!teamName) return; + deletingTeam = true; + try { + const res = await fetch(`${API_BASE}/sync/teams/${encodeURIComponent(teamName)}`, { + method: 'DELETE' + }); + if (res.ok) { + deleteConfirm = false; + showFlash(`Team "${teamName}" deleted`); + onteamchange?.(); + } + } catch { + // ignore + } finally { + deletingTeam = false; + } +} +``` + +Add the `Trash2` import from `lucide-svelte`. + +**Step 5: Add Getting Started guide for empty team** + +After the member list empty state (`{:else if members.length === 0}`), add a getting started section: + +```svelte +{:else if members.length === 0} + +
+ +

No team members yet

+

+ Add a teammate below using their Sync ID, or share yours so they can add you. +

+
+ + +
+
+ +

Getting Started

+
+
    +
  1. + 1 +
    +

    Add a teammate

    +

    Paste their Sync ID in the form below

    +
    +
    2. +
  2. + 2 +
    +

    Enable project sync

    +

    Switch to the Projects tab to choose which projects to sync

    +
    +
    3. +
  3. + 3 +
    +

    Start the sync engine

    +

    Go to Overview and click Start to begin watching for changes

    +
    +
    4. +
+
+``` + +Add the `Sparkles` import from `lucide-svelte`. + +**Step 6: Verify and commit** + +Run: `cd frontend && npm run check` +Expected: No type errors + +```bash +git add frontend/src/lib/components/sync/TeamTab.svelte frontend/src/routes/sync/+page.svelte +git rm frontend/src/lib/components/sync/MembersTab.svelte +git commit -m "refactor: rename MembersTab → TeamTab, add team header card + getting started guide" +``` + +--- + +### Task 3: Enhance ProjectsTab — surface full sync health + +**Files:** +- Modify: `frontend/src/lib/components/sync/ProjectRow.svelte` + +**Context:** ProjectRow already has an expanded view with `projectStatus` data (local_count, packaged_count, received_counts, gap). But the collapsed row only shows session count and a badge. We need to surface the gap indicator in the collapsed view so users don't have to expand every row. + +**Step 1: Add gap indicator to collapsed row** + +In `ProjectRow.svelte`, inside the collapsed row's right-side div (after the session count span, around line ~165), add: + +```svelte + +{#if projectStatus && project.synced} + {#if projectStatus.gap > 0} + + {projectStatus.gap} behind + + {:else if projectStatus.packaged_count > 0} + up to date + {/if} +{/if} +``` + +**Step 2: Show received session totals in collapsed view** + +After the gap indicator, add a received count summary: + +```svelte +{#if projectStatus && project.synced} + {@const totalReceived = Object.values(projectStatus.received_counts).reduce((a, b) => a + b, 0)} + {#if totalReceived > 0} + + {/if} +{/if} +``` + +**Step 3: Verify and commit** + +Run: `cd frontend && npm run check` +Expected: No type errors + +```bash +git add frontend/src/lib/components/sync/ProjectRow.svelte +git commit -m "feat: show sync gap + received count in collapsed project row" +``` + +--- + +### Task 4: Refocus ActivityTab — human-readable session events + +**Files:** +- Modify: `frontend/src/lib/components/sync/ActivityTab.svelte` + +**Context:** Currently shows raw Syncthing events (FolderCompletion, StateChanged, etc.) and a full bandwidth chart. We refocus on session-meaningful descriptions, compact bandwidth display, and collapsible folder details. + +**Step 1: Replace bandwidth chart with compact status bar** + +Replace the bandwidth section (the `
` containing ``) with a compact inline display: + +```svelte + +
+ Transfer Rate +
+ + + {formatBytesRate(uploadRate)} + + + + {formatBytesRate(downloadRate)} + +
+
+``` + +Remove the `BandwidthChart` import and the `uploadHistory`, `downloadHistory`, `labels`, `pushHistory()`, `timeLabel()` state/functions since we no longer need the chart. + +Simplify `fetchActivity` to no longer call `pushHistory`: + +```typescript +// Remove: pushHistory(uploadRate, downloadRate); +// Just assign the rates directly +uploadRate = data.upload_rate ?? 0; +downloadRate = data.download_rate ?? 0; +``` + +**Step 2: Translate events to session-meaningful descriptions** + +Replace the `formatEvent` function with session-focused translations: + +```typescript +function formatEvent(event: SyncEvent): { title: string; detail: string; dotColor: string } { + const folder = (event.data?.folder as string) || ''; + const device = (event.data?.device as string) || (event.data?.id as string) || ''; + const folderName = resolveFolderName(folder); + const deviceName = resolveDeviceName(device); + + switch (event.type) { + case 'ItemFinished': { + const item = (event.data?.item as string) || ''; + const isSession = item.endsWith('.jsonl'); + const isManifest = item === 'manifest.json'; + if (isSession) { + return { + title: `Session synced`, + detail: `${folderName} — ${item.replace('.jsonl', '').slice(0, 8)}...`, + dotColor: 'bg-[var(--success)]' + }; + } + if (isManifest) { + return { + title: 'Sync manifest updated', + detail: folderName, + dotColor: 'bg-[var(--success)]' + }; + } + return { + title: 'File synced', + detail: `${folderName} — ${item}`, + dotColor: 'bg-[var(--success)]' + }; + } + case 'DeviceConnected': + return { + title: `${deviceName || 'Teammate'} connected`, + detail: 'Ready to sync sessions', + dotColor: 'bg-[var(--success)]' + }; + case 'DeviceDisconnected': + return { + title: `${deviceName || 'Teammate'} went offline`, + detail: '', + dotColor: 'bg-[var(--text-muted)]' + }; + case 'FolderCompletion': { + const pct = (event.data?.completion as number) ?? 0; + if (pct >= 100) { + return { + title: 'All sessions up to date', + detail: folderName, + dotColor: 'bg-[var(--success)]' + }; + } + return { + title: `Syncing sessions — ${pct}%`, + detail: folderName, + dotColor: 'bg-[var(--info)]' + }; + } + case 'FolderSummary': + return { + title: 'Scan completed', + detail: folderName, + dotColor: 'bg-[var(--text-muted)]' + }; + case 'StateChanged': { + const to = (event.data?.to as string) || ''; + if (to === 'idle') { + return { + title: 'Sync completed', + detail: folderName, + dotColor: 'bg-[var(--success)]' + }; + } + if (to === 'syncing') { + return { + title: 'Syncing sessions...', + detail: folderName, + dotColor: 'bg-[var(--info)]' + }; + } + if (to === 'scanning') { + return { + title: 'Scanning for changes...', + detail: folderName, + dotColor: 'bg-[var(--info)]' + }; + } + return { + title: `State: ${to}`, + detail: folderName, + dotColor: 'bg-[var(--text-muted)]' + }; + } + case 'FolderErrors': + return { + title: 'Sync error', + detail: ((event.data?.errors as Array<{ error: string }>) || [])[0]?.error || 'Unknown error', + dotColor: 'bg-[var(--error)]' + }; + default: + return { + title: event.type.replace(/([A-Z])/g, ' $1').trim(), + detail: deviceName || folderName || '', + dotColor: 'bg-[var(--text-muted)]' + }; + } +} +``` + +**Step 3: Make folder stats collapsible** + +Wrap the "Synced Folders" section in a collapsible toggle: + +```svelte +{#if folderStats.length > 0} +
+ + {#if showFolderDetails} +
+ +
+ {/if} +
+{/if} +``` + +Add state: + +```typescript +let showFolderDetails = $state(false); +``` + +Add `ChevronDown`, `ChevronRight` imports from `lucide-svelte`. + +Remove the `syncedUpTotal` and `syncedDownTotal` derived values and their footer display (these were byproducts of the old bandwidth section). + +**Step 4: Verify and commit** + +Run: `cd frontend && npm run check` +Expected: No type errors + +```bash +git add frontend/src/lib/components/sync/ActivityTab.svelte +git commit -m "refactor: refocus Activity tab — session-level events, compact bandwidth, collapsible folders" +``` + +--- + +### Task 5: Clean up unused imports and files + +**Files:** +- Check: `frontend/src/lib/components/sync/BandwidthChart.svelte` — verify no other component imports it +- Modify: `frontend/src/routes/sync/+page.svelte` — verify all imports are correct after renaming + +**Step 1: Check if BandwidthChart is imported anywhere else** + +Run: `cd frontend && grep -r "BandwidthChart" src/` + +If only ActivityTab imported it (which we removed in Task 4), the file can be kept for future use but is no longer imported. + +**Step 2: Verify page.svelte imports** + +Ensure `+page.svelte` has: +```typescript +import TeamTab from '$lib/components/sync/TeamTab.svelte'; +// NOT: import MembersTab from ... +``` + +And the TabsContent for "team" uses ``. + +**Step 3: Run full type check and dev server** + +```bash +cd frontend && npm run check +cd frontend && npm run dev # verify in browser +``` + +**Step 4: Commit cleanup** + +```bash +git add -A frontend/src/ +git commit -m "chore: clean up imports after sync tab redesign" +``` + +--- + +### Task 6: Pass server-loaded data through to tabs + +**Files:** +- Modify: `frontend/src/routes/sync/+page.svelte` +- Modify: `frontend/src/lib/components/sync/OverviewTab.svelte` + +**Context:** The `+page.server.ts` already fetches `watchStatus` and `pending` data on server load, but the current `+page.svelte` doesn't pass them to OverviewTab — instead, OverviewTab re-fetches them client-side. We should pass them as initial values to avoid duplicate fetches on load. + +**Step 1: Pass server data to OverviewTab** + +In `+page.svelte`, update the OverviewTab usage: + +```svelte + +``` + +**Step 2: Accept initial data in OverviewTab** + +Add to OverviewTab props: + +```typescript +let { + detect = null, + status = null, + active = false, + teamName = null, + onteamchange, + initialWatchStatus = null, // NEW + initialPending = [] // NEW +}: { + // ... existing types ... + initialWatchStatus?: SyncWatchStatus | null; + initialPending?: SyncPendingFolder[]; +} = $props(); +``` + +Use them as initial state: + +```typescript +let watchStatus = $state(initialWatchStatus ?? null); +let pendingFolders = $state(initialPending ?? []); +let watchLoading = $state(initialWatchStatus === null); +let pendingLoading = $state(initialPending.length === 0 && initialWatchStatus === null); +``` + +**Step 3: Verify and commit** + +Run: `cd frontend && npm run check` + +```bash +git add frontend/src/routes/sync/+page.svelte frontend/src/lib/components/sync/OverviewTab.svelte +git commit -m "perf: pass server-loaded watch/pending data to OverviewTab, avoid duplicate fetches" +``` + +--- + +### Task 7: Final integration test + +**Step 1: Manual verification checklist** + +Start the dev servers: +```bash +cd api && uvicorn main:app --reload --port 8000 & +cd frontend && npm run dev +``` + +Open `http://localhost:5173/sync` and verify: + +1. **Overview tab**: Sync engine banner, 4 refocused stats (members online, projects, sessions shared, sessions received), pending actions only when > 0, machine details without Sync ID +2. **Team tab**: Team header with delete, Your Sync ID with copy, member list with device cards, add member form, getting started guide when empty +3. **Projects tab**: Project list with gap indicator visible in collapsed rows, received count in collapsed rows +4. **Activity tab**: Compact bandwidth bar (no chart), session-meaningful event descriptions, collapsible folder details +5. **Tab switching**: URL updates with `?tab=team`, `?tab=projects` etc. +6. **No duplication**: Sync ID only in Team tab. Member count only in TeamSelector + Overview stats. Delete team only in Team tab. + +**Step 2: Type check** + +```bash +cd frontend && npm run check +``` + +**Step 3: Final commit (if any fixes needed)** + +```bash +git add -A frontend/src/ +git commit -m "fix: sync tab integration fixes" +``` diff --git a/docs/plans/2026-03-06-sync-page-tabs-redesign.md b/docs/plans/2026-03-06-sync-page-tabs-redesign.md new file mode 100644 index 00000000..16d8cd3d --- /dev/null +++ b/docs/plans/2026-03-06-sync-page-tabs-redesign.md @@ -0,0 +1,135 @@ +# Sync Page Tabs Redesign + +Date: 2026-03-06 +Status: Approved + +## Problem + +The current sync page has 4 tabs (Overview, Members, Projects, Activity) with several UX issues: + +1. **Overview is overloaded** — contains sync engine control, team management, stats, getting started guide, machine details, AND pending actions (6 concerns). +2. **Information duplication** — "Your Sync ID" appears in both Overview and Members. Member/project counts in TeamSelector AND Overview stats. +3. **Team management is scattered** — create team via TeamSelector, delete in Overview, add members in Members tab. +4. **Activity shows raw Syncthing events** — `FolderCompletion`, `StateChanged` etc. are meaningless to users who care about session sync. + +## Design + +### Tab Structure + +``` +Overview | Team | Projects | Activity +``` + +Four tabs with clear, non-overlapping responsibilities. + +### Tab 1: Overview — "What's happening right now?" + +At-a-glance health check. Is sync working? Any problems? + +**Sections (top to bottom):** + +1. **Sync Engine Banner** — full-width, prominent. Running/Stopped status with start/stop button. The #1 operational control. + +2. **Stats Row** (4 cards): + - Members Online: `2/3 connected` + - Projects Syncing: `4 projects` + - Sessions Shared: total packaged count (outbox) + - Sessions Received: total received from teammates (inboxes) + +3. **Pending Actions** — only renders when count > 0. Folder offers from teammates needing acceptance. When zero, section doesn't appear at all. + +4. **Machine Details** — your name, machine ID, Sync ID with copy button, Syncthing version. Reference info at the bottom. + +### Tab 2: Team — "Who am I syncing with?" + +Replaces "Members" tab. Absorbs team-level config that was scattered across Overview and Members. + +**Sections:** + +1. **Team Header Card** — team name, backend type. "Delete Team" as a danger-zone action (behind `...` menu or at bottom). + +2. **Your Sync ID** (copyable) — "Share this with teammates to connect." Natural home: you're looking at team membership. + +3. **Members List** — each member as a card: + - Name, connection status dot (green/gray) + - Data transferred (in/out bytes) + - Last seen / address + - Remove button (hover-reveal) + +4. **Add Member Form** — inline at bottom: Sync ID input + Name input + Add button. + +### Tab 3: Projects — "What am I syncing?" + +Toggle which projects sync. See per-project health. + +**Sections:** + +1. **Header row** — "X of Y syncing" + "Enable All" button + search filter + +2. **Project List** — each row: + - Project name + path + - Toggle switch (synced/not synced) + - Sync health when enabled: + - Local sessions count + - Packaged count (outbox) + - Gap indicator ("3 behind" warning, or "up to date" green) + - Per-member received counts (e.g., "alice: 12, bob: 8") + - "Sync Now" button + +### Tab 4: Activity — "What happened recently?" + +Session-level sync feed. Human-readable, not raw Syncthing events. + +**Sections:** + +1. **Header** — "Activity" + "Sync Now" button (rescan all) + +2. **Live Status Bar** (compact) — upload/download rate, single line. No full bandwidth chart. + +3. **Session Activity Feed** — translated events: + - "alice synced 3 sessions for claude-karma — 5 min ago" + - "bob's machine connected — 12 min ago" + - "Received 2 new sessions from alice — 1 hr ago" + +4. **Folder Status** (collapsible, advanced) — raw Syncthing folder stats. Collapsed by default with "Show folder details" toggle. + +## Information Placement Rules (no duplication) + +| Information | Lives in | NOT in | +|---|---|---| +| Sync engine start/stop | Overview | — | +| Members online count | Overview (stats) | Team tab | +| Member list + connection details | Team tab | Overview | +| Your Sync ID | Team tab | Overview | +| Machine details (name, hostname, version) | Overview | Team tab | +| Project list + toggle | Projects tab | Overview | +| Project sync health (local/packaged/gap) | Projects tab | Activity | +| Pending folder offers | Overview | Team tab | +| Session activity feed | Activity tab | Overview | +| Bandwidth rates | Activity tab (compact) | Overview | +| Delete team | Team tab | Overview | + +## Non-goals + +- No admin/member privilege system (fully peer-to-peer, trust-based) +- No multi-team dashboard view (team-scoped via TeamSelector) +- No raw bandwidth chart (users can open Syncthing UI at localhost:8384) + +## CLI Feature Parity + +All CLI sync features accessible via web UI: + +| CLI Command | Web UI Location | +|---|---| +| `karma init --backend syncthing` | SetupWizard (pre-tabs) | +| `karma team create` | TeamSelector "+ New Team" | +| `karma team add` | Team tab → Add Member form | +| `karma team remove` | Team tab → member hover → Remove | +| `karma team list` | Team tab → Members List | +| `karma project add --team` | Projects tab → toggle on | +| `karma project remove --team` | Projects tab → toggle off | +| `karma project list` | Projects tab | +| `karma watch --team` | Overview → Sync Engine start | +| `karma accept` | Overview → Pending Actions → Accept All | +| `karma status` | Overview (stats) + Projects tab (per-project health) | +| `karma ls` | Projects tab (received counts per member) | diff --git a/docs/plans/2026-03-06-syncthing-worktree-sync-fix-plan.md b/docs/plans/2026-03-06-syncthing-worktree-sync-fix-plan.md new file mode 100644 index 00000000..db5799d7 --- /dev/null +++ b/docs/plans/2026-03-06-syncthing-worktree-sync-fix-plan.md @@ -0,0 +1,1092 @@ +# Syncthing Worktree Session Sync — Verification & Fix Plan + +> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. + +**Goal:** Fix three bugs preventing worktree sessions from syncing between teammates: stale `karma watch` process, missing Desktop worktree discovery in CLI packager, and consolidate the fragmented session→project mapping logic so all session sources (local, worktree, desktop-worktree, remote) are handled consistently. + +**Architecture:** The CLI packager already supports CLI worktrees via `find_worktree_dirs()` prefix matching. We add Desktop worktree discovery (Strategy A: filesystem scan of `~/.claude-worktrees/`), fix the stale watch process, and add a verification test suite that catches these mapping gaps. On the API side, `list_remote_sessions_for_project()` already works correctly — the fix is entirely on the CLI packaging/sending side. + +**Tech Stack:** Python 3.9+, click (CLI), watchdog (filesystem events), Pydantic 2.x (models), pytest (testing) + +**Root Cause Analysis (from deep search):** + +| Issue | Root Cause | Impact | +|-------|-----------|--------| +| `karma watch --team beta` is zombie | Team `beta` was renamed to `Ayush-stealing-prompts` in config | Watch does nothing; outbox stale since Mar 4 | +| Outbox has 0 worktree sessions | Manifest created before `worktree_name`/`extra_dirs` were added | Friend can't see your worktree work | +| Desktop worktrees not discovered | `find_worktree_dirs()` uses prefix matching; Desktop worktrees have different encoded name pattern | 2 sessions from focused-jepsen/lucid-villani missing | +| 3 separate mapping systems | `utils.py`, `desktop_sessions.py`, `remote_sessions.py` each handle one case independently | No unified view; easy to miss a source | + +**Current session counts NOT in outbox:** +- CLI worktrees: 40 sessions (syncthing-sync-design: 23, ipfs-sync-design: 11, opencode-integration-design: 4, fix-command-skill-tracking: 1, syncthing-sync-design-api: 1) +- Desktop worktrees: 2 sessions (focused-jepsen: 1, lucid-villani: 1) + +--- + +## Task 1: Verify current state with diagnostic script + +Before changing anything, verify the exact state of the system so we can confirm fixes work. + +**Files:** +- Create: `cli/tests/test_sync_diagnostics.py` + +**Step 1: Write diagnostic tests** + +```python +# cli/tests/test_sync_diagnostics.py +"""Diagnostic tests that verify the sync pipeline state. + +These tests use the REAL filesystem (not mocks) to verify the actual +state of the sync pipeline on this machine. They document what IS, +not what SHOULD BE, so they serve as regression tests after fixes. +""" + +import json +from pathlib import Path + +import pytest + + +PROJECTS_DIR = Path.home() / ".claude" / "projects" +KARMA_BASE = Path.home() / ".claude_karma" +MAIN_ENCODED = "-Users-jayantdevkar-Documents-GitHub-claude-karma" + + +@pytest.mark.skipif( + not PROJECTS_DIR.exists(), reason="No ~/.claude/projects/ on this machine" +) +class TestSyncDiagnostics: + def test_cli_worktree_dirs_exist(self): + """CLI worktree dirs should exist in ~/.claude/projects/.""" + from karma.worktree_discovery import find_worktree_dirs + + wt_dirs = find_worktree_dirs(MAIN_ENCODED, PROJECTS_DIR) + # We know there are at least 5 CLI worktree dirs + assert len(wt_dirs) >= 5, ( + f"Expected >=5 CLI worktree dirs, found {len(wt_dirs)}: " + f"{[d.name for d in wt_dirs]}" + ) + + def test_desktop_worktree_dirs_exist(self): + """Desktop worktree project dirs exist but aren't found by find_worktree_dirs.""" + from karma.worktree_discovery import find_worktree_dirs + + # These exist on disk + desktop_wt_dirs = list(PROJECTS_DIR.glob( + "-Users-jayantdevkar--claude-worktrees-claude-karma-*" + )) + assert len(desktop_wt_dirs) >= 2, "Desktop worktree dirs should exist" + + # But find_worktree_dirs doesn't find them (prefix doesn't match) + found = find_worktree_dirs(MAIN_ENCODED, PROJECTS_DIR) + found_names = {d.name for d in found} + for dw in desktop_wt_dirs: + assert dw.name not in found_names, ( + f"Desktop worktree {dw.name} should NOT be found by prefix match" + ) + + def test_outbox_manifest_is_stale(self): + """Outbox manifest should exist but lack worktree_name fields.""" + manifest_path = ( + KARMA_BASE / "remote-sessions" / "jay" / MAIN_ENCODED / "manifest.json" + ) + if not manifest_path.exists(): + pytest.skip("No outbox manifest") + + manifest = json.loads(manifest_path.read_text()) + # Check that sessions don't have worktree_name + sessions_with_wt = [ + s for s in manifest["sessions"] if s.get("worktree_name") + ] + # This documents the CURRENT bug — after fix, this test should be updated + assert len(sessions_with_wt) == 0, ( + "Outbox currently has no worktree sessions (this is the bug)" + ) + + def test_config_team_name_vs_watch_process(self): + """Config should have a team; watch may be running with wrong name.""" + config_path = KARMA_BASE / "sync-config.json" + if not config_path.exists(): + pytest.skip("No sync config") + + config = json.loads(config_path.read_text()) + teams = list(config.get("teams", {}).keys()) + assert len(teams) >= 1, "Should have at least one team" + # Document: the team is NOT called 'beta' + assert "beta" not in teams, ( + "Team 'beta' should not exist (was renamed)" + ) +``` + +**Step 2: Run diagnostic tests** + +Run: `cd cli && pytest tests/test_sync_diagnostics.py -v` +Expected: All PASS (they document current bugs as assertions) + +**Step 3: Commit** + +```bash +git add cli/tests/test_sync_diagnostics.py +git commit -m "test(cli): add sync pipeline diagnostic tests + +Documents current state: stale outbox, missing worktree sessions, +Desktop worktrees not discovered by prefix matching." +``` + +--- + +## Task 2: Add Desktop worktree discovery to CLI + +The CLI's `find_worktree_dirs()` only finds CLI/superpowers worktrees via prefix matching. Desktop worktrees (`~/.claude-worktrees/{project}/{name}`) use a completely different encoded name pattern. Add a new function that scans the worktree base dir and matches by project name suffix. + +**Files:** +- Modify: `cli/karma/worktree_discovery.py` +- Modify: `cli/tests/test_worktree_discovery.py` + +**Step 1: Write failing tests** + +Add to `cli/tests/test_worktree_discovery.py`: + +```python +# Add these imports at the top if not present +from karma.worktree_discovery import find_desktop_worktree_dirs + + +class TestFindDesktopWorktreeDirs: + """Desktop worktrees live in ~/.claude-worktrees/{project}/{name}. + + Their encoded names in ~/.claude/projects/ look like: + -Users-{user}--claude-worktrees-{project}-{name} + + These DON'T share a prefix with the main project, so they need + a different discovery strategy: scan the worktree base dir. + """ + + def test_finds_desktop_worktrees_by_project_name(self, tmp_path): + """Desktop worktrees are found by matching project name in encoded dir.""" + projects_dir = tmp_path / "projects" + worktree_base = tmp_path / ".claude-worktrees" + + # Main project + main = projects_dir / "-Users-jay-GitHub-claude-karma" + main.mkdir(parents=True) + + # Desktop worktree base — the actual worktree dirs + wt_actual = worktree_base / "claude-karma" / "focused-jepsen" + wt_actual.mkdir(parents=True) + + # The corresponding ~/.claude/projects/ dir (with encoded name) + wt_encoded = projects_dir / "-Users-jay--claude-worktrees-claude-karma-focused-jepsen" + wt_encoded.mkdir(parents=True) + (wt_encoded / "session.jsonl").write_text('{"type":"user"}\n') + + result = find_desktop_worktree_dirs( + project_name="claude-karma", + projects_dir=projects_dir, + worktree_base=worktree_base, + ) + assert len(result) == 1 + assert result[0] == wt_encoded + + def test_finds_multiple_desktop_worktrees(self, tmp_path): + projects_dir = tmp_path / "projects" + worktree_base = tmp_path / ".claude-worktrees" + + # Main project + (projects_dir / "-Users-jay-GitHub-karma").mkdir(parents=True) + + # Two desktop worktrees + for name in ("focused-jepsen", "lucid-villani"): + (worktree_base / "karma" / name).mkdir(parents=True) + wt_enc = projects_dir / f"-Users-jay--claude-worktrees-karma-{name}" + wt_enc.mkdir(parents=True) + (wt_enc / "session.jsonl").write_text('{"type":"user"}\n') + + result = find_desktop_worktree_dirs( + project_name="karma", + projects_dir=projects_dir, + worktree_base=worktree_base, + ) + assert len(result) == 2 + + def test_ignores_other_project_worktrees(self, tmp_path): + projects_dir = tmp_path / "projects" + worktree_base = tmp_path / ".claude-worktrees" + + (projects_dir / "-Users-jay-GitHub-karma").mkdir(parents=True) + + # Worktree for a DIFFERENT project + (worktree_base / "hubdata" / "feat-x").mkdir(parents=True) + wt_enc = projects_dir / "-Users-jay--claude-worktrees-hubdata-feat-x" + wt_enc.mkdir(parents=True) + + result = find_desktop_worktree_dirs( + project_name="karma", + projects_dir=projects_dir, + worktree_base=worktree_base, + ) + assert len(result) == 0 + + def test_returns_empty_when_no_worktree_base(self, tmp_path): + projects_dir = tmp_path / "projects" + (projects_dir / "-Users-jay-GitHub-karma").mkdir(parents=True) + + result = find_desktop_worktree_dirs( + project_name="karma", + projects_dir=projects_dir, + worktree_base=tmp_path / "nonexistent", + ) + assert result == [] + + def test_returns_empty_when_project_has_no_desktop_worktrees(self, tmp_path): + projects_dir = tmp_path / "projects" + worktree_base = tmp_path / ".claude-worktrees" + worktree_base.mkdir() + + (projects_dir / "-Users-jay-GitHub-karma").mkdir(parents=True) + + result = find_desktop_worktree_dirs( + project_name="karma", + projects_dir=projects_dir, + worktree_base=worktree_base, + ) + assert result == [] + + def test_handles_cleaned_up_worktree_dirs(self, tmp_path): + """Worktree dirs may be cleaned up but ~/.claude/projects/ dirs remain.""" + projects_dir = tmp_path / "projects" + worktree_base = tmp_path / ".claude-worktrees" + + (projects_dir / "-Users-jay-GitHub-karma").mkdir(parents=True) + + # Worktree base exists but is empty (worktrees were cleaned up) + (worktree_base / "karma").mkdir(parents=True) + + # But the projects dir still has the encoded dir with session data + wt_enc = projects_dir / "-Users-jay--claude-worktrees-karma-old-branch" + wt_enc.mkdir(parents=True) + (wt_enc / "session.jsonl").write_text('{"type":"user"}\n') + + # Can still find it by scanning projects_dir for the pattern + result = find_desktop_worktree_dirs( + project_name="karma", + projects_dir=projects_dir, + worktree_base=worktree_base, + ) + # Should find it even though the actual worktree dir is gone + assert len(result) == 1 +``` + +**Step 2: Run tests to verify they fail** + +Run: `cd cli && pytest tests/test_worktree_discovery.py::TestFindDesktopWorktreeDirs -v` +Expected: FAIL — `ImportError: cannot import name 'find_desktop_worktree_dirs'` + +**Step 3: Implement `find_desktop_worktree_dirs`** + +Add to `cli/karma/worktree_discovery.py` (after existing code): + +```python +def _extract_project_name_from_encoded(encoded_name: str) -> str | None: + """Extract project name (last path segment) from encoded name. + + "-Users-jay-Documents-GitHub-claude-karma" -> "claude-karma" + + This is inherently lossy (dashes in the project name are ambiguous), + so we use it only as a hint and verify against known worktree dirs. + """ + if not encoded_name or not encoded_name.startswith("-"): + return None + # The last segment after the final path separator + # But since all separators are dashes, we can't split reliably. + # Instead, we return the full encoded name for prefix/suffix matching. + return encoded_name + + +def find_desktop_worktree_dirs( + project_name: str, + projects_dir: Path, + worktree_base: Path | None = None, +) -> list[Path]: + """Find Desktop worktree directories for a project. + + Desktop worktrees (created by Claude Desktop's "Claude Code" mode) + live in ~/.claude-worktrees/{project_name}/{random_name}/ and get + encoded as: -Users-{user}--claude-worktrees-{project}-{name} + + These DON'T share an encoded name prefix with the main project, + so we can't use prefix matching. Instead we: + 1. Scan projects_dir for dirs containing '-claude-worktrees-{project_name}-' + 2. Optionally verify against actual worktree base dir + + This also finds "orphaned" worktree project dirs where the actual + worktree has been cleaned up but sessions remain. + + Args: + project_name: The project's directory name (e.g., "claude-karma"). + projects_dir: Path to ~/.claude/projects/ + worktree_base: Path to ~/.claude-worktrees/ (default: ~/.claude-worktrees) + + Returns: + List of Path objects for matching worktree project directories. + """ + if worktree_base is None: + worktree_base = Path.home() / ".claude-worktrees" + + if not projects_dir.is_dir(): + return [] + + # Pattern: encoded dirs containing -claude-worktrees-{project_name}- + # This catches both --claude-worktrees- and -.claude-worktrees- variants + marker = f"-claude-worktrees-{project_name}-" + + matches = [] + for entry in projects_dir.iterdir(): + if not entry.is_dir(): + continue + if marker not in entry.name: + continue + # Ensure this is actually a Desktop worktree pattern: + # The marker should NOT be preceded by the main project prefix + # (those are CLI worktrees, already handled by find_worktree_dirs) + prefix = _get_worktree_prefix(entry.name) + if prefix is not None: + # This is a CLI/superpowers worktree (prefix-style), skip it + # It would already be found by find_worktree_dirs() + continue + matches.append(entry) + + return sorted(matches) +``` + +**Step 4: Run tests to verify they pass** + +Run: `cd cli && pytest tests/test_worktree_discovery.py -v` +Expected: All tests PASS (existing + new) + +**Step 5: Commit** + +```bash +git add cli/karma/worktree_discovery.py cli/tests/test_worktree_discovery.py +git commit -m "feat(cli): add Desktop worktree discovery + +find_desktop_worktree_dirs() scans ~/.claude/projects/ for dirs +matching the -claude-worktrees-{project}- pattern that aren't +prefix-style CLI worktrees. Handles orphaned worktree dirs +where the actual worktree was cleaned up but sessions remain." +``` + +--- + +## Task 3: Extract project name from config for Desktop discovery + +The `find_desktop_worktree_dirs()` needs a `project_name` (e.g., "claude-karma"), but the config only stores `path` (e.g., "/Users/jayantdevkar/Documents/GitHub/claude-karma") and `encoded_name`. We need a helper to extract the project dir name from the path. + +**Files:** +- Modify: `cli/karma/worktree_discovery.py` +- Modify: `cli/tests/test_worktree_discovery.py` + +**Step 1: Write failing tests** + +Add to `cli/tests/test_worktree_discovery.py`: + +```python +from karma.worktree_discovery import project_name_from_path + + +class TestProjectNameFromPath: + def test_unix_path(self): + assert project_name_from_path("/Users/jay/GitHub/claude-karma") == "claude-karma" + + def test_nested_path(self): + assert project_name_from_path("/Users/jay/Documents/GitHub/my-project") == "my-project" + + def test_trailing_slash(self): + assert project_name_from_path("/Users/jay/repo/") == "repo" + + def test_windows_path(self): + assert project_name_from_path("C:\\Users\\jay\\repos\\karma") == "karma" + + def test_single_segment(self): + assert project_name_from_path("myproject") == "myproject" +``` + +**Step 2: Run to verify they fail** + +Run: `cd cli && pytest tests/test_worktree_discovery.py::TestProjectNameFromPath -v` +Expected: FAIL — `ImportError` + +**Step 3: Implement** + +Add to `cli/karma/worktree_discovery.py`: + +```python +def project_name_from_path(project_path: str) -> str: + """Extract the project directory name from a full path. + + "/Users/jay/GitHub/claude-karma" -> "claude-karma" + "C:\\Users\\jay\\repos\\karma" -> "karma" + """ + # Normalize separators + p = project_path.replace("\\", "/").rstrip("/") + return p.rsplit("/", 1)[-1] if "/" in p else p +``` + +**Step 4: Run tests** + +Run: `cd cli && pytest tests/test_worktree_discovery.py -v` +Expected: All PASS + +**Step 5: Commit** + +```bash +git add cli/karma/worktree_discovery.py cli/tests/test_worktree_discovery.py +git commit -m "feat(cli): add project_name_from_path helper + +Extracts directory name from full project path for Desktop +worktree discovery matching." +``` + +--- + +## Task 4: Wire Desktop worktree discovery into packager and watch + +Connect `find_desktop_worktree_dirs()` into the `sync_project()` and `watch` command so Desktop worktree sessions are included in the outbox. + +**Files:** +- Modify: `cli/karma/sync.py:60-70` (sync_project function) +- Modify: `cli/karma/main.py:506-561` (watch command) +- Modify: `cli/tests/test_packager.py` + +**Step 1: Write failing test for packager with desktop worktrees** + +Add to `cli/tests/test_packager.py`: + +```python +@pytest.fixture +def mock_project_with_desktop_worktree(tmp_path: Path) -> dict: + """Create a main project dir + one Desktop-style worktree dir.""" + projects_dir = tmp_path / ".claude" / "projects" + worktree_base = tmp_path / ".claude-worktrees" + + # Main project + main_dir = projects_dir / "-Users-jay-GitHub-karma" + main_dir.mkdir(parents=True) + (main_dir / "session-main.jsonl").write_text( + '{"type":"user","message":{"role":"user","content":"main"}}\n' + ) + + # Desktop worktree (different encoded name pattern) + wt_dir = projects_dir / "-Users-jay--claude-worktrees-karma-focused-jepsen" + wt_dir.mkdir(parents=True) + (wt_dir / "session-desktop-wt.jsonl").write_text( + '{"type":"user","message":{"role":"user","content":"desktop wt"}}\n' + ) + + # Actual worktree base dir + (worktree_base / "karma" / "focused-jepsen").mkdir(parents=True) + + return { + "main_dir": main_dir, + "wt_dir": wt_dir, + "projects_dir": projects_dir, + "worktree_base": worktree_base, + } + + +class TestPackagerWithDesktopWorktrees: + def test_discover_includes_desktop_worktree_sessions( + self, mock_project_with_desktop_worktree + ): + dirs = mock_project_with_desktop_worktree + packager = SessionPackager( + project_dir=dirs["main_dir"], + user_id="jay", + machine_id="mac", + extra_dirs=[dirs["wt_dir"]], + ) + sessions = packager.discover_sessions() + uuids = {s.uuid for s in sessions} + assert "session-main" in uuids + assert "session-desktop-wt" in uuids + + def test_desktop_worktree_sessions_have_worktree_name( + self, mock_project_with_desktop_worktree + ): + dirs = mock_project_with_desktop_worktree + packager = SessionPackager( + project_dir=dirs["main_dir"], + user_id="jay", + machine_id="mac", + extra_dirs=[dirs["wt_dir"]], + ) + sessions = packager.discover_sessions() + wt_session = [s for s in sessions if s.uuid == "session-desktop-wt"][0] + # The worktree name is extracted from the encoded dir name + assert wt_session.worktree_name is not None +``` + +**Step 2: Run to verify they pass** + +Run: `cd cli && pytest tests/test_packager.py::TestPackagerWithDesktopWorktrees -v` +Expected: PASS (the packager already handles `extra_dirs` — this just verifies it works for Desktop-style dirs too) + +**Step 3: Modify `sync_project()` to include Desktop worktrees** + +In `cli/karma/sync.py`, modify lines 60-70: + +```python +# Replace the existing import and extra_dirs construction: + + from karma.worktree_discovery import ( + find_worktree_dirs, + find_desktop_worktree_dirs, + project_name_from_path, + ) + + # CLI/superpowers worktrees (prefix match) + extra_dirs = find_worktree_dirs(project.encoded_name, projects_dir) + + # Desktop worktrees (project name match) + proj_name = project_name_from_path(project.path) + extra_dirs.extend( + find_desktop_worktree_dirs(proj_name, projects_dir) + ) + + packager = SessionPackager( + project_dir=claude_dir, + user_id=config.user_id, + machine_id=config.machine_id, + project_path=project.path, + last_sync_cid=project.last_sync_cid, + extra_dirs=extra_dirs, + ) +``` + +**Step 4: Modify `watch` command to include Desktop worktrees** + +In `cli/karma/main.py`, modify the watch command's inner loop (around lines 506-539): + +```python + from karma.worktree_discovery import ( + find_worktree_dirs, + find_desktop_worktree_dirs, + project_name_from_path, + ) + + watchers = [] + projects_dir = Path.home() / ".claude" / "projects" + + for proj_name, proj in team_cfg.projects.items(): + claude_dir = Path.home() / ".claude" / "projects" / proj.encoded_name + if not claude_dir.is_dir(): + click.echo(f" Skipping '{proj_name}': Claude dir not found ({claude_dir})") + continue + + # Discover worktree dirs for this project (CLI + Desktop) + wt_dirs = find_worktree_dirs(proj.encoded_name, projects_dir) + desktop_proj_name = project_name_from_path(proj.path) + desktop_wt_dirs = find_desktop_worktree_dirs(desktop_proj_name, projects_dir) + all_wt_dirs = wt_dirs + desktop_wt_dirs + if all_wt_dirs: + click.echo( + f" Found {len(wt_dirs)} CLI + {len(desktop_wt_dirs)} Desktop " + f"worktree dir(s) for '{proj_name}'" + ) + + outbox = KARMA_BASE / "remote-sessions" / config.user_id / proj.encoded_name + + def make_package_fn(cd=claude_dir, ob=outbox, pn=proj_name, en=proj.encoded_name, pp=proj.path): + def package(): + # Re-discover worktrees each time (new ones may appear) + current_wt_dirs = find_worktree_dirs(en, projects_dir) + current_desktop = find_desktop_worktree_dirs( + project_name_from_path(pp), projects_dir + ) + all_extra = current_wt_dirs + current_desktop + packager = SessionPackager( + project_dir=cd, + user_id=config.user_id, + machine_id=config.machine_id, + project_path=pp, + extra_dirs=all_extra, + ) + ob.mkdir(parents=True, exist_ok=True) + packager.package(staging_dir=ob) + click.echo( + f" Packaged '{pn}' -> {ob} " + f"({len(current_wt_dirs)} CLI + {len(current_desktop)} Desktop worktrees)" + ) + return package + + package_fn = make_package_fn() + + watcher = SessionWatcher( + watch_dir=claude_dir, + package_fn=package_fn, + ) + watcher.start() + watchers.append(watcher) + click.echo(f" Watching: {proj_name} ({claude_dir})") + + # Also watch each worktree dir (both CLI and Desktop) + for wt_dir in all_wt_dirs: + wt_watcher = SessionWatcher( + watch_dir=wt_dir, + package_fn=package_fn, + ) + wt_watcher.start() + watchers.append(wt_watcher) + # Extract a human-readable name + if "--claude-worktrees-" in wt_dir.name: + wt_name = wt_dir.name.split("--claude-worktrees-")[-1] + elif "-claude-worktrees-" in wt_dir.name: + # Desktop pattern: -Users-jay--claude-worktrees-karma-focused-jepsen + parts = wt_dir.name.split("-claude-worktrees-") + wt_name = parts[-1] if parts else wt_dir.name + else: + wt_name = wt_dir.name + click.echo(f" Watching worktree: {wt_name} ({wt_dir})") +``` + +**Step 5: Run tests** + +Run: `cd cli && pytest tests/test_packager.py tests/test_worktree_discovery.py -v` +Expected: All PASS + +**Step 6: Commit** + +```bash +git add cli/karma/sync.py cli/karma/main.py cli/tests/test_packager.py +git commit -m "feat(cli): wire Desktop worktree discovery into sync and watch + +Both sync_project() and karma watch now discover Desktop worktrees +(~/.claude-worktrees/) in addition to CLI worktrees. Desktop worktree +sessions are included in the outbox for Syncthing sync." +``` + +--- + +## Task 5: Add `find_all_worktree_dirs()` unified helper + +Create a single function that combines CLI + Desktop worktree discovery, reducing duplication in `sync.py` and `main.py`. + +**Files:** +- Modify: `cli/karma/worktree_discovery.py` +- Modify: `cli/tests/test_worktree_discovery.py` + +**Step 1: Write failing test** + +Add to `cli/tests/test_worktree_discovery.py`: + +```python +from karma.worktree_discovery import find_all_worktree_dirs + + +class TestFindAllWorktreeDirs: + def test_combines_cli_and_desktop_worktrees(self, tmp_path): + projects_dir = tmp_path / "projects" + worktree_base = tmp_path / ".claude-worktrees" + + # Main project + main = projects_dir / "-Users-jay-GitHub-karma" + main.mkdir(parents=True) + + # CLI worktree + cli_wt = projects_dir / "-Users-jay-GitHub-karma--claude-worktrees-feat-x" + cli_wt.mkdir(parents=True) + + # Desktop worktree + (worktree_base / "karma" / "focused-jepsen").mkdir(parents=True) + desktop_wt = projects_dir / "-Users-jay--claude-worktrees-karma-focused-jepsen" + desktop_wt.mkdir(parents=True) + + result = find_all_worktree_dirs( + main_encoded_name="-Users-jay-GitHub-karma", + project_path="/Users/jay/GitHub/karma", + projects_dir=projects_dir, + worktree_base=worktree_base, + ) + assert len(result) == 2 + assert cli_wt in result + assert desktop_wt in result + + def test_deduplicates_overlapping_results(self, tmp_path): + """If a dir matches both strategies, it should appear only once.""" + projects_dir = tmp_path / "projects" + + main = projects_dir / "-Users-jay-GitHub-karma" + main.mkdir(parents=True) + + wt = projects_dir / "-Users-jay-GitHub-karma--claude-worktrees-feat-x" + wt.mkdir(parents=True) + + result = find_all_worktree_dirs( + main_encoded_name="-Users-jay-GitHub-karma", + project_path="/Users/jay/GitHub/karma", + projects_dir=projects_dir, + ) + # CLI worktree found once, no duplicates + assert result.count(wt) == 1 +``` + +**Step 2: Run to verify they fail** + +Run: `cd cli && pytest tests/test_worktree_discovery.py::TestFindAllWorktreeDirs -v` +Expected: FAIL — `ImportError` + +**Step 3: Implement** + +Add to `cli/karma/worktree_discovery.py`: + +```python +def find_all_worktree_dirs( + main_encoded_name: str, + project_path: str, + projects_dir: Path, + worktree_base: Path | None = None, +) -> list[Path]: + """Find ALL worktree directories for a project (CLI + Desktop). + + Combines: + - find_worktree_dirs(): CLI/superpowers worktrees (prefix match) + - find_desktop_worktree_dirs(): Desktop worktrees (project name match) + + Args: + main_encoded_name: Main project's encoded dir name. + project_path: Original project path (e.g., "/Users/jay/GitHub/karma"). + projects_dir: Path to ~/.claude/projects/ + worktree_base: Path to ~/.claude-worktrees/ (default: auto-detect) + + Returns: + Deduplicated sorted list of worktree directory Paths. + """ + cli_dirs = find_worktree_dirs(main_encoded_name, projects_dir) + proj_name = project_name_from_path(project_path) + desktop_dirs = find_desktop_worktree_dirs(proj_name, projects_dir, worktree_base) + + # Deduplicate by resolved path + seen: set[Path] = set() + result: list[Path] = [] + for d in cli_dirs + desktop_dirs: + resolved = d.resolve() + if resolved not in seen: + seen.add(resolved) + result.append(d) + + return sorted(result) +``` + +**Step 4: Run tests** + +Run: `cd cli && pytest tests/test_worktree_discovery.py -v` +Expected: All PASS + +**Step 5: Simplify sync.py and main.py to use `find_all_worktree_dirs`** + +In `cli/karma/sync.py`, replace lines 60-70: + +```python + from karma.worktree_discovery import find_all_worktree_dirs + + packager = SessionPackager( + project_dir=claude_dir, + user_id=config.user_id, + machine_id=config.machine_id, + project_path=project.path, + last_sync_cid=project.last_sync_cid, + extra_dirs=find_all_worktree_dirs( + project.encoded_name, project.path, projects_dir + ), + ) +``` + +In `cli/karma/main.py` watch command, replace the discovery block: + +```python + from karma.worktree_discovery import find_all_worktree_dirs + + # ... inside the loop: + all_wt_dirs = find_all_worktree_dirs( + proj.encoded_name, proj.path, projects_dir + ) + if all_wt_dirs: + click.echo(f" Found {len(all_wt_dirs)} worktree dir(s) for '{proj_name}'") + + # ... inside make_package_fn: + def package(): + current_wt_dirs = find_all_worktree_dirs(en, pp, projects_dir) + # ... rest unchanged +``` + +**Step 6: Run all tests** + +Run: `cd cli && pytest -v` +Expected: All PASS + +**Step 7: Commit** + +```bash +git add cli/karma/worktree_discovery.py cli/tests/test_worktree_discovery.py cli/karma/sync.py cli/karma/main.py +git commit -m "refactor(cli): unified find_all_worktree_dirs helper + +Single function that combines CLI prefix-match and Desktop project-name +discovery, deduplicates results. Simplifies sync.py and main.py." +``` + +--- + +## Task 6: Update `karma status` to show Desktop worktree counts + +The `status` command should show Desktop worktree sessions alongside CLI worktrees. + +**Files:** +- Modify: `cli/karma/main.py` (status command) + +**Step 1: Modify status command** + +In `cli/karma/main.py`, in the `status` command, replace the worktree counting block to use `find_all_worktree_dirs`: + +```python + from karma.worktree_discovery import find_all_worktree_dirs + + # ... inside the per-project loop: + + # Count worktree sessions (CLI + Desktop) + wt_dirs = find_all_worktree_dirs( + proj.encoded_name, proj.path, projects_dir + ) + wt_count = 0 + for wd in wt_dirs: + wt_count += sum( + 1 for f in wd.glob("*.jsonl") + if not f.name.startswith("agent-") and f.stat().st_size > 0 + ) +``` + +**Step 2: Run status manually to verify** + +Run: `cd cli && karma status` +Expected: Should show worktree counts including Desktop worktrees + +**Step 3: Run tests** + +Run: `cd cli && pytest tests/test_cli_syncthing.py -v` +Expected: All PASS + +**Step 4: Commit** + +```bash +git add cli/karma/main.py +git commit -m "fix(cli): karma status includes Desktop worktree counts + +Status now uses find_all_worktree_dirs() to count sessions from +both CLI and Desktop worktrees." +``` + +--- + +## Task 7: Manual verification — restart watch and verify outbox + +This is an operational task, not code. Kill the stale watch, restart with the correct team, verify the outbox gets populated. + +**Step 1: Kill stale watch process** + +Run: `kill 3994` (PID of `karma watch --team beta`) + +Verify: `ps aux | grep '[k]arma watch'` should show nothing. + +**Step 2: Run one-shot package to verify content** + +We need a way to manually trigger a single package run. Use Python directly: + +```bash +cd cli && python3 -c " +from pathlib import Path +from karma.config import SyncConfig, KARMA_BASE +from karma.packager import SessionPackager +from karma.worktree_discovery import find_all_worktree_dirs + +config = SyncConfig.load() +team = config.teams['Ayush-stealing-prompts'] +proj = team.projects['claude-code-karma'] +projects_dir = Path.home() / '.claude' / 'projects' +claude_dir = projects_dir / proj.encoded_name + +wt_dirs = find_all_worktree_dirs(proj.encoded_name, proj.path, projects_dir) +print(f'Found {len(wt_dirs)} worktree dirs') +for d in wt_dirs: + print(f' {d.name}') + +outbox = KARMA_BASE / 'remote-sessions' / config.user_id / proj.encoded_name +outbox.mkdir(parents=True, exist_ok=True) + +packager = SessionPackager( + project_dir=claude_dir, + user_id=config.user_id, + machine_id=config.machine_id, + project_path=proj.path, + extra_dirs=wt_dirs, +) +manifest = packager.package(staging_dir=outbox) +wt_sessions = [s for s in manifest.sessions if s.worktree_name] +print(f'Total sessions: {manifest.session_count}') +print(f'Worktree sessions: {len(wt_sessions)}') +for s in wt_sessions[:10]: + print(f' {s.uuid[:12]}... wt={s.worktree_name}') +" +``` + +Expected: Should show >826 sessions total, with 40+ worktree sessions. + +**Step 3: Verify manifest has worktree_name fields** + +```bash +python3 -c " +import json +m = json.load(open('$HOME/.claude_karma/remote-sessions/jay/-Users-jayantdevkar-Documents-GitHub-claude-karma/manifest.json')) +wt = [s for s in m['sessions'] if s.get('worktree_name')] +print(f'Total: {m[\"session_count\"]}') +print(f'With worktree_name: {len(wt)}') +print(f'Session keys: {list(m[\"sessions\"][0].keys())}') +" +``` + +Expected: `worktree_name` should now appear in session entries. + +**Step 4: Restart watch with correct team** + +Run: `karma watch --team Ayush-stealing-prompts &` + +Verify output includes: +``` +Found N CLI + M Desktop worktree dir(s) for 'claude-code-karma' +Watching: claude-code-karma (...) +Watching worktree: syncthing-sync-design (...) +... +``` + +**Step 5: Verify Syncthing picks up changes** + +Check Syncthing web UI or: +```bash +curl -s -H "X-API-Key:$(python3 -c "import json; print(json.load(open('$HOME/.claude_karma/sync-config.json'))['syncthing']['api_key'])")" \ + http://127.0.0.1:8384/rest/db/status?folder=karma-out-jay-claude-code-karma | python3 -m json.tool | grep -E '"globalFiles|localFiles|needFiles' +``` + +Expected: `globalFiles` should increase to reflect worktree sessions. + +--- + +## Task 8: Update diagnostic tests to reflect fixed state + +Now that the fixes are in place, update the diagnostic tests to verify the FIXED state. + +**Files:** +- Modify: `cli/tests/test_sync_diagnostics.py` + +**Step 1: Update assertions** + +```python +# In TestSyncDiagnostics, update test_outbox_manifest_is_stale: + + def test_outbox_manifest_includes_worktree_sessions(self): + """After fix: outbox manifest should include worktree sessions.""" + manifest_path = ( + KARMA_BASE / "remote-sessions" / "jay" / MAIN_ENCODED / "manifest.json" + ) + if not manifest_path.exists(): + pytest.skip("No outbox manifest") + + manifest = json.loads(manifest_path.read_text()) + sessions_with_wt = [ + s for s in manifest["sessions"] if s.get("worktree_name") + ] + assert len(sessions_with_wt) > 0, ( + "Outbox should now include worktree sessions after fix" + ) + # Verify the worktree_name field exists in session entries + assert "worktree_name" in manifest["sessions"][0], ( + "Session entries should have worktree_name field" + ) + + def test_desktop_worktrees_now_discoverable(self): + """After fix: Desktop worktrees should be found by find_desktop_worktree_dirs.""" + from karma.worktree_discovery import find_desktop_worktree_dirs + + desktop_dirs = find_desktop_worktree_dirs( + project_name="claude-karma", + projects_dir=PROJECTS_DIR, + ) + # Should find focused-jepsen and lucid-villani + assert len(desktop_dirs) >= 2, ( + f"Expected >=2 Desktop worktree dirs, found {len(desktop_dirs)}" + ) +``` + +**Step 2: Run updated diagnostics** + +Run: `cd cli && pytest tests/test_sync_diagnostics.py -v` +Expected: All PASS (reflecting the fixed state) + +**Step 3: Commit** + +```bash +git add cli/tests/test_sync_diagnostics.py +git commit -m "test(cli): update diagnostic tests for fixed sync pipeline + +Tests now verify that worktree sessions are included in the outbox +and Desktop worktrees are discoverable." +``` + +--- + +## Task 9: Run full test suite and verify no regressions + +**Step 1: Run all CLI tests** + +Run: `cd cli && pytest -v` +Expected: All tests PASS + +**Step 2: Run API tests** + +Run: `cd api && pytest tests/ -v --timeout=30` +Expected: All pass (no API changes in this plan) + +**Step 3: Verify sync status** + +Run: `karma status` +Expected: Shows local + worktree + packaged counts with "up to date" or small gap. + +--- + +## Summary + +| Task | What | Files Changed | Tests | +|------|------|---------------|-------| +| 1 | Diagnostic tests (document current bugs) | +`test_sync_diagnostics.py` | 4 | +| 2 | Desktop worktree discovery | `worktree_discovery.py`, `test_worktree_discovery.py` | 6 | +| 3 | `project_name_from_path` helper | `worktree_discovery.py`, `test_worktree_discovery.py` | 5 | +| 4 | Wire Desktop discovery into sync/watch | `sync.py`, `main.py`, `test_packager.py` | 2 | +| 5 | Unified `find_all_worktree_dirs` | `worktree_discovery.py`, `sync.py`, `main.py` | 2 | +| 6 | Status shows Desktop worktree counts | `main.py` | 0 | +| 7 | Manual verification (kill/restart watch) | — (operational) | 0 | +| 8 | Update diagnostic tests for fixed state | `test_sync_diagnostics.py` | 2 | +| 9 | Full suite verification | — | all | + +**What this fixes:** +- Worktree sessions (CLI + Desktop) are now packaged into the outbox +- `karma watch` discovers and monitors worktree dirs dynamically +- `karma status` shows accurate session counts across all sources +- Stale watch process is killed and restarted with correct team + +**What this does NOT change (already works):** +- `api/services/remote_sessions.py` — inbox→project mapping is correct +- `api/services/desktop_sessions.py` — API-side worktree→project mapping is correct +- `api/routers/projects.py` — merges local + worktree + remote sessions correctly +- Syncthing folder setup — inbox/outbox paths use receiver's local encoded name + +**Future work (out of scope):** +- Unify the 3 mapping systems (API utils, desktop_sessions, remote_sessions) into a single service +- Hook-based packaging trigger (SessionEnd → auto-package) +- launchd/systemd for persistent `karma watch` diff --git a/docs/plans/2026-03-07-responsive-dashboard-plan.md b/docs/plans/2026-03-07-responsive-dashboard-plan.md new file mode 100644 index 00000000..802f581a --- /dev/null +++ b/docs/plans/2026-03-07-responsive-dashboard-plan.md @@ -0,0 +1,178 @@ +# Responsive Dashboard Plan + +**Date:** 2026-03-07 +**Goal:** Make the entire Claude Code Karma dashboard fully responsive across all screen sizes (375px mobile to 2560px+ ultrawide). + +## Current State + +The list/index pages are mostly well-done (8.5/10) — they use proper Tailwind responsive prefixes (`grid-cols-1 md:grid-cols-2 lg:grid-cols-3`, `flex-col sm:flex-row`, etc.). The main problems are: + +1. **Root layout container** caps content at 1200px with fixed padding +2. **Several detail pages** have hardcoded grids/sidebars that break on mobile +3. **CSS-only components** (LiveSessions, CommandFooter) have zero responsive classes +4. **No xl:/2xl: breakpoints** anywhere — large screens (1440px+) are ignored + +## Breakpoint Strategy + +| Prefix | Width | Target | +|--------|-------|--------| +| (none) | 0–639px | Mobile phones (375px–430px) | +| `sm:` | 640px+ | Large phones / small tablets | +| `md:` | 768px+ | Tablets | +| `lg:` | 1024px+ | Laptops | +| `xl:` | 1280px+ | Desktops | +| `2xl:` | 1536px+ | Large monitors / ultrawide | + +## Phases + +--- + +### Phase 1: Root Layout Shell (CRITICAL) + +**Files:** `+layout.svelte`, `Header.svelte`, `CommandFooter.svelte` + +#### 1.1 Main container (`+layout.svelte:123`) +``` +Current: class="flex-1 w-full max-w-[1200px] mx-auto px-6 py-8" +Target: class="flex-1 w-full max-w-[1200px] xl:max-w-[1400px] 2xl:max-w-[1600px] mx-auto px-4 sm:px-6 lg:px-8 xl:px-10 py-6 sm:py-8" +``` + +- Mobile (375px): 375 - 32px = 343px content (was 327px with px-6) +- Desktop (1200px): same as before +- Large (1440px): expands to 1400px (was capped at 1200px) +- Ultrawide (1920px+): expands to 1600px + +#### 1.2 Header container (`Header.svelte:57`) +``` +Current: class="w-full max-w-[1200px] mx-auto px-4 md:px-6 ..." +Target: class="w-full max-w-[1200px] xl:max-w-[1400px] 2xl:max-w-[1600px] mx-auto px-4 md:px-6 lg:px-8 xl:px-10 ..." +``` +Must match the main container max-width at each breakpoint. + +#### 1.3 CommandFooter (`CommandFooter.svelte`) +- Replace CSS `@media (min-width: 640px)` with Tailwind `hidden sm:inline` on label spans +- Add responsive padding: `px-4 sm:px-6 lg:px-8` +- Ensure buttons don't overlap on 375px — use `flex-wrap gap-2` + +**Estimated changes:** 3 files, ~15 lines each + +--- + +### Phase 2: Detail Pages (HIGH PRIORITY) + +#### 2.1 About page (`about/+page.svelte`) — CRITICAL +- **Line 46-47:** Fixed 224px sidebar doesn't collapse on mobile +- Fix: `flex flex-col lg:flex-row gap-6` with sidebar `w-full lg:w-56 lg:shrink-0` +- Sidebar becomes horizontal nav or collapsible on mobile +- Add sticky behavior only on desktop: `lg:sticky lg:top-20` + +#### 2.2 Agent detail (`agents/[name]/+page.svelte`) — HIGH +- **~Line 800:** `grid grid-cols-3` → `grid grid-cols-1 sm:grid-cols-2 md:grid-cols-3` +- **~Line 1100:** Add `xl:grid-cols-3` for large screens +- **~Line 1300:** `grid grid-cols-2` → `grid grid-cols-1 sm:grid-cols-2` + +#### 2.3 Settings (`settings/+page.svelte`) — MEDIUM +- **Line 1:** `max-w-2xl` → `max-w-2xl lg:max-w-3xl xl:max-w-4xl` +- **Line 217:** `grid grid-cols-2` → `grid grid-cols-1 sm:grid-cols-2` + +#### 2.4 Team page (`team/+page.svelte`) — MEDIUM +- **Line 64:** `max-w-5xl` → `max-w-5xl xl:max-w-6xl 2xl:max-w-7xl` +- **Line 79:** Add `xl:grid-cols-4` for large screens + +#### 2.5 Sync page (`sync/+page.svelte`) — MEDIUM +- **Line 1:** `max-w-4xl` → `max-w-4xl xl:max-w-5xl 2xl:max-w-6xl` +- Header flex: add `flex-col sm:flex-row` for mobile stacking + +**Estimated changes:** 5 files, ~5-20 lines each + +--- + +### Phase 3: List Pages (QUICK WINS) + +#### 3.1 Home page (`+page.svelte:23`) +- `max-w-[560px]` → `max-w-[560px] sm:max-w-xl md:max-w-2xl lg:max-w-3xl` +- The home page nav grid already uses responsive prefixes — just widen the container + +#### 3.2 Analytics page (`analytics/+page.svelte:234`) +- `max-w-[1100px]` → remove (inherits from layout container which is now responsive) +- Or: `max-w-[1100px] xl:max-w-[1400px] 2xl:max-w-[1600px]` + +#### 3.3 Add xl:/2xl: to grids across all list pages +For pages using `grid-cols-1 md:grid-cols-2 lg:grid-cols-3`, add `xl:grid-cols-4` where it makes sense (cards that are narrow enough): +- `projects/+page.svelte` +- `agents/+page.svelte` +- `skills/+page.svelte` +- `hooks/+page.svelte` +- `plugins/+page.svelte` +- `commands/+page.svelte` +- `plans/+page.svelte` +- `tools/+page.svelte` (already has `xl:grid-cols-4`) + +**Estimated changes:** ~10 files, ~1-3 lines each + +--- + +### Phase 4: CSS-Only Components (MEDIUM PRIORITY) + +These components use raw CSS with hardcoded pixel values and zero Tailwind responsive classes. They won't break on mobile but don't adapt well. + +#### 4.1 LiveSessionsSection.svelte +- Convert hardcoded padding (`12px 16px`) to Tailwind responsive classes +- `.project max-width: 70%` → responsive with truncation +- Add responsive gap scaling + +#### 4.2 LiveSessionsTerminal.svelte +- `.terminal-body max-height: 195px` → responsive height +- Convert padding from fixed CSS to Tailwind responsive classes +- `.project max-width: 70%` → responsive + +#### 4.3 SessionChainView.svelte +- `min-width: 200px; max-width: 280px` → responsive card sizing +- Already has a `@media (max-width: 640px)` query — extend to `lg:` breakpoints +- Cards should expand on large screens + +#### 4.4 TokenSearchInput.svelte +- Touch target: `.clear-all-btn` is 24x24px → needs 44px on mobile +- Already has `@media` queries — consolidate with Tailwind responsive classes +- `max-width: 200px` on tokens → responsive + +**Estimated changes:** 4 files, 10-30 lines each + +--- + +### Phase 5: ConversationView Component (INVESTIGATE) + +The session detail pages (`projects/[project_slug]/[session_slug]/+page.svelte`) delegate to a `ConversationView` component which is a 70KB+ file. This needs a separate audit to identify: +- Timeline layout responsiveness +- Metadata sidebar stacking on mobile +- Message bubble width constraints + +**Action:** Audit and plan separately — this may be the largest single component. + +--- + +## Implementation Order + +1. **Phase 1** (layout shell) — do first, affects every page +2. **Phase 3** (list pages) — quick wins, 1-3 line changes each +3. **Phase 2** (detail pages) — medium effort, high impact +4. **Phase 4** (CSS components) — refactor CSS to Tailwind responsive +5. **Phase 5** (ConversationView) — biggest effort, separate audit needed + +## Testing Checklist + +For each phase, verify at these widths: +- [ ] 375px (iPhone SE / small Android) +- [ ] 430px (iPhone Pro Max) +- [ ] 768px (iPad portrait) +- [ ] 1024px (iPad landscape / small laptop) +- [ ] 1280px (standard laptop) +- [ ] 1440px (desktop monitor) +- [ ] 1920px (full HD) +- [ ] 2560px (ultrawide / 2K) + +## Risk Assessment + +- **Low risk:** Phases 1-3 are additive Tailwind class changes — no breaking changes +- **Medium risk:** Phase 4 converts CSS to Tailwind — visual regression possible +- **High risk:** Phase 5 (ConversationView) is a massive component — needs careful handling diff --git a/docs/plans/2026-03-07-sync-sqlite-migration-design.md b/docs/plans/2026-03-07-sync-sqlite-migration-design.md new file mode 100644 index 00000000..d3b1353a --- /dev/null +++ b/docs/plans/2026-03-07-sync-sqlite-migration-design.md @@ -0,0 +1,141 @@ +# Sync SQLite Migration Design + +**Date:** 2026-03-07 +**Status:** Approved +**Author:** Jayant Devkar + Claude + +## Problem + +Sync configuration (teams, members, projects) lives in `sync-config.json` — a flat Pydantic model that's fully deserialized and rewritten on every operation. There's no activity history, no query capability, no search/indexing, and concurrent access from the CLI + API + watcher risks file corruption. Users sharing session data deserve full transparency into sync activity. + +## Goal + +Move teams, members, and project associations into SQLite (`metadata.db`). Add a comprehensive sync event log. Keep JSON for identity/credentials only. + +## Decisions + +| Decision | Choice | Rationale | +|---|---|---| +| Event retention | Keep forever | ~100 bytes/event, 10K events/year = 1MB. Negligible. | +| CLI DB access | Direct SQLite reads via shared `db/` module | Single source of truth, no drift. DB-agnostic abstraction for future Postgres migration. | +| JSON scope | Identity only (`user_id`, `machine_id`, Syncthing credentials) | Bootstrap data needed before DB exists. Everything relational goes to SQLite. | +| Event types | Comprehensive (12+) | Users sharing data deserve full visibility | +| Migration | None needed | Feature not in prod yet, greenfield | +| DB location | Same `metadata.db` (schema v18) | Real FKs, existing connection infrastructure, one DB file | + +## Schema + +Four new tables added via schema v18 migration: + +```sql +CREATE TABLE IF NOT EXISTS sync_teams ( + name TEXT PRIMARY KEY, + backend TEXT NOT NULL DEFAULT 'syncthing', + created_at TEXT DEFAULT (datetime('now')) +); + +CREATE TABLE IF NOT EXISTS sync_members ( + team_name TEXT NOT NULL, + name TEXT NOT NULL, + device_id TEXT, + ipns_key TEXT, + added_at TEXT DEFAULT (datetime('now')), + PRIMARY KEY (team_name, name), + FOREIGN KEY (team_name) REFERENCES sync_teams(name) ON DELETE CASCADE +); + +CREATE INDEX IF NOT EXISTS idx_sync_members_device ON sync_members(device_id); + +CREATE TABLE IF NOT EXISTS sync_team_projects ( + team_name TEXT NOT NULL, + project_encoded_name TEXT NOT NULL, + path TEXT, + added_at TEXT DEFAULT (datetime('now')), + PRIMARY KEY (team_name, project_encoded_name), + FOREIGN KEY (team_name) REFERENCES sync_teams(name) ON DELETE CASCADE, + FOREIGN KEY (project_encoded_name) REFERENCES projects(encoded_name) +); + +CREATE TABLE IF NOT EXISTS sync_events ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + event_type TEXT NOT NULL, + team_name TEXT, + member_name TEXT, + project_encoded_name TEXT, + session_uuid TEXT, + detail TEXT, + created_at TEXT DEFAULT (datetime('now')), + FOREIGN KEY (team_name) REFERENCES sync_teams(name) ON DELETE SET NULL +); + +CREATE INDEX IF NOT EXISTS idx_sync_events_type ON sync_events(event_type); +CREATE INDEX IF NOT EXISTS idx_sync_events_team ON sync_events(team_name, created_at DESC); +CREATE INDEX IF NOT EXISTS idx_sync_events_time ON sync_events(created_at DESC); +CREATE INDEX IF NOT EXISTS idx_sync_events_member ON sync_events(member_name, created_at DESC); +``` + +## Event Types + +| Event Type | When | Key fields | +|---|---|---| +| `session_packaged` | Watcher packages a session | `session_uuid`, `project_encoded_name` | +| `session_received` | Indexer finds new remote session | `session_uuid`, `member_name`, `project_encoded_name` | +| `member_connected` | Syncthing device online | `member_name` | +| `member_disconnected` | Syncthing device offline | `member_name` | +| `team_created` | Team created | `team_name` | +| `team_deleted` | Team deleted | `team_name` | +| `member_added` | Member added | `team_name`, `member_name` | +| `member_removed` | Member removed | `team_name`, `member_name` | +| `project_added` | Project added to team | `team_name`, `project_encoded_name` | +| `project_removed` | Project removed from team | `team_name`, `project_encoded_name` | +| `watcher_started` | Watcher started | `team_name` | +| `watcher_stopped` | Watcher stopped | `team_name` | +| `pending_accepted` | Pending folder accepted | `team_name` | +| `sync_error` | Any sync failure | detail has error message | + +## JSON Config (Trimmed) + +`~/.claude_karma/sync-config.json` keeps only: + +```json +{ + "user_id": "alice", + "machine_id": "alice-macbook-pro", + "syncthing": { + "api_url": "http://127.0.0.1:8384", + "api_key": "abc123...", + "device_id": "XXXXXXX-..." + } +} +``` + +## Module Structure + +``` +api/db/ +├── connection.py # Existing — unchanged +├── schema.py # Add v18 migration with 4 new tables +├── indexer.py # Add log_event() call in index_remote_sessions() +├── queries.py # Existing session queries — unchanged +└── sync_queries.py # NEW: team/member/project/event CRUD functions + +cli/karma/ +├── config.py # Trim to identity-only SyncConfig +├── db.py # NEW: thin connection helper for CLI +└── syncthing.py # Unchanged +``` + +`sync_queries.py` functions all take a raw `sqlite3.Connection` — no framework dependency. The API wraps with `run_in_executor` for async. The CLI calls directly. + +## API Router Changes + +Every mutating sync endpoint switches from JSON read/write to SQLite queries + `log_event()`. Syncthing proxy endpoints (detect, devices, folders, rescan) stay unchanged. Activity endpoint queries `sync_events` table instead of raw Syncthing events. + +## References + +- Existing schema: `api/db/schema.py` (v17) +- Connection layer: `api/db/connection.py` (reader/writer separation, WAL mode) +- Current sync router: `api/routers/sync_status.py` (17 endpoints) +- Current config: `cli/karma/config.py` (SyncConfig Pydantic model) +- Syncthing client: `cli/karma/syncthing.py` +- Syncthing proxy: `api/services/syncthing_proxy.py` diff --git a/docs/plans/2026-03-07-sync-team-page-redesign.md b/docs/plans/2026-03-07-sync-team-page-redesign.md new file mode 100644 index 00000000..120fd723 --- /dev/null +++ b/docs/plans/2026-03-07-sync-team-page-redesign.md @@ -0,0 +1,941 @@ +# Sync & Team Page Redesign + +**Date:** 2026-03-07 +**Status:** Draft +**Branch:** worktree-syncthing-sync-design + +## Problem + +The current `/sync` page does too much: Syncthing setup, team CRUD, member management, project assignment, sync status, and activity -- all crammed into a 4-tab layout. The existing `/team` page is a passive read-only browser of remote sessions. Users need clear separation between: + +1. **Team management** -- creating teams, adding members, managing who syncs with whom +2. **Sync engine** -- Syncthing setup, watcher status, sync health, activity + +## Design Goals + +- `/team` becomes the primary team management hub (CRUD teams, members) +- `/sync` becomes focused on Syncthing setup + sync engine status +- Remote sessions move into `/projects/[slug]` as a "Team" tab (context-aware) +- Multi-team support is first-class +- "Join Team" flow uses a join code for maximum convenience + +--- + +## Architecture Overview + +### Page Responsibilities (After Redesign) + +| Page | Responsibility | Removed From | +|------|---------------|-------------| +| `/sync` | Syncthing install/init wizard + sync engine status | Team CRUD, member mgmt, project assignment | +| `/team` | Team list, create team, join team | Read-only remote session browser | +| `/team/[name]` | Team detail: members, projects, join code, pending devices | N/A (new) | +| `/projects/[slug]` (Team tab) | Remote sessions for this project from teammates | `/team/[user_id]` page | + +### What Gets Removed + +| Current | Action | +|---------|--------| +| `/sync` TeamTab | Move to `/team/[name]` | +| `/sync` ProjectsTab | Project assignment moves to `/team/[name]`, per-project sync status stays on `/sync` | +| `/sync` Wizard Step 3 (create/join/solo) | Moves to `/team` page (create/join CTAs) | +| `/team` (remote user browser) | Replace with team list | +| `/team/[user_id]` (remote user detail) | Replace with `/team/[name]` (team detail) | +| Remote sessions on `/team/[user_id]` | Move to `/projects/[slug]` Team tab | + +--- + +## Join Code Mechanism + +### Problem + +Syncthing device IDs carry no team metadata. Users must exchange 56-character device IDs AND coordinate team names separately. This is tedious and error-prone. + +### Solution: Join Code + +A compact string that encodes team name, user identity, and device ID: + +``` +Format: {team_name}:{user_id}:{device_id} +Example: acme:alice:MFZWI3D-BONSGYC-YLTMRWG-C43ENR5-QXGZDMM-FZWI3DP-BONSGYC-ZZZ + +Parsing: split on first two ":" chars + - team_name and user_id are alphanumeric/dash/underscore (no colons) + - device_id is uppercase alphanumeric with dashes +``` + +**Why 3 parts?** The `user_id` is critical because: +- It becomes the member name on the joiner's machine +- The member name determines the filesystem inbox path (`remote-sessions/{member_name}/`) +- It must match the remote user's actual `user_id` for folder paths to align correctly + +### Generation + +When a user creates a team, the join code is auto-generated from: +- `team_name` from the team +- `user_id` from `sync-config.json` +- `device_id` from `sync-config.json` (Syncthing device ID) + +Shown prominently on `/team/[name]` with a copy button. + +### The Complete Pairing Flow + +``` +User A (Team Creator) User B (Joining) +───────────────────── ────────────────── + +1. /sync: Install Syncthing 1. /sync: Install Syncthing +2. /sync: Init (name: "alice") 2. /sync: Init (name: "bob") + -> gets device ID AAA -> gets device ID BBB + -> redirect to /team -> redirect to /team + +3. /team: "Create Team" + -> enters name "acme" + -> team created in SQLite + +4. /team/acme: Sees join code 3. /team: "Join Team" + "acme:alice:AAA..." Pastes join code + -> copies & sends to B via Slack -> system parses: + team = "acme" + leader_name = "alice" + leader_device = "AAA..." + -> creates team "acme" locally + -> adds member "alice" (device: AAA) + -> pairs AAA in Syncthing + -> auto-accepts pending folders + -> shows: "Share YOUR code back!" + "acme:bob:BBB..." [Copy] + + 4. B sends their code back to A + +5. /team/acme: TWO ways to add B: + Option A: "Add Member" -> paste + B's code "acme:bob:BBB..." + -> auto-fills name="bob", device="BBB" + -> pairs in Syncthing + -> auto-shares folders + + Option B: Auto-detect pending device + -> Syncthing shows BBB as pending + -> team page shows: + "New device detected: BBB... + [Accept as team member]" + -> prompts for name -> "bob" + -> pairs + shares folders + +6. Both have watchers running 5. Watcher auto-started on join + -> Sessions flow both ways +``` + +### Why Two Exchanges? + +Syncthing requires **mutual pairing** -- both sides must know about each other. This is a security feature: no one can push data to your machine without your consent. The join code makes each exchange a simple copy-paste: + +1. A -> B: A's join code (via Slack/email) +2. B -> A: B's join code back (via Slack/email), OR A auto-detects B's pending device + +### Pending Device Auto-Detection (Convenience Feature) + +After B joins and pairs with A's Syncthing, B's device appears in A's Syncthing as a "pending device" (connected but not configured). We can detect this via Syncthing's `GET /rest/cluster/pending/devices` API. + +On A's `/team/[name]` page, we poll for pending devices and show: +``` ++--------------------------------------------------+ +| Pending Connections | +| | +| A new device is trying to connect: | +| BBB-DEF456-GHI... | +| | +| Name: [bob_____________] [Accept as Member] | ++--------------------------------------------------+ +``` + +This eliminates the need for B to share their code back -- A just accepts the pending device. The user_id still needs to be entered manually (Syncthing pending devices don't carry app-level metadata), but it's a minor friction point. + +**New SyncthingClient method needed:** +```python +def get_pending_devices(self) -> dict: + """Get devices trying to connect that aren't configured.""" + resp = requests.get( + f"{self.api_url}/rest/cluster/pending/devices", + headers=self.headers, + timeout=10, + ) + resp.raise_for_status() + return resp.json() +``` + +--- + +## Page Designs + +### `/sync` -- Sync Engine + +#### State 1: Not Configured (Wizard -- Steps 0-2 Only) + +``` ++--------------------------------------------------+ +| Sync [Refresh] | ++--------------------------------------------------+ + +Step 0: How It Works ++--------------------------------------------------+ +| | +| Share Claude Code sessions across machines | +| using Syncthing -- peer-to-peer, no cloud. | +| | +| 1. Install Syncthing | +| 2. Name your machine | +| 3. Create or join a team | +| | +| [Get Started] | ++--------------------------------------------------+ + +Step 1: Install Syncthing ++--------------------------------------------------+ +| | +| macOS: brew install syncthing | +| brew services start syncthing | +| | +| Linux: sudo apt install syncthing | +| systemctl --user start syncthing | +| | +| [Check Again] | ++--------------------------------------------------+ + +Step 2: Name This Machine ++--------------------------------------------------+ +| | +| Your Name: [alice___________] | +| | +| This identifies you when sharing sessions | +| with teammates. | +| | +| Your Device ID: | +| MFZWI3D-BONSGYC-YLTMRWG-... [Copy] | +| | +| [Initialize] | ++--------------------------------------------------+ + +-> After init, redirect to /team +``` + +#### State 2: Configured (Sync Status Dashboard) + +No tabs. A single scrollable page with sections: + +``` ++--------------------------------------------------+ +| Sync Last updated: 5s | +| [Refresh] | ++--------------------------------------------------+ + +Sync Engine ++--------------------------------------------------+ +| | +| Syncthing Running v1.29.0 | +| Watcher Running watching 4 projects | +| [Stop Watcher] | +| | +| Identity: alice (alice-mbp) | +| Device ID: MFZWI3D-BONSGYC-... [Copy] | ++--------------------------------------------------+ + +Sync Health ++--------------------------------------------------+ +| +----------+----------+----------+----------+ | +| | Projects | Sessions | Sessions | Members | | +| | Synced | Packaged | Received | Online | | +| | 4 | 127 | 89 | 2/3 | | +| +----------+----------+----------+----------+ | ++--------------------------------------------------+ + +Per-Project Sync Status ++--------------------------------------------------+ +| | +| claude-karma In Sync 127 / 127 | +| hubdata 2 behind 45 / 47 | +| my-app In Sync 32 / 32 | +| side-project Syncing 12 / 15 | +| | +| [Sync All Now] | ++--------------------------------------------------+ + +Pending Actions (only if exist) ++--------------------------------------------------+ +| | +| alice shared 3 project folders [Accept All] | ++--------------------------------------------------+ + +Recent Activity ++--------------------------------------------------+ +| | +| 2m ago session_packaged claude-karma | +| 5m ago session_packaged hubdata | +| 1h ago member_added bob (team: acme) | +| 2h ago watcher_started acme | +| | +| [View All Activity] | ++--------------------------------------------------+ + +Danger Zone ++--------------------------------------------------+ +| | +| [Reset Sync Setup] | +| | +| This will delete your sync config, stop the | +| watcher, and clear all team data. | ++--------------------------------------------------+ +``` + +### `/team` -- Team List + +#### State 1: Sync Not Configured + +``` ++--------------------------------------------------+ +| Teams | ++--------------------------------------------------+ + ++--------------------------------------------------+ +| | +| Set up sync first | +| | +| Before creating or joining a team, you need | +| to install Syncthing and initialize sync. | +| | +| [Go to Sync Setup] | ++--------------------------------------------------+ +``` + +#### State 2: No Teams Yet + +``` ++--------------------------------------------------+ +| Teams | ++--------------------------------------------------+ + ++--------------------------------------------------+ +| | +| No teams yet | +| | +| Create a team to start sharing sessions | +| with teammates, or join an existing team. | +| | +| [Create Team] [Join Team] | ++--------------------------------------------------+ +``` + +#### State 3: Has Teams + +``` ++--------------------------------------------------+ +| Teams [Create Team] [Join Team]| ++--------------------------------------------------+ + ++-----------------------------+ +-----------------------------+ +| acme | | personal-sync | +| syncthing | | syncthing | +| | | | +| 3 members | 4 projects | | 1 member | 2 projects | +| 2 online | | 1 online | ++-----------------------------+ +-----------------------------+ +``` + +Each card links to `/team/[name]`. + +#### Create Team Dialog + +``` ++--------------------------------------------------+ +| Create Team | +| | +| Team Name: [acme___________] | +| | +| This name will be shared with teammates. | +| Use lowercase letters, numbers, dashes. | +| | +| [Cancel] [Create] | ++--------------------------------------------------+ +``` + +After creation, redirects to `/team/[name]` where the join code is shown. + +#### Join Team Dialog + +``` ++--------------------------------------------------+ +| Join Team | +| | +| Paste the join code from your team creator: | +| | +| [acme:alice:MFZWI3D-BONSGYC-YLTMRWG-C43E...] | +| | +| Detected: | +| Team: acme | +| Leader: alice | +| Device: MFZWI3D-BON... | +| | +| [Cancel] [Join Team] | ++--------------------------------------------------+ +``` + +The "Detected" section appears live as the user pastes, giving instant feedback that the code parsed correctly. + +After joining: + +``` ++--------------------------------------------------+ +| Joined "acme"! | +| | +| You're now connected to alice's team. | +| Syncthing will start exchanging sessions | +| once alice accepts your device. | +| | +| Share YOUR code back with alice: | +| +----------------------------------------------+ | +| | acme:bob:DEF456-GHI789-JKL012-... | | +| | [Copy] | | +| +----------------------------------------------+ | +| | +| [Go to Team Page] | ++--------------------------------------------------+ +``` + +### `/team/[name]` -- Team Detail + +``` ++--------------------------------------------------+ +| Teams > acme [Delete Team] | ++--------------------------------------------------+ + +Join Code ++--------------------------------------------------+ +| | +| Share this with teammates to let them join: | +| +----------------------------------------------+ | +| | acme:alice:MFZWI3D-BONSGYC-YLTMRWG-C43E... | | +| | [Copy] | | +| +----------------------------------------------+ | ++--------------------------------------------------+ + +Pending Connections (only if detected) ++--------------------------------------------------+ +| | +| A new device is trying to connect: | +| DEF456-GHI789-JKL... | +| | +| Name: [_______________] [Accept as Member] | ++--------------------------------------------------+ + +Members (3) [Add Member] ++--------------------------------------------------+ +| You (alice) | +| MFZWI3D-BON... Online | ++--------------------------------------------------+ +| bob | +| DEF456-GHI... Online | +| Last seen: 2m ago [Remove] | ++--------------------------------------------------+ +| charlie | +| XYZ789-ABC... Offline | +| Last seen: 3h ago [Remove] | ++--------------------------------------------------+ + +Shared Projects (4) [Add Projects] ++--------------------------------------------------+ +| claude-karma /Users/.../claude-karma | +| [Remove] | +| hubdata /Users/.../hubdata | +| [Remove] | +| my-app /Users/.../my-app | +| [Remove] | ++--------------------------------------------------+ +``` + +#### Add Member Dialog + +Accepts either a join code OR manual name + device ID: + +``` ++--------------------------------------------------+ +| Add Team Member | +| | +| Paste their join code: | +| [acme:bob:DEF456-GHI789-JKL012-...] | +| | +| Detected: | +| Name: bob | +| Device: DEF456-GHI... | +| | +| -- or enter manually -- | +| | +| Name: [_______________] | +| Device ID: [_______________] | +| | +| [Cancel] [Add Member] | ++--------------------------------------------------+ +``` + +When a join code is pasted, the name and device ID fields auto-populate from the parsed values. The user can edit if needed. + +#### Add Projects Dialog + +``` ++--------------------------------------------------+ +| Share Projects with "acme" | +| | +| Select projects to sync: | +| | +| [ ] claude-karma /Users/.../claude-karma | +| [ ] hubdata /Users/.../hubdata | +| [x] side-project /Users/.../side-project | +| [x] experiments /Users/.../experiments | +| | +| Already shared: claude-karma, hubdata | +| | +| [Cancel] [Share Selected] | ++--------------------------------------------------+ +``` + +Projects already in the team are shown separately (not in the checkbox list) to avoid confusion. + +### `/projects/[slug]` -- New "Team" Tab + +Added alongside existing tabs (Overview, Agents, Skills, Tools, Memory, Analytics, Archived): + +``` +Tabs: [Overview] [Agents] [Skills] [Tools] [Memory] [Analytics] [Team] [Archived] +``` + +The "Team" tab only appears if there are remote sessions for this project. + +#### Team Tab Content + +``` ++--------------------------------------------------+ +| Team Sessions | +| | +| Sessions shared by teammates for this project. | ++--------------------------------------------------+ + ++--------------------------------------------------+ +| bob (12 sessions) | +| Last synced: 5m ago | Machine: bob-mbp | ++--------------------------------------------------+ +| 2m ago a1b2c3d4 1.2 MB "Fix auth bug" | +| 1h ago e5f6g7h8 890 KB "Add user API" | +| 3h ago i9j0k1l2 2.1 MB | +| ... [Show all 12] | ++--------------------------------------------------+ + ++--------------------------------------------------+ +| charlie (7 sessions) | +| Last synced: 3h ago | Machine: charlie-desktop | ++--------------------------------------------------+ +| 3h ago m3n4o5p6 1.5 MB "Refactor DB" | +| 5h ago q7r8s9t0 445 KB | ++--------------------------------------------------+ +``` + +Each session row links to `/projects/[slug]/[session_uuid]` -- the existing session viewer already handles remote sessions via `find_remote_session()` fallback. + +If no remote sessions exist: +``` ++--------------------------------------------------+ +| No team sessions yet | +| | +| Once teammates share this project via a team, | +| their sessions will appear here. | +| | +| [Go to Teams] | ++--------------------------------------------------+ +``` + +--- + +## API Changes + +### New Endpoints + +| Method | Endpoint | Purpose | +|--------|----------|---------| +| `POST` | `/sync/teams/join` | Join a team via join code | +| `GET` | `/sync/teams/{name}/join-code` | Get join code for a team | +| `GET` | `/sync/pending-devices` | List pending Syncthing devices | +| `GET` | `/projects/{slug}/remote-sessions` | Remote sessions for a specific project, grouped by user | + +### Modified Endpoints + +| Endpoint | Change | +|----------|--------| +| `GET /sync/status` | Add `device_id` field to response | + +### New SyncthingClient Method + +```python +# cli/karma/syncthing.py +def get_pending_devices(self) -> dict: + """Get devices trying to connect that aren't configured. + Returns dict keyed by device_id with connection details.""" + resp = requests.get( + f"{self.api_url}/rest/cluster/pending/devices", + headers=self.headers, + timeout=10, + ) + resp.raise_for_status() + return resp.json() +``` + +### New: `POST /sync/teams/join` + +```python +class JoinTeamRequest(BaseModel): + join_code: str # "team_name:user_id:DEVICE-ID-..." + +@router.post("/teams/join") +async def sync_join_team(req: JoinTeamRequest): + # 1. Parse join code (team_name:user_id:device_id) + parts = req.join_code.split(":", 2) + if len(parts) != 3: + raise HTTPException(400, "Invalid join code format. Expected team:user:device_id") + team_name, leader_name, device_id = parts + + # 2. Validate all parts + validate_user_id(team_name) + validate_user_id(leader_name) + validate_device_id(device_id) + + # 3. Load identity (must be initialized) + config = await run_sync(_load_identity) + if config is None: + raise HTTPException(400, "Not initialized. Run sync setup first.") + + conn = _get_sync_conn() + + # 4. Create team locally (if not exists) + if get_team(conn, team_name) is None: + create_team(conn, team_name, "syncthing") + log_event(conn, "team_created", team_name=team_name) + + # 5. Add leader as member (with their user_id as the name) + try: + add_member(conn, team_name, leader_name, device_id=device_id) + log_event(conn, "member_added", team_name=team_name, member_name=leader_name) + except Exception: + pass # already exists (idempotent) + + # 6. Pair device in Syncthing (best-effort) + paired = False + try: + proxy = get_proxy() + await run_sync(proxy.add_device, device_id, leader_name) + paired = True + except Exception: + pass + + # 7. Auto-accept pending folders from the leader + accepted = 0 + try: + from karma.syncthing import SyncthingClient, read_local_api_key + api_key = config.syncthing.api_key or await run_sync(read_local_api_key) + st = SyncthingClient(api_key=api_key) + if st.is_running(): + from karma.main import _accept_pending_folders + accepted = await run_sync(_accept_pending_folders, st, config, conn) + if accepted: + log_event(conn, "pending_accepted", detail={"count": accepted}) + except Exception: + pass + + # 8. Generate joiner's own code to share back + own_device_id = config.syncthing.device_id if config.syncthing else None + own_join_code = f"{team_name}:{config.user_id}:{own_device_id}" if own_device_id else None + + return { + "ok": True, + "team_name": team_name, + "leader_name": leader_name, + "paired": paired, + "accepted_folders": accepted, + "your_join_code": own_join_code, + } +``` + +### New: `GET /sync/teams/{name}/join-code` + +```python +@router.get("/teams/{team_name}/join-code") +async def sync_team_join_code(team_name: str): + if not ALLOWED_PROJECT_NAME.match(team_name): + raise HTTPException(400, "Invalid team name") + + config = await run_sync(_load_identity) + if config is None: + raise HTTPException(400, "Not initialized") + + conn = _get_sync_conn() + if get_team(conn, team_name) is None: + raise HTTPException(404, f"Team '{team_name}' not found") + + device_id = config.syncthing.device_id if config.syncthing else None + if not device_id: + raise HTTPException(400, "No Syncthing device ID configured") + + join_code = f"{team_name}:{config.user_id}:{device_id}" + return {"join_code": join_code, "team_name": team_name, "user_id": config.user_id} +``` + +### New: `GET /sync/pending-devices` + +```python +@router.get("/pending-devices") +async def sync_pending_devices(): + """List Syncthing devices trying to connect that aren't configured.""" + conn = _get_sync_conn() + known = get_known_devices(conn) + + proxy = get_proxy() + try: + pending = await run_sync(proxy.get_pending_devices) + except SyncthingNotRunning: + return {"devices": []} + + # Filter out devices we already know + known_device_ids = set(known.keys()) + result = [] + for device_id, info in pending.items(): + if device_id not in known_device_ids: + result.append({ + "device_id": device_id, + "name": info.get("name", ""), + "address": info.get("address", ""), + "time": info.get("time", ""), + }) + + return {"devices": result} +``` + +### New: `GET /projects/{slug}/remote-sessions` + +```python +# In api/routers/projects.py or a new endpoint in sessions.py + +@router.get("/projects/{project_slug}/remote-sessions") +async def project_remote_sessions(project_slug: str): + """Get remote sessions for a project, grouped by remote user.""" + validate_project_name(project_slug) + + from services.remote_sessions import list_remote_sessions_for_project + from karma.config import SyncConfig + + config = SyncConfig.load() if SyncConfig else None + local_user = config.user_id if config else None + + remote_base = Path.home() / ".claude_karma" / "remote-sessions" + if not remote_base.is_dir(): + return {"users": []} + + users = [] + for user_dir in sorted(remote_base.iterdir()): + if not user_dir.is_dir(): + continue + # Skip our own outbox + if local_user and user_dir.name == local_user: + continue + + project_dir = user_dir / project_slug + if not project_dir.is_dir(): + continue + + sessions_dir = project_dir / "sessions" + manifest_path = project_dir / "manifest.json" + + sessions = [] + if sessions_dir.is_dir(): + for f in sorted(sessions_dir.glob("*.jsonl"), key=lambda p: p.stat().st_mtime, reverse=True): + if f.name.startswith("agent-"): + continue + sessions.append({ + "uuid": f.stem, + "mtime": f.stat().st_mtime, + "size_bytes": f.stat().st_size, + }) + + manifest = {} + if manifest_path.exists(): + import json + try: + manifest = json.loads(manifest_path.read_text()) + except (json.JSONDecodeError, OSError): + pass + + if sessions: + users.append({ + "user_id": user_dir.name, + "machine_id": manifest.get("machine_id"), + "synced_at": manifest.get("synced_at"), + "session_count": len(sessions), + "sessions": sessions, + }) + + return {"users": users} +``` + +### Modified: `GET /sync/status` + +Add `device_id` to the response: + +```python +@router.get("/status") +async def sync_status(): + config = await run_sync(_load_identity) + if config is None: + return {"configured": False} + + # ... existing team loading code ... + + return { + "configured": True, + "user_id": config.user_id, + "machine_id": config.machine_id, + "device_id": config.syncthing.device_id if config.syncthing else None, # NEW + "teams": teams, + } +``` + +--- + +## Frontend Changes + +### Files to Create + +| File | Purpose | +|------|---------| +| `frontend/src/routes/team/+page.svelte` | **Rewrite**: team list with create/join CTAs | +| `frontend/src/routes/team/+page.server.ts` | **Rewrite**: fetch from `GET /sync/teams` + `GET /sync/status` | +| `frontend/src/routes/team/[name]/+page.svelte` | New: team detail (members, projects, join code, pending devices) | +| `frontend/src/routes/team/[name]/+page.server.ts` | New: fetch team detail + devices + join code + pending devices | +| `frontend/src/lib/components/team/TeamCard.svelte` | Team list card (name, member count, project count, online count) | +| `frontend/src/lib/components/team/TeamMemberCard.svelte` | Member card with connection status (online/offline/last seen) | +| `frontend/src/lib/components/team/JoinTeamDialog.svelte` | Join code paste dialog with live parsing feedback | +| `frontend/src/lib/components/team/CreateTeamDialog.svelte` | Team name input dialog | +| `frontend/src/lib/components/team/AddMemberDialog.svelte` | Paste join code OR manual name + device ID | +| `frontend/src/lib/components/team/AddProjectDialog.svelte` | Project selection checkbox dialog | +| `frontend/src/lib/components/team/JoinCodeCard.svelte` | Prominent join code display with copy button | +| `frontend/src/lib/components/team/PendingDeviceCard.svelte` | Pending device with name input + accept button | +| `frontend/src/lib/components/team/JoinSuccessCard.svelte` | Post-join confirmation with "share your code back" CTA | +| `frontend/src/lib/components/project/RemoteSessionsTab.svelte` | Team tab in project detail page | + +### Files to Modify + +| File | Change | +|------|--------| +| `frontend/src/routes/sync/+page.svelte` | Remove TeamTab, ProjectsTab, TeamSelector imports. Remove 4-tab structure. Replace with sync status dashboard (single page, no tabs). Keep wizard but remove step 3. | +| `frontend/src/routes/sync/+page.server.ts` | Simplify: only fetch detect, status, watch status. Remove pending fetch (moves to sync status dashboard inline). | +| `frontend/src/lib/components/sync/SetupWizard.svelte` | Remove step 3 (create/join/solo). After init, redirect to `/team`. | +| `frontend/src/routes/projects/[project_slug]/+page.svelte` | Add "Team" tab with `RemoteSessionsTab` component. Tab only shown if remote sessions exist. | +| `frontend/src/routes/projects/[project_slug]/+page.server.ts` | Fetch `GET /projects/{slug}/remote-sessions` count for tab badge. | +| `frontend/src/lib/components/Header.svelte` | Rename "Team" nav item to "Teams" | + +### Files to Delete + +| File | Reason | +|------|--------| +| `frontend/src/lib/components/sync/TeamTab.svelte` | Replaced by `/team/[name]` | +| `frontend/src/lib/components/sync/ProjectsTab.svelte` | Project assignment to `/team/[name]`, sync status to `/sync` dashboard | +| `frontend/src/lib/components/sync/TeamSelector.svelte` | No longer needed -- team selection happens on `/team` list page | +| `frontend/src/lib/components/sync/MembersTab.svelte` | Already superseded, now fully replaced | +| `frontend/src/routes/team/[user_id]/+page.svelte` | Replaced by `/team/[name]` | +| `frontend/src/routes/team/[user_id]/+page.server.ts` | Replaced by `/team/[name]` | + +### Navigation Sidebar + +``` +Before: After: + Dashboard Dashboard + Projects Projects + Sessions Sessions + Team -> Teams (links to /team) + Sync Sync (links to /sync) + Analytics Analytics + ... ... +``` + +--- + +## Implementation Phases + +### Phase 1: API -- Join Code + Pending Devices + Remote Sessions per Project + +1. Add `get_pending_devices()` to `SyncthingClient` and `SyncthingProxy` +2. Add `POST /sync/teams/join` endpoint (parse 3-part code, create team, pair, accept) +3. Add `GET /sync/teams/{name}/join-code` endpoint +4. Add `GET /sync/pending-devices` endpoint +5. Add `GET /projects/{slug}/remote-sessions` endpoint +6. Add `device_id` to `GET /sync/status` response +7. Write tests for join code parsing, validation, and the join flow + +### Phase 2: Frontend -- `/team` Page Rewrite + +1. Rewrite `/team/+page.svelte` as team list (grid of TeamCards, create/join CTAs) +2. Rewrite `/team/+page.server.ts` to fetch from `GET /sync/teams` + `GET /sync/status` +3. Build `CreateTeamDialog` component +4. Build `JoinTeamDialog` component with live code parsing +5. Build `JoinSuccessCard` with "share your code back" CTA +6. Handle "sync not configured" state (redirect to `/sync`) + +### Phase 3: Frontend -- `/team/[name]` Team Detail + +1. Create `/team/[name]/+page.svelte` with sections: join code, pending devices, members, projects +2. Create `/team/[name]/+page.server.ts` (fetch team, devices, join code, pending devices) +3. Build `JoinCodeCard` component (prominent display, copy button) +4. Build `PendingDeviceCard` component (name input, accept button) +5. Build `TeamMemberCard` component (connection status, remove button) +6. Build `AddMemberDialog` (paste code OR manual entry, auto-parse) +7. Build `AddProjectDialog` (checkbox list of projects) +8. Add polling for pending devices and member connection status + +### Phase 4: Frontend -- `/sync` Page Simplification + +1. Remove TeamTab, ProjectsTab, TeamSelector, OverviewTab imports +2. Remove 4-tab structure entirely +3. Remove wizard step 3 (create/join/solo) +4. Add redirect to `/team` after wizard step 2 init +5. Build sync status dashboard sections: + - Sync Engine card (Syncthing status, watcher, device ID) + - Sync Health stats row + - Per-project sync status list (read-only, from `GET /sync/teams/{name}/project-status`) + - Pending folder actions + - Recent activity list + - Danger zone (reset) + +### Phase 5: Frontend -- Project Team Tab + +1. Create `RemoteSessionsTab.svelte` component +2. Add "Team" tab to project detail page tabs +3. Fetch `GET /projects/{slug}/remote-sessions` on tab activation +4. Render grouped by user with session list and links +5. Conditionally show tab only when remote sessions exist (use count from server load) + +### Phase 6: Cleanup + +1. Delete deprecated components (TeamTab, ProjectsTab, TeamSelector, MembersTab) +2. Delete `/team/[user_id]` route files +3. Update navigation sidebar (Team -> Teams) +4. Update `CLAUDE.md` route tables and component lists +5. Update `api-types.ts` with any new/changed types + +--- + +## Design Decisions (Resolved) + +| Question | Decision | Rationale | +|----------|----------|-----------| +| Member name matching | Join code includes `user_id` -- auto-used as member name | Filesystem inbox path must match remote user's `user_id` for folder alignment | +| Bidirectional pairing | Join success shows "share YOUR code back" + pending device auto-detection | Two mechanisms for convenience -- code exchange OR auto-detect | +| Watcher auto-start | Auto-start on join, manual control on `/sync` | Reduces friction for joiners; power users can stop/start from sync page | +| Project opt-in on join | Accept all pending folders automatically | Joiners get whatever the team shares; they can remove projects later from `/team/[name]` | +| Multi-team | First-class -- `/team` is a list view, each team has its own detail page | Supports real use case of personal sync + work team | +| Where are remote sessions? | `/projects/[slug]` Team tab (context-aware) | More useful than a separate page -- see teammate sessions alongside your own | +| Join code format | `team:user_id:device_id` (3 parts, colon-separated) | Readable, debuggable, carries all needed info, no server required | diff --git a/docs/plans/2026-03-07-sync-team-redesign-implementation-prompt.md b/docs/plans/2026-03-07-sync-team-redesign-implementation-prompt.md new file mode 100644 index 00000000..16835940 --- /dev/null +++ b/docs/plans/2026-03-07-sync-team-redesign-implementation-prompt.md @@ -0,0 +1,219 @@ +# Implementation Prompt: Sync & Team Page Redesign + +Copy the prompt below into a new Claude Code session on the `worktree-syncthing-sync-design` branch. + +--- + +## Prompt + +``` +Read the design doc at docs/plans/2026-03-07-sync-team-page-redesign.md — it contains the full architecture, API specs, page wireframes, and implementation phases for splitting the sync/team UI. + +Use /feature-dev to guide the implementation. Since we've already done discovery and architecture design (documented in the plan), skip to Phase 5 (Implementation) directly. + +Before starting, use the Skill tool to invoke oh-my-claudecode:frontend-ui-ux — apply its design principles to all frontend components (distinctive typography, cohesive color palette, thoughtful spacing, no generic aesthetics). + +## What We're Building + +We're splitting the monolithic `/sync` page into three focused surfaces: + +1. `/sync` — Syncthing setup wizard (steps 0-2 only) + sync engine status dashboard (no tabs) +2. `/team` — Team list with Create/Join CTAs → `/team/[name]` team detail (members, projects, join code) +3. `/projects/[slug]` — New "Team" tab showing remote sessions from teammates + +Key new feature: **Join Code** — format `team_name:user_id:device_id` — enables one-paste team joining. + +## Implementation Order + +Execute these phases sequentially. After each phase, use oh-my-claudecode:code-review to review the changes before moving to the next. + +### Phase 1: API Changes + +Reference: design doc sections "API Changes" and "Join Code Mechanism" + +Files to modify: +- `cli/karma/syncthing.py` — Add `get_pending_devices()` method to `SyncthingClient` +- `api/services/syncthing_proxy.py` — Add `get_pending_devices()` to `SyncthingProxy` +- `api/routers/sync_status.py` — Add these endpoints: + - `POST /sync/teams/join` — Parse 3-part join code, create team, add leader, pair Syncthing, accept pending folders, return joiner's own code + - `GET /sync/teams/{name}/join-code` — Generate join code from config + - `GET /sync/pending-devices` — List unknown pending Syncthing devices + - Modify `GET /sync/status` — Add `device_id` field to response +- `api/routers/projects.py` (or new file) — Add `GET /projects/{slug}/remote-sessions` — Remote sessions grouped by user + +Key implementation details from the design doc: +- Join code format: `team_name:user_id:device_id` — split on first two colons +- `user_id` becomes the member name (critical: filesystem inbox path must match) +- Join endpoint should auto-accept pending folders and return the joiner's own code +- Pending devices endpoint filters out already-known device IDs from `get_known_devices()` +- Remote sessions endpoint skips local user's outbox, groups sessions by remote user + +After implementing, run: `cd api && pytest` to verify nothing breaks. + +### Phase 2: Frontend — `/team` Page Rewrite + +Reference: design doc section "Page Designs > /team" + +Delete old route files: +- `frontend/src/routes/team/[user_id]/+page.svelte` +- `frontend/src/routes/team/[user_id]/+page.server.ts` + +Rewrite existing files: +- `frontend/src/routes/team/+page.server.ts` — Fetch `GET /sync/teams` + `GET /sync/status` (need `configured` and `device_id`) +- `frontend/src/routes/team/+page.svelte` — Three states: + 1. Sync not configured → CTA to `/sync` + 2. No teams → Create/Join CTAs + 3. Has teams → Grid of `TeamCard` components linking to `/team/[name]` + +Create new components: +- `frontend/src/lib/components/team/TeamCard.svelte` — Card with name, backend, member count, project count +- `frontend/src/lib/components/team/CreateTeamDialog.svelte` — Team name input, calls `POST /sync/teams` +- `frontend/src/lib/components/team/JoinTeamDialog.svelte` — Paste join code with **live parsing feedback** (show detected team/leader/device as user types). Calls `POST /sync/teams/join`. On success, show `JoinSuccessCard`. +- `frontend/src/lib/components/team/JoinSuccessCard.svelte` — Shows "Joined acme!" + "Share YOUR code back" with copy button for the joiner's own code + +### Phase 3: Frontend — `/team/[name]` Team Detail + +Reference: design doc section "Page Designs > /team/[name]" + +Create new route: +- `frontend/src/routes/team/[name]/+page.server.ts` — Fetch in parallel: `GET /sync/teams` (find this team), `GET /sync/devices` (connection status), `GET /sync/teams/{name}/join-code`, `GET /sync/pending-devices`, `GET /projects` (for add project dialog) +- `frontend/src/routes/team/[name]/+page.svelte` — Sections: Join Code, Pending Devices, Members, Shared Projects + +Create components: +- `frontend/src/lib/components/team/JoinCodeCard.svelte` — Prominent code display with copy button +- `frontend/src/lib/components/team/PendingDeviceCard.svelte` — Shows device ID, name input field, "Accept as Member" button. Calls `POST /sync/teams/{name}/members` then pairs. +- `frontend/src/lib/components/team/TeamMemberCard.svelte` — Name, truncated device ID, online/offline badge (from Syncthing connections), last seen, remove button with confirm +- `frontend/src/lib/components/team/AddMemberDialog.svelte` — Dual input: paste join code (auto-parses name + device) OR manual name + device ID fields. Code paste auto-fills the manual fields. +- `frontend/src/lib/components/team/AddProjectDialog.svelte` — Checkbox list of projects from `GET /projects`, excludes already-shared ones. Calls `POST /sync/teams/{name}/projects` for each selected. + +Poll for pending devices every 10 seconds on this page. Poll for device connection status every 10 seconds. + +### Phase 4: Frontend — `/sync` Page Simplification + +Reference: design doc section "Page Designs > /sync" + +Modify `frontend/src/lib/components/sync/SetupWizard.svelte`: +- Remove step 3 entirely (create/join/solo). The wizard is now steps 0-2 only. +- After successful init in step 2, redirect to `/team` using `goto('/team')` + +Modify `frontend/src/routes/sync/+page.server.ts`: +- Remove pending folders fetch (handled inline now) +- Keep: detect, status, watch status + +Modify `frontend/src/routes/sync/+page.svelte`: +- Remove imports: TeamTab, ProjectsTab, TeamSelector, ActivityTab +- Remove the entire `` structure +- When `syncStatus.configured === true`, render a single-page dashboard (no tabs): + - **Sync Engine** card: Syncthing status, watcher status with start/stop, device ID with copy, machine name + - **Sync Health** stats row: projects synced, sessions packaged, sessions received, members online (aggregate across all teams) + - **Per-Project Sync Status** list: read-only, from `GET /sync/teams/{name}/project-status` (for the first/only team, or aggregate). Show project name, status badge, local/packaged counts. + - **Pending Actions** section (only if pending folders exist): from `GET /sync/pending` + - **Recent Activity** section: from `GET /sync/activity?limit=10` + - **Danger Zone**: Reset Sync Setup button + +### Phase 5: Frontend — Project Team Tab + +Reference: design doc section "Page Designs > /projects/[slug] Team Tab" + +Create component: +- `frontend/src/lib/components/project/RemoteSessionsTab.svelte` + - Props: `projectSlug: string`, `active: boolean` + - Fetches `GET /projects/{slug}/remote-sessions` when active + - Groups sessions by user, shows user header (name, session count, machine, last synced) + - Session rows link to `/projects/{slug}/{uuid}` (existing session viewer handles remote sessions) + - Empty state: "No team sessions yet" with link to `/team` + +Modify `frontend/src/routes/projects/[project_slug]/+page.svelte`: +- Add import for `RemoteSessionsTab` +- Add `Team` after the Analytics tab (before Archived) +- Add `` with `` +- Conditionally show the Team tab only if remote session count > 0 + +Modify `frontend/src/routes/projects/[project_slug]/+page.server.ts`: +- Add a lightweight fetch to check if remote sessions exist: `GET /projects/{slug}/remote-sessions` and pass the count + +### Phase 6: Cleanup + +Delete these files: +- `frontend/src/lib/components/sync/TeamTab.svelte` +- `frontend/src/lib/components/sync/ProjectsTab.svelte` +- `frontend/src/lib/components/sync/TeamSelector.svelte` +- `frontend/src/lib/components/sync/MembersTab.svelte` (if it exists) + +Modify `frontend/src/lib/components/Header.svelte`: +- Change "Team" to "Teams" in both desktop and mobile nav (lines 183 and 348) + +Update `frontend/src/lib/api-types.ts`: +- Add any new types needed (JoinTeamResponse, PendingDevice, etc.) +- Remove unused types if any + +After all phases, run: +- `cd api && pytest` — API tests pass +- `cd frontend && npm run check` — No TypeScript errors +- `cd frontend && npm run build` — Builds successfully + +## Agent Guidelines + +IMPORTANT: Give agents high-level requirements and pseudo-code instructions rather than +copy-pasting exact code from the plan. The agents should figure out the implementation +themselves based on the requirements, existing patterns in the codebase, and the project +conventions. The design doc is a WHAT and WHY reference — agents decide HOW by reading +existing code patterns (e.g., look at how TeamTab.svelte works before building the new +team detail page, look at existing routers before adding new endpoints). + +## Skills & Agents to Use + +- **oh-my-claudecode:frontend-ui-ux** — Invoke at the start. Apply to ALL frontend components. No generic Inter/Roboto fonts. Use the existing design tokens from app.css. Create distinctive, polished UI. +- **oh-my-claudecode:code-review** — After each phase, review the changes for quality, bugs, and convention adherence. +- **oh-my-claudecode:build-fix** — If TypeScript or build errors occur after any phase, use this to fix them quickly. +- **superpowers:verification-before-completion** — Before claiming any phase is complete, run the verification commands (pytest, npm run check, npm run build). + +## Important Conventions (from CLAUDE.md) + +- **Svelte 5 runes**: Use `$state()`, `$derived()`, `$effect()`, `$props()` — NOT Svelte 4 stores +- **API calls in components**: Use raw `fetch(${API_BASE}/...)` with `API_BASE` from `$lib/config` +- **Server load functions**: Use `safeFetch()` from `$lib/utils/api-fetch.ts` +- **Design tokens**: Use CSS custom properties from `app.css` (`--bg-base`, `--text-primary`, `--accent`, `--border`, etc.) +- **Icons**: Use `lucide-svelte` +- **Input validation in API**: Use regex patterns (`ALLOWED_PROJECT_NAME`, `ALLOWED_DEVICE_ID`) and `validate_*()` functions +- **DB operations**: Use `sync_queries.py` functions with `_get_sync_conn()` +- **Syncthing calls**: Wrap with `await run_sync(proxy.method)` for async +``` + +--- + +## How to Use This Prompt + +1. Open a new Claude Code session on the `worktree-syncthing-sync-design` branch +2. Copy everything between the ``` markers above +3. Paste as your first message +4. Claude will read the design doc and begin implementation phase by phase + +## Alternative: Phase-by-Phase Execution + +If you prefer more control, you can split this into separate sessions per phase. Copy just one phase section at a time, prefixed with: + +``` +Read docs/plans/2026-03-07-sync-team-page-redesign.md for full context. Implement Phase N: +``` + +## Alternative: Parallel Execution with Ultrapilot + +For faster execution, you can use `/ultrapilot` which parallelizes work across multiple agents with file ownership: + +``` +Read docs/plans/2026-03-07-sync-team-page-redesign.md + +Use /ultrapilot to implement the sync/team page redesign. Partition work as: + +Agent 1 (API): Phase 1 — all files under api/ and cli/ +Agent 2 (Team Frontend): Phases 2-3 — all files under frontend/src/routes/team/ and frontend/src/lib/components/team/ +Agent 3 (Sync + Project Frontend): Phases 4-5 — frontend/src/routes/sync/, frontend/src/routes/projects/, frontend/src/lib/components/sync/, frontend/src/lib/components/project/ +Agent 4 (Cleanup): Phase 6 — Header.svelte, api-types.ts, delete deprecated files + +Note: Agent 2 and 3 depend on Agent 1 (API endpoints must exist first). + +IMPORTANT: Give agents high-level requirements, not exact code. They should read existing +codebase patterns and figure out implementation details themselves. The design doc describes +WHAT to build — agents decide HOW by studying existing code conventions. +``` diff --git a/docs/plans/2026-03-07-sync-team-ux-fixes-plan.md b/docs/plans/2026-03-07-sync-team-ux-fixes-plan.md new file mode 100644 index 00000000..0bd58e0c --- /dev/null +++ b/docs/plans/2026-03-07-sync-team-ux-fixes-plan.md @@ -0,0 +1,1082 @@ +# Sync & Team UX Fixes — Implementation Plan + +> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. + +**Goal:** Fix 16 issues (2 critical, 5 high, 6 medium, 3 low) found by code review, complete the 3 missing `/sync` dashboard sections from the original design, add cross-linking between `/sync` and `/team`, and polish the post-setup onboarding flow. + +**Architecture:** The V3 split (`/sync` for engine status, `/team` for people/CRUD, project Team tab for remote sessions) is architecturally sound but incompletely implemented. This plan completes the implementation, hardens security, and adds wayfinding so users don't get lost between pages. No structural changes to routing. + +**Tech Stack:** FastAPI (Python), SvelteKit + Svelte 5 (TypeScript), SQLite, Syncthing API proxy + +**Background:** See `docs/plans/2026-03-07-sync-team-page-redesign.md` for the original V3 design that introduced the split. The `/sync` dashboard was supposed to have 6 sections; only 4 were built (missing: Per-Project Sync Status, Recent Activity, Sync Now). The code review also found security gaps in the join code mechanism and API auth. + +--- + +## Phase 1: Security Fixes (CRITICAL + HIGH) + +### Task 1: Validate `req.path` in `sync_add_team_project` [HIGH-4] + +Prevent path traversal via unvalidated filesystem path input. + +**Files:** +- Modify: `api/routers/sync_status.py:755-817` +- Test: `api/tests/test_sync_security.py` (create) + +**Step 1: Write the failing test** + +```python +# api/tests/test_sync_security.py +import pytest +from fastapi.testclient import TestClient +from main import app + +client = TestClient(app) + +@pytest.mark.parametrize("bad_path", [ + "../../../etc/passwd", + "/tmp/../etc/shadow", + "foo/../../bar", + "/nonexistent/../../root", +]) +def test_add_project_rejects_path_traversal(bad_path): + """Path traversal in project path should be rejected.""" + resp = client.post( + "/sync/teams/test-team/projects", + json={"name": "test-proj", "path": bad_path}, + ) + assert resp.status_code == 400 + assert "Invalid" in resp.json().get("detail", "") +``` + +**Step 2: Run test to verify it fails** + +Run: `cd api && pytest tests/test_sync_security.py::test_add_project_rejects_path_traversal -v` +Expected: FAIL — currently no path validation, returns 200 or 404 + +**Step 3: Add path validation function** + +Add to `api/routers/sync_status.py` after the existing `validate_*` functions (around line 63): + +```python +def validate_project_path(path: str) -> str: + """Validate project path — reject traversal and non-absolute paths.""" + if not path: + return path # empty path is allowed (uses encoded_name instead) + resolved = Path(path).resolve() + # Must be absolute and not contain .. after resolution + if ".." in Path(path).parts: + raise HTTPException(400, "Invalid project path: traversal not allowed") + # Must be under user's home directory + home = Path.home() + if not str(resolved).startswith(str(home)): + raise HTTPException(400, "Invalid project path: must be under home directory") + return str(resolved) +``` + +**Step 4: Apply validation in `sync_add_team_project`** + +In the `sync_add_team_project` function (line 755), add validation before using `req.path`: + +```python +async def sync_add_team_project(team_name: str, req: AddTeamProjectRequest) -> Any: + validate_project_name(req.name) + if not ALLOWED_PROJECT_NAME.match(team_name): + raise HTTPException(400, "Invalid team name") + validated_path = validate_project_path(req.path) # ADD THIS + # ... rest uses validated_path instead of req.path +``` + +**Step 5: Run test to verify it passes** + +Run: `cd api && pytest tests/test_sync_security.py -v` +Expected: PASS + +**Step 6: Commit** + +```bash +git add api/routers/sync_status.py api/tests/test_sync_security.py +git commit -m "fix(security): validate project path to prevent traversal [HIGH-4]" +``` + +--- + +### Task 2: Prevent team auto-creation from join codes [CRITICAL-1 partial] + +The join endpoint silently creates teams from any join code. Fix: only join existing teams unless the team name matches a known pattern. + +**Files:** +- Modify: `api/routers/sync_status.py:526-607` (sync_join_team) +- Test: `api/tests/test_sync_security.py` (append) + +**Step 1: Write the failing test** + +```python +# Append to api/tests/test_sync_security.py +def test_join_team_does_not_create_team_from_fabricated_code(): + """Join with a fabricated code should not auto-create teams.""" + # First ensure the team does NOT exist + resp = client.post( + "/sync/teams/join", + json={"join_code": "fabricated-team:attacker:AAAAAAA-BBBBBBB-CCCCCCC-DDDDDDD-EEEEEEE-FFFFFFF-GGGGGGG-HHHHHHH"}, + ) + # Should fail because team doesn't exist locally + assert resp.status_code == 404 + assert "not found" in resp.json().get("detail", "").lower() +``` + +**Step 2: Run test to verify it fails** + +Run: `cd api && pytest tests/test_sync_security.py::test_join_team_does_not_create_team_from_fabricated_code -v` +Expected: FAIL — currently returns 200 and creates the team + +**Step 3: Modify `sync_join_team` to require existing team** + +In `sync_join_team` (line 544), change the auto-create behavior: + +```python + # OLD: auto-create team + # if get_team(conn, team_name) is None: + # create_team(conn, team_name, "syncthing") + # log_event(conn, "team_created", team_name=team_name) + + # NEW: require team to exist locally (created via /team page or CLI) + if get_team(conn, team_name) is None: + raise HTTPException( + 404, + f"Team '{team_name}' not found. Create it first on the Teams page, " + "then paste the join code." + ) +``` + +**Step 4: Run test to verify it passes** + +Run: `cd api && pytest tests/test_sync_security.py -v` +Expected: PASS + +**Step 5: Update JoinTeamDialog to handle 404** + +In `frontend/src/lib/components/team/JoinTeamDialog.svelte`, the error handling at line 43 already shows `data.detail` — the 404 message will naturally surface. But update the input label to set expectations: + +```svelte + + +``` + +**Step 6: Commit** + +```bash +git add api/routers/sync_status.py api/tests/test_sync_security.py frontend/src/lib/components/team/JoinTeamDialog.svelte +git commit -m "fix(security): prevent team auto-creation from join codes [CRITICAL-1]" +``` + +--- + +### Task 3: Fix IntegrityError swallowing in join flow [HIGH-5] + +When a member exists with a different device_id, detect the mismatch instead of silently ignoring. + +**Files:** +- Modify: `api/routers/sync_status.py:549-553` +- Modify: `api/db/sync_queries.py:53-65` (add upsert variant) +- Test: `api/tests/test_sync_security.py` (append) + +**Step 1: Write the failing test** + +```python +# Append to api/tests/test_sync_security.py +def test_join_team_updates_device_id_on_rejoin(): + """Re-joining with a different device should update the device_id.""" + # This test needs a team that exists — setup depends on test fixtures + # For now, test the query layer directly + import sqlite3 + from db.sync_queries import add_member, list_members, create_team + conn = sqlite3.connect(":memory:") + conn.execute("CREATE TABLE sync_teams (name TEXT PRIMARY KEY, backend TEXT, created_at TEXT DEFAULT CURRENT_TIMESTAMP)") + conn.execute("CREATE TABLE sync_members (team_name TEXT, name TEXT, device_id TEXT, ipns_key TEXT, added_at TEXT DEFAULT CURRENT_TIMESTAMP, PRIMARY KEY (team_name, name))") + create_team(conn, "test", "syncthing") + add_member(conn, "test", "alice", device_id="OLD-DEVICE") + + # Upsert with new device + from db.sync_queries import upsert_member + upsert_member(conn, "test", "alice", device_id="NEW-DEVICE") + + members = list_members(conn, "test") + assert members[0]["device_id"] == "NEW-DEVICE" +``` + +**Step 2: Add `upsert_member` to sync_queries.py** + +```python +# api/db/sync_queries.py — add after add_member (line 65) +def upsert_member( + conn: sqlite3.Connection, + team_name: str, + name: str, + device_id: Optional[str] = None, + ipns_key: Optional[str] = None, +) -> dict: + """Insert or update member — updates device_id if member already exists.""" + conn.execute( + """INSERT INTO sync_members (team_name, name, device_id, ipns_key) + VALUES (?, ?, ?, ?) + ON CONFLICT(team_name, name) DO UPDATE SET + device_id = COALESCE(excluded.device_id, device_id)""", + (team_name, name, device_id, ipns_key), + ) + conn.commit() + return {"team_name": team_name, "name": name, "device_id": device_id} +``` + +**Step 3: Use `upsert_member` in `sync_join_team`** + +Replace lines 549-553 in `sync_status.py`: + +```python + # OLD: + # try: + # add_member(conn, team_name, leader_name, device_id=device_id) + # log_event(conn, "member_added", team_name=team_name, member_name=leader_name) + # except sqlite3.IntegrityError: + # pass + + # NEW: + from db.sync_queries import upsert_member + upsert_member(conn, team_name, leader_name, device_id=device_id) + log_event(conn, "member_added", team_name=team_name, member_name=leader_name) +``` + +**Step 4: Run tests** + +Run: `cd api && pytest tests/test_sync_security.py -v` +Expected: PASS + +**Step 5: Commit** + +```bash +git add api/db/sync_queries.py api/routers/sync_status.py api/tests/test_sync_security.py +git commit -m "fix(sync): upsert member on rejoin instead of silently ignoring [HIGH-5]" +``` + +--- + +### Task 4: Cap activity limit + sanitize error responses [HIGH-3, LOW-2] + +**Files:** +- Modify: `api/routers/sync_status.py:1133-1161` +- Test: `api/tests/test_sync_security.py` (append) + +**Step 1: Write the failing test** + +```python +def test_activity_limit_is_capped(): + """Activity endpoint should cap limit at 200.""" + resp = client.get("/sync/activity?limit=999999") + assert resp.status_code == 200 + # Can't test the SQL directly, but verify the endpoint doesn't crash + +def test_activity_invalid_event_type(): + """Activity with invalid event_type should return empty, not error.""" + resp = client.get("/sync/activity?event_type=DROP TABLE") + assert resp.status_code == 200 +``` + +**Step 2: Modify `sync_activity`** + +```python +VALID_EVENT_TYPES = { + "team_created", "team_deleted", "member_added", "member_removed", + "project_added", "project_removed", "watcher_started", "watcher_stopped", + "sync_now", "pending_accepted", "folders_shared", +} + +@router.get("/activity") +async def sync_activity( + team_name: str | None = None, + event_type: str | None = None, + limit: int = 50, + offset: int = 0, +) -> Any: + """Get recent sync activity events and bandwidth stats.""" + # Clamp limit + limit = max(1, min(limit, 200)) + + # Validate event_type + if event_type and event_type not in VALID_EVENT_TYPES: + event_type = None # ignore invalid types, return all + + conn = _get_sync_conn() + events = query_events(conn, team_name=team_name, event_type=event_type, + limit=limit, offset=offset) + # ... rest unchanged +``` + +**Step 3: Sanitize error responses** + +In the same file, fix the two endpoints that leak internals: + +```python +# Line 979 (sync_watch_start) +except Exception as e: + logger.exception("Failed to start watcher") + raise HTTPException(500, "Failed to start watcher. Check server logs.") + +# Line 1044 (sync_accept_pending) +except Exception as e: + logger.exception("Failed to accept pending folders") + raise HTTPException(500, "Failed to accept pending folders. Check server logs.") +``` + +**Step 4: Run tests** + +Run: `cd api && pytest tests/test_sync_security.py -v` + +**Step 5: Commit** + +```bash +git add api/routers/sync_status.py api/tests/test_sync_security.py +git commit -m "fix(security): cap activity limit, validate event_type, sanitize errors [HIGH-3, LOW-2]" +``` + +--- + +## Phase 2: Complete Missing `/sync` Dashboard Sections + +### Task 5: Add Per-Project Sync Status section to OverviewTab + +This was in the original design but never built. Shows each project with sync gap indicators. + +**Files:** +- Modify: `frontend/src/lib/components/sync/OverviewTab.svelte` +- Modify: `frontend/src/lib/api-types.ts` (add type) + +**Step 1: Add TypeScript type** + +In `frontend/src/lib/api-types.ts`, add after the existing sync types: + +```typescript +export interface SyncProjectStatus { + name: string; + encoded_name: string; + path: string; + local_count: number; + packaged_count: number; + received_counts: Record; + gap: number; +} +``` + +**Step 2: Add state and fetch logic to OverviewTab** + +In `OverviewTab.svelte`, add after the stats section (around line 133): + +```typescript +// ── Per-project sync status ────────────────────────────────────────── +import type { SyncProjectStatus } from '$lib/api-types'; +import { Package, AlertTriangle, CheckCircle2 as CheckCircle2Icon } from 'lucide-svelte'; + +let projectStatuses = $state([]); +let projectStatusLoading = $state(true); + +async function loadProjectStatus() { + if (!teamName) { projectStatusLoading = false; return; } + try { + const res = await fetch( + `${API_BASE}/sync/teams/${encodeURIComponent(teamName)}/project-status` + ).catch(() => null); + if (res?.ok) { + const data = await res.json(); + projectStatuses = data.projects ?? []; + } + } catch { /* non-critical */ } + finally { projectStatusLoading = false; } +} +``` + +Add `loadProjectStatus()` call to the `$effect` block at line 201 inside `untrack()`. + +**Step 3: Add the template section** + +Insert after the Pending Actions section (after line 369), before Machine Details: + +```svelte + +{#if !projectStatusLoading && projectStatuses.length > 0} +
+
+
+ +

Project Sync Status

+
+ +
+
+ {#each projectStatuses as proj (proj.encoded_name)} +
+
+ + + {proj.name} + +
+
+ + {proj.packaged_count}/{proj.local_count} + + {#if proj.gap === 0} + + + In Sync + + {:else} + + + {proj.gap} behind + + {/if} +
+
+ {/each} +
+
+{/if} +``` + +**Step 4: Add "Sync All Now" handler** + +```typescript +let syncingAll = $state(false); + +async function handleSyncAllNow() { + if (!teamName || syncingAll) return; + syncingAll = true; + try { + const res = await fetch( + `${API_BASE}/sync/teams/${encodeURIComponent(teamName)}/sync-now`, + { method: 'POST' } + ).catch(() => null); + if (res?.ok) { + pushSyncAction('sync_now' as any, 'Triggered sync for all projects', teamName ?? ''); + // Refresh project status after sync + await loadProjectStatus(); + } + } finally { + syncingAll = false; + } +} +``` + +**Step 5: Verify manually** + +Run: `cd frontend && npm run check` +Expected: No type errors + +**Step 6: Commit** + +```bash +git add frontend/src/lib/components/sync/OverviewTab.svelte frontend/src/lib/api-types.ts +git commit -m "feat(sync): add Per-Project Sync Status section to dashboard [P0]" +``` + +--- + +### Task 6: Add Recent Activity section to OverviewTab + +Wire up the existing `/sync/activity` API to a visible section. + +**Files:** +- Modify: `frontend/src/lib/components/sync/OverviewTab.svelte` +- Modify: `frontend/src/lib/api-types.ts` + +**Step 1: Add TypeScript type** + +```typescript +export interface SyncEvent { + id: number; + event_type: string; + team_name: string | null; + member_name: string | null; + project_encoded_name: string | null; + detail: string | null; + created_at: string; +} +``` + +**Step 2: Add state, fetch, and humanize logic** + +```typescript +import { Clock } from 'lucide-svelte'; +import type { SyncEvent } from '$lib/api-types'; + +let recentEvents = $state([]); +let eventsLoading = $state(true); + +function humanizeEvent(e: SyncEvent): string { + const who = e.member_name ? `${e.member_name} ` : ''; + const team = e.team_name ? ` (${e.team_name})` : ''; + switch (e.event_type) { + case 'member_added': return `${who}joined${team}`; + case 'member_removed': return `${who}left${team}`; + case 'team_created': return `Team "${e.team_name}" created`; + case 'team_deleted': return `Team "${e.team_name}" deleted`; + case 'project_added': return `Project "${e.project_encoded_name}" shared${team}`; + case 'project_removed': return `Project "${e.project_encoded_name}" removed${team}`; + case 'watcher_started': return `Watcher started${team}`; + case 'watcher_stopped': return `Watcher stopped${team}`; + case 'sync_now': return `Manual sync triggered${team}`; + case 'pending_accepted': return `Pending folders accepted`; + case 'folders_shared': return `Folders shared with ${who}${team}`; + default: return e.event_type; + } +} + +async function loadActivity() { + try { + const res = await fetch(`${API_BASE}/sync/activity?limit=8`).catch(() => null); + if (res?.ok) { + const data = await res.json(); + recentEvents = data.events ?? []; + } + } catch { /* non-critical */ } + finally { eventsLoading = false; } +} +``` + +Add `loadActivity()` to the `$effect` `untrack()` block. + +**Step 3: Add the template** + +Insert after Per-Project Sync Status, before Machine Details: + +```svelte + +{#if !eventsLoading && recentEvents.length > 0} +
+
+ +

Recent Activity

+
+
+ {#each recentEvents as event (event.id)} +
+ {humanizeEvent(event)} + + {formatRelativeTime(event.created_at)} + +
+ {/each} +
+
+{/if} +``` + +**Step 4: Verify** + +Run: `cd frontend && npm run check` + +**Step 5: Commit** + +```bash +git add frontend/src/lib/components/sync/OverviewTab.svelte frontend/src/lib/api-types.ts +git commit -m "feat(sync): add Recent Activity section to dashboard [P1]" +``` + +--- + +### Task 7: Collapse Machine Details into accordion [MEDIUM, P2] + +**Files:** +- Modify: `frontend/src/lib/components/sync/OverviewTab.svelte:372-434` + +**Step 1: Add collapsed state** + +```typescript +let machineDetailsOpen = $state(false); +``` + +**Step 2: Replace the Machine Details section** + +Replace the static card (lines 372-434) with a collapsible version: + +```svelte + +
+ + + {#if machineDetailsOpen} +
+ + ... +
+ {/if} +
+``` + +**Step 3: Commit** + +```bash +git add frontend/src/lib/components/sync/OverviewTab.svelte +git commit -m "feat(sync): collapse Machine Details section by default [MEDIUM]" +``` + +--- + +## Phase 3: Cross-Linking & Wayfinding + +### Task 8: Add watcher status banner to team detail page [P0] + +Users on `/team/[name]` need to know if sync is actually running. + +**Files:** +- Create: `frontend/src/lib/components/sync/SyncStatusBanner.svelte` +- Modify: `frontend/src/routes/team/[name]/+page.svelte` +- Modify: `frontend/src/routes/team/[name]/+page.server.ts` + +**Step 1: Create the banner component** + +```svelte + + + +{#if running} +
+ + Sync active + + Manage + +
+{:else} +
+ + + {syncthingUp ? 'Session watcher paused' : 'Syncthing not running'} + + + Start sync + +
+{/if} +``` + +**Step 2: Fetch watcher status in team detail page.server.ts** + +Add to the parallel fetch in `frontend/src/routes/team/[name]/+page.server.ts`: + +```typescript +// Add to imports +import type { SyncWatchStatus, SyncDetect } from '$lib/api-types'; + +// Add to the Promise.all (line 24): +const [teamsData, devices, joinCodeData, pendingData, syncStatus, watchStatus, detectData] = await Promise.all([ + // ... existing fetches ..., + fetchWithFallback(fetch, `${API_BASE}/sync/watch/status`, { running: false }), + fetchWithFallback(fetch, `${API_BASE}/sync/detect`, { running: false }), +]); + +// Add to return: +return { + // ... existing fields ..., + watchStatus, + detectData, +}; +``` + +**Step 3: Add banner to team detail page** + +In `frontend/src/routes/team/[name]/+page.svelte`, add after PageHeader: + +```svelte +import SyncStatusBanner from '$lib/components/sync/SyncStatusBanner.svelte'; + + +
+ +
+``` + +**Step 4: Verify** + +Run: `cd frontend && npm run check` + +**Step 5: Commit** + +```bash +git add frontend/src/lib/components/sync/SyncStatusBanner.svelte \ + frontend/src/routes/team/[name]/+page.svelte \ + frontend/src/routes/team/[name]/+page.server.ts +git commit -m "feat(team): add sync status banner to team detail page [P0]" +``` + +--- + +### Task 9: Make stats clickable with navigation links [P2] + +**Files:** +- Modify: `frontend/src/lib/components/sync/OverviewTab.svelte:280-302` + +**Step 1: Wrap stats in anchor tags** + +Replace the static stat cards with navigable versions. For "Members Online", link to `/team/{teamName}`. For "Projects", link to `/team/{teamName}`. For "Sessions Received", show per-project breakdown. + +Replace the stats grid (lines 280-302): + +```svelte +
+ + +

{connectedMembers}/{totalMembers}

+

Members Online

+ + + +

{projectCount}

+

Projects

+ +
+ +

{sessionsSharedCount}

+

Sessions Shared

+
+
+ +

{sessionsReceivedCount}

+

Sessions Received

+
+
+``` + +**Step 2: Commit** + +```bash +git add frontend/src/lib/components/sync/OverviewTab.svelte +git commit -m "feat(sync): make Members and Projects stats clickable to team page [P2]" +``` + +--- + +### Task 10: Consolidate home page nav cards [P2] + +Replace two separate "Teams" and "Sync" cards with a single "Sync & Teams" entry. + +**Files:** +- Modify: `frontend/src/routes/+page.svelte:40-41` + +**Step 1: Replace two cards with one** + +```svelte + + + + + + +``` + +**Step 2: Add a redirect from `/team` sync page subtitle pointing to `/sync`** + +In `/team/+page.svelte`, update the subtitle to mention sync: + +```svelte +subtitle="Create and manage teams to share sessions with teammates · Sync status on /sync" +``` + +**Step 3: Commit** + +```bash +git add frontend/src/routes/+page.svelte frontend/src/routes/team/+page.svelte +git commit -m "feat(nav): consolidate Sync and Teams into single nav card [P2]" +``` + +--- + +## Phase 4: Polish & Bug Fixes + +### Task 11: Fix stale stats on team switch [MEDIUM-4] + +**Files:** +- Modify: `frontend/src/lib/components/sync/OverviewTab.svelte:197-205` + +**Step 1: Reset `statsLoaded` when teamName changes** + +Add at line 197, before the `$effect`: + +```typescript +// Reset loaded flags when team changes so loading indicators reappear +$effect(() => { + const _team = teamName; // track + statsLoaded = false; + projectStatusLoading = true; + eventsLoading = true; +}); +``` + +**Step 2: Commit** + +```bash +git add frontend/src/lib/components/sync/OverviewTab.svelte +git commit -m "fix(sync): reset stats when switching teams [MEDIUM-4]" +``` + +--- + +### Task 12: Add AbortController to team detail polling [HIGH-1] + +**Files:** +- Modify: `frontend/src/routes/team/[name]/+page.svelte:51-72` + +**Step 1: Add AbortController** + +Replace the polling `onMount` block: + +```typescript +onMount(() => { + let abortController = new AbortController(); + + const interval = setInterval(async () => { + abortController.abort(); + abortController = new AbortController(); + const signal = abortController.signal; + try { + const [pendingRes, devicesRes] = await Promise.all([ + fetch(`${API_BASE}/sync/pending-devices`, { signal }), + fetch(`${API_BASE}/sync/devices`, { signal }) + ]); + if (pendingRes.ok) { + const pd = await pendingRes.json(); + pendingDevices = pd.devices ?? []; + } + if (devicesRes.ok) { + const dd = await devicesRes.json(); + devices = dd.devices ?? []; + } + } catch (e) { + if (e instanceof DOMException && e.name === 'AbortError') return; + } + }, POLLING_INTERVALS.SYNC_STATUS); + + return () => { + clearInterval(interval); + abortController.abort(); + }; +}); +``` + +**Step 2: Commit** + +```bash +git add frontend/src/routes/team/[name]/+page.svelte +git commit -m "fix(team): add AbortController to polling to prevent stale state updates [HIGH-1]" +``` + +--- + +### Task 13: Fix SetupWizard dynamic import navigation [MEDIUM-5] + +**Files:** +- Modify: `frontend/src/lib/components/sync/SetupWizard.svelte:1-46` + +**Step 1: Replace dynamic import with static import + guard** + +```typescript +// At top of script: +import { goto } from '$app/navigation'; + +let hasNavigated = false; + +// Replace the $effect (lines 42-46): +$effect(() => { + if (status?.configured && step === 2 && !hasNavigated) { + hasNavigated = true; + goto('/team'); + } +}); +``` + +**Step 2: Commit** + +```bash +git add frontend/src/lib/components/sync/SetupWizard.svelte +git commit -m "fix(sync): use static import for goto and prevent duplicate navigation [MEDIUM-5]" +``` + +--- + +### Task 14: Remove dead `syncActions` store calls or wire up consumer [HIGH-2] + +Since we added the Recent Activity section in Task 6 (which uses server events), the client-side `syncActions` store is redundant. Remove the dead calls. + +**Files:** +- Modify: `frontend/src/lib/components/sync/OverviewTab.svelte` (remove `pushSyncAction` calls) +- Delete: `frontend/src/lib/stores/syncActions.svelte.ts` + +**Step 1: Remove imports and calls from OverviewTab** + +Remove the import line: +```typescript +// REMOVE: import { pushSyncAction } from '$lib/stores/syncActions.svelte'; +``` + +Remove calls at lines 55, 68, and 172 (the `pushSyncAction(...)` calls in `startWatch`, `stopWatch`, and `acceptAll`). + +**Step 2: Delete the store file** + +```bash +rm frontend/src/lib/stores/syncActions.svelte.ts +``` + +**Step 3: Verify no other imports** + +Run: `cd frontend && grep -r "syncActions" src/` +Expected: No matches + +**Step 4: Type check** + +Run: `cd frontend && npm run check` + +**Step 5: Commit** + +```bash +git add -A +git commit -m "fix(sync): remove dead syncActions store — replaced by server activity feed [HIGH-2]" +``` + +--- + +### Task 15: Fix device ID truncation [LOW-4] + +**Files:** +- Modify: `frontend/src/lib/components/team/TeamMemberCard.svelte:84-86` +- Modify: `frontend/src/lib/components/team/PendingDeviceCard.svelte:57-59` +- Modify: `frontend/src/lib/components/team/AddMemberDialog.svelte:101` + +**Step 1: Fix in all three files** + +Replace `{value.slice(0, 20)}...` with: + +```svelte +{value.length > 20 ? value.slice(0, 20) + '...' : value} +``` + +Apply to: +- `TeamMemberCard.svelte:85` — `member.device_id` +- `PendingDeviceCard.svelte:58` — `device.device_id` +- `AddMemberDialog.svelte:101` — `parsed.device_id` + +**Step 2: Commit** + +```bash +git add frontend/src/lib/components/team/TeamMemberCard.svelte \ + frontend/src/lib/components/team/PendingDeviceCard.svelte \ + frontend/src/lib/components/team/AddMemberDialog.svelte +git commit -m "fix(team): only show ellipsis when device ID is actually truncated [LOW-4]" +``` + +--- + +### Task 16: Add minimum team name length [LOW-3] + +**Files:** +- Modify: `api/routers/sync_status.py:487` +- Modify: `frontend/src/lib/components/team/CreateTeamDialog.svelte:18` + +**Step 1: API — require 2+ chars** + +```python +# Line 487: +if not ALLOWED_PROJECT_NAME.match(req.name) or len(req.name) > 64 or len(req.name) < 2: + raise HTTPException(400, "Team name must be 2-64 characters (letters, numbers, dashes, underscores)") +``` + +**Step 2: Frontend — match validation** + +```typescript +// CreateTeamDialog.svelte line 18: +let isValid = $derived(/^[a-zA-Z0-9_-]{2,64}$/.test(teamName)); +``` + +**Step 3: Commit** + +```bash +git add api/routers/sync_status.py frontend/src/lib/components/team/CreateTeamDialog.svelte +git commit -m "fix(team): require minimum 2-character team name [LOW-3]" +``` + +--- + +## Summary + +| Phase | Tasks | Issues Addressed | +|---|---|---| +| **Phase 1: Security** | Tasks 1-4 | CRITICAL-1, HIGH-3, HIGH-4, HIGH-5, LOW-2 | +| **Phase 2: Dashboard** | Tasks 5-7 | Per-Project Status, Activity, Sync Now, Machine Details collapse | +| **Phase 3: Wayfinding** | Tasks 8-10 | Watcher banner on team page, clickable stats, nav consolidation | +| **Phase 4: Polish** | Tasks 11-16 | MEDIUM-4, HIGH-1, MEDIUM-5, HIGH-2, LOW-4, LOW-3 | + +**Not addressed (deferred — requires separate design work):** +- CRITICAL-2: Full API authentication (needs auth design beyond scope of this UX fix) +- MEDIUM-1: Read connection separation (optimization, not UX) +- MEDIUM-2: Join code split consistency (edge case, no real-world impact today) +- MEDIUM-3: Partial project add failure (rare edge case) +- MEDIUM-6: Singleton thread safety (unlikely in single-event-loop FastAPI) +- Getting Started checklist (needs UX design + persistence model) +- Better ProjectTeamTab session metadata (needs API enhancement) diff --git a/docs/plans/2026-03-08-sync-permissions-and-security.md b/docs/plans/2026-03-08-sync-permissions-and-security.md new file mode 100644 index 00000000..56afcd6b --- /dev/null +++ b/docs/plans/2026-03-08-sync-permissions-and-security.md @@ -0,0 +1,706 @@ +# Sync Permissions, Security & Activity — Design Document + +**Date:** 2026-03-08 +**Status:** Draft +**Branch:** `worktree-syncthing-sync-design` + +## Problem Statement + +The current sync handshake flow auto-accepts everything once a join code is used. +Users have no control over: +1. Which projects they share when joining a team +2. Whether to accept incoming project shares from teammates +3. What files are received (no validation) + +Activity logging exists but is incomplete — some events lack team/member context, +making it impossible to show a useful team-scoped activity feed. + +## Design Principles + +1. **Explicit sharing, automatic receiving** — You choose what to SEND. You auto-receive from trusted teammates (with validation). +2. **Join code = device trust, not data trust** — The join code pairs devices and creates membership. It does NOT auto-share your sessions. +3. **Team-scoped everything** — All events, approvals, and activity tied to a team. +4. **Validate at the boundary** — Every file from a remote peer is validated before indexing. +5. **Log everything the user cares about** — Every meaningful state change creates an activity event. + +## Trust Model + +``` +Level 0: Anonymous — Unknown device, rejected +Level 1: Device trust — Join code exchanged, Syncthing paired (automatic) +Level 2: Team membership — Member added to team DB (automatic via join code) +Level 3: Project sharing — User explicitly shares project with team (REQUIRES USER ACTION) +Level 4: Session sync — Files flow between paired folders (automatic, with validation) +``` + +Key insight: Levels 1-2 are automatic (the join code IS the consent). +Level 3 requires explicit user action. Level 4 is automatic but validated. + +## Flow Redesign + +### Scenario 1: Bob Joins Alice's Team + +#### Step 1: Join (automatic — levels 1-2) + +Bob pastes `acme:alice:DEVICE-ID` into JoinTeamDialog. + +**API: `POST /sync/teams/join`** (CHANGED) + +What it does now: +- Parse join code ✓ +- Create team locally ✓ +- Add self + leader as members ✓ +- Pair device in Syncthing ✓ +- Create handshake folder ✓ + +What it NO LONGER does: +- ~~Auto-create outbox/inbox folders~~ +- ~~Auto-add matching local projects~~ +- ~~Auto-accept pending folders~~ + +What it NOW returns: + +```json +{ + "ok": true, + "team_name": "acme", + "team_created": true, + "leader_name": "alice", + "paired": true, + "matching_projects": [ + { + "encoded_name": "-Users-bob-work-acme-app", + "path": "/Users/bob/work/acme-app", + "git_identity": "alice/acme-app", + "session_count": 42 + } + ] +} +``` + +The `matching_projects` list shows local projects whose `git_identity` matches +a project already shared in the team. This is a SUGGESTION, not an auto-share. + +#### Step 2: Share Projects (explicit — level 3) + +**UX: JoinTeamDialog success state** (CHANGED) + +After successful join, the dialog shows: + +``` +┌─────────────────────────────────────────────┐ +│ ✓ Joined team "acme" │ +│ │ +│ Connected with alice (pairing active) │ +│ │ +│ These local projects match the team: │ +│ ┌─────────────────────────────────────┐ │ +│ │ ☑ acme-app │ │ +│ │ /Users/bob/work/acme-app │ │ +│ │ 42 sessions │ │ +│ └─────────────────────────────────────┘ │ +│ │ +│ [ Share Selected ] [ Skip for Now ] │ +│ │ +│ You can always share projects later from │ +│ the team page. │ +└─────────────────────────────────────────────┘ +``` + +"Share Selected" calls existing `POST /sync/teams/{name}/projects` for each +selected project, which creates outbox + inbox folders. + +"Skip for Now" navigates to team detail page without sharing anything. + +#### Step 3: Receive (automatic — level 4, with validation) + +Once Bob has shared at least one project, Syncthing folders are live. +Alice's watcher packages sessions → Syncthing syncs → Bob's inbox receives. + +The receive path validates files before indexing (see Security section). + +#### Step 4: Alice discovers Bob (automatic) + +On Alice's machine, `/sync/pending-devices` poll triggers `_auto_accept_pending_peers()`: +1. Sees Bob's device as pending +2. Matches via karma-join-bob-acme handshake folder → team=acme, username=bob +3. Auto-accepts device, adds as member ✓ +4. Auto-creates inbox for Bob's outbox (to RECEIVE Bob's sessions) ✓ +5. Adds Bob's device to Alice's existing outbox folders (so Bob receives Alice's sessions) ✓ +6. Logs: `member_auto_accepted`, `folders_shared` + +This is fine because Alice already shared her projects with the team. +Adding a new member just extends the share — the team-level consent covers it. + +### Scenario 2: Project Present on Both Members + +Alice has `acme-app`, Bob has `acme-app` (same git_identity). + +1. Bob joins team → sees `acme-app` in `matching_projects` +2. Bob checks the box and clicks "Share Selected" +3. API creates Bob's outbox for `acme-app` (sendonly → Alice) +4. API creates inbox for Alice's outbox (receiveonly ← Alice) +5. Sessions flow both ways + +**Key change**: Bob CHOSE to share. Previously this was automatic. + +### Scenario 3: Only the Sharer Has the Project + +Alice shares `acme-app`. Bob joins but doesn't have this project locally. + +1. Bob joins → `matching_projects` is empty (no local git_identity match) +2. Bob clicks "Skip for Now" or shares different projects +3. Alice's auto-accept creates inbox for Bob (empty, ready for when Bob starts working) +4. Meanwhile: Bob receives Alice's sessions via inbox +5. Bob can see Alice's `acme-app` sessions in remote sessions view +6. If Bob later clones the repo: next time they visit team page, a banner shows + "You have a local project matching acme-app — share it?" + +### Scenario 4: New Member Joins, 1+ Projects Already Shared + +Team `acme` has Alice + Carol sharing `acme-app` and `acme-api`. Dave joins. + +1. Dave pastes join code → paired with Alice (code issuer) +2. `matching_projects` shows which of Dave's local projects match +3. Dave selects and shares +4. Alice's pending-devices poll: auto-accepts Dave, creates inbox for Dave, adds Dave to existing outboxes +5. **Carol's discovery**: Next poll of `/sync/pending-devices` on Carol's machine: + - Carol's watcher triggers a pending check (NEW — see Watcher Enhancement below) + - `_auto_accept_pending_peers()` finds Dave's device + - Matches via handshake folder or join-code trust + - Creates inbox for Dave, adds Dave to Carol's outboxes + - Log: `member_auto_accepted(dave)` on Carol's machine + +**Watcher Enhancement** (addresses Carol discovery delay): + +```python +# watcher.py — add periodic pending check +class SessionWatcher: + PENDING_CHECK_INTERVAL = 300 # 5 minutes + + async def _check_pending_peers(self): + """Periodically check for new team members.""" + # Calls _auto_accept_pending_peers() via API + # This ensures all running watchers discover new members + # even without the frontend being open +``` + +### Scenario 5: Member Removal (currently broken) + +Alice removes Bob from team `acme`. + +**Current**: DB row deleted, Syncthing folders remain, sync continues. + +**Fixed flow**: + +```python +# sync_status.py — remove_member endpoint (CHANGED) +async def sync_remove_member(team_name, device_id): + # 1. Remove from DB + remove_member(conn, team_name, device_id) + + # 2. Remove device from all team's Syncthing folders + projects = list_team_projects(conn, team_name) + for proj in projects: + suffix = _compute_proj_suffix(...) + # Remove from my outbox device list + proxy.remove_device_from_folder(f"karma-out-{config.user_id}-{suffix}", device_id) + # Remove their inbox folder entirely + proxy.remove_folder(f"karma-out-{member_name}-{suffix}") + + # 3. Remove handshake folder + proxy.remove_folder(f"karma-join-{member_name}-{team_name}") + + # 4. Optionally remove device from Syncthing entirely + # (only if device is not in any other team) + other_teams = [m for m in get_all_memberships(conn, device_id) if m != team_name] + if not other_teams: + proxy.remove_device(device_id) + + # 5. Log + log_event(conn, "member_removed", team_name=team_name, member_name=member_name) +``` + +### Scenario 6: Re-joining (idempotent) + +Bob uses the join code again. Everything is idempotent: +- `upsert_member` → ON CONFLICT DO UPDATE ✓ +- Handshake folder → already exists ✓ +- `matching_projects` returned again for re-selection ✓ +- No duplicate folders created ✓ + +## Activity Logging Redesign + +### Schema Change + +```sql +-- No new table needed. Fix the existing sync_events usage: + +-- ALL events MUST have team_name (enforce in code, not schema — keep nullable for migration) +-- ALL member-related events MUST have member_name +-- detail JSON gets structured sub-fields +``` + +### Event Types (Revised) + +| Event Type | team_name | member_name | project | detail | +|-----------|-----------|-------------|---------|--------| +| `team_created` | ✓ required | creator | - | `{join_code: "..."}` | +| `team_deleted` | ✓ required | deleter | - | - | +| `member_joined` (NEW) | ✓ | joiner | - | `{via: "join_code"}` | +| `member_auto_accepted` | ✓ | accepted member | - | `{strategy: "handshake"\|"join_code_trust"}` | +| `member_removed` | ✓ | removed member | - | `{removed_by: "self"\|"alice"}` | +| `project_shared` (NEW) | ✓ | sharer | ✓ | `{session_count: N}` | +| `project_removed` | ✓ | remover | ✓ | - | +| `folders_shared` | ✓ | for_member | - | `{outboxes: N, inboxes: N}` | +| `pending_accepted` | ✓ required | from_member | ✓ optional | `{count: N, folders: [...]}` | +| `session_packaged` | ✓ | packager | ✓ | `{uuid: "...", size_bytes: N}` | +| `session_received` | ✓ | from_member | ✓ | `{uuid: "...", size_bytes: N}` | +| `file_rejected` (NEW) | ✓ | from_member | ✓ | `{reason: "...", file: "..."}` | +| `sync_now` | ✓ | triggerer | ✓ optional | - | +| `watcher_started` | ✓ | - | - | - | +| `watcher_stopped` | ✓ | - | - | - | + +### Activity API Changes + +```python +# GET /sync/activity — UNCHANGED (already supports team_name filter) +# But now ALL events have team_name, so team filter always works + +# NEW: GET /sync/teams/{team_name}/activity — convenience alias +@router.get("/teams/{team_name}/activity") +async def sync_team_activity(team_name: str, limit: int = 50, offset: int = 0): + """Team-scoped activity feed for the team detail page.""" + # Same as /sync/activity?team_name=X but validates team exists +``` + +### Frontend: Team Activity Section + +**Location: `/team/[name]` page** (team detail) + +Add an "Activity" section below the existing sections: + +``` +┌─────────────────────────────────────────────────────┐ +│ Activity [Filter ▾] │ +│─────────────────────────────────────────────────────│ +│ ● bob shared acme-app (42 sessions) 2m ago │ +│ ● bob joined the team via join code 5m ago │ +│ ● alice shared acme-api (18 sessions) 1h ago │ +│ ● carol was auto-accepted as member 1h ago │ +│ ● alice created team acme 2h ago │ +│ │ +│ [ Load More ] │ +└─────────────────────────────────────────────────────┘ +``` + +Each event type gets: +- An icon (user+ for joins, folder for shares, sync for sessions, shield for rejections) +- Human-readable description +- Relative timestamp +- Color coding (green for positive, yellow for warnings, red for rejections) + +**Location: `/sync` overview page** — keep the global activity feed (all teams). + +## Disk Space & Session Limits + +### Rule + +``` +FREE DISK >= 10 GiB → sync per user's setting (default: all) +FREE DISK < 10 GiB → force "recent 100" regardless of setting +``` + +### User Setting + +Stored per team in `sync_teams.sync_session_limit`: + +| Value | Behavior | +|-------|----------| +| `all` (default) | Sync every session for shared projects | +| `recent_100` | Only the 100 most recent sessions per project | +| `recent_10` | Only the 10 most recent sessions per project | + +### Schema Change + +```sql +-- Migration v23 +ALTER TABLE sync_teams ADD COLUMN sync_session_limit TEXT DEFAULT 'all'; +``` + +### API + +```python +# PATCH /sync/teams/{team_name}/settings +class UpdateTeamSettingsRequest(BaseModel): + sync_session_limit: Literal["all", "recent_100", "recent_10"] +``` + +### Packager Logic + +```python +import shutil + +MIN_FREE_BYTES = 10 * 1024 * 1024 * 1024 # 10 GiB + +def _get_session_limit(team_session_limit: str, dest_path: Path) -> int | None: + """Return max sessions to package, or None for unlimited. + + If disk has < 10 GiB free, force recent 100 regardless of setting. + """ + free = shutil.disk_usage(dest_path).free + if free < MIN_FREE_BYTES: + return 100 # safety cap + + limits = {"all": None, "recent_100": 100, "recent_10": 10} + return limits.get(team_session_limit, None) +``` + +Applied in `packager.package()`: +- Sort sessions by mtime descending +- Slice to limit +- Manifest `session_count` reflects total, `sessions` array has only synced ones + +### UX: Team Detail Page (`/team/[name]`) + +In the Projects section, a segmented control: + +``` +Sessions to sync: [ All ] [ Recent 100 ] [ Recent 10 ] +``` + +- Calls `PATCH /sync/teams/{name}/settings` on change +- If disk < 10 GiB, show warning banner: + "Low disk space — limited to recent 100 sessions regardless of setting" + +## File Validation & Security + +### Validation Pipeline + +Every file received via Syncthing passes through validation before indexing: + +``` +Syncthing receives file + ↓ +ValidateReceivedFile (NEW) + ├─ Check: file extension in allowlist? + ├─ Check: file size within limits? + ├─ Check: path safe (no traversal)? + ├─ Check: content parseable (JSONL/JSON)? + ├─ PASS → proceed to indexer + └─ FAIL → quarantine + log file_rejected event +``` + +### Allowlist + +```python +# api/services/file_validator.py (NEW) + +ALLOWED_EXTENSIONS = {".jsonl", ".json", ".txt"} +MAX_JSONL_SIZE = 200 * 1024 * 1024 # 200 MB per session file +MAX_JSON_SIZE = 10 * 1024 * 1024 # 10 MB per manifest/todo +MAX_TXT_SIZE = 50 * 1024 * 1024 # 50 MB per tool result +MAX_FILES_PER_SESSION = 500 # subagents + tool results +MAX_TOTAL_SIZE_PER_PROJECT = 2 * 1024 * 1024 * 1024 # 2 GB +``` + +### Path Sanitization + +```python +def validate_remote_path(base_dir: Path, relative_parts: list[str]) -> Path: + """Construct and validate a path from remote-derived components. + + Ensures the resolved path is strictly under base_dir. + Rejects: .., symlinks, non-alphanumeric chars (except - and _). + """ + # Validate each component + SAFE_PART = re.compile(r'^[a-zA-Z0-9_\-\.]+$') + for part in relative_parts: + if not SAFE_PART.match(part): + raise ValueError(f"Unsafe path component: {part!r}") + if part in (".", ".."): + raise ValueError(f"Path traversal attempt: {part!r}") + + constructed = base_dir.joinpath(*relative_parts).resolve() + + # Verify it's still under base_dir + if not str(constructed).startswith(str(base_dir.resolve())): + raise ValueError(f"Path escapes base: {constructed}") + + return constructed +``` + +### JSONL Content Validation + +```python +def validate_jsonl_file(path: Path, max_size: int = MAX_JSONL_SIZE) -> bool: + """Quick validation of a JSONL file before indexing.""" + # Size check + if path.stat().st_size > max_size: + return False + + # Sample first and last lines — must be valid JSON + with open(path) as f: + first_line = f.readline() + if not first_line.strip(): + return False + try: + obj = json.loads(first_line) + # Must have expected top-level keys + if not isinstance(obj, dict): + return False + if "type" not in obj and "role" not in obj: + return False + except json.JSONDecodeError: + return False + + return True +``` + +### Manifest Schema Validation + +```python +from pydantic import BaseModel, field_validator +from typing import Optional + +class ManifestSession(BaseModel): + uuid: str + mtime: str + size_bytes: int = 0 + worktree_name: Optional[str] = None + git_branch: Optional[str] = None + +class SyncManifest(BaseModel): + """Validated manifest for remote session packages.""" + version: int + user_id: str + machine_id: str + project_path: str + project_encoded: str + synced_at: str + session_count: int + sessions: list[ManifestSession] + sync_backend: str = "syncthing" + skill_classifications: dict[str, str] = {} + + @field_validator("user_id", "machine_id") + @classmethod + def validate_identifiers(cls, v): + if not re.match(r'^[a-zA-Z0-9_\-\.]+$', v): + raise ValueError(f"Unsafe identifier: {v!r}") + return v + + @field_validator("skill_classifications") + @classmethod + def validate_classifications(cls, v): + VALID_CATEGORIES = {"plugin_skill", "mcp_tool", "slash_command", "hook_command"} + return {k: cat for k, cat in v.items() if cat in VALID_CATEGORIES} +``` + +### Quarantine + +Files that fail validation are moved to a quarantine directory instead of deleted: + +``` +~/.claude_karma/quarantine/ +├── 2026-03-08T14:30:00Z_alice_malformed-session.jsonl +└── 2026-03-08T14:31:00Z_bob_oversized-tool-result.txt +``` + +A `file_rejected` event is logged with the reason, so the user sees it in the activity feed: + +``` +⚠ Rejected file from alice: session.jsonl exceeds 200MB limit 5m ago +``` + +## Member Removal Cleanup + +### API Change: `DELETE /sync/teams/{team_name}/members/{device_id}` + +```python +async def sync_remove_member(team_name: str, device_id: str): + # 1. Get member info before deletion + member = get_member_by_device_id(conn, device_id) + member_name = member["name"] if member else "unknown" + + # 2. Remove from DB + remove_member(conn, team_name, device_id) + + # 3. Cleanup Syncthing folders (best-effort) + try: + proxy = get_proxy() + projects = list_team_projects(conn, team_name) + for proj in projects: + suffix = _compute_proj_suffix(...) + # Remove device from our outbox sharing list + try: + await run_sync(proxy.remove_device_from_folder, + f"karma-out-{config.user_id}-{suffix}", device_id) + except Exception: + pass + # Remove their inbox folder from our Syncthing + try: + await run_sync(proxy.remove_folder, + f"karma-out-{member_name}-{suffix}") + except Exception: + pass + + # Remove handshake folder + try: + await run_sync(proxy.remove_folder, + f"karma-join-{member_name}-{team_name}") + except Exception: + pass + + # Remove device entirely if not in other teams + all_memberships = conn.execute( + "SELECT team_name FROM sync_members WHERE device_id = ?", + (device_id,) + ).fetchall() + if not all_memberships: + await run_sync(proxy.remove_device, device_id) + except Exception as e: + logger.warning("Cleanup failed for removed member %s: %s", member_name, e) + + # 4. Log + log_event(conn, "member_removed", team_name=team_name, + member_name=member_name, + detail={"removed_by": config.user_id}) + + return {"ok": True, "member_name": member_name, "cleanup": True} +``` + +## Watcher Enhancement: Periodic Peer Discovery + +```python +# cli/karma/watcher.py (CHANGED) + +PEER_CHECK_INTERVAL = 300 # 5 minutes + +class SessionWatcher: + def __init__(self, ...): + self._last_peer_check = 0 + + def _maybe_check_peers(self): + """Check for new team members periodically.""" + now = time.time() + if now - self._last_peer_check < PEER_CHECK_INTERVAL: + return + + self._last_peer_check = now + try: + # Import and call the pending acceptance logic + from karma.main import _accept_pending_folders + accepted = _accept_pending_folders(self.st, self.config, self.conn) + if accepted: + logger.info("Watcher discovered %d new folders from peers", accepted) + except Exception as e: + logger.debug("Peer check failed: %s", e) +``` + +This ensures Carol discovers Dave within 5 minutes even without +the frontend open, as long as the watcher is running. + +## UX: Permission Steps at the Right Place + +### Page-by-Page Breakdown + +#### `/sync` (Setup & Overview) +- **Permission**: Initialize sync identity (one-time) +- **Activity**: Global activity feed (all teams, last 8 events) +- **No approval actions here** — this is the overview/status page + +#### `/team` (Team List) +- **Permission**: Create team, Join team +- **Pending**: Shows incoming device connections with "Ask for join code" CTA +- **No project-level actions here** — keeps the list page simple + +#### `/team/[name]` (Team Detail) — THE MAIN CONTROL CENTER +- **Permissions**: + - Share projects: "Add Projects" button → AddProjectDialog with multi-select + - Accept incoming shares: "Incoming Shares" section with Accept/Reject per project + - Remove members: Per-member remove button with confirmation + - Leave team: Danger zone +- **Activity**: Team-scoped activity feed (dedicated section) +- **Status**: Per-project sync status (local vs packaged vs received) + +#### JoinTeamDialog (Modal overlay) +- **Permission**: Confirm join + select projects to share (in one flow) +- Shows parsed join code details before confirming +- After success: shows matching projects for immediate sharing +- "Skip for Now" always available — no forced sharing + +### Flow Diagram + +``` +User pastes join code + ↓ +JoinTeamDialog parses + shows details + ↓ +[Join Team] button + ↓ +API pairs device + creates membership + ↓ +Dialog shows success + matching projects + ↓ +User selects projects → [Share Selected] + OR +[Skip for Now] → navigate to /team/[name] + ↓ +/team/[name] page: + ├── Members section (alice, bob) + ├── Projects section (shared by you + received) + ├── Incoming Shares (from other members, accept/reject) + └── Activity feed (everything that happened) +``` + +## Implementation Tasks + +### Backend (API) + +1. **Schema migration v23** — Add `sync_session_limit TEXT DEFAULT 'all'` to `sync_teams` +2. **Modify `sync_join_team()`** — Remove auto-share, return `matching_projects` list +3. **Add `validate_received_file()`** — New service in `api/services/file_validator.py` +4. **Add `SyncManifest` Pydantic model** — Validate manifest.json on receive +5. **Integrate validation into indexer** — Call validator before `Session.from_path()` +6. **Enrich all `log_event()` calls** — Ensure team_name + member_name on every event +7. **Add `GET /sync/teams/{team_name}/activity`** — Team-scoped activity endpoint +8. **Add `PATCH /sync/teams/{team_name}/settings`** — Session limit update endpoint +9. **Fix `sync_remove_member()`** — Add Syncthing folder cleanup +10. **Add quarantine directory** — Move rejected files, log `file_rejected` events + +### CLI + +11. **Packager session limit** — Add `_get_session_limit()` + disk space check to `package()` +12. **Add file validation to `_accept_pending_folders()`** — Validate before creating inbox +13. **Add peer check to watcher** — Periodic `_accept_pending_folders()` call every 5 min +14. **Add path sanitization** — `validate_remote_path()` for all remote-derived paths + +### Frontend + +15. **Modify JoinTeamDialog** — Show matching projects after join success +16. **Add Activity section to team detail page** — `TeamActivityFeed.svelte` component +17. **Add session limit selector to team detail** — Segmented control + low-disk warning +18. **Add file rejection warnings** — Show `file_rejected` events prominently in feed + +## Migration / Backwards Compatibility + +- Existing teams continue to work (no schema change) +- Existing auto-shared folders remain intact (no cleanup of working state) +- The only behavior change: NEW joins won't auto-share projects +- Activity events from before this change will have null team_name — that's fine, + the UI shows "—" for missing context + +## Security Summary + +| Attack Vector | Current | After Fix | +|--------------|---------|-----------| +| Malicious JSONL (crash indexer) | No validation | Size + format check | +| Oversized files (disk exhaustion) | No limits | Per-file + per-project caps | +| Path traversal via folder ID | Relies on Path() | Explicit regex + resolve check | +| Git identity spoofing | Auto-resolves wrong project | Manifest validated, project sharing explicit | +| Non-JSONL files injected | Any file accepted | Extension allowlist | +| Removed member keeps syncing | Folders persist | Full Syncthing cleanup | +| 3rd member discovery delay | Frontend poll only | Watcher periodic check (5 min) | +| Disk exhaustion via sync | No limits | 10 GiB floor → force recent 100 | +| Unbounded session count | All sessions synced | User-controlled: all / 100 / 10 | diff --git a/docs/plans/2026-03-08-sync-titles-design.md b/docs/plans/2026-03-08-sync-titles-design.md new file mode 100644 index 00000000..345e5b6b --- /dev/null +++ b/docs/plans/2026-03-08-sync-titles-design.md @@ -0,0 +1,147 @@ +# Sync Session Titles Across Devices + +## Problem + +When sessions are synced via Syncthing, the receiver sees remote sessions without titles. The hook-generated titles (from git commits or Haiku) are stored only in the sender's local SQLite and disk cache — they never reach the outbox. + +Claude Code's native `SessionTitleMessage` entries (type: "summary") are inside the JSONL and do get synced, but the receiver's `_build_remote_metadata()` only reads first/last lines for performance — it never extracts them. + +**Result**: Owner sees a list of UUIDs/slugs for freelancer sessions, making team activity opaque. + +## Design: `titles.json` Sidecar File + +A separate `titles.json` file in each outbox directory, written independently of the packager, synced by Syncthing like any other file. + +### Why not add titles to manifest.json? + +Timing gap. The watcher fires on JSONL changes; the title hook fires on SessionEnd. The title is generated AFTER packaging. And the title POST doesn't modify any JSONL, so no re-trigger occurs. A separate file avoids this chicken-and-egg problem. + +### File location + +``` +~/.claude_karma/remote-sessions/{user_id}/{encoded_name}/ + ├── manifest.json (structural: uuids, mtimes, worktrees) + ├── titles.json (display: uuid → title) ← NEW + └── sessions/ + └── *.jsonl +``` + +### File format + +```json +{ + "version": 1, + "updated_at": "2026-03-08T14:30:00Z", + "titles": { + "abc-123-uuid": { + "title": "Fix auth bug in login flow", + "source": "git", + "generated_at": "2026-03-08T12:00:00Z" + }, + "def-456-uuid": { + "title": "Add pagination to users API", + "source": "haiku", + "generated_at": "2026-03-08T13:00:00Z" + } + } +} +``` + +Fields per entry: +- `title` — the display title string +- `source` — how it was generated: `"git"`, `"haiku"`, or `"fallback"` +- `generated_at` — ISO timestamp of generation + +## Data Flow + +``` +SENDER RECEIVER +══════ ════════ + +SessionEnd + ├─ Watcher → packages JSONL + manifest + │ └─ packager also dumps known titles from cache → titles.json + │ + └─ Title hook → POST /sessions/{id}/title + ├─ SQLite ✅ (existing) + ├─ Disk cache ✅ (existing) + └─ Outbox titles.json ✅ (NEW) + │ + Syncthing syncs titles.json + │ + ▼ + Receiver reads titles.json + alongside manifest + │ + ▼ + Dashboard shows title ✅ +``` + +Both write paths (packager + title POST handler) merge into the same `titles.json`. The packager catches older sessions' titles from the cache; the title handler catches the latest session's title even if the packager already ran. + +## Changes + +### Sender side + +**1. `api/routers/sessions.py` — POST /sessions/{uuid}/title handler** + +After storing in SQLite + disk cache (existing), also write to the outbox `titles.json`: +- Read sync-config.json to get `user_id` +- Find the session's `encoded_name` +- Write/merge into `~/.claude_karma/remote-sessions/{user_id}/{encoded_name}/titles.json` +- Use atomic write (write to `.tmp`, rename) to avoid partial reads + +**2. `cli/karma/packager.py` — `package()` method** + +After writing `manifest.json`, also write `titles.json`: +- Read from the local title cache (`SessionTitleCache`) for all discovered sessions +- Merge with any existing `titles.json` in the staging dir (preserve titles for sessions we didn't re-discover) +- Write atomically + +**3. New utility: `cli/karma/titles_io.py`** + +Shared read/write logic for `titles.json`: +- `read_titles(path) -> dict[str, TitleInfo]` +- `write_title(path, uuid, title, source)` — merge-and-write +- `write_titles_bulk(path, entries)` — bulk write from packager +- Atomic file writes with `.tmp` + rename + +### Receiver side + +**4. `api/services/remote_sessions.py` — metadata builder** + +- New `_load_remote_titles(user_id, encoded_name) -> dict[str, str]` (cached with TTL, same pattern as `_load_manifest_worktree_map`) +- `_build_remote_metadata()` populates title from this cache +- `list_remote_sessions_for_project()` and `iter_all_remote_session_metadata()` pass titles through + +**5. `api/services/session_filter.py` — SessionMetadata** + +- Add `remote_title: Optional[str] = None` field +- Search/filter logic can match against remote titles + +### No changes needed + +- `cli/karma/manifest.py` — manifest model stays structural +- `hooks/session_title_generator.py` — it POSTs to API, which handles the rest +- `api/db/sync_queries.py` — no DB schema changes +- `api/services/syncthing_proxy.py` — Syncthing handles file sync automatically + +## Edge Cases + +| Case | Handling | +|------|----------| +| Title generated before first package | Packager reads from cache, includes in titles.json | +| Title generated after package | POST handler writes to outbox titles.json directly | +| Multiple titles for same session | Use latest (by generated_at); sender already deduplicates | +| Session deleted but title remains | Harmless — orphan entries in titles.json are ignored | +| titles.json doesn't exist yet | Create it; receiver treats missing file as "no titles" | +| Concurrent writes (packager + hook) | Atomic writes prevent corruption; last writer wins but both merge | +| Receiver has own title for remote session | Remote title takes priority (it was generated on the source machine with full context) | + +## Testing + +- Unit: `titles_io.py` read/write/merge logic +- Integration: POST /title → verify titles.json written in outbox +- Integration: packager → verify titles.json includes cached titles +- Integration: remote_sessions → verify titles loaded from inbox titles.json +- E2E: generate title on sender → verify it appears in receiver's session list diff --git a/docs/plans/2026-03-08-sync-titles-plan.md b/docs/plans/2026-03-08-sync-titles-plan.md new file mode 100644 index 00000000..207009c9 --- /dev/null +++ b/docs/plans/2026-03-08-sync-titles-plan.md @@ -0,0 +1,776 @@ +# Sync Session Titles Implementation Plan + +> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. + +**Goal:** Share hook-generated session titles across devices via a `titles.json` sidecar file in the Syncthing outbox, so receivers see meaningful session names instead of UUIDs. + +**Architecture:** A new `titles_io.py` module provides atomic read/write/merge for `titles.json`. The sender writes titles from two paths: (1) the packager dumps cached titles during packaging, (2) the POST /title handler writes immediately when a new title is generated. The receiver reads `titles.json` alongside `manifest.json` using the same TTL-cached pattern already used for worktree attribution. + +**Tech Stack:** Python 3.9+, Pydantic, pytest, existing SessionTitleCache, existing remote_sessions service + +--- + +### Task 1: Create `titles_io.py` — shared titles.json read/write + +**Files:** +- Create: `cli/karma/titles_io.py` +- Create: `api/tests/test_titles_io.py` + +**Step 1: Write the failing tests** + +```python +# api/tests/test_titles_io.py +"""Tests for titles_io read/write/merge logic.""" + +import json +from pathlib import Path + +import pytest + +# Add CLI to path for import +import sys +sys.path.insert(0, str(Path(__file__).parent.parent.parent / "cli")) + +from karma.titles_io import read_titles, write_title, write_titles_bulk + + +class TestReadTitles: + def test_returns_empty_dict_when_file_missing(self, tmp_path): + result = read_titles(tmp_path / "titles.json") + assert result == {} + + def test_returns_empty_dict_when_file_corrupt(self, tmp_path): + path = tmp_path / "titles.json" + path.write_text("not json") + result = read_titles(path) + assert result == {} + + def test_reads_valid_titles(self, tmp_path): + path = tmp_path / "titles.json" + path.write_text(json.dumps({ + "version": 1, + "titles": { + "uuid-1": {"title": "Fix bug", "source": "git", "generated_at": "2026-03-08T12:00:00Z"} + } + })) + result = read_titles(path) + assert "uuid-1" in result + assert result["uuid-1"]["title"] == "Fix bug" + assert result["uuid-1"]["source"] == "git" + + def test_ignores_unknown_version(self, tmp_path): + path = tmp_path / "titles.json" + path.write_text(json.dumps({"version": 99, "titles": {"a": {"title": "x"}}})) + result = read_titles(path) + assert result == {} + + +class TestWriteTitle: + def test_creates_file_if_missing(self, tmp_path): + path = tmp_path / "titles.json" + write_title(path, "uuid-1", "Fix bug", "git") + + data = json.loads(path.read_text()) + assert data["version"] == 1 + assert data["titles"]["uuid-1"]["title"] == "Fix bug" + assert data["titles"]["uuid-1"]["source"] == "git" + assert "generated_at" in data["titles"]["uuid-1"] + assert "updated_at" in data + + def test_merges_with_existing(self, tmp_path): + path = tmp_path / "titles.json" + write_title(path, "uuid-1", "First title", "git") + write_title(path, "uuid-2", "Second title", "haiku") + + data = json.loads(path.read_text()) + assert len(data["titles"]) == 2 + assert data["titles"]["uuid-1"]["title"] == "First title" + assert data["titles"]["uuid-2"]["title"] == "Second title" + + def test_overwrites_existing_uuid(self, tmp_path): + path = tmp_path / "titles.json" + write_title(path, "uuid-1", "Old title", "fallback") + write_title(path, "uuid-1", "New title", "haiku") + + data = json.loads(path.read_text()) + assert data["titles"]["uuid-1"]["title"] == "New title" + assert data["titles"]["uuid-1"]["source"] == "haiku" + + def test_creates_parent_dirs(self, tmp_path): + path = tmp_path / "deep" / "nested" / "titles.json" + write_title(path, "uuid-1", "Test", "git") + assert path.exists() + + +class TestWriteTitlesBulk: + def test_writes_multiple_titles(self, tmp_path): + path = tmp_path / "titles.json" + entries = { + "uuid-1": {"title": "First", "source": "git"}, + "uuid-2": {"title": "Second", "source": "haiku"}, + } + write_titles_bulk(path, entries) + + data = json.loads(path.read_text()) + assert len(data["titles"]) == 2 + + def test_merges_with_existing_preserving_newer(self, tmp_path): + path = tmp_path / "titles.json" + # Write initial + write_title(path, "uuid-1", "Original", "haiku") + + # Bulk write that includes uuid-1 with different title + entries = { + "uuid-1": {"title": "Bulk override", "source": "git"}, + "uuid-2": {"title": "New entry", "source": "haiku"}, + } + write_titles_bulk(path, entries) + + data = json.loads(path.read_text()) + assert len(data["titles"]) == 2 + # Bulk should overwrite + assert data["titles"]["uuid-1"]["title"] == "Bulk override" + + def test_handles_empty_entries(self, tmp_path): + path = tmp_path / "titles.json" + write_titles_bulk(path, {}) + # Should create valid empty file + data = json.loads(path.read_text()) + assert data["titles"] == {} +``` + +**Step 2: Run tests to verify they fail** + +Run: `cd api && python -m pytest tests/test_titles_io.py -v` +Expected: FAIL with `ModuleNotFoundError: No module named 'karma.titles_io'` + +**Step 3: Write the implementation** + +```python +# cli/karma/titles_io.py +"""Atomic read/write/merge for titles.json sidecar files. + +Used by both the session packager (bulk dump of cached titles) and the +POST /sessions/{uuid}/title handler (single title write on generation). + +File format: +{ + "version": 1, + "updated_at": "2026-03-08T14:30:00Z", + "titles": { + "uuid": {"title": "...", "source": "git|haiku|fallback", "generated_at": "..."} + } +} +""" + +import json +from datetime import datetime, timezone +from pathlib import Path +from typing import Optional + + +_VERSION = 1 + + +def read_titles(path: Path) -> dict[str, dict]: + """Read titles.json. Returns {uuid: {title, source, generated_at}} or empty dict.""" + if not path.is_file(): + return {} + try: + data = json.loads(path.read_text(encoding="utf-8")) + if data.get("version") != _VERSION: + return {} + return data.get("titles", {}) + except (json.JSONDecodeError, OSError, TypeError): + return {} + + +def write_title( + path: Path, + uuid: str, + title: str, + source: str, + generated_at: Optional[str] = None, +) -> None: + """Write or merge a single title into titles.json. Atomic (tmp+rename).""" + existing = read_titles(path) + existing[uuid] = { + "title": title, + "source": source, + "generated_at": generated_at or datetime.now(timezone.utc).isoformat(), + } + _write_file(path, existing) + + +def write_titles_bulk(path: Path, entries: dict[str, dict]) -> None: + """Bulk write/merge titles into titles.json. Atomic (tmp+rename). + + Args: + path: Path to titles.json + entries: {uuid: {"title": str, "source": str}} — generated_at added if missing + """ + existing = read_titles(path) + now = datetime.now(timezone.utc).isoformat() + for uuid, entry in entries.items(): + existing[uuid] = { + "title": entry["title"], + "source": entry.get("source", "unknown"), + "generated_at": entry.get("generated_at", now), + } + _write_file(path, existing) + + +def _write_file(path: Path, titles: dict[str, dict]) -> None: + """Atomically write titles dict to path.""" + path.parent.mkdir(parents=True, exist_ok=True) + payload = { + "version": _VERSION, + "updated_at": datetime.now(timezone.utc).isoformat(), + "titles": titles, + } + tmp_path = path.with_suffix(".tmp") + tmp_path.write_text(json.dumps(payload, indent=2, ensure_ascii=False) + "\n", encoding="utf-8") + tmp_path.replace(path) +``` + +**Step 4: Run tests to verify they pass** + +Run: `cd api && python -m pytest tests/test_titles_io.py -v` +Expected: All PASS + +**Step 5: Commit** + +```bash +git add cli/karma/titles_io.py api/tests/test_titles_io.py +git commit -m "feat(sync): add titles_io module for titles.json sidecar read/write" +``` + +--- + +### Task 2: Packager writes `titles.json` during packaging + +**Files:** +- Modify: `cli/karma/packager.py:199-221` (after manifest write) +- Create: `api/tests/test_packager_titles.py` + +**Step 1: Write the failing test** + +```python +# api/tests/test_packager_titles.py +"""Tests for packager writing titles.json alongside manifest.""" + +import json +import sys +from pathlib import Path + +import pytest + +sys.path.insert(0, str(Path(__file__).parent.parent.parent / "cli")) + +from karma.packager import SessionPackager + + +@pytest.fixture +def project_dir(tmp_path): + """Create a fake Claude project directory with sessions.""" + claude_projects = tmp_path / ".claude" / "projects" / "-Users-test-acme" + claude_projects.mkdir(parents=True) + + # Create session JSONL files + for uuid in ("sess-001", "sess-002"): + (claude_projects / f"{uuid}.jsonl").write_text( + json.dumps({ + "type": "user", + "message": {"role": "user", "content": "hello"}, + "timestamp": "2026-03-08T12:00:00Z", + }) + "\n" + ) + return claude_projects + + +class TestPackagerWritesTitles: + def test_writes_titles_json_from_cache(self, project_dir, tmp_path): + """Packager should write titles.json with any cached titles.""" + staging = tmp_path / "staging" + staging.mkdir() + + # Pre-populate a title cache file so packager can read it + from karma.titles_io import write_title + cache_titles_path = staging / "titles.json" + # We won't have a real title cache, so test that titles.json is at least created + packager = SessionPackager( + project_dir=project_dir, + user_id="alice", + machine_id="alice-mbp", + project_path="/Users/test/acme", + ) + manifest = packager.package(staging) + + # manifest.json should exist + assert (staging / "manifest.json").exists() + + # titles.json should exist (may be empty if no title cache) + titles_path = staging / "titles.json" + assert titles_path.exists() + data = json.loads(titles_path.read_text()) + assert data["version"] == 1 + assert isinstance(data["titles"], dict) + + def test_preserves_existing_titles_in_staging(self, project_dir, tmp_path): + """Packager should merge with existing titles.json (from prior title hook writes).""" + staging = tmp_path / "staging" + staging.mkdir() + + # Pre-populate titles.json with a title from a prior hook write + from karma.titles_io import write_title + write_title(staging / "titles.json", "sess-001", "Prior hook title", "haiku") + + packager = SessionPackager( + project_dir=project_dir, + user_id="alice", + machine_id="alice-mbp", + project_path="/Users/test/acme", + ) + packager.package(staging) + + data = json.loads((staging / "titles.json").read_text()) + # Prior title should still be present + assert data["titles"]["sess-001"]["title"] == "Prior hook title" +``` + +**Step 2: Run tests to verify they fail** + +Run: `cd api && python -m pytest tests/test_packager_titles.py -v` +Expected: FAIL (titles.json not created by packager) + +**Step 3: Implement — add titles.json write to packager** + +Modify `cli/karma/packager.py`. After the manifest write at line 219, add: + +```python + # Write titles.json — merge cached titles with any existing titles + from karma.titles_io import read_titles, write_titles_bulk + + titles_path = staging_dir / "titles.json" + # Bulk write preserves existing entries (from prior title hook writes) + # For now, packager writes an empty titles.json if no external titles are provided. + # The title_entries parameter allows callers to inject cached titles. + if not titles_path.exists(): + write_titles_bulk(titles_path, {}) + + manifest_path = staging_dir / "manifest.json" +``` + +Wait — the packager doesn't have access to the API's SessionTitleCache (it's a CLI module). The packager should write an empty `titles.json` if none exists, preserving any that the title hook already wrote. The actual titles come from the POST handler (Task 3). + +The real merge point: `write_titles_bulk` with an empty dict when no new titles — this ensures the file exists and preserves anything already there. + +Add after line 219 of `cli/karma/packager.py`: + +```python + # Ensure titles.json exists in staging (preserves any prior title hook writes) + from karma.titles_io import write_titles_bulk + titles_path = staging_dir / "titles.json" + if not titles_path.exists(): + write_titles_bulk(titles_path, {}) +``` + +**Step 4: Run tests to verify they pass** + +Run: `cd api && python -m pytest tests/test_packager_titles.py -v` +Expected: All PASS + +**Step 5: Commit** + +```bash +git add cli/karma/packager.py api/tests/test_packager_titles.py +git commit -m "feat(sync): packager creates titles.json sidecar in outbox" +``` + +--- + +### Task 3: POST /title handler writes to outbox `titles.json` + +**Files:** +- Modify: `api/routers/sessions.py:1726-1792` (set_session_title endpoint) +- Modify: `api/tests/api/test_set_session_title.py` (add outbox write test) + +**Step 1: Write the failing test** + +Add to `api/tests/api/test_set_session_title.py`: + +```python +class TestSetSessionTitleOutbox: + """Tests for title propagation to Syncthing outbox titles.json.""" + + def test_writes_to_outbox_titles_json(self, client, sample_session_for_title, tmp_path): + """POST /sessions/{uuid}/title should write to outbox titles.json.""" + session_uuid, encoded_name = sample_session_for_title + + # Set up sync config so the handler knows where the outbox is + karma_base = tmp_path / ".claude_karma" + karma_base.mkdir() + sync_config = { + "user_id": "testuser", + "machine_id": "test-machine", + } + (karma_base / "sync-config.json").write_text(json.dumps(sync_config)) + + # Create outbox directory + outbox = karma_base / "remote-sessions" / "testuser" / encoded_name + outbox.mkdir(parents=True) + + with patch("routers.sessions.settings") as mock_settings: + # Keep existing settings but override karma_base + mock_settings.karma_base = karma_base + mock_settings.projects_dir = settings.projects_dir + mock_settings.use_sqlite = False + + response = client.post( + f"/sessions/{session_uuid}/title", + json={"title": "Test Outbox Title"}, + ) + + assert response.status_code == 200 + + # Verify titles.json was written in outbox + titles_path = outbox / "titles.json" + if titles_path.exists(): + import json as json_mod + data = json_mod.loads(titles_path.read_text()) + assert data["titles"][session_uuid]["title"] == "Test Outbox Title" +``` + +**Step 2: Run tests to verify they fail** + +Run: `cd api && python -m pytest tests/api/test_set_session_title.py::TestSetSessionTitleOutbox -v` +Expected: FAIL (no outbox write logic yet) + +**Step 3: Implement — add outbox write to POST handler** + +Modify `api/routers/sessions.py`, in `set_session_title()` function. After the SQLite update block (after line 1787), add before the return statement: + +```python + # Write to Syncthing outbox titles.json (best-effort, non-blocking) + try: + import sys + from pathlib import Path + + cli_path = Path(__file__).parent.parent.parent / "cli" + if str(cli_path) not in sys.path: + sys.path.insert(0, str(cli_path)) + + sync_config_path = settings.karma_base / "sync-config.json" + if sync_config_path.exists(): + sync_data = json.loads(sync_config_path.read_text()) + user_id = sync_data.get("user_id") + if user_id: + outbox_dir = settings.karma_base / "remote-sessions" / user_id / encoded_name + if outbox_dir.exists(): + from karma.titles_io import write_title as write_outbox_title + + # Determine title source from existing data + source = "hook" + write_outbox_title( + outbox_dir / "titles.json", uuid, title, source + ) + except Exception as e: + logger.debug("Failed to write title to outbox: %s", e) + # Best-effort — don't fail the request +``` + +**Step 4: Run tests to verify they pass** + +Run: `cd api && python -m pytest tests/api/test_set_session_title.py -v` +Expected: All PASS + +**Step 5: Commit** + +```bash +git add api/routers/sessions.py api/tests/api/test_set_session_title.py +git commit -m "feat(sync): POST /title writes to Syncthing outbox titles.json" +``` + +--- + +### Task 4: Receiver reads titles from inbox `titles.json` + +**Files:** +- Modify: `api/services/remote_sessions.py:333-514` +- Modify: `api/tests/test_remote_sessions.py` + +**Step 1: Write the failing tests** + +Add to `api/tests/test_remote_sessions.py`: + +```python +class TestRemoteSessionTitles: + """Tests for title loading from inbox titles.json.""" + + def test_loads_title_from_titles_json(self, karma_base): + """Remote sessions should have titles populated from titles.json.""" + encoded = "-Users-jayant-acme" + alice_dir = karma_base / "remote-sessions" / "alice" / encoded + + # Write titles.json + titles_data = { + "version": 1, + "updated_at": "2026-03-08T12:00:00Z", + "titles": { + "sess-001": { + "title": "Fix authentication bug", + "source": "git", + "generated_at": "2026-03-08T12:00:00Z", + }, + "sess-002": { + "title": "Add user pagination", + "source": "haiku", + "generated_at": "2026-03-08T13:00:00Z", + }, + }, + } + (alice_dir / "titles.json").write_text(json.dumps(titles_data)) + + with patch("services.remote_sessions.settings") as mock_settings: + mock_settings.karma_base = karma_base + results = list_remote_sessions_for_project("-Users-jayant-acme") + + # Find alice's sessions + by_uuid = {r.uuid: r for r in results} + assert by_uuid["sess-001"].session_titles == ["Fix authentication bug"] + assert by_uuid["sess-002"].session_titles == ["Add user pagination"] + + def test_handles_missing_titles_json(self, karma_base): + """Sessions should work fine without titles.json (backward compat).""" + with patch("services.remote_sessions.settings") as mock_settings: + mock_settings.karma_base = karma_base + results = list_remote_sessions_for_project("-Users-jayant-acme") + + # No titles.json exists in fixture — sessions should still load + assert len(results) == 3 + for r in results: + assert r.session_titles is None or r.session_titles == [] + + def test_iter_all_includes_titles(self, karma_base): + """iter_all_remote_session_metadata should also include titles.""" + encoded = "-Users-jayant-acme" + alice_dir = karma_base / "remote-sessions" / "alice" / encoded + titles_data = { + "version": 1, + "titles": { + "sess-001": {"title": "Fix bug", "source": "git", "generated_at": "2026-03-08T12:00:00Z"} + }, + } + (alice_dir / "titles.json").write_text(json.dumps(titles_data)) + + with patch("services.remote_sessions.settings") as mock_settings: + mock_settings.karma_base = karma_base + results = list(iter_all_remote_session_metadata()) + + by_uuid = {r.uuid: r for r in results} + assert by_uuid["sess-001"].session_titles == ["Fix bug"] + + def test_titles_cache_has_ttl(self, karma_base): + """Title cache should expire after TTL.""" + import services.remote_sessions as mod + + encoded = "-Users-jayant-acme" + alice_dir = karma_base / "remote-sessions" / "alice" / encoded + + # Write initial titles + titles_data = {"version": 1, "titles": {"sess-001": {"title": "V1", "source": "git", "generated_at": "2026-03-08T12:00:00Z"}}} + (alice_dir / "titles.json").write_text(json.dumps(titles_data)) + + with patch("services.remote_sessions.settings") as mock_settings: + mock_settings.karma_base = karma_base + # First load + results1 = list_remote_sessions_for_project("-Users-jayant-acme") + + by_uuid1 = {r.uuid: r for r in results1} + assert by_uuid1["sess-001"].session_titles == ["V1"] +``` + +**Step 2: Run tests to verify they fail** + +Run: `cd api && python -m pytest tests/test_remote_sessions.py::TestRemoteSessionTitles -v` +Expected: FAIL (session_titles not populated) + +**Step 3: Implement — add title loading to remote_sessions.py** + +Add a title loading function (same pattern as `_load_manifest_worktree_map`): + +```python +# Add near the top with other caches (after line 44) +_titles_cache: dict[tuple[str, str], tuple[float, dict[str, str]]] = {} +_TITLES_TTL = 30.0 # seconds + + +def _load_remote_titles(user_id: str, encoded_name: str) -> dict[str, str]: + """ + Load titles.json for a (user_id, encoded_name) pair and return + a mapping of uuid -> title string. + + Results are cached with a TTL. + """ + cache_key = (user_id, encoded_name) + now = time.monotonic() + + cached = _titles_cache.get(cache_key) + if cached is not None: + cache_time, cache_data = cached + if (now - cache_time) < _TITLES_TTL: + return cache_data + + result: dict[str, str] = {} + titles_path = ( + _get_remote_sessions_dir() / user_id / encoded_name / "titles.json" + ) + if titles_path.exists(): + try: + with open(titles_path) as f: + data = json.load(f) + if data.get("version") == 1: + for uuid, entry in data.get("titles", {}).items(): + title = entry.get("title") + if title: + result[uuid] = title + except (json.JSONDecodeError, OSError) as e: + logger.debug( + "Failed to load titles for %s/%s: %s", user_id, encoded_name, e + ) + + _titles_cache[cache_key] = (now, result) + return result +``` + +Modify `_build_remote_metadata()` to accept a `title` parameter (line 457-513): + +Add `title: Optional[str] = None` parameter, and populate `session_titles`: + +```python +def _build_remote_metadata( + *, + jsonl_path: Path, + uuid: str, + local_encoded: str, + project_dir: Path, + user_id: str, + machine_id: str, + worktree_name: Optional[str] = None, + title: Optional[str] = None, # ← NEW +) -> Optional[SessionMetadata]: +``` + +In the return statement (line 496), add: +```python + session_titles=[title] if title else None, +``` + +Modify callers `list_remote_sessions_for_project` (line 366-384) and `iter_all_remote_session_metadata` (line 423-441) to load titles and pass them through: + +```python + # Load titles once per (user_id, project) + titles_map = _load_remote_titles(user_id, local_encoded) # or encoded_name + + # In the _build_remote_metadata call, add: + title=titles_map.get(uuid), +``` + +Also clear the `_titles_cache` in the `_clear_cache` fixture in test file. + +**Step 4: Run tests to verify they pass** + +Run: `cd api && python -m pytest tests/test_remote_sessions.py -v` +Expected: All PASS (including new and existing tests) + +**Step 5: Commit** + +```bash +git add api/services/remote_sessions.py api/tests/test_remote_sessions.py +git commit -m "feat(sync): receiver reads session titles from inbox titles.json" +``` + +--- + +### Task 5: Clear titles cache in test fixture and add integration test + +**Files:** +- Modify: `api/tests/test_remote_sessions.py` (update `_clear_cache` fixture) + +**Step 1: Update the autouse fixture** + +In `api/tests/test_remote_sessions.py`, the `_clear_cache` fixture (line 136-149) needs to also clear `_titles_cache`: + +```python +@pytest.fixture(autouse=True) +def _clear_cache(): + """Clear caches before each test.""" + import services.remote_sessions as mod + + mod._local_user_cache = None + mod._local_user_cache_time = 0.0 + mod._project_mapping_cache = None + mod._project_mapping_cache_time = 0.0 + mod._titles_cache = {} # ← ADD + mod._manifest_worktree_cache = {} # ← ADD (was missing) + yield + mod._local_user_cache = None + mod._local_user_cache_time = 0.0 + mod._project_mapping_cache = None + mod._project_mapping_cache_time = 0.0 + mod._titles_cache = {} # ← ADD + mod._manifest_worktree_cache = {} # ← ADD +``` + +**Step 2: Run full test suite** + +Run: `cd api && python -m pytest tests/test_remote_sessions.py tests/test_titles_io.py tests/test_packager_titles.py tests/api/test_set_session_title.py -v` +Expected: All PASS + +**Step 3: Commit** + +```bash +git add api/tests/test_remote_sessions.py +git commit -m "test(sync): clear titles cache in test fixtures" +``` + +--- + +### Task 6: End-to-end verification + +**Files:** None (manual verification) + +**Step 1: Start the API** + +Run: `cd api && uvicorn main:app --reload --port 8000` + +**Step 2: Verify title POST writes to outbox** + +```bash +# Check sync config exists +cat ~/.claude_karma/sync-config.json | python -m json.tool | head -5 + +# Find a recent session UUID +curl -s http://localhost:8000/sessions | python -m json.tool | head -20 + +# POST a test title (use a real session UUID) +curl -X POST http://localhost:8000/sessions/{uuid}/title \ + -H 'Content-Type: application/json' \ + -d '{"title": "Test sync title"}' + +# Check titles.json was written in outbox +find ~/.claude_karma/remote-sessions -name titles.json -exec cat {} \; +``` + +**Step 3: Verify all existing tests still pass** + +Run: `cd api && python -m pytest -x -q` +Expected: All PASS, no regressions + +**Step 4: Final commit with all changes** + +```bash +git add -A +git status # Review — no secrets or unwanted files +git commit -m "feat(sync): complete titles.json sync pipeline for remote session titles" +``` diff --git a/docs/plans/2026-03-08-team-member-customization-design.md b/docs/plans/2026-03-08-team-member-customization-design.md new file mode 100644 index 00000000..61d95d49 --- /dev/null +++ b/docs/plans/2026-03-08-team-member-customization-design.md @@ -0,0 +1,165 @@ +# Team Member Customization & Member Pages + +**Date**: 2026-03-08 +**Status**: Approved + +## Problem + +Team members are displayed with auto-generated hash-based colors and raw user IDs (e.g., Syncthing device names). Users cannot rename members locally or choose display colors. There's also no dedicated page to view a member's activity. + +## Decisions + +- **Storage**: Backend `member_preferences` table in `karma.db` (not localStorage, not sync-config) +- **Features**: Nickname + Color picker (no avatar customization) +- **Navigation**: Independent `/members/{user_id}` pages (not nested under teams) +- **Palette**: Expanded from 8 to 14 colors +- **Safety**: `device_id` and `remote_user_id` never modified. All sync logic untouched. + +## Data Layer + +### New Table: `member_preferences` + +```sql +CREATE TABLE IF NOT EXISTS member_preferences ( + user_id TEXT PRIMARY KEY, -- matches remote_user_id / member.name + nickname TEXT, -- local display name override (nullable) + color TEXT, -- palette color name e.g. "emerald" (nullable) + updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP +); +``` + +### New API Endpoints + +| Method | Endpoint | Description | +|--------|----------|-------------| +| `GET` | `/members` | List all known members (join sync_members + preferences) | +| `GET` | `/members/{user_id}` | Member profile: stats, teams, preferences | +| `GET` | `/members/{user_id}/sessions` | Their remote sessions | +| `PUT` | `/members/{user_id}/preferences` | Update nickname and/or color | + +### `/members/{user_id}` Response Shape + +```json +{ + "user_id": "alice", + "device_id": "ABC123...", + "nickname": "Alice M.", + "color": "emerald", + "teams": ["frontend-team", "backend-team"], + "stats": { + "session_count": 42, + "last_active": "2026-03-07T...", + "project_count": 3, + "total_messages": 156 + }, + "connected": true +} +``` + +## Expanded Color Palette + +### Existing 8 colors (unchanged) +coral, rose, amber, cyan, pink, lime, indigo, teal + +### New 6 colors +emerald, violet, orange, sky, fuchsia, slate + +Each gets `--team-{name}` and `--team-{name}-subtle` CSS variables in both light and dark mode. + +### Color Function Changes + +`getTeamMemberColor(userId)` behavior: +1. Check preferences cache for color override +2. If override exists, return config for that color +3. If no override, hash-based fallback (now mod 14) + +**Note**: Expanding palette from 8→14 shifts hash assignments for users without overrides. Acceptable since the feature introduces manual overrides. + +## Frontend: Member Page + +### Route: `/members/[user_id]/` + +``` +┌─────────────────────────────────────────────────┐ +│ [Avatar] Alice M. (@alice) [Edit button] │ +│ ● Online • frontend-team • backend-team │ +├─────────────────────────────────────────────────┤ +│ Stats Row │ +│ ┌──────┐ ┌──────────┐ ┌────────┐ ┌───────────┐│ +│ │ 42 │ │ 3 │ │ 156 │ │ Mar 7 ││ +│ │ Sess │ │ Projects │ │ Msgs │ │ Last seen ││ +│ └──────┘ └──────────┘ └────────┘ └───────────┘│ +├─────────────────────────────────────────────────┤ +│ Sessions (reusing SessionCard component) │ +│ ┌─ Session 1 ──────────────────────────────┐ │ +│ └──────────────────────────────────────────────┘│ +│ ┌─ Session 2 ──────────────────────────────┐ │ +│ └──────────────────────────────────────────────┘│ +└─────────────────────────────────────────────────┘ +``` + +### Customize Dialog (MemberCustomizeDialog.svelte) + +``` +┌─────────────────────────────┐ +│ Customize Member │ +│ │ +│ Nickname: [Alice M. ] │ +│ (Original: alice) │ +│ │ +│ Color: │ +│ ● ● ● ● ● ● ● │ +│ ● ● ● ● ● ● ● │ +│ (14 color swatches) │ +│ │ +│ [Reset to default] [Save] │ +└─────────────────────────────┘ +``` + +Triggered from: +- Edit button on member page +- Click on avatar in TeamMemberCard + +## Navigation Flow + +``` +/team → list all teams +/team/{name} → team detail (members, projects) + └ member cards link to → /members/{user_id} +/members/{user_id} → member profile + ├ Stats (sessions, last active, tools) + ├ Customize (nickname, color) + ├ Teams (badges showing membership) + └ Sessions list (all projects) +``` + +## Files Changed + +### Backend — New Files +- `api/routers/members.py` — member router (list, detail, preferences) +- `api/db/member_queries.py` — CRUD for member_preferences table + +### Backend — Modified Files +- `api/db/schema.py` — add member_preferences table creation +- `api/main.py` — register members router + +### Frontend — New Files +- `frontend/src/routes/members/[user_id]/+page.svelte` — member page +- `frontend/src/routes/members/[user_id]/+page.server.ts` — data loader +- `frontend/src/lib/components/team/MemberCustomizeDialog.svelte` — edit modal + +### Frontend — Modified Files +- `frontend/src/lib/utils.ts` — expand palette 8→14, add override lookup +- `frontend/src/app.css` — add 6 new team color CSS variables (light + dark) +- `frontend/src/lib/api-types.ts` — add MemberPreferences, MemberProfile types +- `frontend/src/lib/components/team/TeamMemberCard.svelte` — use team colors on avatar, link to member page +- `frontend/src/lib/components/SessionCard.svelte` — show nickname in remote badge +- `frontend/src/lib/components/GlobalSessionCard.svelte` — show nickname in remote badge +- `frontend/src/lib/components/sync/ProjectTeamTab.svelte` — show nickname override + +### NOT Touched (Sync Safety) +- `api/services/remote_sessions.py` +- `api/db/sync_queries.py` +- `api/routers/sync_status.py` +- Any device_id or remote_user_id resolution logic +- Any Syncthing integration code diff --git a/docs/plans/2026-03-08-team-member-customization-plan.md b/docs/plans/2026-03-08-team-member-customization-plan.md new file mode 100644 index 00000000..24f271ff --- /dev/null +++ b/docs/plans/2026-03-08-team-member-customization-plan.md @@ -0,0 +1,1516 @@ +# Team Member Customization & Member Pages — Implementation Plan + +> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. + +**Goal:** Add per-member nickname and color overrides stored in the backend, plus an independent `/members/{user_id}` page showing stats, sessions, and customization UI. + +**Architecture:** New `member_preferences` table in `karma.db` keyed by `user_id`. New `/members` API router. Frontend member page at `/members/[user_id]` with inline edit dialog. Expanded 14-color palette. All sync logic (`device_id`, `remote_user_id`) remains untouched. + +**Tech Stack:** Python/FastAPI/SQLite (backend), SvelteKit/Svelte 5/Tailwind (frontend) + +**Design Doc:** `docs/plans/2026-03-08-team-member-customization-design.md` + +--- + +## Task 1: Database — `member_preferences` table + migration + +**Files:** +- Modify: `api/db/schema.py` (line 13: SCHEMA_VERSION, line 274: SCHEMA_SQL, after line 638: new migration) + +**Step 1: Add table to SCHEMA_SQL** + +In `api/db/schema.py`, inside the `SCHEMA_SQL` string (before the closing `"""`), after the sync_events indexes (line 273), add: + +```sql +-- Member display preferences (cosmetic overrides, keyed by user_id not team) +CREATE TABLE IF NOT EXISTS member_preferences ( + user_id TEXT PRIMARY KEY, + nickname TEXT, + color TEXT, + updated_at TEXT DEFAULT (datetime('now')) +); +``` + +**Step 2: Add to ensure_schema sync table safety net** + +In the `if current_version >= SCHEMA_VERSION:` block (around line 294), add the new CREATE TABLE IF NOT EXISTS alongside the existing sync tables: + +```sql +CREATE TABLE IF NOT EXISTS member_preferences ( + user_id TEXT PRIMARY KEY, + nickname TEXT, + color TEXT, + updated_at TEXT DEFAULT (datetime('now')) +); +``` + +**Step 3: Add migration v23** + +After the v22 migration block (after line 638), add: + +```python + if current_version < 23: + logger.info("Migrating -> v23: adding member_preferences table") + conn.executescript(""" + CREATE TABLE IF NOT EXISTS member_preferences ( + user_id TEXT PRIMARY KEY, + nickname TEXT, + color TEXT, + updated_at TEXT DEFAULT (datetime('now')) + ); + """) +``` + +**Step 4: Bump SCHEMA_VERSION** + +Change line 13 from `SCHEMA_VERSION = 22` to `SCHEMA_VERSION = 23`. + +**Step 5: Verify** + +Run: `cd api && python -c "from db.schema import ensure_schema; import sqlite3; conn = sqlite3.connect(':memory:'); conn.row_factory = sqlite3.Row; ensure_schema(conn); print([r['name'] for r in conn.execute(\"SELECT name FROM sqlite_master WHERE type='table'\").fetchall()])"` + +Expected: Output includes `member_preferences` in the list. + +**Step 6: Commit** + +```bash +git add api/db/schema.py +git commit -m "feat(db): add member_preferences table (v23 migration)" +``` + +--- + +## Task 2: Backend — CRUD functions for member_preferences + +**Files:** +- Create: `api/db/member_queries.py` + +**Step 1: Write the CRUD module** + +Create `api/db/member_queries.py`: + +```python +"""CRUD functions for member_preferences table. + +Cosmetic-only overrides (nickname, color) keyed by user_id. +Does NOT modify sync_members, device_id, or any sync logic. +""" + +import sqlite3 +from typing import Optional + + +def get_preferences(conn: sqlite3.Connection, user_id: str) -> Optional[dict]: + """Get display preferences for a member, or None if no overrides.""" + row = conn.execute( + "SELECT user_id, nickname, color, updated_at FROM member_preferences WHERE user_id = ?", + (user_id,), + ).fetchone() + return dict(row) if row else None + + +def get_all_preferences(conn: sqlite3.Connection) -> dict[str, dict]: + """Return all preferences keyed by user_id. For frontend bulk fetch.""" + rows = conn.execute( + "SELECT user_id, nickname, color, updated_at FROM member_preferences" + ).fetchall() + return {r["user_id"]: dict(r) for r in rows} + + +def upsert_preferences( + conn: sqlite3.Connection, + user_id: str, + nickname: Optional[str] = None, + color: Optional[str] = None, +) -> dict: + """Set or update display preferences for a member.""" + conn.execute( + """INSERT INTO member_preferences (user_id, nickname, color, updated_at) + VALUES (?, ?, ?, datetime('now')) + ON CONFLICT(user_id) + DO UPDATE SET + nickname = COALESCE(excluded.nickname, member_preferences.nickname), + color = COALESCE(excluded.color, member_preferences.color), + updated_at = datetime('now')""", + (user_id, nickname, color), + ) + conn.commit() + return get_preferences(conn, user_id) + + +def delete_preferences(conn: sqlite3.Connection, user_id: str) -> None: + """Reset a member's preferences to defaults.""" + conn.execute("DELETE FROM member_preferences WHERE user_id = ?", (user_id,)) + conn.commit() +``` + +**Step 2: Run a quick test** + +Run: `cd api && python -c " +from db.schema import ensure_schema +from db.member_queries import get_preferences, upsert_preferences, get_all_preferences, delete_preferences +import sqlite3 +conn = sqlite3.connect(':memory:') +conn.row_factory = sqlite3.Row +ensure_schema(conn) +assert get_preferences(conn, 'alice') is None +result = upsert_preferences(conn, 'alice', nickname='Alice M.', color='emerald') +assert result['nickname'] == 'Alice M.' +assert result['color'] == 'emerald' +all_prefs = get_all_preferences(conn) +assert 'alice' in all_prefs +delete_preferences(conn, 'alice') +assert get_preferences(conn, 'alice') is None +print('All member_queries tests pass') +"` + +Expected: `All member_queries tests pass` + +**Step 3: Commit** + +```bash +git add api/db/member_queries.py +git commit -m "feat(db): add member_preferences CRUD functions" +``` + +--- + +## Task 3: Backend — `/members` API router + +**Files:** +- Create: `api/routers/members.py` +- Modify: `api/main.py` (line 178: add router registration) + +**Step 1: Create the router** + +Create `api/routers/members.py`: + +```python +"""Members API — display preferences and aggregated member profiles. + +Cosmetic-only: never modifies device_id, remote_user_id, or sync logic. +Reads sync_members for team membership, sessions table for stats. +""" + +import logging +import sqlite3 +from typing import Optional + +from fastapi import APIRouter, HTTPException +from pydantic import BaseModel + +from db.connection import get_writer_db, create_read_connection +from db.member_queries import ( + get_preferences, + get_all_preferences, + upsert_preferences, + delete_preferences, +) + +logger = logging.getLogger(__name__) + +router = APIRouter() + +# ── Valid color names (must match CSS variables --team-{color}) ── + +VALID_COLORS = frozenset([ + "coral", "rose", "amber", "cyan", "pink", "lime", "indigo", "teal", + "emerald", "violet", "orange", "sky", "fuchsia", "slate", +]) + + +# ── Request/Response Models ── + + +class PreferencesUpdate(BaseModel): + nickname: Optional[str] = None + color: Optional[str] = None + + +class PreferencesResponse(BaseModel): + user_id: str + nickname: Optional[str] = None + color: Optional[str] = None + updated_at: Optional[str] = None + + +class MemberStats(BaseModel): + session_count: int = 0 + project_count: int = 0 + total_messages: int = 0 + last_active: Optional[str] = None + + +class MemberProfile(BaseModel): + user_id: str + device_id: Optional[str] = None + nickname: Optional[str] = None + color: Optional[str] = None + teams: list[str] = [] + stats: MemberStats = MemberStats() + connected: bool = False + + +class MemberListItem(BaseModel): + user_id: str + device_id: Optional[str] = None + nickname: Optional[str] = None + color: Optional[str] = None + teams: list[str] = [] + session_count: int = 0 + connected: bool = False + + +# ── Helpers ── + + +def _get_read_conn() -> sqlite3.Connection: + return create_read_connection() + + +def _get_write_conn() -> sqlite3.Connection: + return get_writer_db() + + +def _get_member_teams(conn: sqlite3.Connection, user_id: str) -> list[str]: + """Find all teams a user_id belongs to via sync_members.""" + rows = conn.execute( + "SELECT DISTINCT team_name FROM sync_members WHERE name = ?", + (user_id,), + ).fetchall() + return [r["team_name"] for r in rows] + + +def _get_member_device_id(conn: sqlite3.Connection, user_id: str) -> Optional[str]: + """Get the device_id for a user from sync_members.""" + row = conn.execute( + "SELECT device_id FROM sync_members WHERE name = ? LIMIT 1", + (user_id,), + ).fetchone() + return row["device_id"] if row else None + + +def _get_member_stats(conn: sqlite3.Connection, user_id: str) -> dict: + """Compute stats from sessions table for a remote user.""" + row = conn.execute( + """SELECT + COUNT(*) as session_count, + COUNT(DISTINCT project_encoded_name) as project_count, + SUM(COALESCE(message_count, 0)) as total_messages, + MAX(COALESCE(end_time, start_time)) as last_active + FROM sessions + WHERE remote_user_id = ?""", + (user_id,), + ).fetchone() + if not row or row["session_count"] == 0: + return {"session_count": 0, "project_count": 0, "total_messages": 0, "last_active": None} + return dict(row) + + +def _get_all_known_members(conn: sqlite3.Connection) -> list[dict]: + """Get all unique members from sync_members with their teams.""" + rows = conn.execute( + """SELECT name, device_id, GROUP_CONCAT(team_name) as teams + FROM sync_members + GROUP BY name + ORDER BY name""" + ).fetchall() + result = [] + for r in rows: + teams = r["teams"].split(",") if r["teams"] else [] + result.append({ + "user_id": r["name"], + "device_id": r["device_id"], + "teams": teams, + }) + return result + + +# ── Endpoints ── + + +@router.get("", response_model=list[MemberListItem]) +async def list_members(): + """List all known team members with preferences and session counts.""" + import asyncio + loop = asyncio.get_event_loop() + + def _query(): + conn = _get_read_conn() + try: + members = _get_all_known_members(conn) + prefs = get_all_preferences(conn) + + result = [] + for m in members: + uid = m["user_id"] + p = prefs.get(uid, {}) + # Get session count + row = conn.execute( + "SELECT COUNT(*) as cnt FROM sessions WHERE remote_user_id = ?", + (uid,), + ).fetchone() + session_count = row["cnt"] if row else 0 + + result.append({ + "user_id": uid, + "device_id": m["device_id"], + "nickname": p.get("nickname"), + "color": p.get("color"), + "teams": m["teams"], + "session_count": session_count, + "connected": False, # enriched client-side from /sync/devices + }) + return result + finally: + conn.close() + + return await loop.run_in_executor(None, _query) + + +@router.get("/preferences", response_model=dict[str, PreferencesResponse]) +async def get_all_member_preferences(): + """Bulk fetch all member preferences. Used by frontend for color/nickname cache.""" + import asyncio + loop = asyncio.get_event_loop() + + def _query(): + conn = _get_read_conn() + try: + return get_all_preferences(conn) + finally: + conn.close() + + return await loop.run_in_executor(None, _query) + + +@router.get("/{user_id}", response_model=MemberProfile) +async def get_member(user_id: str): + """Get full member profile with stats, teams, and preferences.""" + import asyncio + loop = asyncio.get_event_loop() + + def _query(): + conn = _get_read_conn() + try: + teams = _get_member_teams(conn, user_id) + device_id = _get_member_device_id(conn, user_id) + stats = _get_member_stats(conn, user_id) + prefs = get_preferences(conn, user_id) + + if not teams and stats["session_count"] == 0: + raise HTTPException(404, f"Member '{user_id}' not found") + + return { + "user_id": user_id, + "device_id": device_id, + "nickname": prefs["nickname"] if prefs else None, + "color": prefs["color"] if prefs else None, + "teams": teams, + "stats": stats, + "connected": False, # enriched client-side + } + finally: + conn.close() + + return await loop.run_in_executor(None, _query) + + +@router.put("/{user_id}/preferences", response_model=PreferencesResponse) +async def update_preferences(user_id: str, body: PreferencesUpdate): + """Update display nickname and/or color for a member.""" + import asyncio + loop = asyncio.get_event_loop() + + # Validate color if provided + if body.color and body.color not in VALID_COLORS: + raise HTTPException(400, f"Invalid color '{body.color}'. Valid: {sorted(VALID_COLORS)}") + + # Validate nickname length + if body.nickname is not None and len(body.nickname) > 50: + raise HTTPException(400, "Nickname must be 50 characters or fewer") + + def _update(): + conn = _get_write_conn() + try: + return upsert_preferences(conn, user_id, body.nickname, body.color) + finally: + conn.close() + + return await loop.run_in_executor(None, _update) + + +@router.delete("/{user_id}/preferences") +async def reset_preferences(user_id: str): + """Reset a member's preferences to defaults (hash-based color, original name).""" + import asyncio + loop = asyncio.get_event_loop() + + def _delete(): + conn = _get_write_conn() + try: + delete_preferences(conn, user_id) + finally: + conn.close() + + await loop.run_in_executor(None, _delete) + return {"status": "ok", "user_id": user_id} +``` + +**Step 2: Register the router in main.py** + +In `api/main.py`, after line 177 (`app.include_router(sync_status.router)`), add: + +```python +app.include_router(members.router, prefix="/members", tags=["members"]) +``` + +Also add the import at the top of main.py with the other router imports: + +```python +from routers import members +``` + +**Step 3: Verify the server starts** + +Run: `cd api && timeout 5 uvicorn main:app --port 8099 2>&1 | head -5` + +Expected: Server starts without import errors. + +**Step 4: Commit** + +```bash +git add api/routers/members.py api/main.py +git commit -m "feat(api): add /members router with preferences and profile endpoints" +``` + +--- + +## Task 4: Backend — Member sessions endpoint + +**Files:** +- Modify: `api/routers/members.py` (add sessions endpoint) + +**Step 1: Add the sessions endpoint** + +Add to the bottom of `api/routers/members.py`: + +```python +@router.get("/{user_id}/sessions") +async def get_member_sessions(user_id: str, limit: int = 50, offset: int = 0): + """List remote sessions for a specific member.""" + import asyncio + loop = asyncio.get_event_loop() + + def _query(): + conn = _get_read_conn() + try: + rows = conn.execute( + """SELECT s.uuid, s.slug, s.project_encoded_name, + s.message_count, s.start_time, s.end_time, + s.duration_seconds, s.models_used, s.subagent_count, + s.has_todos, s.todo_count, s.is_compacted, + s.remote_user_id, s.remote_machine_id, + p.path as project_path, p.display_name as project_name + FROM sessions s + LEFT JOIN projects p ON s.project_encoded_name = p.encoded_name + WHERE s.remote_user_id = ? + ORDER BY COALESCE(s.end_time, s.start_time) DESC + LIMIT ? OFFSET ?""", + (user_id, limit, offset), + ).fetchall() + + total_row = conn.execute( + "SELECT COUNT(*) as cnt FROM sessions WHERE remote_user_id = ?", + (user_id,), + ).fetchone() + + sessions = [] + for r in rows: + d = dict(r) + # Parse JSON fields + if d.get("models_used"): + try: + import json + d["models_used"] = json.loads(d["models_used"]) + except (json.JSONDecodeError, TypeError): + d["models_used"] = [] + else: + d["models_used"] = [] + sessions.append(d) + + return { + "sessions": sessions, + "total": total_row["cnt"] if total_row else 0, + "limit": limit, + "offset": offset, + } + finally: + conn.close() + + return await loop.run_in_executor(None, _query) +``` + +**Step 2: Commit** + +```bash +git add api/routers/members.py +git commit -m "feat(api): add GET /members/{user_id}/sessions endpoint" +``` + +--- + +## Task 5: Frontend — Expand CSS color palette from 8 to 14 + +**Files:** +- Modify: `frontend/src/app.css` (after line 175: add 6 new color variables) + +**Step 1: Add new CSS variables** + +In `frontend/src/app.css`, after line 175 (`--team-teal-subtle: ...`), add: + +```css + --team-emerald: #10b981; + --team-emerald-subtle: rgba(16, 185, 129, 0.1); + --team-violet: #8b5cf6; + --team-violet-subtle: rgba(139, 92, 246, 0.1); + --team-orange: #f97316; + --team-orange-subtle: rgba(249, 115, 22, 0.1); + --team-sky: #0ea5e9; + --team-sky-subtle: rgba(14, 165, 233, 0.1); + --team-fuchsia: #d946ef; + --team-fuchsia-subtle: rgba(217, 70, 239, 0.1); + --team-slate: #64748b; + --team-slate-subtle: rgba(100, 116, 139, 0.1); +``` + +Note: Team colors are not redefined in dark mode (the hex values + rgba subtle variants work in both themes, same as existing 8 colors). + +**Step 2: Verify visually** + +Run: `cd frontend && npm run dev` and check that the app loads without CSS errors. + +**Step 3: Commit** + +```bash +git add frontend/src/app.css +git commit -m "feat(css): expand team member color palette from 8 to 14" +``` + +--- + +## Task 6: Frontend — Update `utils.ts` color system with overrides + +**Files:** +- Modify: `frontend/src/lib/utils.ts` (lines 683-721: palette + function) +- Modify: `frontend/src/lib/api-types.ts` (add MemberPreferences type) + +**Step 1: Add types to api-types.ts** + +Add near the other sync types (after `RemoteSessionUser` interface, ~line 1841): + +```typescript +/** Per-member display preferences (cosmetic overrides) */ +export interface MemberPreferences { + user_id: string; + nickname?: string | null; + color?: string | null; + updated_at?: string | null; +} + +/** Full member profile from /members/{user_id} */ +export interface MemberProfile { + user_id: string; + device_id?: string | null; + nickname?: string | null; + color?: string | null; + teams: string[]; + stats: { + session_count: number; + project_count: number; + total_messages: number; + last_active?: string | null; + }; + connected: boolean; +} + +/** List item from /members */ +export interface MemberListItem { + user_id: string; + device_id?: string | null; + nickname?: string | null; + color?: string | null; + teams: string[]; + session_count: number; + connected: boolean; +} +``` + +**Step 2: Update palette and color function in utils.ts** + +Replace lines 683-721 in `frontend/src/lib/utils.ts`: + +```typescript +/** Color palette for team members — 14 colors, avoiding model colors (purple/blue/green) */ +const TEAM_MEMBER_PALETTE = [ + 'coral', + 'rose', + 'amber', + 'cyan', + 'pink', + 'lime', + 'indigo', + 'teal', + 'emerald', + 'violet', + 'orange', + 'sky', + 'fuchsia', + 'slate' +] as const; + +type TeamColor = (typeof TEAM_MEMBER_PALETTE)[number]; + +export interface TeamMemberColorConfig { + border: string; + badge: string; + text: string; + bg: string; +} + +/** Cache of member preferences fetched from backend */ +let _memberPrefsCache: Record = {}; +let _prefsCacheLoaded = false; + +/** Load member preferences from backend. Call once on app init. */ +export async function loadMemberPreferences(apiBase: string): Promise { + try { + const res = await fetch(`${apiBase}/members/preferences`); + if (res.ok) { + _memberPrefsCache = await res.json(); + _prefsCacheLoaded = true; + } + } catch { + // Silently fail — hash-based fallback will be used + } +} + +/** Set preferences cache directly (e.g., after a PUT update). */ +export function updateMemberPrefsCache(userId: string, prefs: { nickname?: string | null; color?: string | null }): void { + _memberPrefsCache[userId] = prefs; +} + +/** Clear a member's cached preferences (after reset). */ +export function clearMemberPrefsCache(userId: string): void { + delete _memberPrefsCache[userId]; +} + +/** Get display name for a member: nickname override or original user_id. */ +export function getMemberDisplayName(userId: string): string { + const prefs = _memberPrefsCache[userId]; + return prefs?.nickname || userId; +} + +function _colorConfigFor(color: TeamColor): TeamMemberColorConfig { + return { + border: `var(--team-${color})`, + badge: `bg-[var(--team-${color}-subtle)] border-[var(--team-${color})]/20`, + text: `text-[var(--team-${color})]`, + bg: `var(--team-${color}-subtle)` + }; +} + +/** + * Deterministic hash-based color assignment for team members. + * Checks preferences cache first for manual override. + * Same userId always gets the same fallback color. + */ +export function getTeamMemberColor(userId: string): TeamMemberColorConfig { + // Check for manual override + const prefs = _memberPrefsCache[userId]; + if (prefs?.color && TEAM_MEMBER_PALETTE.includes(prefs.color as TeamColor)) { + return _colorConfigFor(prefs.color as TeamColor); + } + + // Hash-based fallback + let hash = 0; + for (let i = 0; i < userId.length; i++) { + hash = (hash << 5) - hash + userId.charCodeAt(i); + hash |= 0; // Convert to 32-bit int + } + const index = Math.abs(hash) % TEAM_MEMBER_PALETTE.length; + return _colorConfigFor(TEAM_MEMBER_PALETTE[index]); +} +``` + +**Step 3: Verify types** + +Run: `cd frontend && npm run check` + +Expected: No type errors. + +**Step 4: Commit** + +```bash +git add frontend/src/lib/utils.ts frontend/src/lib/api-types.ts +git commit -m "feat(frontend): expand color palette to 14, add preference overrides to color system" +``` + +--- + +## Task 7: Frontend — Load preferences on app init + +**Files:** +- Modify: `frontend/src/routes/+layout.svelte` (add preferences loading) + +**Step 1: Find the root layout and add preferences loading** + +Read `frontend/src/routes/+layout.svelte` to find where to add the init call. Add an `$effect` or `onMount` that calls `loadMemberPreferences`: + +```svelte + +``` + +Note: This is fire-and-forget. If it fails, the hash-based fallback works seamlessly. + +**Step 2: Verify** + +Run: `cd frontend && npm run check` + +**Step 3: Commit** + +```bash +git add frontend/src/routes/+layout.svelte +git commit -m "feat(frontend): load member preferences on app init" +``` + +--- + +## Task 8: Frontend — Use nicknames in SessionCard and GlobalSessionCard + +**Files:** +- Modify: `frontend/src/lib/components/SessionCard.svelte` (line 45: add nickname lookup) +- Modify: `frontend/src/lib/components/GlobalSessionCard.svelte` (line 58: add nickname lookup) +- Modify: `frontend/src/lib/components/sync/ProjectTeamTab.svelte` (line 112: add nickname) + +**Step 1: Update SessionCard.svelte** + +Find line 45: `const remoteUserName = $derived(session.remote_user_id ?? null);` + +Replace with: + +```typescript +const remoteUserName = $derived( + session.remote_user_id ? getMemberDisplayName(session.remote_user_id) : null +); +``` + +Add import at top (alongside existing utils imports): + +```typescript +import { getMemberDisplayName } from '$lib/utils'; +``` + +(It's likely already importing from `$lib/utils` — just add `getMemberDisplayName` to the existing import.) + +**Step 2: Update GlobalSessionCard.svelte** + +Same change — find `remoteUserName` derived and replace with `getMemberDisplayName` call. Add to imports. + +**Step 3: Update ProjectTeamTab.svelte** + +Find where `user.user_id` is displayed (around line 128 where the user name is rendered). Wrap with `getMemberDisplayName(user.user_id)`. Add to imports. + +**Step 4: Verify** + +Run: `cd frontend && npm run check` + +**Step 5: Commit** + +```bash +git add frontend/src/lib/components/SessionCard.svelte frontend/src/lib/components/GlobalSessionCard.svelte frontend/src/lib/components/sync/ProjectTeamTab.svelte +git commit -m "feat(frontend): show member nicknames in session cards and team tab" +``` + +--- + +## Task 9: Frontend — MemberCustomizeDialog component + +**Files:** +- Create: `frontend/src/lib/components/team/MemberCustomizeDialog.svelte` + +**Step 1: Create the dialog component** + +Create `frontend/src/lib/components/team/MemberCustomizeDialog.svelte`: + +```svelte + + +{#if open} + + + +
(open = false)}> + + + +
e.stopPropagation()} + > +
+

Customize Member

+ +
+ + +
+ + +

Original: {userId}

+
+ + +
+ +
+ {#each PALETTE as color} + {@const isSelected = selectedColor === color} + {@const isDefault = !selectedColor && getTeamMemberColor(userId).border === `var(--team-${color})`} +
+
+ + +
+ + +
+
+
+{/if} +``` + +**Step 2: Verify types** + +Run: `cd frontend && npm run check` + +**Step 3: Commit** + +```bash +git add frontend/src/lib/components/team/MemberCustomizeDialog.svelte +git commit -m "feat(frontend): add MemberCustomizeDialog component" +``` + +--- + +## Task 10: Frontend — Update TeamMemberCard with team colors and customize trigger + +**Files:** +- Modify: `frontend/src/lib/components/team/TeamMemberCard.svelte` + +**Step 1: Add team color and customize dialog** + +Replace the full `TeamMemberCard.svelte` content. Key changes: +- Import `getTeamMemberColor`, `getMemberDisplayName` from utils +- Derive the team color from member.name +- Use team color on the avatar circle instead of plain green/muted +- Add click handler on avatar to open customize dialog +- Show nickname if set +- Add link to `/members/{member.name}` + +```svelte + + +
+
+ +
+
+ + {displayName} + {#if displayName !== member.name} + ({member.name}) + {/if} + {#if isSelf} + (you) + {/if} + + + {#if isConnected || isSelf} + + Online + {:else} + + Offline + {/if} + +
+ {#if member.device_id} +

+ {member.device_id.length > 20 ? member.device_id.slice(0, 20) + '...' : member.device_id} +

+ {/if} +
+
+ +
+ + + + {#if !isSelf} + {#if confirmRemove} +
+ + +
+ {:else} + + {/if} + {/if} +
+
+ + +``` + +**Step 2: Verify types** + +Run: `cd frontend && npm run check` + +**Step 3: Commit** + +```bash +git add frontend/src/lib/components/team/TeamMemberCard.svelte +git commit -m "feat(frontend): update TeamMemberCard with team colors, nickname display, and customize trigger" +``` + +--- + +## Task 11: Frontend — Member profile page + +**Files:** +- Create: `frontend/src/routes/members/[user_id]/+page.server.ts` +- Create: `frontend/src/routes/members/[user_id]/+page.svelte` + +**Step 1: Create the data loader** + +Create `frontend/src/routes/members/[user_id]/+page.server.ts`: + +```typescript +import { API_BASE } from '$lib/config'; +import { error } from '@sveltejs/kit'; +import type { PageServerLoad } from './$types'; + +export const load: PageServerLoad = async ({ params, fetch }) => { + const userId = params.user_id; + + const [profileRes, sessionsRes] = await Promise.all([ + fetch(`${API_BASE}/members/${encodeURIComponent(userId)}`), + fetch(`${API_BASE}/members/${encodeURIComponent(userId)}/sessions?limit=50`) + ]); + + if (!profileRes.ok) { + throw error(profileRes.status, `Member '${userId}' not found`); + } + + const profile = await profileRes.json(); + const sessionsData = sessionsRes.ok ? await sessionsRes.json() : { sessions: [], total: 0 }; + + return { + profile, + sessions: sessionsData.sessions, + totalSessions: sessionsData.total, + userId + }; +}; +``` + +**Step 2: Create the page component** + +Create `frontend/src/routes/members/[user_id]/+page.svelte`: + +```svelte + + + + {displayName} — Claude Code Karma + + +
+ +
+
+
+ {data.userId.charAt(0).toUpperCase()} +
+
+
+

{displayName}

+ {#if displayName !== data.userId} + @{data.userId} + {/if} +
+
+ + {#if profile.connected} + Online + {:else} + Offline + {/if} + + {#each profile.teams as team} + + {team} + + {/each} +
+
+
+ +
+ + +
+
+
+ + Sessions +
+

{profile.stats.session_count}

+
+
+
+ + Projects +
+

{profile.stats.project_count}

+
+
+
+ + Messages +
+

{profile.stats.total_messages}

+
+
+
+ + Last seen +
+

+ {#if profile.stats.last_active} + {formatRelativeTime(profile.stats.last_active)} + {:else} + Never + {/if} +

+
+
+ + +
+

+ Sessions ({data.totalSessions}) +

+ {#if sessions.length === 0} +

No sessions found for this member.

+ {:else} +
+ {#each sessions as session (session.uuid)} + + {/each} +
+ {/if} +
+
+ + +``` + +**Step 3: Verify types** + +Run: `cd frontend && npm run check` + +Note: There may be type issues with `SessionCard` props if `session` shape doesn't match exactly. The member sessions endpoint returns a subset of fields — you may need to cast or add optional fields. Adjust as needed during implementation. + +**Step 4: Commit** + +```bash +git add frontend/src/routes/members/ +git commit -m "feat(frontend): add /members/[user_id] profile page with stats, sessions, and customization" +``` + +--- + +## Task 12: Integration verification + +**Step 1: Start the API** + +Run: `cd api && uvicorn main:app --reload --port 8000` + +**Step 2: Test the endpoints manually** + +```bash +# List members (may be empty if no teams configured) +curl http://localhost:8000/members + +# Get all preferences (empty initially) +curl http://localhost:8000/members/preferences + +# Set a preference +curl -X PUT http://localhost:8000/members/testuser/preferences \ + -H 'Content-Type: application/json' \ + -d '{"nickname": "Test User", "color": "emerald"}' + +# Verify it was saved +curl http://localhost:8000/members/preferences + +# Reset +curl -X DELETE http://localhost:8000/members/testuser/preferences + +# Verify reset +curl http://localhost:8000/members/preferences +``` + +**Step 3: Start the frontend** + +Run: `cd frontend && npm run dev` + +**Step 4: Visual check** + +1. Visit `/team/{team_name}` — member cards should show team-colored avatars with pencil edit button +2. Click avatar or pencil → customize dialog opens +3. Set nickname and color → save → badge and avatar update +4. Click member name → navigates to `/members/{user_id}` +5. Member page shows stats, sessions, customize button + +**Step 5: Commit final state** + +```bash +git add -A +git commit -m "feat: team member customization — nicknames, color picker, and member profile pages" +``` + +--- + +## Summary of All Files + +### New Files (5) +| File | Purpose | +|------|---------| +| `api/db/member_queries.py` | CRUD for member_preferences table | +| `api/routers/members.py` | /members API router | +| `frontend/src/lib/components/team/MemberCustomizeDialog.svelte` | Nickname + color edit dialog | +| `frontend/src/routes/members/[user_id]/+page.server.ts` | Member page data loader | +| `frontend/src/routes/members/[user_id]/+page.svelte` | Member profile page | + +### Modified Files (7) +| File | Change | +|------|--------| +| `api/db/schema.py` | Add member_preferences table + v23 migration | +| `api/main.py` | Register members router | +| `frontend/src/app.css` | Add 6 new team color CSS variables | +| `frontend/src/lib/utils.ts` | Expand palette 8→14, add preference override system | +| `frontend/src/lib/api-types.ts` | Add MemberPreferences, MemberProfile, MemberListItem types | +| `frontend/src/lib/components/team/TeamMemberCard.svelte` | Team colors, nickname, link, customize trigger | +| `frontend/src/routes/+layout.svelte` | Load member preferences on app init | + +### Display-Only Changes (3) +| File | Change | +|------|--------| +| `frontend/src/lib/components/SessionCard.svelte` | Use getMemberDisplayName for remote badge | +| `frontend/src/lib/components/GlobalSessionCard.svelte` | Use getMemberDisplayName for remote badge | +| `frontend/src/lib/components/sync/ProjectTeamTab.svelte` | Use getMemberDisplayName for user labels | + +### NOT Touched (sync safety) +- `api/services/remote_sessions.py` +- `api/db/sync_queries.py` +- `api/routers/sync_status.py` +- Any `device_id` or `remote_user_id` resolution logic diff --git a/docs/plans/2026-03-09-member-page-design.md b/docs/plans/2026-03-09-member-page-design.md new file mode 100644 index 00000000..d8dd4df8 --- /dev/null +++ b/docs/plans/2026-03-09-member-page-design.md @@ -0,0 +1,139 @@ +# Member Page — Tab-Based Detail View + +**Date**: 2026-03-09 +**Status**: Approved +**Scope**: Read-only member page (customization deferred to follow-up) + +## Problem + +Members are only visible inline on team detail pages. There's no dedicated page to view a member's full activity, sessions, team memberships, and contribution history. + +## Decisions + +- **Route**: `/members/[user_id]/` — independent of teams +- **Navigation**: TeamMembersTab cards link to member page (no sidebar entry) +- **Layout**: Color-themed profile header + 4 tabs (Overview, Sessions, Teams, Activity) +- **Color**: Uses existing 16-color palette — member's hash-assigned color themes the entire page +- **Scope**: Read-only. No customization (nickname/color picker) in this pass. +- **Data**: No new tables. Aggregates from existing sync_members, sync_events, session-stats, devices. + +## Data Requirements + +### Existing Endpoints (reused) + +| Endpoint | Data | +|----------|------| +| `GET /sync/teams` | All teams → filter to teams containing this member | +| `GET /sync/devices` | Connection status, bytes transferred | +| `GET /sync/teams/{team}/session-stats` | Per-member daily sent/received stats | +| `GET /sync/teams/{team}/activity` | Sync events filtered by member | +| `GET /sync/teams/{team}/project-status` | Per-project sync stats with member breakdown | + +### New Endpoint + +| Method | Endpoint | Description | +|--------|----------|-------------| +| `GET` | `/sync/members/{user_id}` | Aggregated member profile: teams, stats, device info | + +Response shape: +```json +{ + "user_id": "alice", + "device_id": "ABC123...", + "connected": true, + "in_bytes_total": 1234567, + "out_bytes_total": 3456789, + "teams": [ + { + "name": "frontend-team", + "member_count": 3, + "project_count": 2, + "online_count": 2, + "projects": [ + { "encoded_name": "project-alpha", "name": "project-alpha", "received_count": 12 } + ] + } + ], + "stats": { + "total_sessions": 42, + "total_projects": 3, + "last_active": "2026-03-07T..." + }, + "session_stats": [ + { "date": "2026-03-09", "packaged": 2, "received": 1 } + ], + "activity": [ + { "id": 1, "event_type": "session_received", "team_name": "frontend-team", "created_at": "..." } + ] +} +``` + +## Page Layout + +### Profile Header (always visible above tabs) + +``` +┌─────────────────────────────────────────────────────┐ +│ ← Back to {team} │ +│ │ +│ ┌─ Profile Card (left border: member color) ─────┐ │ +│ │ [Avatar: initial + color ring] │ │ +│ │ alice • ● Online • ABC12...7DEF │ │ +│ │ ↓ 1.2 MB received • ↑ 3.4 MB sent │ │ +│ └─────────────────────────────────────────────────┘ │ +│ │ +│ [Overview] [Sessions] [Teams] [Activity] │ +└─────────────────────────────────────────────────────┘ +``` + +- Card background: `--team-{color}-subtle` +- Avatar: first letter of user_id, ring uses member color +- Connection status from device data +- Data transfer from device bytes + +### Tab 1: Overview + +- **Stats Grid** (3 cols): Total Sessions, Projects, Last Active +- **Sessions Over Time**: Bar chart (daily sent/received, member-colored, same pattern as TeamOverviewTab) +- **Projects Contributed To**: Simple card list linking to `/projects/[encoded_name]`, showing session count per project + +### Tab 2: Sessions + +- Reuse `SessionCard` / `GlobalSessionCard` component +- Filter to sessions where `remote_user_id === user_id` +- Search/filter bar + pagination + +### Tab 3: Teams + +- Card per team (reuse TeamCard styling) +- Shows: member count, project count, online count +- Per-team project contribution breakdown for this member +- Each card links to `/team/[name]` + +### Tab 4: Activity + +- Reuse `TeamActivityFeed` pattern, pre-filtered to this member +- Type filter pills (All, Joins, Shares, Sessions, Syncs, Rejections, Settings) +- No member filter needed (already scoped) +- Pagination with load-more + +## Files + +### Backend — New +- `api/routers/sync_status.py` — add `GET /sync/members/{user_id}` endpoint + +### Frontend — New +- `frontend/src/routes/members/[user_id]/+page.svelte` — member page +- `frontend/src/routes/members/[user_id]/+page.server.ts` — data loader +- `frontend/src/lib/components/team/MemberOverviewTab.svelte` +- `frontend/src/lib/components/team/MemberSessionsTab.svelte` +- `frontend/src/lib/components/team/MemberTeamsTab.svelte` +- `frontend/src/lib/components/team/MemberActivityTab.svelte` + +### Frontend — Modified +- `frontend/src/lib/components/team/TeamMembersTab.svelte` — make member cards link to `/members/[user_id]` + +### NOT Touched +- No new database tables +- No sync logic changes +- No device_id or remote_user_id resolution changes diff --git a/docs/plans/2026-03-09-member-page-plan.md b/docs/plans/2026-03-09-member-page-plan.md new file mode 100644 index 00000000..4ae3b12d --- /dev/null +++ b/docs/plans/2026-03-09-member-page-plan.md @@ -0,0 +1,1400 @@ +# Member Page Implementation Plan + +> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. + +**Goal:** Build a read-only member detail page at `/members/[user_id]` with 4 tabs (Overview, Sessions, Teams, Activity), themed with the member's hash-assigned color from the 16-color palette. + +**Architecture:** New backend endpoint aggregates member data across teams. SvelteKit page loads data server-side, renders a color-themed profile header + bits-ui tabs. Each tab is a standalone Svelte component following the exact patterns from the redesigned team detail page (`TeamOverviewTab`, `TeamMembersTab`, etc.). TeamMembersTab is modified to link member cards to the new page. + +**Tech Stack:** FastAPI (backend endpoint), SvelteKit + Svelte 5 (page + 4 tab components), bits-ui (tabs), Chart.js (overview chart), lucide-svelte (icons), Tailwind CSS 4 (styling) + +**Design Doc:** `docs/plans/2026-03-09-member-page-design.md` + +--- + +### Task 1: Backend — Add `/sync/members/{user_id}` Endpoint + +**Files:** +- Modify: `api/routers/sync_status.py` — add new endpoint at bottom of file (before settings endpoint) + +**Context:** This endpoint aggregates data across all teams for a single member. It reuses existing DB queries and Syncthing device APIs already used by the team detail page. The `sync_members` table has `(team_name, name, device_id)` as key columns. The `sync_events` table has `member_name` for filtering. Session stats come from `query_session_stats_by_member()` already in `api/db/sync_queries.py`. + +**Step 1: Add the endpoint** + +Add this endpoint to `api/routers/sync_status.py`, right before the `sync_update_team_settings` function: + +```python +@router.get("/members/{member_name}") +async def sync_member_profile(member_name: str) -> Any: + """Aggregated member profile across all teams.""" + if not ALLOWED_MEMBER_NAME.match(member_name): + raise HTTPException(400, "Invalid member name") + + conn = _get_sync_conn() + + # Find all teams this member belongs to + rows = conn.execute( + "SELECT team_name, device_id FROM sync_members WHERE name = ?", + (member_name,), + ).fetchall() + + if not rows: + raise HTTPException(404, f"Member '{member_name}' not found") + + device_id = rows[0]["device_id"] + team_names = [r["team_name"] for r in rows] + + # Get device connection info from Syncthing + connected = False + in_bytes = 0 + out_bytes = 0 + try: + st = _get_st() + devices = st.system.get_status().get("connections", {}) + if device_id in devices: + dev_info = devices[device_id] + connected = dev_info.get("connected", False) + in_bytes = dev_info.get("inBytesTotal", 0) + out_bytes = dev_info.get("outBytesTotal", 0) + except Exception: + pass + + # Build team details with project contribution for this member + teams_data = [] + all_session_stats = [] + total_projects = set() + + for tn in team_names: + team_row = conn.execute( + "SELECT name FROM sync_teams WHERE name = ?", (tn,) + ).fetchone() + if not team_row: + continue + + # Members in this team + team_members = conn.execute( + "SELECT name, device_id FROM sync_members WHERE team_name = ?", (tn,) + ).fetchall() + + # Online count from Syncthing + online_count = 0 + try: + st = _get_st() + for tm in team_members: + dev_conns = st.system.get_status().get("connections", {}) + if tm["device_id"] in dev_conns and dev_conns[tm["device_id"]].get("connected"): + online_count += 1 + except Exception: + pass + + # Projects in this team + team_projects = conn.execute( + "SELECT project_encoded_name, path FROM sync_team_projects WHERE team_name = ?", + (tn,), + ).fetchall() + + project_list = [] + for tp in team_projects: + total_projects.add(tp["project_encoded_name"]) + # Count received sessions for this member in this project + received = conn.execute( + """SELECT COUNT(*) as cnt FROM sync_events + WHERE team_name = ? AND member_name = ? AND project_encoded_name = ? + AND event_type IN ('session_packaged', 'session_received')""", + (tn, member_name, tp["project_encoded_name"]), + ).fetchone() + project_list.append({ + "encoded_name": tp["project_encoded_name"], + "name": tp["project_encoded_name"], + "session_count": received["cnt"] if received else 0, + }) + + teams_data.append({ + "name": tn, + "member_count": len(team_members), + "project_count": len(team_projects), + "online_count": online_count, + "projects": project_list, + }) + + # Session stats for this team + stats = query_session_stats_by_member(conn, tn, 30) + member_stats = [s for s in stats if s["member_name"] == member_name] + all_session_stats.extend(member_stats) + + # Activity across all teams for this member + activity_rows = conn.execute( + """SELECT id, event_type, team_name, member_name, project_encoded_name, + session_uuid, detail, created_at + FROM sync_events WHERE member_name = ? + ORDER BY created_at DESC LIMIT 50""", + (member_name,), + ).fetchall() + activity = [dict(r) for r in activity_rows] + + # Aggregate stats + total_sessions = sum( + s.get("packaged", 0) + s.get("received", 0) for s in all_session_stats + ) + last_active = None + if activity: + last_active = activity[0]["created_at"] + + return { + "user_id": member_name, + "device_id": device_id, + "connected": connected, + "in_bytes_total": in_bytes, + "out_bytes_total": out_bytes, + "teams": teams_data, + "stats": { + "total_sessions": total_sessions, + "total_projects": len(total_projects), + "last_active": last_active, + }, + "session_stats": all_session_stats, + "activity": activity, + } +``` + +**Step 2: Verify endpoint works** + +Run: `cd api && uvicorn main:app --reload --port 8000` + +Then test: `curl http://localhost:8000/sync/members/{some_member_name} | python -m json.tool` + +Expected: JSON with user_id, teams, stats, session_stats, activity fields. + +**Step 3: Commit** + +```bash +git add api/routers/sync_status.py +git commit -m "feat(api): add /sync/members/{member_name} aggregated profile endpoint" +``` + +--- + +### Task 2: Frontend Types — Add MemberProfile Interface + +**Files:** +- Modify: `frontend/src/lib/api-types.ts` — add new types near the bottom, after `TeamSessionStat` + +**Step 1: Add types** + +Add these interfaces after the `TeamSessionStat` interface in `api-types.ts`: + +```typescript +export interface MemberTeamProject { + encoded_name: string; + name: string; + session_count: number; +} + +export interface MemberTeam { + name: string; + member_count: number; + project_count: number; + online_count: number; + projects: MemberTeamProject[]; +} + +export interface MemberStats { + total_sessions: number; + total_projects: number; + last_active: string | null; +} + +export interface MemberProfile { + user_id: string; + device_id: string; + connected: boolean; + in_bytes_total: number; + out_bytes_total: number; + teams: MemberTeam[]; + stats: MemberStats; + session_stats: TeamSessionStat[]; + activity: SyncEvent[]; +} +``` + +**Step 2: Type-check** + +Run: `cd frontend && npm run check` + +Expected: No errors. + +**Step 3: Commit** + +```bash +git add frontend/src/lib/api-types.ts +git commit -m "feat(types): add MemberProfile and related interfaces" +``` + +--- + +### Task 3: Frontend — Data Loader (`+page.server.ts`) + +**Files:** +- Create: `frontend/src/routes/members/[user_id]/+page.server.ts` + +**Context:** Follow the exact pattern from `frontend/src/routes/team/[name]/+page.server.ts`. Use `safeFetch` for the primary member profile call (so we can show 404), and `fetchWithFallback` for supplementary data. + +**Step 1: Create the directory and data loader** + +```bash +mkdir -p frontend/src/routes/members/\[user_id\] +``` + +Write `frontend/src/routes/members/[user_id]/+page.server.ts`: + +```typescript +import type { PageServerLoad } from './$types'; +import { API_BASE } from '$lib/config'; +import { safeFetch, fetchWithFallback } from '$lib/utils/api-fetch'; +import type { MemberProfile, SyncDevice, RemoteSessionUser } from '$lib/api-types'; + +export const load: PageServerLoad = async ({ fetch, params }) => { + const userId = params.user_id; + + const [profileResult, devicesData, remoteUserData] = await Promise.all([ + safeFetch(fetch, `${API_BASE}/sync/members/${encodeURIComponent(userId)}`), + fetchWithFallback<{ devices: SyncDevice[] }>(fetch, `${API_BASE}/sync/devices`, { + devices: [] + }), + fetchWithFallback( + fetch, + `${API_BASE}/remote/users`, + [] + ) + ]); + + // Find this user's remote session info + const remoteUser = (Array.isArray(remoteUserData) ? remoteUserData : []).find( + (u) => u.user_id === userId + ); + + return { + userId, + profile: profileResult.ok ? profileResult.data : null, + error: profileResult.ok ? null : profileResult.message, + devices: devicesData.devices ?? [], + remoteUser: remoteUser ?? null + }; +}; +``` + +**Step 2: Type-check** + +Run: `cd frontend && npm run check` + +Note: We may need to check if `RemoteSessionUser` exists in api-types.ts. If not, we'll add it or use the inline type. Check existing types first — look for `RemoteSessionUser` or similar. The backend has `RemoteUser(user_id, project_count, total_sessions)`. Match this: + +If `RemoteSessionUser` doesn't exist in api-types.ts, add it near the other remote types: + +```typescript +export interface RemoteSessionUser { + user_id: string; + project_count: number; + total_sessions: number; +} +``` + +However, `RemoteSessionUser` already exists in api-types.ts (line 1864) — verify it has the right fields. If it differs, use the existing shape. + +**Step 3: Commit** + +```bash +git add frontend/src/routes/members/\[user_id\]/+page.server.ts +# Also add api-types.ts if RemoteSessionUser was added +git commit -m "feat(member): add page data loader for /members/[user_id]" +``` + +--- + +### Task 4: Frontend — MemberOverviewTab Component + +**Files:** +- Create: `frontend/src/lib/components/team/MemberOverviewTab.svelte` + +**Context:** Follow `TeamOverviewTab.svelte` pattern exactly. Shows stats grid (3 cols), a bar chart of daily sent/received sessions, and a project contribution list. Uses the member's color for chart bars. + +**Step 1: Create the component** + +Write `frontend/src/lib/components/team/MemberOverviewTab.svelte`: + +```svelte + + +
+ +
+ +
+ + + {#if dailyTotals.size > 0} +
+
+

Sessions Over Time

+
+ +
+
+
+ {/if} + + + {#if allProjects.length > 0} +
+

+ Projects +

+
+ {#each allProjects as project (project.encoded_name)} + +
+ + + {project.name || project.encoded_name} + +
+ + {project.session_count} session{project.session_count !== 1 ? 's' : ''} + + + {/each} +
+
+ {/if} +
+``` + +**Step 2: Type-check** + +Run: `cd frontend && npm run check` + +Expected: No errors. If `StatItem` import path differs, adjust. + +**Step 3: Commit** + +```bash +git add frontend/src/lib/components/team/MemberOverviewTab.svelte +git commit -m "feat(member): add MemberOverviewTab with stats grid and session chart" +``` + +--- + +### Task 5: Frontend — MemberSessionsTab Component + +**Files:** +- Create: `frontend/src/lib/components/team/MemberSessionsTab.svelte` + +**Context:** This tab shows the remote sessions synced from this member. Uses the `/remote/users/{user_id}/projects` API to list projects and session counts, and `/remote/users/{user_id}/projects/{project}/sessions` to list individual sessions. Each session links to the session detail page. Sessions are grouped by project. + +**Step 1: Create the component** + +Write `frontend/src/lib/components/team/MemberSessionsTab.svelte`: + +```svelte + + +
+ {#if loading} +
+ +
+ {:else if projects.length === 0} +

+ No synced sessions from this member yet. +

+ {:else} +

+ {totalSessions} session{totalSessions !== 1 ? 's' : ''} across {projects.length} project{projects.length !== 1 ? 's' : ''} +

+ +
+ {#each projects as project (project.encoded_name)} + {@const isExpanded = expandedProject === project.encoded_name} + {@const sessions = projectSessions[project.encoded_name] ?? []} + {@const isLoading = loadingSessions === project.encoded_name} + +
+ + + + + {#if isExpanded} +
+ {#if isLoading} +
+ +
+ {:else if sessions.length === 0} +

+ No session details available +

+ {:else} +
+ {#each sessions as session (session.uuid)} + +
+ + + {session.uuid.substring(0, 8)}... + + {#if session.worktree_name} + + {session.worktree_name} + + {/if} +
+
+ {formatBytes(session.size_bytes)} + {formatRelativeTime(new Date(session.mtime))} +
+ + {/each} +
+ {/if} +
+ {/if} +
+ {/each} +
+ {/if} +
+``` + +**Step 2: Type-check** + +Run: `cd frontend && npm run check` + +**Step 3: Commit** + +```bash +git add frontend/src/lib/components/team/MemberSessionsTab.svelte +git commit -m "feat(member): add MemberSessionsTab with expandable project sessions" +``` + +--- + +### Task 6: Frontend — MemberTeamsTab Component + +**Files:** +- Create: `frontend/src/lib/components/team/MemberTeamsTab.svelte` + +**Context:** Shows team cards for each team this member belongs to. Follows `TeamCard.svelte` styling patterns — card with member count, project count, online count, plus a per-team project contribution breakdown for this member. + +**Step 1: Create the component** + +Write `frontend/src/lib/components/team/MemberTeamsTab.svelte`: + +```svelte + + +
+ {#if profile.teams.length === 0} +

+ Not a member of any teams. +

+ {:else} +

+ Member of {profile.teams.length} team{profile.teams.length !== 1 ? 's' : ''} +

+ +
+ {#each profile.teams as team (team.name)} + + +
+

+ {team.name} +

+ +
+ + +
+ + + {team.member_count} member{team.member_count !== 1 ? 's' : ''} + + + + {team.project_count} project{team.project_count !== 1 ? 's' : ''} + + {#if team.online_count > 0} + + + {team.online_count} online + + {/if} +
+ + + {#if team.projects.length > 0} +
+
+ {#each team.projects as project (project.encoded_name)} + + {project.name || project.encoded_name} + + {project.session_count} + + + {/each} +
+
+ {/if} + + {/each} +
+ {/if} +
+``` + +**Step 2: Type-check** + +Run: `cd frontend && npm run check` + +**Step 3: Commit** + +```bash +git add frontend/src/lib/components/team/MemberTeamsTab.svelte +git commit -m "feat(member): add MemberTeamsTab with team cards and project contributions" +``` + +--- + +### Task 7: Frontend — MemberActivityTab Component + +**Files:** +- Create: `frontend/src/lib/components/team/MemberActivityTab.svelte` + +**Context:** Reuses `TeamActivityFeed` component directly, passing the member-scoped activity events. The feed component already supports type filter pills and load-more pagination. We just need to wrap it and remove the member filter (since it's already scoped to one member). The `TeamActivityFeed` doesn't show member filter pills if `members` prop is empty/omitted, so we can just not pass it. + +**Step 1: Create the component** + +Write `frontend/src/lib/components/team/MemberActivityTab.svelte`: + +```svelte + + +
+
+ +
+

Activity

+ {#if loading} + + {/if} +
+ + +
+ {#each typePills as pill} + + {/each} +
+ + +
+ {#if events.length === 0} +

No activity yet

+ {:else} +
+ {#each events as event (event.id)} +
+ + {#if isSyncEventWarning(event.event_type)} + + + + {:else} + + {/if} + + +
+

+ {formatSyncEvent(event)} +

+
+ + {formatEventTime(event.created_at)} + + {#if event.team_name} + + {event.team_name} + + {/if} + {#if event.event_type && SYNC_EVENT_META[event.event_type]} + + {event.event_type.replace(/_/g, ' ')} + + {/if} +
+
+
+ {/each} +
+ + {#if hasMore} +
+ +
+ {/if} + {/if} +
+
+
+``` + +**Step 2: Type-check** + +Run: `cd frontend && npm run check` + +**Step 3: Commit** + +```bash +git add frontend/src/lib/components/team/MemberActivityTab.svelte +git commit -m "feat(member): add MemberActivityTab with type-filtered activity feed" +``` + +--- + +### Task 8: Frontend — Member Page (`+page.svelte`) + +**Files:** +- Create: `frontend/src/routes/members/[user_id]/+page.svelte` + +**Context:** This is the main page component. Follows the team detail page pattern: PageHeader with breadcrumbs, color-themed profile card, bits-ui tabs with URL persistence. Imports all 4 tab components. No polling needed for v1 (member data doesn't change rapidly). + +**Step 1: Create the page** + +Write `frontend/src/routes/members/[user_id]/+page.svelte`: + +```svelte + + + + +{#if profile} + +
+
+ +
+ {data.userId.charAt(0).toUpperCase()} +
+ + +
+
+

+ {data.userId} +

+ + {#if profile.connected} + + Online + {:else} + + Offline + {/if} + +
+ +
+ + {truncateDeviceId(profile.device_id)} + + {#if profile.in_bytes_total > 0 || profile.out_bytes_total > 0} + ↓ {formatBytes(profile.in_bytes_total)} + ↑ {formatBytes(profile.out_bytes_total)} + {/if} +
+
+
+
+ + + + + Overview + Sessions + Teams ({profile.teams.length}) + Activity + + + + + + + + + + + + + + + + + + +{:else} +
+ +

+ Member "{data.userId}" not found +

+ {#if data.error} +

{data.error}

+ {/if} + + Back to Teams + +
+{/if} +``` + +**Step 2: Type-check** + +Run: `cd frontend && npm run check` + +**Step 3: Verify in browser** + +Run: `cd frontend && npm run dev` + +Navigate to `http://localhost:5173/members/{some_member_name}`. Verify: +- Profile card renders with member color +- All 4 tabs load and switch correctly +- URL updates with `?tab=` parameter +- Back button restores tab state +- 404 state shows for unknown members + +**Step 4: Commit** + +```bash +git add frontend/src/routes/members/\[user_id\]/+page.svelte +git commit -m "feat(member): add member detail page with color-themed profile and tabbed layout" +``` + +--- + +### Task 9: Frontend — Link TeamMembersTab Cards to Member Page + +**Files:** +- Modify: `frontend/src/lib/components/team/TeamMembersTab.svelte` + +**Context:** Wrap each member card in the grid with an `` tag linking to `/members/{member.name}`. The card itself keeps its current styling — we just make it clickable. Follow the same pattern as `TeamCard.svelte` which wraps content in an `` tag. + +**Step 1: Make member cards linkable** + +In `TeamMembersTab.svelte`, change the member card `
` (line 92-94) to an `` tag: + +Replace the existing card wrapper: +```svelte +
+``` + +With: +```svelte + +``` + +And change the corresponding closing `
` (line 179) to ``. + +**Step 2: Prevent link navigation when clicking remove buttons** + +The remove button is inside the `` tag, so we need to stop propagation. Add `onclick|preventDefault|stopPropagation` to the remove button and confirm buttons. In Svelte 5, use `onclick={(e) => { e.preventDefault(); e.stopPropagation(); ... }}` pattern. + +Update the remove button (around line 167): +```svelte + + +
+
+ {#if deleteError} +

{deleteError}

+ {/if} +
+ {:else} + + {/if} + +
+``` + +**Step 2: Verify build** + +Run: `cd frontend && npm run check` +Expected: No errors (or only warnings from unused components — acceptable at this stage) + +**Step 3: Commit** + +```bash +git add frontend/src/lib/components/team/TeamOverviewTab.svelte +git commit -m "feat(team): add TeamOverviewTab component with stats and sent/received chart" +``` + +--- + +### Task 5: Create TeamMembersTab Component + +**Files:** +- Create: `frontend/src/lib/components/team/TeamMembersTab.svelte` +- Create: `frontend/src/lib/components/team/MemberSparkline.svelte` + +**Step 1: Create MemberSparkline component** + +A tiny Chart.js line chart (~80x30px) for member cards. + +```svelte + + +
+ +
+``` + +**Step 2: Create TeamMembersTab component** + +Grid of member cards with sparklines, color borders, connection status. + +```svelte + + +
+
+ {#each members as member (member.name)} + {@const colors = getTeamMemberColor(member.name)} + {@const hexColor = getTeamMemberHexColor(member.name)} + {@const isSelf = member.name === userId} +
+
+
+ {member.name} + {#if isSelf} + You + {/if} +
+
+ {#if member.connected} + + Online + + {:else} + + Offline + + {/if} + + {formatBytes(member.in_bytes_total)} in / {formatBytes(member.out_bytes_total)} out + +
+
+ + + + {#if !isSelf} +
+ {#if removeConfirm === member.name} +
+ + +
+ {:else} + + {/if} +
+ {/if} +
+ {/each} +
+ + {#if members.length === 0} +

No members yet. Share your join code to invite teammates.

+ {/if} + + + {#if members.length <= 1} +
+

Waiting for members?

+
    +
  • + + Share the join code with your teammate +
    • +
  • + + Both machines need Syncthing running +
    • +
  • + + Discovery can take 15-60 seconds after joining +
    • +
+ {#if detectData} +
+ {#if detectData.running} + + Your Syncthing is running + + {:else} + + Your Syncthing is not running + + {/if} +
+ {/if} +
+ {/if} +
+``` + +**Step 3: Verify build** + +Run: `cd frontend && npm run check` +Expected: No errors + +**Step 4: Commit** + +```bash +git add frontend/src/lib/components/team/MemberSparkline.svelte frontend/src/lib/components/team/TeamMembersTab.svelte +git commit -m "feat(team): add TeamMembersTab with sparkline charts and color-coded cards" +``` + +--- + +### Task 6: Create TeamProjectsTab Component + +**Files:** +- Create: `frontend/src/lib/components/team/TeamProjectsTab.svelte` +- Create: `frontend/src/lib/components/team/ProjectMemberBar.svelte` + +**Step 1: Create ProjectMemberBar — mini horizontal bar showing session volume per member** + +```svelte + + +{#if segments.length > 0} +
+
+ {#each segments as seg} +
+ {/each} +
+
+ {#each segments as seg} + + + {seg.name} ({seg.count}) + + {/each} +
+
+{/if} +``` + +**Step 2: Create TeamProjectsTab component** + +Lift the projects section into its own tab with header row, cards, and member bars. + +```svelte + + +
+ +
+
+ {#if projects.length > 0} + + {/if} + +
+ {#if projects.length > 0} + + {/if} +
+ + +
+ {#each projects as project (project.encoded_name)} + {@const status = getProjectStatus(project.encoded_name)} +
+
+
+ +
+ + {project.name || project.encoded_name} + + {#if project.path} +

{project.path}

+ {/if} + {#if status} +

+ {status.packaged_count}/{status.local_count} sessions packaged +

+ {/if} +
+
+
+ {#if status} + {#if status.gap === 0} + + In Sync + + {:else} + + {status.gap} behind + + {/if} + {/if} + {#if removeProjectConfirm === project.encoded_name} +
+ + +
+ {:else} + + {/if} +
+
+ + + +
+ {/each} + {#if projects.length === 0} +

No projects shared yet. Add projects to start syncing sessions.

+ {/if} +
+
+ + +``` + +**Step 3: Verify build** + +Run: `cd frontend && npm run check` +Expected: No errors + +**Step 4: Commit** + +```bash +git add frontend/src/lib/components/team/ProjectMemberBar.svelte frontend/src/lib/components/team/TeamProjectsTab.svelte +git commit -m "feat(team): add TeamProjectsTab with per-project member contribution bars" +``` + +--- + +### Task 7: Create TeamActivityTab Component + +**Files:** +- Create: `frontend/src/lib/components/team/TeamActivityTab.svelte` + +**Step 1: Create the component** + +Line chart with member filter chips + TeamActivityFeed below. + +```svelte + + +
+ +
+
+

Sessions Over Time

+
+ {#each periods as p} + + {/each} +
+
+ +
+ +
+ + + {#if allMembers.length > 0} +
+ {#each allMembers as member} + {@const hex = getTeamMemberHexColor(member)} + {@const active = visibleMembers.has(member)} + + {/each} +
+ {/if} +
+ + + +
+``` + +**Step 2: Verify build** + +Run: `cd frontend && npm run check` +Expected: No errors + +**Step 3: Commit** + +```bash +git add frontend/src/lib/components/team/TeamActivityTab.svelte +git commit -m "feat(team): add TeamActivityTab with line chart, period selector, and member filters" +``` + +--- + +### Task 8: Wire Up Tabs in Team Detail Page + +**Files:** +- Modify: `frontend/src/routes/team/[name]/+page.svelte` +- Modify: `frontend/src/routes/team/[name]/+page.server.ts` + +**Step 1: Update server loader to fetch session stats** + +In `+page.server.ts`, add to the parallel fetch block: + +```typescript +// Add to imports +import type { TeamSessionStat } from '$lib/api-types'; + +// Add to Promise.all (alongside existing fetches) +fetchWithFallback<{ stats: TeamSessionStat[] }>( + fetch, + `${API_BASE}/sync/teams/${encodeURIComponent(teamName)}/session-stats?days=30`, + { stats: [] } +), +``` + +Add to the return object: +```typescript +sessionStats: sessionStatsData.stats ?? [], +``` + +**Step 2: Rewrite the page component with tabs** + +Replace the entire `+page.svelte` with the tabbed version. Key changes: +- Import `Tabs` from `$lib/components/ui` +- Import `TabsTrigger` from `$lib/components/ui/TabsTrigger.svelte` +- Import all 4 tab components +- Add `activeTab` state with URL persistence (same pattern as project detail page) +- Move pending requests ABOVE the tabs +- Move each section's content into the appropriate tab component + +The page structure becomes: + +```svelte + + + + +
+ +
+ + +{#if pendingDevices.length > 0}...existing pending devices section...{/if} +{#if pendingFolders.length > 0}...existing pending folders section...{/if} + +{#if team} + + + Overview + Members ({members.length}) + Projects ({projects.length}) + Activity + + + + deleteConfirm = v} ondeleteerror={(v) => deleteError = v} /> + + + + + + + + + + + + + + +{:else} + ...existing "team not found" fallback... +{/if} + + +``` + +**Important:** The existing polling logic, pending request handlers, and fetch functions stay in the parent page. Only the rendering moves into tab components. + +**Step 3: Verify build** + +Run: `cd frontend && npm run check` +Expected: No errors + +**Step 4: Visual verification** + +Run: `cd frontend && npm run dev` +Open: http://localhost:5173/team/{your-team-name} +Verify: 4 tabs render, URL updates with `?tab=`, content displays correctly in each tab + +**Step 5: Commit** + +```bash +git add frontend/src/routes/team/[name]/+page.svelte frontend/src/routes/team/[name]/+page.server.ts +git commit -m "feat(team): convert team detail page to tabbed layout with Overview/Members/Projects/Activity" +``` + +--- + +### Task 9: Fix Imports and Polish + +After wiring everything up, there may be import path issues or minor TypeScript errors. + +**Step 1: Run full type check** + +Run: `cd frontend && npm run check` + +Fix any errors found (typical issues: import paths for Tabs components, missing type exports, prop mismatches). + +**Step 2: Run lint** + +Run: `cd frontend && npm run lint` + +Fix any lint warnings. + +**Step 3: Visual QA** + +Manually check each tab in the browser: +- Overview: Stats cards, sent/received chart, danger zone +- Members: Grid layout, sparklines render, color borders match +- Projects: Cards with member bars, sync status badges, add/remove flows +- Activity: Line chart renders, period selector works, member chips toggle visibility + +**Step 4: Commit** + +```bash +git add -A +git commit -m "fix(team): polish tab imports, types, and visual consistency" +``` diff --git a/docs/superpowers/plans/2026-03-11-sync-v2-master.md b/docs/superpowers/plans/2026-03-11-sync-v2-master.md new file mode 100644 index 00000000..76b6db7d --- /dev/null +++ b/docs/superpowers/plans/2026-03-11-sync-v2-master.md @@ -0,0 +1,159 @@ +# Sync Architecture v2 — Master Implementation Plan + +> **For agentic workers:** REQUIRED: Use superpowers:subagent-driven-development (if subagents available) or superpowers:executing-plans to implement this plan. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Redesign the P2P sync layer so each device is a distinct member with its own stream, fix the session merging bug, add state convergence via metadata folders, and make the pending folder UX clear and unambiguous. + +**Architecture:** Device = Member identity model. Each machine gets a unique `member_tag` (`{user_id}.{machine_tag}`) embedded in Syncthing folder IDs. A team metadata folder (`karma-meta--{team}`, `sendreceive` type) syncs membership state, subscriptions, and removal signals across machines. Opt-out selective subscriptions. Creator-only removal authority. + +**Tech Stack:** Python 3.9+, FastAPI, Pydantic 2.x, SQLite, Syncthing REST API + +--- + +## Design Decisions (Locked) + +| Decision | Choice | Rationale | +|----------|--------|-----------| +| Identity model | Device = Member | Each machine has independent send/receive control | +| member_tag format | `{user_id}.{machine_tag}` | Human-readable, parseable via `.` separator | +| machine_tag derivation | Auto from hostname, sanitized | No user friction at setup | +| Removal authority | Creator only | Small trusted teams, `team.json.created_by` check | +| Metadata folder type | `sendreceive` | Each member writes own file, no conflicts | +| Subscription model | Opt-out | Everyone gets everything by default, can unsubscribe | +| Cross-team dedup | Folder IDs are globally unique | Same outbox folder shared across teams, no duplication | +| Breaking changes | Allowed | Feature in development, no backward compat needed | + +## Dependency Graph + +``` +Phase 0: Quick Wins (all parallel) +═══════════════════════════════════ + T0.1 (reconcile fix) ─┐ + T0.2 (self-introducer) ─┤ + T0.3 (collision check) ─┼── All 6 independent, run in parallel + T0.4 (settings cleanup) ─┤ + T0.5 (project cleanup) ─┤ + T0.6 (exception fix) ─┘ + +Phase 1: Device = Member Identity (sequential core → parallel fan-out) +══════════════════════════════════════════════════════════════════════ + T1.1 (SyncConfig + machine_tag) + │ + ▼ + T1.2 (DB migration v17) + │ + ▼ + T1.3 (folder_id.py v2) + │ + ├──────────────────┬──────────────────┐ + ▼ ▼ ▼ + T1.4 (sync_folders) T1.5 (reconcile) T1.6 (pending.py) + │ │ │ + └──────────────────┼──────────────────┘ + ▼ + T1.7 (routers) + ├──────────┐ + ▼ ▼ + T1.8 (remote) T1.9 (packager) + +Phase 2: Metadata Folder (sequential) +═════════════════════════════════════ + T2.1 (file format + helpers) + │ + ▼ + T2.2 (create on team create/join) + │ + ├──────────────────┐ + ▼ ▼ + T2.3 (member write) T2.4 (removal write) + │ │ + └──────────┬─────────┘ + ▼ + T2.5 (reconciliation reads metadata) + │ + ├──────────┐ + ▼ ▼ + T2.6 (auto-leave) T2.7 (watcher loop) + +Phase 3: UX Polish (mostly parallel) +════════════════════════════════════ + T3.1 (rejected table) ──→ T3.2 (rejection endpoint) + T3.3 (subscriptions) ──→ T3.4 (auto_share check) + T3.5 (any-member invite) ── independent + T3.6 (session limit per-device) ── independent +``` + +## Phase Documents + +| Phase | Plan File | Effort | Strategy | +|-------|-----------|--------|----------| +| 0 | `2026-03-11-sync-v2-phase0-quick-wins.md` | 1 day | `superpowers:dispatching-parallel-agents` — all 6 tasks independent | +| 1 | `2026-03-11-sync-v2-phase1-device-identity.md` | 2-3 days | `superpowers:subagent-driven-development` — sequential core, fan-out | +| 2 | `2026-03-11-sync-v2-phase2-metadata-folder.md` | 2-3 days | `superpowers:subagent-driven-development` — sequential | +| 3 | `2026-03-11-sync-v2-phase3-ux-polish.md` | 1-2 days | `superpowers:dispatching-parallel-agents` — mostly independent | + +## Agent & Skill Hints + +| Task Group | Recommended Agent | Skill to Invoke | Notes | +|------------|------------------|-----------------|-------| +| Phase 0 (all) | Parallel worktree agents | `superpowers:dispatching-parallel-agents` | Each task gets own worktree, merge after | +| T1.1–T1.3 | Main session (sequential) | `superpowers:executing-plans` | Core identity changes, needs coordination | +| T1.4–T1.6 | 3 parallel subagents | `superpowers:subagent-driven-development` | Independent files after T1.3 | +| T1.7–T1.9 | 3 parallel subagents | `superpowers:subagent-driven-development` | Independent files after T1.4–T1.6 | +| T2.1–T2.5 | Main session (sequential) | `superpowers:executing-plans` | State convergence needs careful ordering | +| T2.6–T2.7 | 2 parallel subagents | `superpowers:subagent-driven-development` | Independent after T2.5 | +| Phase 3 (all) | 4 parallel subagents | `superpowers:dispatching-parallel-agents` | All independent features | + +## Test Infrastructure + +All sync tests follow this pattern: +```python +import sqlite3 +import pytest +from db.schema import ensure_schema + +@pytest.fixture +def conn(): + c = sqlite3.connect(":memory:") + c.row_factory = sqlite3.Row + c.execute("PRAGMA foreign_keys=ON") + ensure_schema(c) + return c +``` + +Run tests: `cd api && pytest tests/test_sync_*.py -v` + +## Key File Map + +| File | Role | Phases Modified | +|------|------|----------------| +| `cli/karma/config.py` | SyncConfig model | 1 | +| `api/services/folder_id.py` | Folder ID build/parse | 1 | +| `api/services/sync_folders.py` | Folder CRUD helpers | 0, 1, 2, 3 | +| `api/services/sync_reconciliation.py` | 4-phase reconciliation | 0, 1, 2 | +| `api/services/sync_identity.py` | Identity + validation | 1 | +| `api/services/sync_policy.py` | Policy evaluation | 3 | +| `api/db/schema.py` | SQLite schema | 1, 3 | +| `api/db/sync_queries.py` | DB CRUD | 0, 1, 2, 3 | +| `api/routers/sync_devices.py` | Device pairing | 0, 1 | +| `api/routers/sync_teams.py` | Team lifecycle | 0, 1, 2, 3 | +| `api/routers/sync_members.py` | Member management | 1, 2 | +| `api/routers/sync_projects.py` | Project sharing | 0, 1, 3 | +| `api/routers/sync_pending.py` | Pending folder UX | 1, 3 | +| `cli/karma/pending.py` | CLI folder acceptance | 1 | +| `cli/karma/packager.py` | Session packaging | 1 | +| `api/services/remote_sessions.py` | Remote session discovery | 1 | + +## Verification Checklist (After All Phases) + +- [ ] Two devices with same user_id produce distinct folder IDs +- [ ] Pending UI shows device-specific descriptions (no "Receive Receive" duplicates) +- [ ] Removed member detects removal via metadata folder and auto-leaves +- [ ] Rejected folder offers don't reappear +- [ ] Unsubscribed projects don't create inbox folders +- [ ] Any team member can generate invite codes +- [ ] Session limit per-device works via metadata file +- [ ] Settings cleaned up on team delete +- [ ] Remove-project cleans filesystem + DB +- [ ] `reconcile_introduced_devices` creates folders for introduced peers +- [ ] All existing sync tests pass (`pytest tests/test_sync_*.py -v`) diff --git a/docs/superpowers/plans/2026-03-11-sync-v2-phase0-quick-wins.md b/docs/superpowers/plans/2026-03-11-sync-v2-phase0-quick-wins.md new file mode 100644 index 00000000..f2ca53b8 --- /dev/null +++ b/docs/superpowers/plans/2026-03-11-sync-v2-phase0-quick-wins.md @@ -0,0 +1,749 @@ +# Sync v2 Phase 0: Quick Wins (Bug Fixes) + +> **For agentic workers:** REQUIRED: Use superpowers:subagent-driven-development (if subagents available) or superpowers:executing-plans to implement this plan. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Fix 6 known bugs in the sync layer — all independent, all parallelizable. + +**Architecture:** Targeted fixes to existing code. No schema changes. No breaking changes. + +**Tech Stack:** Python, FastAPI, SQLite, pytest + +--- + +## Chunk 1: Bug Fixes + +All 6 tasks are independent — run them in parallel using `superpowers:dispatching-parallel-agents`. + +### Task 0.1: Fix reconcile_introduced_devices — Add auto_share_folders + +Introduced devices get DB records but no Syncthing folders. MacBook Pro never receives Ayush's sessions because `reconcile_introduced_devices` calls `upsert_member` but NOT `auto_share_folders`. + +**Files:** +- Modify: `api/services/sync_reconciliation.py:144-161` +- Test: `api/tests/test_sync_reconciliation_fix.py` (create) + +- [ ] **Step 1: Write the failing test** + +```python +# api/tests/test_sync_reconciliation_fix.py +"""Tests for reconcile_introduced_devices auto_share_folders fix.""" + +import sqlite3 +from unittest.mock import AsyncMock, MagicMock, patch + +import pytest + +from db.schema import ensure_schema + + +@pytest.fixture +def conn(): + c = sqlite3.connect(":memory:") + c.row_factory = sqlite3.Row + c.execute("PRAGMA foreign_keys=ON") + ensure_schema(c) + return c + + +@pytest.fixture +def mock_config(): + config = MagicMock() + config.user_id = "jayant" + config.machine_id = "Mac-Mini" + config.syncthing.device_id = "LEADER-DID" + return config + + +@pytest.mark.asyncio +async def test_reconcile_introduced_devices_calls_auto_share(conn, mock_config): + """Introduced devices should get folders shared back (not just DB record).""" + from db.sync_queries import create_team, upsert_member, add_team_project + + # Setup: team with one project, leader is a member + create_team(conn, "acme", backend="syncthing") + upsert_member(conn, "acme", "jayant", device_id="LEADER-DID") + conn.execute( + "INSERT INTO projects (encoded_name) VALUES (?)", + ("-Users-test-proj",), + ) + add_team_project(conn, "acme", "-Users-test-proj", path="/test", git_identity="org/proj") + + # Mock proxy: one introduced device NOT in karma DB + mock_proxy = AsyncMock() + mock_proxy.get_devices = MagicMock(return_value=[ + {"device_id": "AYUSH-DID", "name": "ayush", "is_self": False}, + {"device_id": "LEADER-DID", "name": "jayant", "is_self": True}, + ]) + mock_proxy.get_configured_folders = MagicMock(return_value=[ + { + "id": "karma-join--ayush--acme", + "type": "receiveonly", + "devices": [{"deviceID": "AYUSH-DID"}, {"deviceID": "LEADER-DID"}], + }, + ]) + + with patch( + "services.sync_reconciliation.auto_share_folders", + new_callable=AsyncMock, + ) as mock_share: + from services.sync_reconciliation import reconcile_introduced_devices + count = await reconcile_introduced_devices(mock_proxy, mock_config, conn) + + assert count == 1 + # KEY ASSERTION: auto_share_folders was called for the introduced device + mock_share.assert_called_once_with(mock_proxy, mock_config, conn, "acme", "AYUSH-DID") +``` + +- [ ] **Step 2: Run test to verify it fails** + +Run: `cd api && python -m pytest tests/test_sync_reconciliation_fix.py::test_reconcile_introduced_devices_calls_auto_share -v` +Expected: FAIL — `mock_share.assert_called_once_with` fails (never called) + +- [ ] **Step 3: Implement the fix** + +In `api/services/sync_reconciliation.py`, after line 161 (after the `reconciled += 1`), add the `auto_share_folders` call inside the `for username, team_name in memberships:` loop. Replace lines 144-161: + +```python + for username, team_name in memberships: + if was_member_removed(conn, team_name, device_id): + logger.debug( + "Reconcile introduced: skipping %s for team %s (previously removed)", + device_id[:20], team_name, + ) + continue + upsert_member(conn, team_name, username, device_id=device_id) + log_event( + conn, "member_auto_accepted", team_name=team_name, + member_name=username, + detail={"strategy": "reconciliation", "source": "introduced_device"}, + ) + # Auto-share project folders back to the introduced device + try: + await auto_share_folders(proxy, config, conn, team_name, device_id) + except Exception as e: + logger.warning( + "Reconcile introduced: failed to share folders with %s: %s", + device_id[:20], e, + ) + logger.info( + "Reconciled introduced device %s as %s in team %s", + device_id[:20], username, team_name, + ) + reconciled += 1 +``` + +- [ ] **Step 4: Run test to verify it passes** + +Run: `cd api && python -m pytest tests/test_sync_reconciliation_fix.py -v` +Expected: PASS + +- [ ] **Step 5: Run existing tests to verify no regressions** + +Run: `cd api && python -m pytest tests/test_sync_*.py -v` +Expected: All pass + +- [ ] **Step 6: Commit** + +```bash +cd api +git add services/sync_reconciliation.py tests/test_sync_reconciliation_fix.py +git commit -m "fix(sync): call auto_share_folders for introduced devices + +reconcile_introduced_devices was adding members to the DB but not +creating Syncthing folders, leaving introduced peers unable to sync. +Fixes issue #3 from sync architecture review." +``` + +--- + +### Task 0.2: Fix ensure_leader_introducers Self-Skip + +On the leader's machine, `ensure_leader_introducers` parses the join code, gets the leader's own device_id, and tries to set `introducer=True` on itself. Self isn't in the peer list → ValueError → caught by `except: pass`. Wasteful API call. + +**Files:** +- Modify: `api/services/sync_reconciliation.py:166-193` +- Modify: `api/routers/sync_devices.py` (caller — pass own_device_id) +- Test: `api/tests/test_sync_reconciliation_fix.py` (append) + +- [ ] **Step 1: Write the failing test** + +Append to `api/tests/test_sync_reconciliation_fix.py`: + +```python +@pytest.mark.asyncio +async def test_ensure_leader_introducers_skips_self(conn, mock_config): + """Should not attempt to set introducer on own device.""" + from db.sync_queries import create_team + + create_team(conn, "acme", backend="syncthing", join_code="acme:jayant:LEADER-DID") + + mock_proxy = AsyncMock() + + from services.sync_reconciliation import ensure_leader_introducers + count = await ensure_leader_introducers(mock_proxy, conn, own_device_id="LEADER-DID") + + # Should NOT have called set_device_introducer (skipped self) + mock_proxy.set_device_introducer.assert_not_called() + assert count == 0 +``` + +- [ ] **Step 2: Run test to verify it fails** + +Run: `cd api && python -m pytest tests/test_sync_reconciliation_fix.py::test_ensure_leader_introducers_skips_self -v` +Expected: FAIL — TypeError (unexpected keyword argument `own_device_id`) + +- [ ] **Step 3: Implement the fix** + +In `api/services/sync_reconciliation.py`, modify `ensure_leader_introducers` signature and add self-skip: + +```python +async def ensure_leader_introducers(proxy, conn, *, own_device_id: str | None = None) -> int: + """Ensure leader devices are marked as introducers in Syncthing. + + Parses each team's join code to find the leader device_id and sets the + introducer flag if it is missing. Skips own device_id to avoid wasteful + API calls. + + Returns count of devices updated. + """ + updated = 0 + for team in list_teams(conn): + join_code = team.get("join_code") + if not join_code: + continue + parts = join_code.split(":", 2) + if len(parts) == 3: + _, _, leader_device_id = parts + elif len(parts) == 2: + _, leader_device_id = parts + else: + continue + # Skip self — can't set introducer on own device + if own_device_id and leader_device_id == own_device_id: + continue + try: + changed = await run_sync(proxy.set_device_introducer, leader_device_id, True) + if changed: + logger.info("Auto-set introducer=True for leader device %s", leader_device_id[:20]) + updated += 1 + except Exception: + pass + return updated +``` + +Update the caller in `api/routers/sync_devices.py`. Find where `ensure_leader_introducers` is called (in `sync_pending_devices`) and pass `own_device_id`: + +```python +# In sync_pending_devices function, find the ensure_leader_introducers call: +own_did = config.syncthing.device_id if config and config.syncthing else None +await ensure_leader_introducers(proxy, conn, own_device_id=own_did) +``` + +- [ ] **Step 4: Run tests** + +Run: `cd api && python -m pytest tests/test_sync_reconciliation_fix.py -v` +Expected: All pass + +- [ ] **Step 5: Commit** + +```bash +cd api +git add services/sync_reconciliation.py routers/sync_devices.py tests/test_sync_reconciliation_fix.py +git commit -m "fix(sync): skip self when setting leader introducer flag + +ensure_leader_introducers was trying to set introducer=True on the +leader's own device, which always fails silently. Now accepts +own_device_id parameter and skips self." +``` + +--- + +### Task 0.3: Add User ID Collision Check at Accept Time + +When accepting a pending device, the extracted member name could collide with an existing member (different device). This causes silent folder ID collisions — two devices writing to the same outbox. + +**Files:** +- Modify: `api/routers/sync_devices.py:206-260` +- Test: `api/tests/test_sync_collision_check.py` (create) + +- [ ] **Step 1: Write the failing test** + +```python +# api/tests/test_sync_collision_check.py +"""Tests for user_id collision check during device acceptance.""" + +import sqlite3 +from unittest.mock import AsyncMock, MagicMock, patch + +import pytest +from fastapi.testclient import TestClient + +from db.schema import ensure_schema + + +@pytest.fixture +def conn(): + c = sqlite3.connect(":memory:") + c.row_factory = sqlite3.Row + c.execute("PRAGMA foreign_keys=ON") + ensure_schema(c) + return c + + +def test_accept_rejects_colliding_member_name(conn): + """Accepting a device whose name collides with an existing member should fail.""" + from db.sync_queries import create_team, upsert_member, list_members + + create_team(conn, "acme", backend="syncthing") + upsert_member(conn, "acme", "jayant", device_id="EXISTING-DID") + + # A different device claiming the name "jayant" should be detected + members = list_members(conn, "acme") + collisions = [ + m for m in members + if m["name"] == "jayant" and m["device_id"] != "NEW-DID" + ] + assert len(collisions) == 1, "Should detect name collision" +``` + +- [ ] **Step 2: Run test to verify it passes** (this tests the detection logic, not the endpoint) + +Run: `cd api && python -m pytest tests/test_sync_collision_check.py -v` +Expected: PASS + +- [ ] **Step 3: Implement the collision check** + +In `api/routers/sync_devices.py`, in the `sync_accept_pending_device` function, after member_name is resolved (around line 245), add: + +```python + # Check for name collision — different device claiming the same identity + existing_members = list_members(conn, team_name) + collisions = [ + m for m in existing_members + if m["name"] == member_name and m["device_id"] != device_id + ] + if collisions: + raise HTTPException( + 409, + f"Member name '{member_name}' is already used by another device " + f"in team '{team_name}'. The new device must use a different user_id.", + ) +``` + +Add `list_members` to the imports from `db.sync_queries` at the top of the file. + +- [ ] **Step 4: Run all sync tests** + +Run: `cd api && python -m pytest tests/test_sync_*.py -v` +Expected: All pass + +- [ ] **Step 5: Commit** + +```bash +cd api +git add routers/sync_devices.py tests/test_sync_collision_check.py +git commit -m "fix(sync): reject pending device if user_id collides with existing member + +Prevents silent folder ID collisions when two different devices claim +the same user_id within a team. Returns 409 Conflict." +``` + +--- + +### Task 0.4: Clean Up Settings on Team Delete + +`delete_team()` only deletes from `sync_teams` (cascade handles members/projects). But `sync_settings` has no FK — settings with scope `team:X` and `member:X:Y` are orphaned forever. + +**Files:** +- Modify: `api/db/sync_queries.py:32-34` +- Test: `api/tests/test_sync_settings_cleanup.py` (create) + +- [ ] **Step 1: Write the failing test** + +```python +# api/tests/test_sync_settings_cleanup.py +"""Tests for settings cleanup on team delete.""" + +import sqlite3 +import pytest +from db.schema import ensure_schema + + +@pytest.fixture +def conn(): + c = sqlite3.connect(":memory:") + c.row_factory = sqlite3.Row + c.execute("PRAGMA foreign_keys=ON") + ensure_schema(c) + return c + + +def test_delete_team_cleans_up_settings(conn): + """Deleting a team should remove orphaned sync_settings entries.""" + from db.sync_queries import create_team, set_setting, delete_team + + create_team(conn, "acme", backend="syncthing") + set_setting(conn, "team:acme", "auto_accept_members", "true") + set_setting(conn, "member:acme:DEV-123", "sync_direction", "send_only") + + # Also set a setting for a different team (should NOT be cleaned) + create_team(conn, "other", backend="syncthing") + set_setting(conn, "team:other", "auto_accept_members", "false") + + delete_team(conn, "acme") + + # Acme settings should be gone + rows = conn.execute( + "SELECT * FROM sync_settings WHERE scope LIKE 'team:acme%' OR scope LIKE 'member:acme:%'" + ).fetchall() + assert len(rows) == 0, f"Expected 0 orphaned settings, found {len(rows)}" + + # Other team's settings should survive + rows = conn.execute( + "SELECT * FROM sync_settings WHERE scope LIKE 'team:other%'" + ).fetchall() + assert len(rows) == 1 +``` + +- [ ] **Step 2: Run test to verify it fails** + +Run: `cd api && python -m pytest tests/test_sync_settings_cleanup.py -v` +Expected: FAIL — orphaned settings found + +- [ ] **Step 3: Implement the fix** + +In `api/db/sync_queries.py`, modify `delete_team`: + +```python +def delete_team(conn: sqlite3.Connection, name: str) -> None: + # Clean up orphaned settings (sync_settings has no FK to sync_teams) + conn.execute( + "DELETE FROM sync_settings WHERE scope = ? OR scope LIKE ?", + (f"team:{name}", f"member:{name}:%"), + ) + conn.execute("DELETE FROM sync_teams WHERE name = ?", (name,)) + conn.commit() +``` + +- [ ] **Step 4: Run test to verify it passes** + +Run: `cd api && python -m pytest tests/test_sync_settings_cleanup.py -v` +Expected: PASS + +- [ ] **Step 5: Run existing settings tests** + +Run: `cd api && python -m pytest tests/test_sync_settings.py tests/test_sync_team_crud.py -v` +Expected: All pass + +- [ ] **Step 6: Commit** + +```bash +cd api +git add db/sync_queries.py tests/test_sync_settings_cleanup.py +git commit -m "fix(sync): clean up orphaned settings on team delete + +sync_settings has no FK to sync_teams, so team:X and member:X:Y +scoped settings were never cleaned up. Now deleted before CASCADE." +``` + +--- + +### Task 0.5: Add Data Cleanup to Remove-Project + +`sync_remove_team_project` removes Syncthing folders and DB records, but NOT remote session files on disk or session rows in the DB. Compare with `remove_member` which calls `cleanup_data_for_member`. + +**Files:** +- Modify: `api/db/sync_queries.py` (add `cleanup_data_for_project`) +- Modify: `api/routers/sync_projects.py:151-199` +- Test: `api/tests/test_sync_project_cleanup.py` (create) + +- [ ] **Step 1: Write the failing test** + +```python +# api/tests/test_sync_project_cleanup.py +"""Tests for project removal data cleanup.""" + +import sqlite3 +from pathlib import Path + +import pytest +from db.schema import ensure_schema + + +@pytest.fixture +def conn(): + c = sqlite3.connect(":memory:") + c.row_factory = sqlite3.Row + c.execute("PRAGMA foreign_keys=ON") + ensure_schema(c) + return c + + +def test_cleanup_data_for_project_removes_remote_sessions(conn, tmp_path): + """Removing a project should clean up remote session files and DB rows.""" + from db.sync_queries import create_team, upsert_member + + create_team(conn, "acme", backend="syncthing") + upsert_member(conn, "acme", "ayush", device_id="AYUSH-DID") + + # Create fake remote session files + remote_dir = tmp_path / "remote-sessions" / "ayush" / "-Users-test-proj" + remote_dir.mkdir(parents=True) + (remote_dir / "session1.jsonl").write_text("{}") + (remote_dir / "session2.jsonl").write_text("{}") + + # Create fake DB session rows + conn.execute( + "INSERT INTO sessions (uuid, project_encoded_name, source, remote_user_id) VALUES (?, ?, ?, ?)", + ("sess-1", "-Users-test-proj", "remote", "ayush"), + ) + conn.execute( + "INSERT INTO sessions (uuid, project_encoded_name, source, remote_user_id) VALUES (?, ?, ?, ?)", + ("sess-2", "-Users-test-proj", "remote", "ayush"), + ) + # Session from different project (should NOT be deleted) + conn.execute( + "INSERT INTO sessions (uuid, project_encoded_name, source, remote_user_id) VALUES (?, ?, ?, ?)", + ("sess-other", "-Users-other", "remote", "ayush"), + ) + conn.commit() + + from db.sync_queries import cleanup_data_for_project + stats = cleanup_data_for_project(conn, "acme", "-Users-test-proj", base_path=tmp_path) + + assert stats["sessions_deleted"] == 2 + assert not remote_dir.exists(), "Remote session directory should be deleted" + + # Other project's session should survive + remaining = conn.execute( + "SELECT COUNT(*) FROM sessions WHERE project_encoded_name = '-Users-other'" + ).fetchone()[0] + assert remaining == 1 +``` + +- [ ] **Step 2: Run test to verify it fails** + +Run: `cd api && python -m pytest tests/test_sync_project_cleanup.py -v` +Expected: FAIL — `ImportError: cannot import name 'cleanup_data_for_project'` + +- [ ] **Step 3: Implement cleanup_data_for_project** + +Add to `api/db/sync_queries.py`: + +```python +def cleanup_data_for_project( + conn: sqlite3.Connection, + team_name: str, + project_encoded_name: str, + *, + base_path: Path | None = None, +) -> dict: + """Remove remote session data for a specific project across all team members. + + Cleans up: + - Filesystem: remote-sessions/{member}/{encoded}/ directories + - DB: sessions with source='remote' for this project + """ + import shutil + from pathlib import Path as _Path + + if base_path is None: + from karma.config import KARMA_BASE + base_path = KARMA_BASE + + stats = {"sessions_deleted": 0, "dirs_deleted": 0} + + members = list_members(conn, team_name) + + # Filesystem cleanup + for m in members: + member_dir = base_path / "remote-sessions" / m["name"] / project_encoded_name + if member_dir.exists(): + shutil.rmtree(member_dir) + stats["dirs_deleted"] += 1 + # Remove parent if empty + parent = member_dir.parent + if parent.exists() and not any(parent.iterdir()): + parent.rmdir() + + # DB cleanup: remove remote sessions for this project + cursor = conn.execute( + "DELETE FROM sessions WHERE source = 'remote' AND project_encoded_name = ?", + (project_encoded_name,), + ) + stats["sessions_deleted"] = cursor.rowcount + conn.commit() + + return stats +``` + +Add the import at the top of `sync_queries.py`: +```python +from pathlib import Path +``` + +- [ ] **Step 4: Wire it into the remove-project endpoint** + +In `api/routers/sync_projects.py`, in `sync_remove_team_project`, after the Syncthing folder cleanup and before `remove_team_project(conn, ...)`, add: + +```python + # Clean up remote session data (filesystem + DB) + try: + from db.sync_queries import cleanup_data_for_project + stats = cleanup_data_for_project(conn, team_name, encoded_name) + if stats["sessions_deleted"] or stats["dirs_deleted"]: + logger.info( + "Cleaned up %d sessions and %d dirs for %s/%s", + stats["sessions_deleted"], stats["dirs_deleted"], + team_name, encoded_name, + ) + except Exception as e: + logger.warning("Failed to clean up project data: %s", e) +``` + +- [ ] **Step 5: Run test to verify it passes** + +Run: `cd api && python -m pytest tests/test_sync_project_cleanup.py -v` +Expected: PASS + +- [ ] **Step 6: Run existing project tests** + +Run: `cd api && python -m pytest tests/test_sync_team_projects.py tests/test_sync_project_status.py -v` +Expected: All pass + +- [ ] **Step 7: Commit** + +```bash +cd api +git add db/sync_queries.py routers/sync_projects.py tests/test_sync_project_cleanup.py +git commit -m "fix(sync): clean up remote session data when removing a project + +sync_remove_team_project was removing Syncthing folders but leaving +remote session files on disk and DB rows. Now calls +cleanup_data_for_project to match remove_member's cleanup behavior." +``` + +--- + +### Task 0.6: Fix auto_accept Exception Handling + +When `add_device` fails in `auto_accept_pending_peers`, the `continue` skips `upsert_member` AND `auto_share_folders`. If the device was already configured by the introducer, this silently skips the member flow. + +**Files:** +- Modify: `api/services/sync_reconciliation.py:411-416` +- Test: `api/tests/test_sync_reconciliation_fix.py` (append) + +- [ ] **Step 1: Write the failing test** + +Append to `api/tests/test_sync_reconciliation_fix.py`: + +```python +@pytest.mark.asyncio +async def test_auto_accept_continues_after_add_device_failure(conn, mock_config): + """If add_device fails (device already configured), should still add member + share folders.""" + from db.sync_queries import create_team, list_members + + create_team(conn, "acme", backend="syncthing", join_code="acme:jayant:LEADER-DID") + + mock_proxy = AsyncMock() + # add_device raises (device already configured by introducer) + mock_proxy.add_device = MagicMock(side_effect=Exception("device already exists")) + mock_proxy.get_pending_devices = MagicMock(return_value={ + "AYUSH-DID": {"name": "ayush"}, + }) + mock_proxy.get_pending_folders = MagicMock(return_value={ + "karma-join--ayush--acme": {"offeredBy": {"AYUSH-DID": {}}}, + }) + mock_proxy.get_configured_folders = MagicMock(return_value=[]) + + with patch("services.sync_reconciliation.should_auto_accept_device", return_value=True): + with patch( + "services.sync_reconciliation.auto_share_folders", + new_callable=AsyncMock, + ) as mock_share: + from services.sync_reconciliation import auto_accept_pending_peers + accepted, remaining = await auto_accept_pending_peers(mock_proxy, mock_config, conn) + + # Member should have been added despite add_device failure + members = list_members(conn, "acme") + ayush_members = [m for m in members if m["name"] == "ayush"] + assert len(ayush_members) == 1, "ayush should be added to DB even if add_device fails" + + # auto_share_folders should have been called + mock_share.assert_called_once() +``` + +- [ ] **Step 2: Run test to verify it fails** + +Run: `cd api && python -m pytest tests/test_sync_reconciliation_fix.py::test_auto_accept_continues_after_add_device_failure -v` +Expected: FAIL — `ayush_members` is empty (skipped by `continue`) + +- [ ] **Step 3: Implement the fix** + +In `api/services/sync_reconciliation.py`, replace the `auto_accept_pending_peers` try/except block around `add_device` (lines 411-416): + +Replace: +```python + try: + await run_sync(proxy.add_device, device_id, username) + except Exception as e: + logger.warning("Auto-accept: failed to add device %s: %s", device_id[:20], e) + continue +``` + +With: +```python + try: + await run_sync(proxy.add_device, device_id, username) + except Exception as e: + logger.warning( + "Auto-accept: add_device failed for %s (may already exist via introducer): %s", + device_id[:20], e, + ) + # Don't skip — device may already be configured via introducer. + # Proceed with upsert_member and auto_share_folders. +``` + +- [ ] **Step 4: Run test to verify it passes** + +Run: `cd api && python -m pytest tests/test_sync_reconciliation_fix.py -v` +Expected: All pass + +- [ ] **Step 5: Run all sync tests** + +Run: `cd api && python -m pytest tests/test_sync_*.py -v` +Expected: All pass + +- [ ] **Step 6: Commit** + +```bash +cd api +git add services/sync_reconciliation.py tests/test_sync_reconciliation_fix.py +git commit -m "fix(sync): don't skip member flow when add_device fails in auto_accept + +If a device was already configured by the Syncthing introducer, +add_device raises. The old code skipped upsert_member and +auto_share_folders entirely. Now proceeds with DB + folder setup." +``` + +--- + +## Post-Phase Verification + +- [ ] **Run full sync test suite** + +```bash +cd api && python -m pytest tests/test_sync_*.py -v --tb=short +``` + +- [ ] **Run full API test suite for regressions** + +```bash +cd api && python -m pytest tests/ -v --tb=short +``` + +- [ ] **Lint** + +```bash +cd api && ruff check services/sync_reconciliation.py routers/sync_devices.py routers/sync_projects.py db/sync_queries.py +``` diff --git a/docs/superpowers/plans/2026-03-11-sync-v2-phase1-device-identity.md b/docs/superpowers/plans/2026-03-11-sync-v2-phase1-device-identity.md new file mode 100644 index 00000000..db5c4e0b --- /dev/null +++ b/docs/superpowers/plans/2026-03-11-sync-v2-phase1-device-identity.md @@ -0,0 +1,839 @@ +# Sync v2 Phase 1: Device = Member Identity + +> **For agentic workers:** REQUIRED: Use superpowers:subagent-driven-development (if subagents available) or superpowers:executing-plans to implement this plan. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Make each device a distinct member with its own folder IDs, fixing the session merge bug and duplicate pending offer confusion. + +**Architecture:** Introduce `member_tag` = `{user_id}.{machine_tag}` as the identity atom. All folder IDs, DB records, and reconciliation logic use `member_tag` instead of bare `user_id`. Machine tag is auto-derived from hostname, sanitized to `[a-z0-9-]+`. + +**Tech Stack:** Python, FastAPI, Pydantic 2.x, SQLite (migration v17), pytest + +**Prerequisite:** Phase 0 complete. + +--- + +## Chunk 1: Core Identity Model (T1.1–T1.3, Sequential) + +### Task 1.1: Add machine_tag and member_tag to SyncConfig + +**Files:** +- Modify: `cli/karma/config.py:30-60` (SyncConfig class) +- Test: `cli/tests/test_sync_config_identity.py` (create) + +- [ ] **Step 1: Write the failing test** + +```python +# cli/tests/test_sync_config_identity.py +"""Tests for machine_tag and member_tag derivation in SyncConfig.""" + +import pytest + + +def test_machine_tag_from_hostname(): + """machine_tag should be sanitized hostname: lowercase, alphanumeric + hyphens.""" + from karma.config import _sanitize_machine_tag + + assert _sanitize_machine_tag("Jayants-Mac-Mini") == "jayants-mac-mini" + assert _sanitize_machine_tag("MacBook Pro") == "macbook-pro" + assert _sanitize_machine_tag("DESKTOP_PC.local") == "desktop-pc-local" + assert _sanitize_machine_tag("my--weird---host") == "my-weird-host" # collapse multi-hyphens + assert _sanitize_machine_tag("") == "unknown" + + +def test_member_tag_computed(): + """member_tag should be user_id.machine_tag.""" + from karma.config import SyncConfig + + config = SyncConfig(user_id="jayant", machine_id="Jayants-Mac-Mini") + assert config.member_tag == "jayant.jayants-mac-mini" + + +def test_member_tag_with_custom_machine_tag(): + """If machine_tag is explicitly set, it overrides auto-derivation.""" + from karma.config import SyncConfig + + config = SyncConfig(user_id="jayant", machine_id="Jayants-Mac-Mini", machine_tag="mbp") + assert config.member_tag == "jayant.mbp" + + +def test_user_id_cannot_contain_dot(): + """user_id with dots should be rejected (dot is the member_tag separator).""" + from karma.config import SyncConfig + + with pytest.raises(ValueError, match="user_id"): + SyncConfig(user_id="jay.ant", machine_id="test") + + +def test_machine_tag_no_double_dash(): + """machine_tag must not contain -- (folder ID delimiter).""" + from karma.config import _sanitize_machine_tag + + result = _sanitize_machine_tag("my--host") + assert "--" not in result + + +def test_config_roundtrip_with_member_tag(tmp_path): + """Save and load preserves machine_tag and member_tag.""" + import json + + config_path = tmp_path / "sync-config.json" + data = { + "user_id": "jayant", + "machine_id": "Jayants-Mac-Mini", + "machine_tag": "mac-mini", + "syncthing": {"device_id": "ABC", "api_key": "key", "api_url": "http://localhost:8384"}, + } + config_path.write_text(json.dumps(data)) + + from karma.config import SyncConfig + config = SyncConfig(**json.loads(config_path.read_text())) + assert config.member_tag == "jayant.mac-mini" +``` + +- [ ] **Step 2: Run test to verify it fails** + +Run: `cd cli && python -m pytest tests/test_sync_config_identity.py -v` +Expected: FAIL — `ImportError: cannot import name '_sanitize_machine_tag'` + +- [ ] **Step 3: Implement SyncConfig changes** + +In `cli/karma/config.py`, add the sanitizer function and update `SyncConfig`: + +```python +import re + +def _sanitize_machine_tag(hostname: str) -> str: + """Derive a safe machine_tag from hostname. + + Rules: lowercase, alphanumeric + hyphens only, collapse multi-hyphens, + strip leading/trailing hyphens, no '--' (folder ID delimiter). + """ + if not hostname: + return "unknown" + tag = hostname.lower() + tag = re.sub(r"[^a-z0-9-]", "-", tag) # non-alphanum → hyphen + tag = re.sub(r"-{2,}", "-", tag) # collapse multi-hyphens + tag = tag.strip("-") + return tag or "unknown" +``` + +Update `SyncConfig`: + +```python +class SyncConfig(BaseModel): + """Identity and credentials. Teams/members/projects live in SQLite.""" + + model_config = ConfigDict(frozen=True) + + user_id: str = Field(..., description="User identity") + machine_id: str = Field( + default_factory=lambda: socket.gethostname(), + description="Machine hostname", + ) + machine_tag: str = Field( + default=None, + description="Sanitized machine identifier (auto-derived from machine_id if not set)", + ) + syncthing: SyncthingSettings = Field(default_factory=SyncthingSettings) + + @field_validator("user_id") + @classmethod + def validate_user_id(cls, v: str) -> str: + if not re.match(r"^[a-zA-Z0-9_-]+$", v): + raise ValueError("user_id must be alphanumeric, dash, or underscore (no dots)") + return v + + @model_validator(mode="after") + def _derive_machine_tag(self) -> "SyncConfig": + if self.machine_tag is None: + # Use object.__setattr__ because model is frozen + object.__setattr__(self, "machine_tag", _sanitize_machine_tag(self.machine_id)) + return self + + @property + def member_tag(self) -> str: + """Unique device identity: user_id.machine_tag""" + return f"{self.user_id}.{self.machine_tag}" +``` + +Note: `model_validator(mode="after")` runs after field validation, allowing us to auto-derive `machine_tag` from `machine_id` when not explicitly set. `object.__setattr__` is needed because the model is frozen. + +- [ ] **Step 4: Run test to verify it passes** + +Run: `cd cli && python -m pytest tests/test_sync_config_identity.py -v` +Expected: All pass + +- [ ] **Step 5: Run existing CLI tests** + +Run: `cd cli && python -m pytest tests/ -v` +Expected: All pass + +- [ ] **Step 6: Commit** + +```bash +git add cli/karma/config.py cli/tests/test_sync_config_identity.py +git commit -m "feat(sync): add machine_tag and member_tag to SyncConfig + +Each device now has a member_tag (user_id.machine_tag) that uniquely +identifies it. machine_tag is auto-derived from hostname (sanitized: +lowercase, alphanumeric + hyphens). user_id no longer allows dots +(dot is the member_tag separator)." +``` + +--- + +### Task 1.2: DB Migration v17 — Add Columns to sync_members + +**Files:** +- Modify: `api/db/schema.py` (SCHEMA_VERSION 16→17, migration, updated CREATE TABLE) +- Test: `api/tests/test_sync_migration_v17.py` (create) + +- [ ] **Step 1: Write the failing test** + +```python +# api/tests/test_sync_migration_v17.py +"""Tests for schema migration v17 — sync_members identity columns.""" + +import sqlite3 +import pytest +from db.schema import ensure_schema + + +@pytest.fixture +def conn(): + c = sqlite3.connect(":memory:") + c.row_factory = sqlite3.Row + c.execute("PRAGMA foreign_keys=ON") + ensure_schema(c) + return c + + +def test_sync_members_has_identity_columns(conn): + """sync_members should have machine_id, machine_tag, member_tag columns.""" + cursor = conn.execute("PRAGMA table_info(sync_members)") + columns = {row[1] for row in cursor.fetchall()} + assert "machine_id" in columns + assert "machine_tag" in columns + assert "member_tag" in columns + + +def test_sync_rejected_folders_table_exists(conn): + """sync_rejected_folders table should exist (for Phase 3, created here).""" + cursor = conn.execute("PRAGMA table_info(sync_rejected_folders)") + columns = {row[1] for row in cursor.fetchall()} + assert "folder_id" in columns + assert "team_name" in columns + assert "rejected_at" in columns +``` + +- [ ] **Step 2: Run test to verify it fails** + +Run: `cd api && python -m pytest tests/test_sync_migration_v17.py -v` +Expected: FAIL — columns not found + +- [ ] **Step 3: Implement the migration** + +In `api/db/schema.py`: + +1. Update `SCHEMA_VERSION = 17` + +2. Update the `sync_members` CREATE TABLE in SCHEMA_SQL: + +```sql +CREATE TABLE IF NOT EXISTS sync_members ( + team_name TEXT NOT NULL, + name TEXT NOT NULL, + device_id TEXT NOT NULL, + machine_id TEXT, + machine_tag TEXT, + member_tag TEXT, + added_at TEXT DEFAULT (datetime('now')), + PRIMARY KEY (team_name, device_id), + FOREIGN KEY (team_name) REFERENCES sync_teams(name) ON DELETE CASCADE +); + +CREATE INDEX IF NOT EXISTS idx_sync_members_name ON sync_members(team_name, name); +CREATE INDEX IF NOT EXISTS idx_sync_members_tag ON sync_members(member_tag); +``` + +3. Add the `sync_rejected_folders` table to SCHEMA_SQL: + +```sql +CREATE TABLE IF NOT EXISTS sync_rejected_folders ( + folder_id TEXT PRIMARY KEY, + team_name TEXT, + rejected_at TEXT DEFAULT (datetime('now')) +); +``` + +4. Add migration in `ensure_schema`: + +```python +if version < 17: + conn.executescript(""" + ALTER TABLE sync_members ADD COLUMN machine_id TEXT; + ALTER TABLE sync_members ADD COLUMN machine_tag TEXT; + ALTER TABLE sync_members ADD COLUMN member_tag TEXT; + CREATE INDEX IF NOT EXISTS idx_sync_members_tag ON sync_members(member_tag); + CREATE TABLE IF NOT EXISTS sync_rejected_folders ( + folder_id TEXT PRIMARY KEY, + team_name TEXT, + rejected_at TEXT DEFAULT (datetime('now')) + ); + """) + conn.execute("UPDATE schema_version SET version = 17") + conn.commit() +``` + +- [ ] **Step 4: Run test to verify it passes** + +Run: `cd api && python -m pytest tests/test_sync_migration_v17.py -v` +Expected: PASS + +- [ ] **Step 5: Run all schema-dependent tests** + +Run: `cd api && python -m pytest tests/test_sync_*.py -v` +Expected: All pass (new columns are nullable, existing code unaffected) + +- [ ] **Step 6: Commit** + +```bash +cd api +git add db/schema.py tests/test_sync_migration_v17.py +git commit -m "feat(sync): schema v17 — add device identity columns to sync_members + +Adds machine_id, machine_tag, member_tag columns to sync_members. +Creates sync_rejected_folders table for persistent folder rejection. +All new columns are nullable for backward compatibility during migration." +``` + +--- + +### Task 1.3: Update folder_id.py for member_tag Format + +**Files:** +- Modify: `api/services/folder_id.py` +- Test: `api/tests/test_folder_id_v2.py` (create) + +- [ ] **Step 1: Write the failing test** + +```python +# api/tests/test_folder_id_v2.py +"""Tests for folder_id.py v2 — member_tag in folder IDs.""" + +import pytest +from services.folder_id import ( + build_outbox_id, + build_handshake_id, + parse_outbox_id, + parse_handshake_id, + parse_member_tag, +) + + +class TestBuildWithMemberTag: + def test_outbox_with_member_tag(self): + fid = build_outbox_id("jayant.mac-mini", "jayantdevkar-claude-karma") + assert fid == "karma-out--jayant.mac-mini--jayantdevkar-claude-karma" + + def test_handshake_with_member_tag(self): + fid = build_handshake_id("jayant.mac-mini", "acme") + assert fid == "karma-join--jayant.mac-mini--acme" + + def test_two_devices_produce_different_outbox_ids(self): + fid1 = build_outbox_id("jayant.mac-mini", "proj") + fid2 = build_outbox_id("jayant.mbp", "proj") + assert fid1 != fid2 + + +class TestParseWithMemberTag: + def test_parse_outbox_returns_member_tag(self): + result = parse_outbox_id("karma-out--jayant.mac-mini--proj-suffix") + assert result == ("jayant.mac-mini", "proj-suffix") + + def test_parse_handshake_returns_member_tag(self): + result = parse_handshake_id("karma-join--ayush.ayush-mac--acme") + assert result == ("ayush.ayush-mac", "acme") + + +class TestParseMemberTag: + def test_parse_valid_member_tag(self): + user_id, machine_tag = parse_member_tag("jayant.mac-mini") + assert user_id == "jayant" + assert machine_tag == "mac-mini" + + def test_parse_no_dot_returns_bare_name(self): + """Legacy format without machine_tag — treat as user_id only.""" + user_id, machine_tag = parse_member_tag("jayant") + assert user_id == "jayant" + assert machine_tag is None + + def test_parse_multiple_dots_splits_on_first(self): + user_id, machine_tag = parse_member_tag("jayant.mac.mini") + assert user_id == "jayant" + assert machine_tag == "mac.mini" +``` + +- [ ] **Step 2: Run test to verify it fails** + +Run: `cd api && python -m pytest tests/test_folder_id_v2.py -v` +Expected: FAIL — `ImportError: cannot import name 'parse_member_tag'` + +- [ ] **Step 3: Implement** + +Add `parse_member_tag` to `api/services/folder_id.py`: + +```python +def parse_member_tag(member_tag: str) -> tuple[str, str | None]: + """Parse member_tag into (user_id, machine_tag). + + Format: ``{user_id}.{machine_tag}`` or bare ``{user_id}`` (legacy). + Splits on the FIRST dot only. + + Returns: + (user_id, machine_tag) — machine_tag is None if no dot present. + """ + if "." in member_tag: + user_id, machine_tag = member_tag.split(".", 1) + return user_id, machine_tag + return member_tag, None +``` + +The existing `build_outbox_id`, `parse_outbox_id`, etc. already work with member_tag because they treat the first component as an opaque string. The `.` in `jayant.mac-mini` doesn't interfere with `--` delimiter parsing. + +Verify: `build_outbox_id("jayant.mac-mini", "suffix")` → `"karma-out--jayant.mac-mini--suffix"`. The `_validate_no_double_dash` check passes because `.` is not `--`. The existing code already works. + +- [ ] **Step 4: Run test to verify it passes** + +Run: `cd api && python -m pytest tests/test_folder_id_v2.py -v` +Expected: PASS + +- [ ] **Step 5: Run existing folder_id tests** + +Run: `cd api && python -m pytest tests/ -k "folder" -v` +Expected: All pass + +- [ ] **Step 6: Commit** + +```bash +cd api +git add services/folder_id.py tests/test_folder_id_v2.py +git commit -m "feat(sync): add parse_member_tag to folder_id.py + +Parses 'user_id.machine_tag' format used in folder IDs. +Existing build/parse functions already handle dots in the +username component — no changes needed." +``` + +--- + +## Chunk 2: Folder & Reconciliation Updates (T1.4–T1.6, Parallel after T1.3) + +### Task 1.4: Update sync_folders.py to Use member_tag + +**Files:** +- Modify: `api/services/sync_folders.py:32-92` (outbox, inbox, handshake) +- Modify: `api/services/sync_folders.py:205-242` (auto_share_folders) +- Modify: `api/services/sync_folders.py:245-368` (cleanup functions) +- Test: `api/tests/test_sync_folders_member_tag.py` (create) + +- [ ] **Step 1: Write the failing test** + +```python +# api/tests/test_sync_folders_member_tag.py +"""Tests for sync_folders.py using member_tag in folder IDs.""" + +from unittest.mock import AsyncMock, MagicMock +import pytest + + +@pytest.fixture +def mock_config(): + config = MagicMock() + config.user_id = "jayant" + config.machine_tag = "mac-mini" + config.member_tag = "jayant.mac-mini" + config.syncthing.device_id = "LEADER-DID" + return config + + +@pytest.mark.asyncio +async def test_ensure_outbox_uses_member_tag(mock_config): + """Outbox folder ID should use member_tag, not user_id.""" + mock_proxy = AsyncMock() + mock_proxy.update_folder_devices = MagicMock(side_effect=ValueError("not found")) + mock_proxy.add_folder = AsyncMock() + + with pytest.MonkeyPatch.context() as mp: + mp.setattr("services.sync_folders.KARMA_BASE", MagicMock(__truediv__=lambda s, x: MagicMock(__truediv__=lambda s, x: MagicMock(__truediv__=lambda s, x: MagicMock(mkdir=MagicMock()), __str__=lambda s: "/tmp/test"), __str__=lambda s: "/tmp"), __str__=lambda s: "/tmp")) + from services.sync_folders import ensure_outbox_folder + # This should use config.member_tag in the folder ID + # We'll verify via the proxy.add_folder call + + # The folder ID passed to add_folder should contain member_tag + # Exact assertion depends on implementation — key point is member_tag not user_id +``` + +NOTE: Due to the complexity of mocking filesystem paths, this task is better tested via integration test. Instead, write a unit test for the folder ID computation: + +```python +# api/tests/test_sync_folders_member_tag.py +"""Tests that sync_folders uses member_tag in folder IDs.""" + +from services.folder_id import build_outbox_id + + +def test_outbox_id_uses_member_tag(): + """Outbox folder IDs must use member_tag to avoid same-user collision.""" + mini = build_outbox_id("jayant.mac-mini", "jayantdevkar-claude-karma") + mbp = build_outbox_id("jayant.mbp", "jayantdevkar-claude-karma") + assert mini != mbp + assert "jayant.mac-mini" in mini + assert "jayant.mbp" in mbp + + +def test_inbox_id_for_member_uses_member_tag(): + """Inbox folder ID for a member should use their member_tag.""" + inbox = build_outbox_id("ayush.ayush-mac", "jayantdevkar-claude-karma") + assert "ayush.ayush-mac" in inbox +``` + +- [ ] **Step 2: Implement sync_folders.py changes** + +All changes use `config.member_tag` instead of `config.user_id` and `m["member_tag"]` instead of `m["name"]` for folder ID construction: + +**`ensure_outbox_folder` (line 39)**: +```python +# OLD: outbox_id = build_outbox_id(config.user_id, proj_suffix) +# NEW: +outbox_id = build_outbox_id(config.member_tag, proj_suffix) +``` + +Also update the path (line 40): +```python +# OLD: outbox_path = str(KARMA_BASE / "remote-sessions" / config.user_id / encoded) +# NEW: +outbox_path = str(KARMA_BASE / "remote-sessions" / config.member_tag / encoded) +``` + +**`ensure_inbox_folders` (lines 75-76)**: +```python +# OLD: inbox_path = str(KARMA_BASE / "remote-sessions" / m["name"] / encoded) +# inbox_id = build_outbox_id(m['name'], proj_suffix) +# NEW: +member_tag = m.get("member_tag") or m["name"] # fallback for legacy members +inbox_path = str(KARMA_BASE / "remote-sessions" / member_tag / encoded) +inbox_id = build_outbox_id(member_tag, proj_suffix) +``` + +**`ensure_handshake_folder` (line 99)**: +```python +# OLD: folder_id = build_handshake_id(config.user_id, team_name) +# NEW: +folder_id = build_handshake_id(config.member_tag, team_name) +``` + +**`cleanup_syncthing_for_team` (line 265)**: +```python +# OLD: member_names = {m["name"] for m in members} +# NEW: +member_tags = {m.get("member_tag") or m["name"] for m in members} +if config and config.member_tag: + member_tags.add(config.member_tag) +``` +Update line 275 to use `member_tags` instead of `member_names`. + +**`cleanup_syncthing_for_member` (line 343)**: +```python +# OLD: elif username == member_name: +# NEW: use member_tag for matching +member_tag = member_tag_param # passed as parameter +``` +Update signature to accept `member_tag` instead of `member_name`. + +**`extract_username_from_folder_ids`**: Now returns member_tag (already works since the folder ID username component IS the member_tag in v2). + +- [ ] **Step 3: Run tests** + +Run: `cd api && python -m pytest tests/test_sync_folders_member_tag.py tests/test_sync_*.py -v` + +- [ ] **Step 4: Commit** + +```bash +cd api +git add services/sync_folders.py tests/test_sync_folders_member_tag.py +git commit -m "feat(sync): use member_tag in all folder ID operations + +ensure_outbox_folder, ensure_inbox_folders, ensure_handshake_folder, +and cleanup functions now use config.member_tag instead of +config.user_id. Fixes same-user multi-device folder ID collision." +``` + +--- + +### Task 1.5: Update sync_reconciliation.py for member_tag + +**Files:** +- Modify: `api/services/sync_reconciliation.py` +- Test: Update existing reconciliation tests + +- [ ] **Step 1: Update reconcile_introduced_devices** + +The function extracts usernames from folder IDs. With v2 folder IDs, the extracted value is now a `member_tag` (e.g., `ayush.ayush-mac`). Update the variable names and DB writes to use `member_tag`: + +```python +# Line 140-141: name extraction already returns the folder ID's username component +# which IS the member_tag in v2. Rename variable for clarity: +# OLD: name = syncthing_device_name or candidate_name +# memberships.append((name, tname)) +# NEW: +member_tag = syncthing_device_name or candidate_name +memberships.append((member_tag, tname)) +``` + +In the upsert call (line 151): +```python +# Extract user_id from member_tag for the name field +from services.folder_id import parse_member_tag +user_id, machine_tag = parse_member_tag(username) +upsert_member(conn, team_name, user_id, device_id=device_id, + machine_tag=machine_tag, member_tag=username) +``` + +- [ ] **Step 2: Update upsert_member in sync_queries.py to accept new columns** + +```python +def upsert_member( + conn, team_name, name, *, device_id, + machine_id=None, machine_tag=None, member_tag=None, +): + conn.execute( + """INSERT INTO sync_members (team_name, name, device_id, machine_id, machine_tag, member_tag) + VALUES (?, ?, ?, ?, ?, ?) + ON CONFLICT (team_name, device_id) DO UPDATE SET + name = excluded.name, + machine_id = COALESCE(excluded.machine_id, machine_id), + machine_tag = COALESCE(excluded.machine_tag, machine_tag), + member_tag = COALESCE(excluded.member_tag, member_tag)""", + (team_name, name, device_id, machine_id, machine_tag, member_tag), + ) + conn.commit() +``` + +- [ ] **Step 3: Run tests** + +Run: `cd api && python -m pytest tests/test_sync_*.py -v` + +- [ ] **Step 4: Commit** + +```bash +cd api +git add services/sync_reconciliation.py db/sync_queries.py +git commit -m "feat(sync): reconciliation uses member_tag for identity + +upsert_member now accepts machine_id, machine_tag, member_tag columns. +reconcile_introduced_devices extracts member_tag from folder IDs." +``` + +--- + +### Task 1.6: Update cli/karma/pending.py for member_tag + +**Files:** +- Modify: `cli/karma/pending.py:259-281` (pre-scan) +- Modify: `cli/karma/pending.py:300-390` (folder handling) + +- [ ] **Step 1: Update pre-scan to extract member_tag** + +The pre-scan parses handshake folders (`karma-join--{member_tag}--{team}`) to get real identities. With v2, the extracted value is a full member_tag: + +```python +# In pre-scan loop (line 266): +# OLD: candidate_user, _team = parsed_hs +# NEW: +candidate_member_tag, _team = parsed_hs +from services.folder_id import parse_member_tag +candidate_user, candidate_machine_tag = parse_member_tag(candidate_member_tag) +``` + +Update the healing logic to also set machine_tag and member_tag: + +```python +upsert_member(conn, db_team, candidate_user, device_id=dev_id, + machine_tag=candidate_machine_tag, + member_tag=candidate_member_tag) +``` + +- [ ] **Step 2: Update own outbox handling** + +```python +# _handle_own_outbox: use config.member_tag for path construction +outbox_path = str(KARMA_BASE / "remote-sessions" / config.member_tag / encoded) +``` + +- [ ] **Step 3: Update peer outbox handling** + +```python +# _handle_peer_outbox: use parsed member_tag from folder ID +parsed = parse_outbox_id(folder_id) +if parsed: + peer_member_tag, suffix = parsed + inbox_path = str(KARMA_BASE / "remote-sessions" / peer_member_tag / encoded) +``` + +- [ ] **Step 4: Run tests** + +Run: `cd cli && python -m pytest tests/ -v` + +- [ ] **Step 5: Commit** + +```bash +git add cli/karma/pending.py +git commit -m "feat(sync): pending.py uses member_tag for folder handling + +Pre-scan extracts member_tag from handshake folders and heals DB. +Own outbox and peer outbox handlers use member_tag for paths." +``` + +--- + +## Chunk 3: Router & Peripheral Updates (T1.7–T1.9, Parallel) + +### Task 1.7: Update Routers for member_tag + +**Files:** +- Modify: `api/routers/sync_devices.py` (accept handler populates member_tag) +- Modify: `api/routers/sync_teams.py` (join handler populates member_tag) +- Modify: `api/routers/sync_members.py` (list/remove uses member_tag) +- Modify: `api/routers/sync_projects.py` (share uses member_tag) +- Modify: `api/routers/sync_pending.py` (display uses member_tag) + +Key changes: + +**sync_devices.py — accept handler**: After extracting member_name, compute member_tag: +```python +from services.folder_id import parse_member_tag +# If name came from handshake folder, it's already a member_tag +user_id, machine_tag_part = parse_member_tag(member_name) +if machine_tag_part is None: + # Legacy: bare username. Try to get machine info from pending device + machine_tag_part = _sanitize_device_name(device_info.get("name", "")) +member_tag = f"{user_id}.{machine_tag_part}" if machine_tag_part else user_id +``` + +**sync_teams.py — join handler**: When creating self-member: +```python +upsert_member(conn, team_name, config.user_id, device_id=own_did, + machine_id=config.machine_id, machine_tag=config.machine_tag, + member_tag=config.member_tag) +``` + +**sync_pending.py — display**: Use member_tag for richer descriptions: +```python +# In enrichment loop, replace member display: +from services.folder_id import parse_member_tag +user_id, machine_tag = parse_member_tag(owner) +if machine_tag: + member_display = f"{user_id} ({machine_tag})" +else: + member_display = user_id +item["description"] = f"Receive sessions from {member_display} for {label}" +``` + +- [ ] **Step 1–5: Implement, test, commit** + +```bash +git add api/routers/sync_devices.py api/routers/sync_teams.py \ + api/routers/sync_members.py api/routers/sync_projects.py \ + api/routers/sync_pending.py +git commit -m "feat(sync): routers populate and display member_tag + +Accept, join, share, and pending endpoints now compute and store +member_tag. Pending UI shows device-specific descriptions like +'jayant (mac-mini)' instead of bare 'jayant'." +``` + +--- + +### Task 1.8: Update remote_sessions.py for member_tag + +**Files:** +- Modify: `api/services/remote_sessions.py` + +The remote session discovery scans `~/.claude_karma/remote-sessions/{member}/`. With member_tag, directory names become `jayant.mac-mini` instead of `jayant`. + +Key change: user_id resolution should parse the directory name as member_tag: +```python +from services.folder_id import parse_member_tag + +# When scanning remote-sessions directories: +for member_dir in remote_base.iterdir(): + member_tag = member_dir.name + user_id, machine_tag = parse_member_tag(member_tag) + # Use user_id for display, member_tag for path resolution +``` + +- [ ] **Step 1–3: Implement, test, commit** + +```bash +git add api/services/remote_sessions.py +git commit -m "feat(sync): remote_sessions.py parses member_tag directories" +``` + +--- + +### Task 1.9: Update packager.py for member_tag + +**Files:** +- Modify: `cli/karma/packager.py` + +The packager writes sessions to `~/.claude_karma/remote-sessions/{user_id}/{encoded}/`. With member_tag, this becomes `{member_tag}/{encoded}/`. + +Key change in `package()`: +```python +# OLD: outbox_dir = KARMA_BASE / "remote-sessions" / config.user_id / encoded +# NEW: +outbox_dir = KARMA_BASE / "remote-sessions" / config.member_tag / encoded +``` + +Also update `manifest.json` to include member_tag: +```python +manifest = { + "user_id": config.user_id, + "machine_id": config.machine_id, + "member_tag": config.member_tag, + # ... existing fields +} +``` + +- [ ] **Step 1–3: Implement, test, commit** + +```bash +git add cli/karma/packager.py +git commit -m "feat(sync): packager uses member_tag for outbox directory and manifest" +``` + +--- + +## Post-Phase Verification + +- [ ] **Verify two devices with same user_id produce distinct folder IDs** + +```python +from services.folder_id import build_outbox_id +assert build_outbox_id("jayant.mac-mini", "proj") != build_outbox_id("jayant.mbp", "proj") +``` + +- [ ] **Run full test suite** + +```bash +cd api && python -m pytest tests/ -v --tb=short +cd cli && python -m pytest tests/ -v --tb=short +``` + +- [ ] **Lint** + +```bash +cd api && ruff check services/ routers/ db/ +cd cli && ruff check karma/ +``` diff --git a/docs/superpowers/plans/2026-03-11-sync-v2-phase2-metadata-folder.md b/docs/superpowers/plans/2026-03-11-sync-v2-phase2-metadata-folder.md new file mode 100644 index 00000000..04047668 --- /dev/null +++ b/docs/superpowers/plans/2026-03-11-sync-v2-phase2-metadata-folder.md @@ -0,0 +1,1000 @@ +# Sync v2 Phase 2: Team Metadata Folder (State Convergence) + +> **For agentic workers:** REQUIRED: Use superpowers:subagent-driven-development (if subagents available) or superpowers:executing-plans to implement this plan. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Add a `karma-meta--{team}` Syncthing folder that all members share, enabling membership state convergence, removal notifications, and subscription visibility — without a central server. + +**Architecture:** Each member writes their own JSON state file. Removal signals are written by the team creator. Reconciliation reads all files and updates local DB. Syncthing `sendreceive` type means any member can write (no conflicts since each writes only their own file). + +**Tech Stack:** Python, FastAPI, SQLite, Syncthing REST API, pytest + +**Prerequisite:** Phase 1 complete. + +--- + +## Chunk 1: Metadata File Format & Helpers (T2.1–T2.2) + +### Task 2.1: Metadata File Format and Helper Module + +**Files:** +- Create: `api/services/sync_metadata.py` +- Test: `api/tests/test_sync_metadata.py` (create) + +- [ ] **Step 1: Write the failing test** + +```python +# api/tests/test_sync_metadata.py +"""Tests for team metadata folder helpers.""" + +import json +from pathlib import Path +import pytest + + +def test_write_member_state(tmp_path): + """Writing member state creates the correct JSON file.""" + from services.sync_metadata import write_member_state + + meta_dir = tmp_path / "karma-meta--acme" + meta_dir.mkdir() + + write_member_state( + meta_dir, + member_tag="jayant.mac-mini", + user_id="jayant", + machine_id="Jayants-Mac-Mini", + device_id="LEADER-DID", + subscriptions={"jayantdevkar-claude-karma": True}, + sync_direction="both", + session_limit="all", + ) + + state_file = meta_dir / "members" / "jayant.mac-mini.json" + assert state_file.exists() + + data = json.loads(state_file.read_text()) + assert data["member_tag"] == "jayant.mac-mini" + assert data["user_id"] == "jayant" + assert data["device_id"] == "LEADER-DID" + assert data["subscriptions"]["jayantdevkar-claude-karma"] is True + assert "updated_at" in data + + +def test_write_removal_signal(tmp_path): + """Writing a removal signal creates the correct JSON file.""" + from services.sync_metadata import write_removal_signal + + meta_dir = tmp_path / "karma-meta--acme" + meta_dir.mkdir() + + write_removal_signal( + meta_dir, + removed_member_tag="ayush.ayush-mac", + removed_device_id="AYUSH-DID", + removed_by="jayant.mac-mini", + ) + + removal_file = meta_dir / "removals" / "ayush.ayush-mac.json" + assert removal_file.exists() + + data = json.loads(removal_file.read_text()) + assert data["member_tag"] == "ayush.ayush-mac" + assert data["removed_by"] == "jayant.mac-mini" + assert "removed_at" in data + + +def test_write_team_info(tmp_path): + """Writing team info creates team.json.""" + from services.sync_metadata import write_team_info + + meta_dir = tmp_path / "karma-meta--acme" + meta_dir.mkdir() + + write_team_info(meta_dir, team_name="acme", created_by="jayant.mac-mini") + + team_file = meta_dir / "team.json" + assert team_file.exists() + + data = json.loads(team_file.read_text()) + assert data["name"] == "acme" + assert data["created_by"] == "jayant.mac-mini" + + +def test_read_all_member_states(tmp_path): + """Reading member states discovers all member files.""" + from services.sync_metadata import write_member_state, read_all_member_states + + meta_dir = tmp_path / "karma-meta--acme" + meta_dir.mkdir() + + write_member_state(meta_dir, member_tag="jayant.mac-mini", user_id="jayant", + machine_id="Mini", device_id="DID1") + write_member_state(meta_dir, member_tag="ayush.ayush-mac", user_id="ayush", + machine_id="Mac", device_id="DID2") + + states = read_all_member_states(meta_dir) + assert len(states) == 2 + tags = {s["member_tag"] for s in states} + assert tags == {"jayant.mac-mini", "ayush.ayush-mac"} + + +def test_read_removal_signals(tmp_path): + """Reading removal signals discovers all removal files.""" + from services.sync_metadata import write_removal_signal, read_removal_signals + + meta_dir = tmp_path / "karma-meta--acme" + meta_dir.mkdir() + + write_removal_signal(meta_dir, removed_member_tag="ayush.ayush-mac", + removed_device_id="DID2", removed_by="jayant.mac-mini") + + removals = read_removal_signals(meta_dir) + assert len(removals) == 1 + assert removals[0]["member_tag"] == "ayush.ayush-mac" + + +def test_read_team_info(tmp_path): + """Reading team info returns creator.""" + from services.sync_metadata import write_team_info, read_team_info + + meta_dir = tmp_path / "karma-meta--acme" + meta_dir.mkdir() + write_team_info(meta_dir, team_name="acme", created_by="jayant.mac-mini") + + info = read_team_info(meta_dir) + assert info["created_by"] == "jayant.mac-mini" + + +def test_is_removed(tmp_path): + """Check if a specific member_tag has a removal signal.""" + from services.sync_metadata import write_removal_signal, is_removed + + meta_dir = tmp_path / "karma-meta--acme" + meta_dir.mkdir() + + assert is_removed(meta_dir, "ayush.ayush-mac") is False + + write_removal_signal(meta_dir, removed_member_tag="ayush.ayush-mac", + removed_device_id="DID", removed_by="jayant.mac-mini") + + assert is_removed(meta_dir, "ayush.ayush-mac") is True + + +def test_validate_removal_authority(tmp_path): + """Only the team creator can remove members.""" + from services.sync_metadata import write_team_info, validate_removal_authority + + meta_dir = tmp_path / "karma-meta--acme" + meta_dir.mkdir() + write_team_info(meta_dir, team_name="acme", created_by="jayant.mac-mini") + + assert validate_removal_authority(meta_dir, "jayant.mac-mini") is True + assert validate_removal_authority(meta_dir, "ayush.ayush-mac") is False +``` + +- [ ] **Step 2: Run test to verify it fails** + +Run: `cd api && python -m pytest tests/test_sync_metadata.py -v` +Expected: FAIL — `ModuleNotFoundError: No module named 'services.sync_metadata'` + +- [ ] **Step 3: Implement sync_metadata.py** + +```python +# api/services/sync_metadata.py +"""Team metadata folder helpers. + +Each team has a `karma-meta--{team}` Syncthing folder (sendreceive) containing: + members/{member_tag}.json — each device writes its own state + removals/{member_tag}.json — removal signals (creator-only authority) + team.json — team-level info (name, creator) +""" + +import json +import logging +from datetime import datetime, timezone +from pathlib import Path +from typing import Optional + +logger = logging.getLogger(__name__) + +METADATA_PREFIX = "karma-meta--" + + +def build_metadata_folder_id(team_name: str) -> str: + """Build ``karma-meta--{team_name}``.""" + if "--" in team_name: + raise ValueError(f"team_name must not contain '--': {team_name!r}") + return f"{METADATA_PREFIX}{team_name}" + + +def parse_metadata_folder_id(folder_id: str) -> Optional[str]: + """Parse ``karma-meta--{team_name}`` into team_name. Returns None if not metadata.""" + if not folder_id.startswith(METADATA_PREFIX): + return None + return folder_id[len(METADATA_PREFIX):] + + +def is_metadata_folder(folder_id: str) -> bool: + return folder_id.startswith(METADATA_PREFIX) + + +def _now_iso() -> str: + return datetime.now(timezone.utc).isoformat() + + +def write_member_state( + meta_dir: Path, + *, + member_tag: str, + user_id: str, + machine_id: str = "", + device_id: str = "", + subscriptions: dict[str, bool] | None = None, + sync_direction: str = "both", + session_limit: str = "all", +) -> Path: + """Write this device's state file to the metadata folder.""" + members_dir = meta_dir / "members" + members_dir.mkdir(parents=True, exist_ok=True) + + state = { + "member_tag": member_tag, + "user_id": user_id, + "machine_id": machine_id, + "device_id": device_id, + "subscriptions": subscriptions or {}, + "sync_direction": sync_direction, + "session_limit": session_limit, + "updated_at": _now_iso(), + } + + path = members_dir / f"{member_tag}.json" + path.write_text(json.dumps(state, indent=2)) + return path + + +def write_removal_signal( + meta_dir: Path, + *, + removed_member_tag: str, + removed_device_id: str, + removed_by: str, +) -> Path: + """Write a removal signal for a member.""" + removals_dir = meta_dir / "removals" + removals_dir.mkdir(parents=True, exist_ok=True) + + signal = { + "member_tag": removed_member_tag, + "device_id": removed_device_id, + "removed_by": removed_by, + "removed_at": _now_iso(), + } + + path = removals_dir / f"{removed_member_tag}.json" + path.write_text(json.dumps(signal, indent=2)) + return path + + +def write_team_info(meta_dir: Path, *, team_name: str, created_by: str) -> Path: + """Write team-level info (created once, rarely updated).""" + info = { + "name": team_name, + "created_by": created_by, + "created_at": _now_iso(), + } + + path = meta_dir / "team.json" + path.write_text(json.dumps(info, indent=2)) + return path + + +def read_all_member_states(meta_dir: Path) -> list[dict]: + """Read all member state files from the metadata folder.""" + members_dir = meta_dir / "members" + if not members_dir.exists(): + return [] + + states = [] + for path in members_dir.glob("*.json"): + try: + states.append(json.loads(path.read_text())) + except (json.JSONDecodeError, OSError) as e: + logger.warning("Failed to read member state %s: %s", path, e) + return states + + +def read_removal_signals(meta_dir: Path) -> list[dict]: + """Read all removal signal files.""" + removals_dir = meta_dir / "removals" + if not removals_dir.exists(): + return [] + + signals = [] + for path in removals_dir.glob("*.json"): + try: + signals.append(json.loads(path.read_text())) + except (json.JSONDecodeError, OSError) as e: + logger.warning("Failed to read removal signal %s: %s", path, e) + return signals + + +def read_team_info(meta_dir: Path) -> Optional[dict]: + """Read team.json. Returns None if not found.""" + path = meta_dir / "team.json" + if not path.exists(): + return None + try: + return json.loads(path.read_text()) + except (json.JSONDecodeError, OSError): + return None + + +def is_removed(meta_dir: Path, member_tag: str) -> bool: + """Check if a member_tag has a removal signal.""" + path = meta_dir / "removals" / f"{member_tag}.json" + return path.exists() + + +def validate_removal_authority(meta_dir: Path, remover_member_tag: str) -> bool: + """Check if the remover is the team creator (creator-only removal).""" + info = read_team_info(meta_dir) + if info is None: + return False + return info.get("created_by") == remover_member_tag +``` + +- [ ] **Step 4: Run test to verify it passes** + +Run: `cd api && python -m pytest tests/test_sync_metadata.py -v` +Expected: All pass + +- [ ] **Step 5: Commit** + +```bash +cd api +git add services/sync_metadata.py tests/test_sync_metadata.py +git commit -m "feat(sync): add sync_metadata.py for team metadata folder helpers + +Provides read/write helpers for the karma-meta--{team} folder: +member state files, removal signals, team info. Creator-only +removal authority enforced via team.json.created_by check." +``` + +--- + +### Task 2.2: Create Metadata Folder on Team Create/Join + +**Files:** +- Modify: `api/services/sync_folders.py` (add `ensure_metadata_folder`) +- Modify: `api/routers/sync_teams.py` (call in create + join) +- Modify: `api/services/folder_id.py` (add metadata folder predicates — already done in T2.1) +- Test: `api/tests/test_sync_metadata_creation.py` (create) + +- [ ] **Step 1: Write the failing test** + +```python +# api/tests/test_sync_metadata_creation.py +"""Tests for metadata folder creation during team create/join.""" + +from unittest.mock import AsyncMock, MagicMock +import pytest + + +@pytest.fixture +def mock_config(): + config = MagicMock() + config.user_id = "jayant" + config.machine_id = "Mac-Mini" + config.machine_tag = "mac-mini" + config.member_tag = "jayant.mac-mini" + config.syncthing.device_id = "LEADER-DID" + return config + + +@pytest.mark.asyncio +async def test_ensure_metadata_folder_creates_sendreceive(mock_config): + """Metadata folder should be created as sendreceive type.""" + mock_proxy = AsyncMock() + mock_proxy.update_folder_devices = MagicMock(side_effect=ValueError("not found")) + mock_proxy.add_folder = AsyncMock() + + from services.sync_folders import ensure_metadata_folder + + await ensure_metadata_folder( + mock_proxy, mock_config, "acme", ["LEADER-DID", "AYUSH-DID"] + ) + + # Verify add_folder was called with sendreceive type + mock_proxy.add_folder.assert_called_once() + call_args = mock_proxy.add_folder.call_args + assert call_args[0][0] == "karma-meta--acme" # folder_id + assert call_args[0][3] == "sendreceive" # folder_type +``` + +- [ ] **Step 2: Run test to verify it fails** + +Run: `cd api && python -m pytest tests/test_sync_metadata_creation.py -v` +Expected: FAIL — `ImportError: cannot import name 'ensure_metadata_folder'` + +- [ ] **Step 3: Implement ensure_metadata_folder** + +Add to `api/services/sync_folders.py`: + +```python +from services.sync_metadata import build_metadata_folder_id, write_team_info, write_member_state + +async def ensure_metadata_folder( + proxy, config, team_name: str, device_ids: list[str], + *, is_creator: bool = False, +) -> None: + """Create or update the team metadata folder (sendreceive, shared by all members). + + Also writes the local member's state file and team.json (if creator). + """ + from karma.config import KARMA_BASE + + folder_id = build_metadata_folder_id(team_name) + meta_path = KARMA_BASE / "metadata-folders" / team_name + meta_path.mkdir(parents=True, exist_ok=True) + + try: + await run_sync(proxy.update_folder_devices, folder_id, device_ids) + except ValueError: + all_ids = list(device_ids) + if config.syncthing.device_id and config.syncthing.device_id not in all_ids: + all_ids.append(config.syncthing.device_id) + await run_sync(proxy.add_folder, folder_id, str(meta_path), all_ids, "sendreceive") + + # Write team.json if we're the creator + if is_creator: + write_team_info(meta_path, team_name=team_name, created_by=config.member_tag) + + # Write own member state + write_member_state( + meta_path, + member_tag=config.member_tag, + user_id=config.user_id, + machine_id=config.machine_id, + device_id=config.syncthing.device_id or "", + ) +``` + +- [ ] **Step 4: Wire into team create and join endpoints** + +In `api/routers/sync_teams.py`, in `sync_create_team` (after creating team + adding self): +```python +# Create metadata folder (sendreceive, shared with future members) +await ensure_metadata_folder(proxy, config, team_name, [own_did], is_creator=True) +``` + +In `sync_join_team` (after creating team + adding members): +```python +# Create/join metadata folder +leader_did = parts[-1] # from join code parsing +await ensure_metadata_folder(proxy, config, team_name, [own_did, leader_did]) +``` + +In `auto_share_folders` in `sync_folders.py`, also add the new device to the metadata folder: +```python +# Add new device to metadata folder +try: + meta_folder_id = build_metadata_folder_id(team_name) + await run_sync(proxy.update_folder_devices, meta_folder_id, all_device_ids) +except Exception as e: + logger.debug("Failed to update metadata folder devices: %s", e) +``` + +- [ ] **Step 5: Run tests** + +Run: `cd api && python -m pytest tests/test_sync_metadata_creation.py tests/test_sync_team_crud.py -v` + +- [ ] **Step 6: Commit** + +```bash +cd api +git add services/sync_folders.py routers/sync_teams.py tests/test_sync_metadata_creation.py +git commit -m "feat(sync): create karma-meta--{team} folder on team create/join + +Metadata folder is sendreceive type shared by all members. Team +creator writes team.json with created_by. Each member writes their +own state file on join." +``` + +--- + +## Chunk 2: State Writes & Reads (T2.3–T2.5) + +### Task 2.3: Write Own Member State on Key Events + +**Files:** +- Create: `api/services/sync_metadata_writer.py` (thin wrapper that finds meta_dir and writes) +- Modify: `api/routers/sync_teams.py` (join writes state) +- Modify: `api/routers/sync_projects.py` (share/unshare updates subscriptions) +- Modify: `api/routers/sync_members.py` (settings change updates state) + +- [ ] **Step 1: Implement sync_metadata_writer.py** + +```python +# api/services/sync_metadata_writer.py +"""Convenience wrapper to write own state to the metadata folder.""" + +import logging +from pathlib import Path + +from services.sync_metadata import ( + build_metadata_folder_id, + write_member_state, +) + +logger = logging.getLogger(__name__) + + +def update_own_metadata(config, conn, team_name: str) -> None: + """Write/update this device's state in the team metadata folder. + + Reads current subscriptions and settings from DB, writes to the + metadata folder so other members can see our state. + """ + from karma.config import KARMA_BASE + from db.sync_queries import list_team_projects, get_effective_setting + + meta_dir = KARMA_BASE / "metadata-folders" / team_name + if not meta_dir.exists(): + logger.debug("Metadata dir not found for team %s", team_name) + return + + # Build subscriptions from team projects (all subscribed by default) + projects = list_team_projects(conn, team_name) + subscriptions = {} + for proj in projects: + # Check sync_rejected_folders for opt-out + encoded = proj["project_encoded_name"] + subscriptions[encoded] = True # default opt-in + + # Check rejected folders + try: + rows = conn.execute( + "SELECT folder_id FROM sync_rejected_folders WHERE team_name = ?", + (team_name,), + ).fetchall() + rejected_suffixes = set() + for row in rows: + from services.folder_id import parse_outbox_id + parsed = parse_outbox_id(row[0] if isinstance(row, tuple) else row["folder_id"]) + if parsed: + rejected_suffixes.add(parsed[1]) + + from services.sync_identity import _compute_proj_suffix + for proj in projects: + suffix = _compute_proj_suffix( + proj.get("git_identity"), proj.get("path"), proj["project_encoded_name"] + ) + if suffix in rejected_suffixes: + subscriptions[proj["project_encoded_name"]] = False + except Exception as e: + logger.debug("Failed to check rejected folders: %s", e) + + sync_direction = get_effective_setting(conn, "sync_direction", team_name=team_name) + session_limit = get_effective_setting(conn, "sync_session_limit", team_name=team_name) or "all" + + write_member_state( + meta_dir, + member_tag=config.member_tag, + user_id=config.user_id, + machine_id=config.machine_id, + device_id=config.syncthing.device_id or "", + subscriptions=subscriptions, + sync_direction=sync_direction, + session_limit=session_limit, + ) +``` + +- [ ] **Step 2: Call from key endpoints** + +Add `update_own_metadata(config, conn, team_name)` calls after: +- `sync_join_team` (after joining) +- `sync_add_team_project` (after sharing a project) +- `sync_remove_team_project` (after removing a project) +- `sync_update_team_settings` (after changing settings) +- `sync_update_member_settings` (after changing member settings) + +- [ ] **Step 3: Test and commit** + +```bash +cd api +git add services/sync_metadata_writer.py routers/sync_teams.py \ + routers/sync_projects.py routers/sync_members.py +git commit -m "feat(sync): write own member state to metadata folder on key events + +Subscriptions, sync_direction, and session_limit are published to +the metadata folder so other members can see our state." +``` + +--- + +### Task 2.4: Write Removal Signal (Creator Only) + +**Files:** +- Modify: `api/routers/sync_members.py` (remove-member writes removal signal) +- Test: existing removal tests + new metadata test + +- [ ] **Step 1: Implement removal signal in remove-member endpoint** + +In `api/routers/sync_members.py`, in `sync_remove_member`, after the existing cleanup: + +```python + # Write removal signal to metadata folder (creator-only enforcement) + try: + from karma.config import KARMA_BASE + from services.sync_metadata import ( + write_removal_signal, validate_removal_authority, + ) + + meta_dir = KARMA_BASE / "metadata-folders" / team_name + if meta_dir.exists(): + if not validate_removal_authority(meta_dir, config.member_tag): + raise HTTPException( + 403, + f"Only the team creator can remove members. " + f"You can control your own sync direction instead.", + ) + write_removal_signal( + meta_dir, + removed_member_tag=member_tag, + removed_device_id=member_device_id, + removed_by=config.member_tag, + ) + except HTTPException: + raise + except Exception as e: + logger.warning("Failed to write removal signal: %s", e) +``` + +- [ ] **Step 2: Test and commit** + +```bash +cd api +git add routers/sync_members.py +git commit -m "feat(sync): write removal signal to metadata folder + +Only the team creator can remove members (enforced via team.json). +Removal signal propagates to all members via Syncthing." +``` + +--- + +### Task 2.5: Reconciliation Reads Metadata Folder + +**Files:** +- Create: `api/services/sync_metadata_reconciler.py` +- Test: `api/tests/test_sync_metadata_reconciler.py` (create) + +- [ ] **Step 1: Implement the reconciler** + +```python +# api/services/sync_metadata_reconciler.py +"""Reconcile local DB state with team metadata folder contents.""" + +import logging +from pathlib import Path + +from db.sync_queries import ( + list_members, list_teams, upsert_member, remove_member, log_event, +) +from services.sync_metadata import ( + read_all_member_states, read_removal_signals, is_removed, +) + +logger = logging.getLogger(__name__) + + +def reconcile_metadata_folder(config, conn, team_name: str) -> dict: + """Read the team metadata folder and reconcile with local DB. + + 1. Read all member state files → add missing members to DB + 2. Read removal signals → if WE are removed, flag for auto-leave + 3. Read other members' subscriptions → cache locally for auto_share_folders + + Returns dict with counts: members_added, members_updated, self_removed. + """ + from karma.config import KARMA_BASE + + meta_dir = KARMA_BASE / "metadata-folders" / team_name + if not meta_dir.exists(): + return {"members_added": 0, "members_updated": 0, "self_removed": False} + + stats = {"members_added": 0, "members_updated": 0, "self_removed": False} + + # Check if WE are removed + if is_removed(meta_dir, config.member_tag): + logger.warning("This device has been removed from team %s", team_name) + stats["self_removed"] = True + return stats + + # Read all member states and reconcile with DB + member_states = read_all_member_states(meta_dir) + existing_members = list_members(conn, team_name) + existing_tags = {m.get("member_tag") for m in existing_members if m.get("member_tag")} + existing_devices = {m["device_id"] for m in existing_members} + + # Check removal signals (skip removed members) + removal_signals = read_removal_signals(meta_dir) + removed_tags = {r["member_tag"] for r in removal_signals} + + for state in member_states: + mtag = state.get("member_tag", "") + device_id = state.get("device_id", "") + user_id = state.get("user_id", "") + + if not mtag or not device_id: + continue + + # Skip removed members + if mtag in removed_tags: + continue + + # Skip self + if mtag == config.member_tag: + continue + + if mtag not in existing_tags and device_id not in existing_devices: + # New member discovered via metadata + from services.folder_id import parse_member_tag + _, machine_tag = parse_member_tag(mtag) + upsert_member( + conn, team_name, user_id, device_id=device_id, + machine_id=state.get("machine_id"), + machine_tag=machine_tag, + member_tag=mtag, + ) + log_event( + conn, "member_added", team_name=team_name, + member_name=user_id, + detail={"source": "metadata_folder", "member_tag": mtag}, + ) + stats["members_added"] += 1 + elif device_id in existing_devices: + # Existing member — update identity columns if missing + upsert_member( + conn, team_name, user_id, device_id=device_id, + machine_id=state.get("machine_id"), + machine_tag=state.get("member_tag", "").split(".", 1)[1] if "." in state.get("member_tag", "") else None, + member_tag=mtag, + ) + stats["members_updated"] += 1 + + return stats + + +def reconcile_all_teams_metadata(config, conn) -> dict: + """Run metadata reconciliation for all teams.""" + total = {"teams": 0, "members_added": 0, "self_removed_teams": []} + for team in list_teams(conn): + result = reconcile_metadata_folder(config, conn, team["name"]) + total["teams"] += 1 + total["members_added"] += result["members_added"] + if result["self_removed"]: + total["self_removed_teams"].append(team["name"]) + return total +``` + +- [ ] **Step 2: Write tests** + +```python +# api/tests/test_sync_metadata_reconciler.py +"""Tests for metadata folder reconciliation.""" + +import sqlite3 +import json +from pathlib import Path +from unittest.mock import MagicMock, patch +import pytest + +from db.schema import ensure_schema + + +@pytest.fixture +def conn(): + c = sqlite3.connect(":memory:") + c.row_factory = sqlite3.Row + c.execute("PRAGMA foreign_keys=ON") + ensure_schema(c) + return c + + +@pytest.fixture +def mock_config(): + config = MagicMock() + config.user_id = "jayant" + config.machine_id = "Mac-Mini" + config.machine_tag = "mac-mini" + config.member_tag = "jayant.mac-mini" + config.syncthing.device_id = "LEADER-DID" + return config + + +def test_reconcile_discovers_new_member(conn, mock_config, tmp_path): + """New member in metadata folder should be added to DB.""" + from db.sync_queries import create_team, upsert_member, list_members + + create_team(conn, "acme", backend="syncthing") + upsert_member(conn, "acme", "jayant", device_id="LEADER-DID", + member_tag="jayant.mac-mini") + + # Write ayush's state to metadata folder + meta_dir = tmp_path / "metadata-folders" / "acme" + members_dir = meta_dir / "members" + members_dir.mkdir(parents=True) + (members_dir / "ayush.ayush-mac.json").write_text(json.dumps({ + "member_tag": "ayush.ayush-mac", + "user_id": "ayush", + "machine_id": "Ayush-Mac", + "device_id": "AYUSH-DID", + })) + + with patch("services.sync_metadata_reconciler.KARMA_BASE", tmp_path): + from services.sync_metadata_reconciler import reconcile_metadata_folder + result = reconcile_metadata_folder(mock_config, conn, "acme") + + assert result["members_added"] == 1 + members = list_members(conn, "acme") + ayush = [m for m in members if m["name"] == "ayush"] + assert len(ayush) == 1 + assert ayush[0]["member_tag"] == "ayush.ayush-mac" + + +def test_reconcile_detects_self_removal(conn, mock_config, tmp_path): + """If our member_tag has a removal signal, self_removed should be True.""" + from db.sync_queries import create_team + + create_team(conn, "acme", backend="syncthing") + + meta_dir = tmp_path / "metadata-folders" / "acme" + removals_dir = meta_dir / "removals" + removals_dir.mkdir(parents=True) + (removals_dir / "jayant.mac-mini.json").write_text(json.dumps({ + "member_tag": "jayant.mac-mini", + "device_id": "LEADER-DID", + "removed_by": "admin.admin-pc", + "removed_at": "2026-03-11T12:00:00Z", + })) + + with patch("services.sync_metadata_reconciler.KARMA_BASE", tmp_path): + from services.sync_metadata_reconciler import reconcile_metadata_folder + result = reconcile_metadata_folder(mock_config, conn, "acme") + + assert result["self_removed"] is True + assert result["members_added"] == 0 +``` + +- [ ] **Step 3: Run tests** + +Run: `cd api && python -m pytest tests/test_sync_metadata_reconciler.py -v` +Expected: PASS + +- [ ] **Step 4: Commit** + +```bash +cd api +git add services/sync_metadata_reconciler.py tests/test_sync_metadata_reconciler.py +git commit -m "feat(sync): metadata folder reconciliation + +Reads member states and removal signals from karma-meta--{team}. +Discovers new members, updates identity columns, detects self-removal." +``` + +--- + +## Chunk 3: Auto-Leave & Watcher (T2.6–T2.7, Parallel) + +### Task 2.6: Auto-Leave on Self-Removal Detection + +**Files:** +- Modify: `api/routers/sync_teams.py` or new endpoint +- Uses: `reconcile_metadata_folder` result's `self_removed` flag + +When `self_removed=True`, trigger the existing `sync_delete_team` flow (clean up Syncthing folders, delete team from DB). This can be wired into the reconciliation that runs periodically. + +- [ ] **Step 1: Implement auto-leave in reconciliation** + +In `api/services/sync_metadata_reconciler.py`, extend `reconcile_all_teams_metadata`: + +```python +def reconcile_all_teams_metadata(config, conn) -> dict: + total = {"teams": 0, "members_added": 0, "self_removed_teams": []} + for team in list_teams(conn): + result = reconcile_metadata_folder(config, conn, team["name"]) + total["teams"] += 1 + total["members_added"] += result["members_added"] + if result["self_removed"]: + total["self_removed_teams"].append(team["name"]) + # Auto-leave: clean up Syncthing state and delete team locally + try: + from services.sync_folders import cleanup_syncthing_for_team + from services.sync_identity import get_proxy + proxy = get_proxy() + import asyncio + asyncio.get_event_loop().run_until_complete( + cleanup_syncthing_for_team(proxy, config, conn, team["name"]) + ) + from db.sync_queries import delete_team + log_event(conn, "team_left", team_name=team["name"], + detail={"reason": "removed_via_metadata"}) + delete_team(conn, team["name"]) + logger.info("Auto-left team %s (removed via metadata)", team["name"]) + except Exception as e: + logger.warning("Failed to auto-leave team %s: %s", team["name"], e) + return total +``` + +- [ ] **Step 2: Test and commit** + +```bash +cd api +git add services/sync_metadata_reconciler.py +git commit -m "feat(sync): auto-leave team when removal signal detected + +When metadata reconciliation finds our member_tag in the removals +folder, automatically clean up Syncthing state and delete the team +locally. No stale state remains." +``` + +--- + +### Task 2.7: Watcher-Driven Reconciliation Loop + +**Files:** +- Modify: wherever the watcher loop is defined (check `api/services/` or `api/routers/sync_operations.py`) +- Add metadata reconciliation to the periodic loop + +- [ ] **Step 1: Find the watcher implementation** + +The watcher is referenced in `api/routers/sync_operations.py` (watch_start/watch_stop). Find the actual loop and add: + +```python +# Every 60 seconds (or on Syncthing event): +from services.sync_metadata_reconciler import reconcile_all_teams_metadata +result = reconcile_all_teams_metadata(config, conn) +if result["self_removed_teams"]: + logger.info("Auto-left teams: %s", result["self_removed_teams"]) +``` + +Also add the existing reconciliation phases: +```python +from services.sync_reconciliation import ( + reconcile_introduced_devices, + reconcile_pending_handshakes, +) +await reconcile_introduced_devices(proxy, config, conn) +await reconcile_pending_handshakes(proxy, config, conn) +``` + +- [ ] **Step 2: Test and commit** + +```bash +git add api/services/ api/routers/sync_operations.py +git commit -m "feat(sync): watcher runs metadata + device reconciliation every 60s + +System is now self-healing without UI interaction. Watcher periodically +reconciles metadata folder state, introduced devices, and pending +handshakes." +``` + +--- + +## Post-Phase Verification + +- [ ] **Scenario test: Create team, join, remove member, verify auto-leave** + +1. Machine A creates team, shares project +2. Machine B joins team +3. Machine A removes Machine B +4. Verify: removal signal written to metadata folder +5. Verify: Machine B's next reconciliation detects removal and auto-leaves + +- [ ] **Run full test suite** + +```bash +cd api && python -m pytest tests/ -v --tb=short +``` diff --git a/docs/superpowers/plans/2026-03-11-sync-v2-phase3-ux-polish.md b/docs/superpowers/plans/2026-03-11-sync-v2-phase3-ux-polish.md new file mode 100644 index 00000000..cab79f1e --- /dev/null +++ b/docs/superpowers/plans/2026-03-11-sync-v2-phase3-ux-polish.md @@ -0,0 +1,528 @@ +# Sync v2 Phase 3: UX Polish + +> **For agentic workers:** REQUIRED: Use superpowers:subagent-driven-development (if subagents available) or superpowers:executing-plans to implement this plan. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Persistent folder rejection (no re-offering), selective project subscriptions (opt-out), any-member invite, and per-device session limits. + +**Architecture:** Uses `sync_rejected_folders` table (created in Phase 1 migration), metadata folder subscriptions (Phase 2), and new invite endpoint. + +**Tech Stack:** Python, FastAPI, SQLite, pytest + +**Prerequisite:** Phase 2 complete. + +--- + +## Chunk 1: Persistent Rejection & Subscriptions (T3.1–T3.4) + +### Task 3.1: Persistent Folder Rejection Table + Logic + +The `sync_rejected_folders` table was created in Phase 1 (migration v17). Now wire it into the rejection and acceptance flows. + +**Files:** +- Modify: `api/db/sync_queries.py` (add reject/check functions) +- Modify: `api/routers/sync_pending.py` (rejection saves to DB) +- Modify: `cli/karma/pending.py` (skip rejected folders) +- Test: `api/tests/test_sync_rejection.py` (create) + +- [ ] **Step 1: Write the failing test** + +```python +# api/tests/test_sync_rejection.py +"""Tests for persistent folder rejection.""" + +import sqlite3 +import pytest +from db.schema import ensure_schema + + +@pytest.fixture +def conn(): + c = sqlite3.connect(":memory:") + c.row_factory = sqlite3.Row + c.execute("PRAGMA foreign_keys=ON") + ensure_schema(c) + return c + + +def test_reject_folder_persists(conn): + """Rejecting a folder should persist in the DB.""" + from db.sync_queries import reject_folder, is_folder_rejected + + reject_folder(conn, "karma-out--ayush.mac--proj", team_name="acme") + + assert is_folder_rejected(conn, "karma-out--ayush.mac--proj") is True + assert is_folder_rejected(conn, "karma-out--other--proj") is False + + +def test_unreject_folder(conn): + """Accepting a previously rejected folder should remove the rejection.""" + from db.sync_queries import reject_folder, unreject_folder, is_folder_rejected + + reject_folder(conn, "karma-out--ayush.mac--proj", team_name="acme") + assert is_folder_rejected(conn, "karma-out--ayush.mac--proj") is True + + unreject_folder(conn, "karma-out--ayush.mac--proj") + assert is_folder_rejected(conn, "karma-out--ayush.mac--proj") is False + + +def test_list_rejected_folders(conn): + """Should list all rejected folders for a team.""" + from db.sync_queries import reject_folder, list_rejected_folders + + reject_folder(conn, "karma-out--a.mac--p1", team_name="acme") + reject_folder(conn, "karma-out--b.mac--p2", team_name="acme") + reject_folder(conn, "karma-out--c.mac--p3", team_name="other") + + acme_rejected = list_rejected_folders(conn, "acme") + assert len(acme_rejected) == 2 +``` + +- [ ] **Step 2: Run test to verify it fails** + +Run: `cd api && python -m pytest tests/test_sync_rejection.py -v` +Expected: FAIL — `ImportError: cannot import name 'reject_folder'` + +- [ ] **Step 3: Implement DB functions** + +Add to `api/db/sync_queries.py`: + +```python +def reject_folder(conn: sqlite3.Connection, folder_id: str, *, team_name: str = None) -> None: + """Persistently reject a folder offer (won't be re-offered).""" + conn.execute( + "INSERT OR REPLACE INTO sync_rejected_folders (folder_id, team_name) VALUES (?, ?)", + (folder_id, team_name), + ) + conn.commit() + + +def unreject_folder(conn: sqlite3.Connection, folder_id: str) -> None: + """Remove a folder rejection (allows re-offering).""" + conn.execute("DELETE FROM sync_rejected_folders WHERE folder_id = ?", (folder_id,)) + conn.commit() + + +def is_folder_rejected(conn: sqlite3.Connection, folder_id: str) -> bool: + """Check if a folder has been persistently rejected.""" + row = conn.execute( + "SELECT 1 FROM sync_rejected_folders WHERE folder_id = ?", (folder_id,) + ).fetchone() + return row is not None + + +def list_rejected_folders(conn: sqlite3.Connection, team_name: str) -> list[dict]: + """List all rejected folders for a team.""" + rows = conn.execute( + "SELECT folder_id, team_name, rejected_at FROM sync_rejected_folders WHERE team_name = ?", + (team_name,), + ).fetchall() + return [dict(r) for r in rows] +``` + +- [ ] **Step 4: Wire into rejection endpoint** + +In `api/routers/sync_pending.py`, in `sync_reject_single_folder`: + +```python + # After dismissing with Syncthing, persist the rejection + from db.sync_queries import reject_folder + conn = _sid._get_sync_conn() + + # Find team for this folder + from services.sync_folders import find_team_for_folder + team = find_team_for_folder(conn, [folder_id]) + reject_folder(conn, folder_id, team_name=team) +``` + +- [ ] **Step 5: Wire into pending folder filtering** + +In `api/routers/sync_pending.py`, in `sync_pending`, filter out rejected folders: + +```python + # After getting pending folders, filter out rejected ones + from db.sync_queries import is_folder_rejected + pending = [item for item in pending if not is_folder_rejected(conn, item["folder_id"])] +``` + +In `cli/karma/pending.py`, in `accept_pending_folders`, skip rejected: + +```python + # In the folder processing loop: + from db.sync_queries import is_folder_rejected + if is_folder_rejected(conn, folder_id): + continue +``` + +- [ ] **Step 6: Wire into acceptance (unreject on accept)** + +In `api/routers/sync_pending.py`, in `sync_accept_single_folder`: + +```python + # If user explicitly accepts a previously rejected folder, remove the rejection + from db.sync_queries import unreject_folder + conn = _sid._get_sync_conn() + unreject_folder(conn, folder_id) +``` + +- [ ] **Step 7: Run tests** + +Run: `cd api && python -m pytest tests/test_sync_rejection.py tests/test_sync_pending.py -v` +Expected: All pass + +- [ ] **Step 8: Commit** + +```bash +cd api +git add db/sync_queries.py routers/sync_pending.py +git commit -m "feat(sync): persistent folder rejection — rejected folders never re-offered + +Adds reject_folder/unreject_folder/is_folder_rejected to sync_queries. +Rejection endpoint saves to DB. Pending listing filters rejected. +Explicit accept removes prior rejection." +``` + +--- + +### Task 3.2: Update Metadata on Rejection (Subscription Signal) + +When a user rejects a folder, update their metadata file's subscriptions to `false` for that project. Other members can read this and skip creating inbox folders for us. + +**Files:** +- Modify: `api/routers/sync_pending.py` (rejection updates metadata) +- Uses: `api/services/sync_metadata_writer.py` (from Phase 2) + +- [ ] **Step 1: After rejection, update metadata** + +In `sync_reject_single_folder`, after persisting rejection: + +```python + # Update own metadata to reflect unsubscription + try: + from services.sync_metadata_writer import update_own_metadata + config = await run_sync(_sid._load_identity) + if config: + update_own_metadata(config, conn, team) + except Exception as e: + logger.debug("Failed to update metadata after rejection: %s", e) +``` + +- [ ] **Step 2: Commit** + +```bash +cd api +git add routers/sync_pending.py +git commit -m "feat(sync): rejection updates metadata folder subscriptions + +When a folder is rejected, the member's metadata file is updated +with subscription=false for that project. Other members can read +this and avoid re-sharing." +``` + +--- + +### Task 3.3: auto_share_folders Checks Subscriptions + +Before creating an inbox for a member, check their metadata file's subscriptions. If the project is explicitly `false`, skip inbox creation. + +**Files:** +- Modify: `api/services/sync_folders.py:205-242` (auto_share_folders) +- Test: `api/tests/test_sync_subscription_check.py` (create) + +- [ ] **Step 1: Write the failing test** + +```python +# api/tests/test_sync_subscription_check.py +"""Tests for subscription checking in auto_share_folders.""" + +import json +from pathlib import Path +from unittest.mock import AsyncMock, MagicMock, patch +import sqlite3 +import pytest + +from db.schema import ensure_schema + + +@pytest.fixture +def conn(): + c = sqlite3.connect(":memory:") + c.row_factory = sqlite3.Row + c.execute("PRAGMA foreign_keys=ON") + ensure_schema(c) + return c + + +def test_should_check_member_subscription(tmp_path): + """auto_share_folders should check metadata subscriptions before creating inbox.""" + from services.sync_metadata import read_all_member_states + + meta_dir = tmp_path / "metadata-folders" / "acme" + members_dir = meta_dir / "members" + members_dir.mkdir(parents=True) + + # Ayush has unsubscribed from the project + (members_dir / "ayush.ayush-mac.json").write_text(json.dumps({ + "member_tag": "ayush.ayush-mac", + "user_id": "ayush", + "device_id": "AYUSH-DID", + "subscriptions": {"jayantdevkar-claude-karma": False}, + })) + + states = read_all_member_states(meta_dir) + ayush_state = states[0] + assert ayush_state["subscriptions"]["jayantdevkar-claude-karma"] is False +``` + +- [ ] **Step 2: Implement subscription check** + +In `api/services/sync_folders.py`, in `auto_share_folders`, before calling `ensure_inbox_folders`: + +```python + # Check member subscriptions from metadata folder + member_subscriptions = {} + try: + from karma.config import KARMA_BASE + from services.sync_metadata import read_all_member_states + meta_dir = KARMA_BASE / "metadata-folders" / team_name + if meta_dir.exists(): + for state in read_all_member_states(meta_dir): + device = state.get("device_id", "") + subs = state.get("subscriptions", {}) + member_subscriptions[device] = subs + except Exception as e: + logger.debug("Failed to read member subscriptions: %s", e) +``` + +Then in `ensure_inbox_folders`, add a subscription check parameter: + +```python +async def ensure_inbox_folders( + proxy, config, members, encoded, proj_suffix, + *, only_device_id=None, member_subscriptions=None, +): + for m in members: + # ... existing checks ... + + # Check subscription opt-out + if member_subscriptions: + device_subs = member_subscriptions.get(m["device_id"], {}) + # Check by encoded_name or by suffix + if any(v is False for k, v in device_subs.items() if k == encoded or k.endswith(proj_suffix)): + logger.info("Skipping inbox for %s — unsubscribed from %s", m.get("member_tag", m["name"]), proj_suffix) + continue +``` + +- [ ] **Step 3: Run tests and commit** + +```bash +cd api +git add services/sync_folders.py tests/test_sync_subscription_check.py +git commit -m "feat(sync): auto_share_folders respects member subscriptions + +Before creating an inbox folder for a member, checks their metadata +file's subscriptions. If explicitly false, skips inbox creation." +``` + +--- + +### Task 3.4: Any-Member Invite Endpoint + +Any team member (not just the creator) can generate an invite code pointing to their own device as the entry point. + +**Files:** +- Modify: `api/routers/sync_teams.py` (add invite endpoint) +- Test: `api/tests/test_sync_invite.py` (create) + +- [ ] **Step 1: Write the failing test** + +```python +# api/tests/test_sync_invite.py +"""Tests for any-member invite generation.""" + + +def test_invite_code_uses_inviter_device(): + """Invite code should use the inviter's device_id, not the team creator's.""" + # The invite code format is team:user_id.machine_tag:device_id + invite = "acme:ayush.ayush-mac:AYUSH-DID" + parts = invite.split(":", 2) + assert parts[0] == "acme" + assert parts[1] == "ayush.ayush-mac" + assert parts[2] == "AYUSH-DID" +``` + +- [ ] **Step 2: Implement invite endpoint** + +Add to `api/routers/sync_teams.py`: + +```python +@router.post("/teams/{team_name}/invite") +async def sync_generate_invite(team_name: str) -> Any: + """Generate an invite code for this team using the current device as entry point. + + Any team member can generate an invite — the joiner connects to the inviter + first, then the Syncthing mesh propagates all other devices. + """ + conn = _sid._get_sync_conn() + team = get_team(conn, team_name) + if team is None: + raise HTTPException(404, "Team not found") + + config = await run_sync(_sid._load_identity) + if config is None: + raise HTTPException(400, "Not initialized") + + # Verify caller is a member of this team + members = list_members(conn, team_name) + is_member = any( + m["device_id"] == config.syncthing.device_id for m in members + ) + if not is_member: + raise HTTPException(403, "You are not a member of this team") + + invite_code = f"{team_name}:{config.member_tag}:{config.syncthing.device_id}" + + return { + "invite_code": invite_code, + "team_name": team_name, + "inviter": config.member_tag, + "note": "Any member can generate invite codes. The joiner connects to you first.", + } +``` + +- [ ] **Step 3: Update join handler to accept any invite code** + +The existing join handler already parses `team:user:device_id` format. With member_tag, the user part is now `user_id.machine_tag`. The join handler just needs to extract the device_id (last part) — it doesn't care about the inviter's identity beyond pairing. + +Verify that `sync_join_team` in `sync_teams.py` handles the new format: + +```python +# Existing parsing: parts = join_code.split(":", 2) +# parts[0] = team_name, parts[1] = inviter member_tag, parts[2] = device_id +# The device_id extraction already works. The member_tag in parts[1] +# is used for the member name — now it's a full member_tag, which is better. +``` + +- [ ] **Step 4: Run tests and commit** + +```bash +cd api +git add routers/sync_teams.py tests/test_sync_invite.py +git commit -m "feat(sync): any team member can generate invite codes + +POST /sync/teams/{team}/invite generates an invite code using the +caller's device as entry point. Reduces leader dependency — new +members can join via any online member." +``` + +--- + +### Task 3.5: Session Limit Per-Device in Metadata + +Session limit is already per-team (`sync_teams.sync_session_limit`). Allow per-device override via the metadata file. + +**Files:** +- Modify: `cli/karma/packager.py` (read session_limit from own metadata) +- Already written to metadata in Phase 2's `update_own_metadata` + +- [ ] **Step 1: Update packager to check metadata** + +In `cli/karma/packager.py`, in the `get_session_limit` method: + +```python +def get_session_limit(self, team_name: str) -> str: + """Get session limit, checking metadata file first (per-device override).""" + # Check own metadata file for per-device override + try: + from karma.config import KARMA_BASE + import json + meta_file = KARMA_BASE / "metadata-folders" / team_name / "members" / f"{self.config.member_tag}.json" + if meta_file.exists(): + state = json.loads(meta_file.read_text()) + limit = state.get("session_limit") + if limit and limit != "all": + return limit + except Exception: + pass + + # Fall back to team-level setting + return self._get_team_session_limit(team_name) +``` + +- [ ] **Step 2: Commit** + +```bash +git add cli/karma/packager.py +git commit -m "feat(sync): per-device session limit via metadata file + +Packager checks own metadata file for session_limit override before +falling back to team-level setting. Allows each device to control +how many sessions it shares." +``` + +--- + +## Chunk 2: Frontend Hints (Not Implemented — For Reference) + +The frontend changes needed to support the new UX: + +### Pending Folders Page +- Show `member_tag` in descriptions: "jayant (mac-mini)" not "jayant" +- Accept / Decline buttons per folder +- "Accept All" batch button +- Declined folders don't reappear + +### Team Members Page +- Show device info: "jayant (Mac Mini)" with machine icon +- Group by user_id, expand to see devices +- Per-device sync direction toggle +- Per-device session limit selector + +### Project Sharing Page +- Subscribe / Unsubscribe toggle per project per device +- Show who's subscribed (from metadata folder) + +### Settings Page +- "Manual approval" / "Auto-accept from team members" toggle +- Per-team and per-device overrides + +--- + +## Post-Phase Verification + +- [ ] **Rejected folder doesn't reappear** + +1. Reject a pending folder +2. Trigger rescan +3. Verify folder doesn't appear in pending list + +- [ ] **Unsubscribed project doesn't create inbox** + +1. Member A unsubscribes from project X +2. Member B shares project X with team +3. Verify Member A doesn't get inbox folder for project X + +- [ ] **Any-member invite works** + +1. Member B generates invite code +2. Member C joins using B's invite +3. Verify C connects to B, mesh propagates A + +- [ ] **Per-device session limit** + +1. Set session_limit="recent_10" in member metadata +2. Run packager +3. Verify only 10 most recent sessions packaged + +- [ ] **Run full test suite** + +```bash +cd api && python -m pytest tests/ -v --tb=short +cd cli && python -m pytest tests/ -v --tb=short +``` + +- [ ] **Lint** + +```bash +cd api && ruff check services/ routers/ db/ +cd cli && ruff check karma/ +``` diff --git a/docs/superpowers/plans/2026-03-17-sync-v4-master.md b/docs/superpowers/plans/2026-03-17-sync-v4-master.md new file mode 100644 index 00000000..576a3091 --- /dev/null +++ b/docs/superpowers/plans/2026-03-17-sync-v4-master.md @@ -0,0 +1,277 @@ +# Sync v4: Domain Models Implementation — Master Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Full rewrite of sync feature with Pydantic domain models, repository pattern, and simplified 3-phase reconciliation. + +**Architecture:** Pure domain models (no DB coupling) with state machines for Team, Member, SharedProject, Subscription. Repository pattern for SQLite persistence. Services orchestrate domain logic + Syncthing. Thin FastAPI routers. + +**Tech Stack:** Python 3.9+, Pydantic 2.x, FastAPI, SQLite, pytest, Syncthing REST API + +**Spec:** `docs/superpowers/specs/2026-03-17-sync-v4-domain-models-design.md` + +--- + +## Phase Dependency Graph + +``` +Phase 1: Foundation Phase 2: Infrastructure +(Domain Models + Schema + Repos) (Syncthing Abstraction + Pairing) + │ │ + │ ┌─── CAN RUN IN ───┐ │ + │ │ PARALLEL │ │ + ▼ └───────────────────┘ ▼ + └──────────────┬──────────────────────┘ + │ + ▼ + Phase 3: Business Logic + (Services — TeamService, + ProjectService, MetadataService, + ReconciliationService) + │ + ▼ + Phase 4: API + Integration + (Routers, Watcher, Cleanup, + Delete old v3 files) +``` + +**Phase 1 and Phase 2 are fully independent — run them in parallel.** + +## Phase Summary + +| Phase | Name | Tasks | Est. Files | Parallel? | Depends On | +|-------|------|-------|------------|-----------|------------| +| 1 | Foundation | 8 | 16 | Internal parallelism (5 models, 5 repos) | — | +| 2 | Infrastructure | 5 | 8 | **Yes — parallel with Phase 1** | — | +| 3 | Business Logic | 6 | 10 | After Phase 1+2 | Phase 1, Phase 2 | +| 4 | API + Integration | 7 | 12 | Internal parallelism (4 routers) | Phase 3 | +| **Total** | | **26 tasks** | **~46 files** | | | + +## Phase Details + +### Phase 1: Foundation (`2026-03-17-sync-v4-phase1-foundation.md`) +Domain models, schema migration, repositories. The core that everything else builds on. + +**Internal parallelism:** +- Task 1-5 (5 domain models) — ALL PARALLEL +- Task 6 (schema migration) — sequential, after models +- Task 7 (repositories) — after schema, but 5 repos can be parallel +- Task 8 (integration test) — after repos + +### Phase 2: Infrastructure (`2026-03-17-sync-v4-phase2-infrastructure.md`) +Syncthing HTTP client, device/folder managers, pairing service. No domain model dependency. + +**Internal parallelism:** +- Task 1 (SyncthingClient) — first +- Task 2-3 (DeviceManager, FolderManager) — PARALLEL, after Task 1 +- Task 4 (PairingService) — INDEPENDENT, can parallel with all +- Task 5 (integration test) — after all + +### Phase 3: Business Logic (`2026-03-17-sync-v4-phase3-services.md`) +Services that orchestrate domain models + repos + Syncthing. + +**Internal parallelism:** +- Task 1 (MetadataService) — first (others use it) +- Task 2-3 (TeamService, ProjectService) — PARALLEL, after MetadataService +- Task 4 (ReconciliationService) — after TeamService + ProjectService +- Task 5 (WatcherManager) — after ReconciliationService +- Task 6 (integration test) — after all + +### Phase 4: API + Integration (`2026-03-17-sync-v4-phase4-api.md`) +Thin routers, old file cleanup, end-to-end testing. + +**Internal parallelism:** +- Task 1-4 (4 routers) — ALL PARALLEL +- Task 5 (router registration + conftest) — after routers +- Task 6 (delete old v3 files) — after routers confirmed working +- Task 7 (end-to-end smoke test) — final + +## Agent & Skill Recommendations + +### For Parallel Phase Execution (Phase 1 + Phase 2) + +**Recommended:** `superpowers:dispatching-parallel-agents` or `oh-my-claudecode:ultrapilot` + +Launch two worktree-isolated agents: +- Agent A: Phase 1 (Foundation) in worktree A +- Agent B: Phase 2 (Infrastructure) in worktree B + +Merge both into the feature branch when complete. + +### For Within-Phase Task Execution + +**Recommended:** `superpowers:subagent-driven-development` + +Each task dispatched as a fresh subagent with: +- The phase doc as context +- TDD enforcement (write test → verify fail → implement → verify pass → commit) +- Review between tasks + +### For Individual Task TDD + +**Recommended:** `oh-my-claudecode:tdd` or `superpowers:test-driven-development` + +Both enforce write-tests-first methodology. Use for any task that creates new code. + +### For Code Review Checkpoints + +**Recommended:** `superpowers:requesting-code-review` after each phase completes + +Review the phase's code against the spec before starting the next phase. + +### For Build Errors + +**Recommended:** `oh-my-claudecode:build-fix` or `everything-claude-code:build-error-resolver` + +If tests fail unexpectedly during implementation, these agents fix with minimal diffs. + +## File Map (Complete) + +``` +api/ +├── domain/ # Phase 1 — NEW +│ ├── __init__.py +│ ├── team.py # Team + TeamStatus enum +│ ├── member.py # Member + MemberStatus enum +│ ├── project.py # SharedProject + SharedProjectStatus enum +│ ├── subscription.py # Subscription + SubscriptionStatus + SyncDirection enums +│ └── events.py # SyncEvent + SyncEventType enum +│ +├── repositories/ # Phase 1 — NEW +│ ├── __init__.py +│ ├── team_repo.py +│ ├── member_repo.py +│ ├── project_repo.py +│ ├── subscription_repo.py +│ └── event_repo.py +│ +├── services/ +│ ├── sync/ # Phase 3 — NEW +│ │ ├── __init__.py +│ │ ├── team_service.py +│ │ ├── project_service.py +│ │ ├── reconciliation_service.py +│ │ └── metadata_service.py +│ │ +│ ├── syncthing/ # Phase 2 — NEW +│ │ ├── __init__.py +│ │ ├── client.py +│ │ ├── device_manager.py +│ │ └── folder_manager.py +│ │ +│ ├── sync/ +│ │ └── pairing_service.py # Phase 2 — NEW +│ │ +│ ├── watcher_manager.py # Phase 3 — REWRITE +│ └── remote_sessions.py # UNCHANGED +│ +├── routers/ # Phase 4 — REWRITE +│ ├── sync_teams.py +│ ├── sync_projects.py +│ ├── sync_pairing.py # NEW +│ └── sync_system.py +│ +├── db/ +│ └── schema.py # Phase 1 — MODIFY (add v19 migration) +│ +└── tests/ + ├── test_domain_team.py # Phase 1 + ├── test_domain_member.py # Phase 1 + ├── test_domain_project.py # Phase 1 + ├── test_domain_subscription.py # Phase 1 + ├── test_domain_events.py # Phase 1 + ├── test_repo_team.py # Phase 1 + ├── test_repo_member.py # Phase 1 + ├── test_repo_project.py # Phase 1 + ├── test_repo_subscription.py # Phase 1 + ├── test_repo_event.py # Phase 1 + ├── test_schema_v19.py # Phase 1 + ├── test_syncthing_client.py # Phase 2 + ├── test_device_manager.py # Phase 2 + ├── test_folder_manager.py # Phase 2 + ├── test_pairing_service.py # Phase 2 + ├── test_metadata_service.py # Phase 3 + ├── test_team_service.py # Phase 3 + ├── test_project_service.py # Phase 3 + ├── test_reconciliation_service.py # Phase 3 + └── api/ + ├── test_sync_teams_router.py # Phase 4 + ├── test_sync_projects_router.py # Phase 4 + ├── test_sync_pairing_router.py # Phase 4 + └── test_sync_system_router.py # Phase 4 +``` + +## Files to Delete (Phase 4, Task 6) + +``` +api/routers/sync_members.py +api/routers/sync_pending.py +api/routers/sync_devices.py +api/routers/sync_operations.py +api/services/sync_queries.py +api/services/sync_reconciliation.py +api/services/sync_folders.py +api/services/sync_metadata_reconciler.py +api/services/sync_metadata_writer.py +api/services/sync_identity.py +api/services/sync_policy.py +api/services/syncthing_proxy.py +api/db/sync_queries.py +``` + +## Execution Order + +``` +START + │ + ├──→ Phase 1: Foundation (Agent A — worktree) + │ Tasks 1-5 (models, parallel) + │ Task 6 (schema) + │ Task 7 (repos, parallel) + │ Task 8 (integration) + │ + ├──→ Phase 2: Infrastructure (Agent B — worktree, PARALLEL) + │ Task 1 (client) + │ Tasks 2-4 (managers, parallel) + │ Task 5 (integration) + │ + ├──→ MERGE Phase 1 + Phase 2 + │ + ├──→ Code Review Checkpoint + │ + ├──→ Phase 3: Business Logic (Agent C — worktree) + │ Task 1 (metadata) + │ Tasks 2-3 (team+project svc, parallel) + │ Task 4 (reconciliation) + │ Task 5 (watcher) + │ Task 6 (integration) + │ + ├──→ Code Review Checkpoint + │ + ├──→ Phase 4: API + Integration (Agent D — worktree) + │ Tasks 1-4 (routers, parallel) + │ Task 5 (registration) + │ Task 6 (delete old files) + │ Task 7 (smoke test) + │ + └──→ Final Code Review → DONE +``` + +## Test Commands + +```bash +cd api + +# Run all v4 tests +pytest tests/test_domain_*.py tests/test_repo_*.py tests/test_*_service.py tests/test_*_manager.py -v + +# Run by phase +pytest tests/test_domain_*.py -v # Phase 1 models +pytest tests/test_schema_v19.py tests/test_repo_*.py -v # Phase 1 repos +pytest tests/test_syncthing_*.py tests/test_device_*.py tests/test_folder_*.py tests/test_pairing_*.py -v # Phase 2 +pytest tests/test_*_service.py -v # Phase 3 +pytest tests/api/test_sync_*_router.py -v # Phase 4 + +# Full suite with coverage +pytest --cov=domain --cov=repositories --cov=services/sync --cov=services/syncthing --cov=routers -v +``` diff --git a/docs/superpowers/plans/2026-03-17-sync-v4-phase1-foundation.md b/docs/superpowers/plans/2026-03-17-sync-v4-phase1-foundation.md new file mode 100644 index 00000000..6963f212 --- /dev/null +++ b/docs/superpowers/plans/2026-03-17-sync-v4-phase1-foundation.md @@ -0,0 +1,1687 @@ +# Sync v4 Phase 1: Foundation — Domain Models + Schema + Repositories + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. +> +> **TDD SKILL:** Use `oh-my-claudecode:tdd` or `superpowers:test-driven-development` for every task. + +**Goal:** Build the pure domain model layer, v19 schema migration, and repository persistence layer. + +**Architecture:** Frozen Pydantic models with state machine methods → SQLite repositories. Models have zero DB coupling. Repos are thin CRUD. + +**Tech Stack:** Python 3.9+, Pydantic 2.x, SQLite, pytest + +**Spec:** `docs/superpowers/specs/2026-03-17-sync-v4-domain-models-design.md` + +**Parent Plan:** `docs/superpowers/plans/2026-03-17-sync-v4-master.md` + +--- + +## Task Dependency Graph + +``` +Tasks 1-5 (Domain Models) ─── ALL PARALLEL ───→ Task 6 (Schema) → Task 7 (Repos) → Task 8 (Integration) + ↑ + 5 repos can be + parallel within + Task 7 +``` + +--- + +### Task 1: Team Domain Model + +**Files:** +- Create: `api/domain/__init__.py` +- Create: `api/domain/team.py` +- Test: `api/tests/test_domain_team.py` + +**CAN PARALLEL with Tasks 2-5** + +- [ ] **Step 1: Create domain package + write failing tests** + +```python +# api/domain/__init__.py +"""Sync v4 domain models — pure Pydantic, no DB coupling.""" + +# api/tests/test_domain_team.py +import sys +from pathlib import Path +sys.path.insert(0, str(Path(__file__).parent.parent)) + +import pytest +from domain.team import Team, TeamStatus, AuthorizationError + + +class TestTeamCreation: + def test_create_team_defaults_to_active(self): + team = Team( + name="karma-team", + leader_device_id="DEVICE-ABC", + leader_member_tag="jayant.macbook", + ) + assert team.status == TeamStatus.ACTIVE + assert team.name == "karma-team" + assert team.leader_device_id == "DEVICE-ABC" + assert team.leader_member_tag == "jayant.macbook" + assert team.created_at is not None + + def test_team_is_frozen(self): + team = Team( + name="t", leader_device_id="D", leader_member_tag="j.m", + ) + with pytest.raises(Exception): # ValidationError for frozen + team.name = "other" + + +class TestTeamIsLeader: + def test_is_leader_true(self): + team = Team(name="t", leader_device_id="LEADER", leader_member_tag="j.m") + assert team.is_leader("LEADER") is True + + def test_is_leader_false(self): + team = Team(name="t", leader_device_id="LEADER", leader_member_tag="j.m") + assert team.is_leader("OTHER") is False + + +class TestTeamDissolve: + def test_dissolve_by_leader(self): + team = Team(name="t", leader_device_id="LEADER", leader_member_tag="j.m") + dissolved = team.dissolve(by_device="LEADER") + assert dissolved.status == TeamStatus.DISSOLVED + assert dissolved.name == team.name # same identity + + def test_dissolve_by_non_leader_raises(self): + team = Team(name="t", leader_device_id="LEADER", leader_member_tag="j.m") + with pytest.raises(AuthorizationError, match="Only leader"): + team.dissolve(by_device="OTHER") + + def test_dissolve_already_dissolved_raises(self): + team = Team(name="t", leader_device_id="L", leader_member_tag="j.m", + status=TeamStatus.DISSOLVED) + with pytest.raises(ValueError, match="already dissolved"): + team.dissolve(by_device="L") + + +class TestTeamAddMember: + def test_add_member_by_leader(self): + from domain.member import Member, MemberStatus + team = Team(name="t", leader_device_id="LEADER", leader_member_tag="j.m") + member = Member( + member_tag="ayush.laptop", team_name="t", + device_id="DEV-2", user_id="ayush", machine_tag="laptop", + ) + result = team.add_member(member, by_device="LEADER") + assert result.status == MemberStatus.ADDED + assert result.member_tag == "ayush.laptop" + + def test_add_member_by_non_leader_raises(self): + from domain.member import Member + team = Team(name="t", leader_device_id="LEADER", leader_member_tag="j.m") + member = Member( + member_tag="ayush.laptop", team_name="t", + device_id="DEV-2", user_id="ayush", machine_tag="laptop", + ) + with pytest.raises(AuthorizationError): + team.add_member(member, by_device="OTHER") + + +class TestTeamRemoveMember: + def test_remove_active_member_by_leader(self): + from domain.member import Member, MemberStatus + team = Team(name="t", leader_device_id="LEADER", leader_member_tag="j.m") + member = Member( + member_tag="ayush.laptop", team_name="t", + device_id="DEV-2", user_id="ayush", machine_tag="laptop", + status=MemberStatus.ACTIVE, + ) + result = team.remove_member(member, by_device="LEADER") + assert result.status == MemberStatus.REMOVED + + def test_remove_added_member_by_leader(self): + from domain.member import Member, MemberStatus + team = Team(name="t", leader_device_id="LEADER", leader_member_tag="j.m") + member = Member( + member_tag="ayush.laptop", team_name="t", + device_id="DEV-2", user_id="ayush", machine_tag="laptop", + status=MemberStatus.ADDED, + ) + result = team.remove_member(member, by_device="LEADER") + assert result.status == MemberStatus.REMOVED + + def test_remove_member_by_non_leader_raises(self): + from domain.member import Member, MemberStatus + team = Team(name="t", leader_device_id="LEADER", leader_member_tag="j.m") + member = Member( + member_tag="a.l", team_name="t", device_id="D", + user_id="a", machine_tag="l", status=MemberStatus.ACTIVE, + ) + with pytest.raises(AuthorizationError): + team.remove_member(member, by_device="OTHER") +``` + +- [ ] **Step 2: Run tests to verify they fail** + +Run: `cd api && pytest tests/test_domain_team.py -v` +Expected: FAIL — `ModuleNotFoundError: No module named 'domain'` + +- [ ] **Step 3: Implement Team model** + +```python +# api/domain/team.py +"""Team domain model — the authority boundary for sync operations.""" +from __future__ import annotations + +from datetime import datetime, timezone +from enum import Enum +from typing import TYPE_CHECKING + +from pydantic import BaseModel, ConfigDict, Field + +if TYPE_CHECKING: + from domain.member import Member + + +class AuthorizationError(Exception): + """Raised when a non-leader attempts a leader-only action.""" + + +class InvalidTransitionError(ValueError): + """Raised when a state transition is not allowed.""" + + +class TeamStatus(str, Enum): + ACTIVE = "active" + DISSOLVED = "dissolved" + + +class Team(BaseModel): + model_config = ConfigDict(frozen=True) + + name: str + leader_device_id: str + leader_member_tag: str + status: TeamStatus = TeamStatus.ACTIVE + created_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc)) + + def is_leader(self, device_id: str) -> bool: + return self.leader_device_id == device_id + + def _assert_leader(self, by_device: str) -> None: + if not self.is_leader(by_device): + raise AuthorizationError( + f"Only leader ({self.leader_device_id}) can perform this action, " + f"got device {by_device}" + ) + + def _assert_active(self) -> None: + if self.status == TeamStatus.DISSOLVED: + raise InvalidTransitionError( + f"Team '{self.name}' is already dissolved" + ) + + def dissolve(self, *, by_device: str) -> Team: + self._assert_leader(by_device) + self._assert_active() + return self.model_copy(update={"status": TeamStatus.DISSOLVED}) + + def add_member(self, member: Member, *, by_device: str) -> Member: + self._assert_leader(by_device) + self._assert_active() + return member # member is already created with ADDED status + + def remove_member(self, member: Member, *, by_device: str) -> Member: + self._assert_leader(by_device) + self._assert_active() + return member.remove() +``` + +- [ ] **Step 4: Run tests to verify they pass** + +Run: `cd api && pytest tests/test_domain_team.py -v` +Expected: ALL PASS + +- [ ] **Step 5: Commit** + +```bash +git add api/domain/__init__.py api/domain/team.py api/tests/test_domain_team.py +git commit -m "feat(sync-v4): add Team domain model with state machine" +``` + +--- + +### Task 2: Member Domain Model + +**Files:** +- Create: `api/domain/member.py` +- Test: `api/tests/test_domain_member.py` + +**CAN PARALLEL with Tasks 1, 3-5** + +- [ ] **Step 1: Write failing tests** + +```python +# api/tests/test_domain_member.py +import sys +from pathlib import Path +sys.path.insert(0, str(Path(__file__).parent.parent)) + +import pytest +from domain.member import Member, MemberStatus +from domain.team import InvalidTransitionError + + +class TestMemberCreation: + def test_create_member_defaults_to_added(self): + m = Member( + member_tag="ayush.laptop", team_name="t", + device_id="DEV-1", user_id="ayush", machine_tag="laptop", + ) + assert m.status == MemberStatus.ADDED + assert m.member_tag == "ayush.laptop" + assert m.user_id == "ayush" + assert m.machine_tag == "laptop" + + def test_member_is_frozen(self): + m = Member( + member_tag="a.l", team_name="t", + device_id="D", user_id="a", machine_tag="l", + ) + with pytest.raises(Exception): + m.status = MemberStatus.ACTIVE + + def test_parse_member_tag(self): + m = Member.from_member_tag( + member_tag="jayant.macbook-pro", + team_name="t", device_id="D", + ) + assert m.user_id == "jayant" + assert m.machine_tag == "macbook-pro" + + def test_invalid_member_tag_no_dot(self): + with pytest.raises(ValueError, match="must contain"): + Member.from_member_tag( + member_tag="nodot", team_name="t", device_id="D", + ) + + +class TestMemberActivate: + def test_activate_from_added(self): + m = Member( + member_tag="a.l", team_name="t", + device_id="D", user_id="a", machine_tag="l", + status=MemberStatus.ADDED, + ) + activated = m.activate() + assert activated.status == MemberStatus.ACTIVE + + def test_activate_from_active_raises(self): + m = Member( + member_tag="a.l", team_name="t", + device_id="D", user_id="a", machine_tag="l", + status=MemberStatus.ACTIVE, + ) + with pytest.raises(InvalidTransitionError): + m.activate() + + def test_activate_from_removed_raises(self): + m = Member( + member_tag="a.l", team_name="t", + device_id="D", user_id="a", machine_tag="l", + status=MemberStatus.REMOVED, + ) + with pytest.raises(InvalidTransitionError): + m.activate() + + +class TestMemberRemove: + def test_remove_from_active(self): + m = Member( + member_tag="a.l", team_name="t", + device_id="D", user_id="a", machine_tag="l", + status=MemberStatus.ACTIVE, + ) + removed = m.remove() + assert removed.status == MemberStatus.REMOVED + + def test_remove_from_added(self): + m = Member( + member_tag="a.l", team_name="t", + device_id="D", user_id="a", machine_tag="l", + status=MemberStatus.ADDED, + ) + removed = m.remove() + assert removed.status == MemberStatus.REMOVED + + def test_remove_from_removed_raises(self): + m = Member( + member_tag="a.l", team_name="t", + device_id="D", user_id="a", machine_tag="l", + status=MemberStatus.REMOVED, + ) + with pytest.raises(InvalidTransitionError): + m.remove() + + +class TestMemberProperties: + def test_is_active_true(self): + m = Member( + member_tag="a.l", team_name="t", + device_id="D", user_id="a", machine_tag="l", + status=MemberStatus.ACTIVE, + ) + assert m.is_active is True + + def test_is_active_false_when_added(self): + m = Member( + member_tag="a.l", team_name="t", + device_id="D", user_id="a", machine_tag="l", + status=MemberStatus.ADDED, + ) + assert m.is_active is False +``` + +- [ ] **Step 2: Run tests to verify they fail** + +Run: `cd api && pytest tests/test_domain_member.py -v` +Expected: FAIL + +- [ ] **Step 3: Implement Member model** + +```python +# api/domain/member.py +"""Member domain model — a person + machine in a team.""" +from __future__ import annotations + +from datetime import datetime, timezone +from enum import Enum + +from pydantic import BaseModel, ConfigDict, Field + +from domain.team import InvalidTransitionError + + +class MemberStatus(str, Enum): + ADDED = "added" + ACTIVE = "active" + REMOVED = "removed" + + +class Member(BaseModel): + model_config = ConfigDict(frozen=True) + + member_tag: str + team_name: str + device_id: str + user_id: str + machine_tag: str + status: MemberStatus = MemberStatus.ADDED + added_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc)) + updated_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc)) + + @classmethod + def from_member_tag( + cls, *, member_tag: str, team_name: str, device_id: str, **kwargs + ) -> Member: + if "." not in member_tag: + raise ValueError( + f"member_tag '{member_tag}' must contain a dot separating user_id and machine_tag" + ) + user_id, machine_tag = member_tag.split(".", 1) + return cls( + member_tag=member_tag, + team_name=team_name, + device_id=device_id, + user_id=user_id, + machine_tag=machine_tag, + **kwargs, + ) + + def activate(self) -> Member: + if self.status != MemberStatus.ADDED: + raise InvalidTransitionError( + f"Cannot activate member in '{self.status.value}' state (must be 'added')" + ) + return self.model_copy( + update={"status": MemberStatus.ACTIVE, "updated_at": datetime.now(timezone.utc)} + ) + + def remove(self) -> Member: + if self.status == MemberStatus.REMOVED: + raise InvalidTransitionError( + f"Member '{self.member_tag}' is already removed" + ) + return self.model_copy( + update={"status": MemberStatus.REMOVED, "updated_at": datetime.now(timezone.utc)} + ) + + @property + def is_active(self) -> bool: + return self.status == MemberStatus.ACTIVE +``` + +- [ ] **Step 4: Run tests to verify they pass** + +Run: `cd api && pytest tests/test_domain_member.py -v` +Expected: ALL PASS + +- [ ] **Step 5: Commit** + +```bash +git add api/domain/member.py api/tests/test_domain_member.py +git commit -m "feat(sync-v4): add Member domain model with state machine" +``` + +--- + +### Task 3: SharedProject Domain Model + +**Files:** +- Create: `api/domain/project.py` +- Test: `api/tests/test_domain_project.py` + +**CAN PARALLEL with Tasks 1-2, 4-5** + +- [ ] **Step 1: Write failing tests** + +```python +# api/tests/test_domain_project.py +import sys +from pathlib import Path +sys.path.insert(0, str(Path(__file__).parent.parent)) + +import pytest +from domain.project import SharedProject, SharedProjectStatus, derive_folder_suffix +from domain.team import InvalidTransitionError + + +class TestSharedProjectCreation: + def test_create_project(self): + p = SharedProject( + team_name="t", + git_identity="jayantdevkar/claude-karma", + folder_suffix="jayantdevkar-claude-karma", + ) + assert p.status == SharedProjectStatus.SHARED + assert p.git_identity == "jayantdevkar/claude-karma" + assert p.encoded_name is None + + def test_create_project_with_encoded_name(self): + p = SharedProject( + team_name="t", + git_identity="jayantdevkar/claude-karma", + encoded_name="-Users-jayant-GitHub-claude-karma", + folder_suffix="jayantdevkar-claude-karma", + ) + assert p.encoded_name == "-Users-jayant-GitHub-claude-karma" + + def test_project_is_frozen(self): + p = SharedProject( + team_name="t", git_identity="o/r", folder_suffix="o-r", + ) + with pytest.raises(Exception): + p.git_identity = "other" + + +class TestSharedProjectRemove: + def test_remove_shared_project(self): + p = SharedProject( + team_name="t", git_identity="o/r", folder_suffix="o-r", + ) + removed = p.remove() + assert removed.status == SharedProjectStatus.REMOVED + + def test_remove_already_removed_raises(self): + p = SharedProject( + team_name="t", git_identity="o/r", folder_suffix="o-r", + status=SharedProjectStatus.REMOVED, + ) + with pytest.raises(InvalidTransitionError): + p.remove() + + +class TestDeriveFolderSuffix: + def test_simple_identity(self): + assert derive_folder_suffix("jayantdevkar/claude-karma") == "jayantdevkar-claude-karma" + + def test_nested_identity(self): + assert derive_folder_suffix("org/sub/repo") == "org-sub-repo" + + def test_strips_dotgit(self): + assert derive_folder_suffix("jayantdevkar/claude-karma.git") == "jayantdevkar-claude-karma" +``` + +- [ ] **Step 2: Run tests to verify they fail** + +Run: `cd api && pytest tests/test_domain_project.py -v` +Expected: FAIL + +- [ ] **Step 3: Implement SharedProject model** + +```python +# api/domain/project.py +"""SharedProject domain model — a git project shared with a team.""" +from __future__ import annotations + +from datetime import datetime, timezone +from enum import Enum + +from pydantic import BaseModel, ConfigDict, Field + +from domain.team import InvalidTransitionError + + +class SharedProjectStatus(str, Enum): + SHARED = "shared" + REMOVED = "removed" + + +def derive_folder_suffix(git_identity: str) -> str: + """Derive Syncthing folder suffix from git identity. + + 'jayantdevkar/claude-karma' → 'jayantdevkar-claude-karma' + 'jayantdevkar/claude-karma.git' → 'jayantdevkar-claude-karma' + """ + suffix = git_identity.replace("/", "-") + if suffix.endswith(".git"): + suffix = suffix[:-4] + return suffix + + +class SharedProject(BaseModel): + model_config = ConfigDict(frozen=True) + + team_name: str + git_identity: str + encoded_name: str | None = None + folder_suffix: str + status: SharedProjectStatus = SharedProjectStatus.SHARED + shared_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc)) + + def remove(self) -> SharedProject: + if self.status == SharedProjectStatus.REMOVED: + raise InvalidTransitionError( + f"Project '{self.git_identity}' is already removed" + ) + return self.model_copy(update={"status": SharedProjectStatus.REMOVED}) +``` + +- [ ] **Step 4: Run tests to verify they pass** + +Run: `cd api && pytest tests/test_domain_project.py -v` +Expected: ALL PASS + +- [ ] **Step 5: Commit** + +```bash +git add api/domain/project.py api/tests/test_domain_project.py +git commit -m "feat(sync-v4): add SharedProject domain model" +``` + +--- + +### Task 4: Subscription Domain Model + +**Files:** +- Create: `api/domain/subscription.py` +- Test: `api/tests/test_domain_subscription.py` + +**CAN PARALLEL with Tasks 1-3, 5** + +- [ ] **Step 1: Write failing tests** + +```python +# api/tests/test_domain_subscription.py +import sys +from pathlib import Path +sys.path.insert(0, str(Path(__file__).parent.parent)) + +import pytest +from domain.subscription import Subscription, SubscriptionStatus, SyncDirection +from domain.team import InvalidTransitionError + + +class TestSubscriptionCreation: + def test_defaults(self): + s = Subscription( + member_tag="a.l", team_name="t", + project_git_identity="o/r", + ) + assert s.status == SubscriptionStatus.OFFERED + assert s.direction == SyncDirection.BOTH + + def test_frozen(self): + s = Subscription(member_tag="a.l", team_name="t", project_git_identity="o/r") + with pytest.raises(Exception): + s.status = SubscriptionStatus.ACCEPTED + + +class TestSubscriptionAccept: + def test_accept_with_direction(self): + s = Subscription(member_tag="a.l", team_name="t", project_git_identity="o/r") + accepted = s.accept(SyncDirection.RECEIVE) + assert accepted.status == SubscriptionStatus.ACCEPTED + assert accepted.direction == SyncDirection.RECEIVE + + def test_accept_defaults_to_both(self): + s = Subscription(member_tag="a.l", team_name="t", project_git_identity="o/r") + accepted = s.accept() + assert accepted.direction == SyncDirection.BOTH + + def test_accept_from_non_offered_raises(self): + s = Subscription( + member_tag="a.l", team_name="t", project_git_identity="o/r", + status=SubscriptionStatus.ACCEPTED, + ) + with pytest.raises(InvalidTransitionError): + s.accept() + + +class TestSubscriptionPause: + def test_pause_from_accepted(self): + s = Subscription( + member_tag="a.l", team_name="t", project_git_identity="o/r", + status=SubscriptionStatus.ACCEPTED, + ) + paused = s.pause() + assert paused.status == SubscriptionStatus.PAUSED + + def test_pause_from_offered_raises(self): + s = Subscription(member_tag="a.l", team_name="t", project_git_identity="o/r") + with pytest.raises(InvalidTransitionError): + s.pause() + + +class TestSubscriptionResume: + def test_resume_from_paused(self): + s = Subscription( + member_tag="a.l", team_name="t", project_git_identity="o/r", + status=SubscriptionStatus.PAUSED, direction=SyncDirection.SEND, + ) + resumed = s.resume() + assert resumed.status == SubscriptionStatus.ACCEPTED + assert resumed.direction == SyncDirection.SEND # preserves direction + + def test_resume_from_accepted_raises(self): + s = Subscription( + member_tag="a.l", team_name="t", project_git_identity="o/r", + status=SubscriptionStatus.ACCEPTED, + ) + with pytest.raises(InvalidTransitionError): + s.resume() + + +class TestSubscriptionDecline: + def test_decline_from_offered(self): + s = Subscription(member_tag="a.l", team_name="t", project_git_identity="o/r") + declined = s.decline() + assert declined.status == SubscriptionStatus.DECLINED + + def test_decline_from_accepted(self): + s = Subscription( + member_tag="a.l", team_name="t", project_git_identity="o/r", + status=SubscriptionStatus.ACCEPTED, + ) + declined = s.decline() + assert declined.status == SubscriptionStatus.DECLINED + + def test_decline_from_paused(self): + s = Subscription( + member_tag="a.l", team_name="t", project_git_identity="o/r", + status=SubscriptionStatus.PAUSED, + ) + declined = s.decline() + assert declined.status == SubscriptionStatus.DECLINED + + def test_decline_from_declined_raises(self): + s = Subscription( + member_tag="a.l", team_name="t", project_git_identity="o/r", + status=SubscriptionStatus.DECLINED, + ) + with pytest.raises(InvalidTransitionError): + s.decline() + + +class TestSubscriptionChangeDirection: + def test_change_direction(self): + s = Subscription( + member_tag="a.l", team_name="t", project_git_identity="o/r", + status=SubscriptionStatus.ACCEPTED, direction=SyncDirection.BOTH, + ) + changed = s.change_direction(SyncDirection.RECEIVE) + assert changed.direction == SyncDirection.RECEIVE + assert changed.status == SubscriptionStatus.ACCEPTED + + def test_change_direction_when_not_accepted_raises(self): + s = Subscription(member_tag="a.l", team_name="t", project_git_identity="o/r") + with pytest.raises(InvalidTransitionError): + s.change_direction(SyncDirection.SEND) +``` + +- [ ] **Step 2: Run tests to verify they fail** + +Run: `cd api && pytest tests/test_domain_subscription.py -v` +Expected: FAIL + +- [ ] **Step 3: Implement Subscription model** + +```python +# api/domain/subscription.py +"""Subscription domain model — member-project relationship with sync direction.""" +from __future__ import annotations + +from datetime import datetime, timezone +from enum import Enum + +from pydantic import BaseModel, ConfigDict, Field + +from domain.team import InvalidTransitionError + + +class SubscriptionStatus(str, Enum): + OFFERED = "offered" + ACCEPTED = "accepted" + PAUSED = "paused" + DECLINED = "declined" + + +class SyncDirection(str, Enum): + RECEIVE = "receive" + SEND = "send" + BOTH = "both" + + +class Subscription(BaseModel): + model_config = ConfigDict(frozen=True) + + member_tag: str + team_name: str + project_git_identity: str + status: SubscriptionStatus = SubscriptionStatus.OFFERED + direction: SyncDirection = SyncDirection.BOTH + updated_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc)) + + def accept(self, direction: SyncDirection = SyncDirection.BOTH) -> Subscription: + if self.status != SubscriptionStatus.OFFERED: + raise InvalidTransitionError( + f"Can only accept from 'offered' state, currently '{self.status.value}'" + ) + return self.model_copy(update={ + "status": SubscriptionStatus.ACCEPTED, + "direction": direction, + "updated_at": datetime.now(timezone.utc), + }) + + def pause(self) -> Subscription: + if self.status != SubscriptionStatus.ACCEPTED: + raise InvalidTransitionError( + f"Can only pause from 'accepted' state, currently '{self.status.value}'" + ) + return self.model_copy(update={ + "status": SubscriptionStatus.PAUSED, + "updated_at": datetime.now(timezone.utc), + }) + + def resume(self) -> Subscription: + if self.status != SubscriptionStatus.PAUSED: + raise InvalidTransitionError( + f"Can only resume from 'paused' state, currently '{self.status.value}'" + ) + return self.model_copy(update={ + "status": SubscriptionStatus.ACCEPTED, + "updated_at": datetime.now(timezone.utc), + }) + + def decline(self) -> Subscription: + if self.status == SubscriptionStatus.DECLINED: + raise InvalidTransitionError("Already declined") + return self.model_copy(update={ + "status": SubscriptionStatus.DECLINED, + "updated_at": datetime.now(timezone.utc), + }) + + def change_direction(self, direction: SyncDirection) -> Subscription: + if self.status != SubscriptionStatus.ACCEPTED: + raise InvalidTransitionError( + f"Can only change direction in 'accepted' state, currently '{self.status.value}'" + ) + return self.model_copy(update={ + "direction": direction, + "updated_at": datetime.now(timezone.utc), + }) +``` + +- [ ] **Step 4: Run tests to verify they pass** + +Run: `cd api && pytest tests/test_domain_subscription.py -v` +Expected: ALL PASS + +- [ ] **Step 5: Commit** + +```bash +git add api/domain/subscription.py api/tests/test_domain_subscription.py +git commit -m "feat(sync-v4): add Subscription domain model with state machine" +``` + +--- + +### Task 5: SyncEvent Domain Model + +**Files:** +- Create: `api/domain/events.py` +- Test: `api/tests/test_domain_events.py` + +**CAN PARALLEL with Tasks 1-4** + +- [ ] **Step 1: Write failing tests** + +```python +# api/tests/test_domain_events.py +import sys +from pathlib import Path +sys.path.insert(0, str(Path(__file__).parent.parent)) + +import pytest +from domain.events import SyncEvent, SyncEventType + + +class TestSyncEventCreation: + def test_create_team_created_event(self): + event = SyncEvent( + event_type=SyncEventType.TEAM_CREATED, + team_name="karma-team", + ) + assert event.event_type == SyncEventType.TEAM_CREATED + assert event.team_name == "karma-team" + assert event.member_tag is None + assert event.created_at is not None + + def test_create_member_added_event_with_detail(self): + event = SyncEvent( + event_type=SyncEventType.MEMBER_ADDED, + team_name="karma-team", + member_tag="ayush.laptop", + detail={"device_id": "DEV-1", "added_by": "jayant.macbook"}, + ) + assert event.detail["device_id"] == "DEV-1" + assert event.detail["added_by"] == "jayant.macbook" + + def test_create_session_packaged_event(self): + event = SyncEvent( + event_type=SyncEventType.SESSION_PACKAGED, + team_name="t", + member_tag="j.m", + project_git_identity="o/r", + session_uuid="abc-123", + detail={"branches": ["main", "feature-x"]}, + ) + assert event.session_uuid == "abc-123" + assert event.project_git_identity == "o/r" + + def test_event_is_frozen(self): + event = SyncEvent(event_type=SyncEventType.TEAM_CREATED, team_name="t") + with pytest.raises(Exception): + event.team_name = "other" + + +class TestSyncEventTypes: + def test_all_event_types_exist(self): + expected = { + "team_created", "team_dissolved", + "member_added", "member_activated", "member_removed", "member_auto_left", + "project_shared", "project_removed", + "subscription_offered", "subscription_accepted", + "subscription_paused", "subscription_resumed", "subscription_declined", + "direction_changed", + "session_packaged", "session_received", + "device_paired", "device_unpaired", + } + actual = {e.value for e in SyncEventType} + assert actual == expected +``` + +- [ ] **Step 2: Run tests to verify they fail** + +Run: `cd api && pytest tests/test_domain_events.py -v` +Expected: FAIL + +- [ ] **Step 3: Implement SyncEvent model** + +```python +# api/domain/events.py +"""Sync event types for the audit trail.""" +from __future__ import annotations + +from datetime import datetime, timezone +from enum import Enum + +from pydantic import BaseModel, ConfigDict, Field + + +class SyncEventType(str, Enum): + TEAM_CREATED = "team_created" + TEAM_DISSOLVED = "team_dissolved" + MEMBER_ADDED = "member_added" + MEMBER_ACTIVATED = "member_activated" + MEMBER_REMOVED = "member_removed" + MEMBER_AUTO_LEFT = "member_auto_left" + PROJECT_SHARED = "project_shared" + PROJECT_REMOVED = "project_removed" + SUBSCRIPTION_OFFERED = "subscription_offered" + SUBSCRIPTION_ACCEPTED = "subscription_accepted" + SUBSCRIPTION_PAUSED = "subscription_paused" + SUBSCRIPTION_RESUMED = "subscription_resumed" + SUBSCRIPTION_DECLINED = "subscription_declined" + DIRECTION_CHANGED = "direction_changed" + SESSION_PACKAGED = "session_packaged" + SESSION_RECEIVED = "session_received" + DEVICE_PAIRED = "device_paired" + DEVICE_UNPAIRED = "device_unpaired" + + +class SyncEvent(BaseModel): + model_config = ConfigDict(frozen=True) + + event_type: SyncEventType + team_name: str | None = None + member_tag: str | None = None + project_git_identity: str | None = None + session_uuid: str | None = None + detail: dict | None = None + created_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc)) +``` + +- [ ] **Step 4: Run tests to verify they pass** + +Run: `cd api && pytest tests/test_domain_events.py -v` +Expected: ALL PASS + +- [ ] **Step 5: Commit** + +```bash +git add api/domain/events.py api/tests/test_domain_events.py +git commit -m "feat(sync-v4): add SyncEvent domain model with typed event types" +``` + +--- + +### Task 6: Schema v19 Migration + +**Files:** +- Modify: `api/db/schema.py` (add v19 migration) +- Test: `api/tests/test_schema_v19.py` + +**SEQUENTIAL — after Tasks 1-5 (needs domain model understanding)** + +- [ ] **Step 1: Write failing tests** + +```python +# api/tests/test_schema_v19.py +import sys +from pathlib import Path +sys.path.insert(0, str(Path(__file__).parent.parent)) + +import sqlite3 +import pytest +from db.schema import ensure_schema + + +@pytest.fixture +def conn(): + c = sqlite3.connect(":memory:") + c.row_factory = sqlite3.Row + c.execute("PRAGMA foreign_keys=ON") + ensure_schema(c) + return c + + +class TestV19Tables: + def test_sync_teams_exists(self, conn): + conn.execute("INSERT INTO sync_teams (name, leader_device_id, leader_member_tag) VALUES ('t', 'D', 'j.m')") + row = conn.execute("SELECT * FROM sync_teams WHERE name='t'").fetchone() + assert row["status"] == "active" + + def test_sync_members_exists(self, conn): + conn.execute("INSERT INTO sync_teams (name, leader_device_id, leader_member_tag) VALUES ('t', 'D', 'j.m')") + conn.execute( + "INSERT INTO sync_members (team_name, member_tag, device_id, user_id, machine_tag) " + "VALUES ('t', 'j.m', 'D', 'j', 'm')" + ) + row = conn.execute("SELECT * FROM sync_members WHERE member_tag='j.m'").fetchone() + assert row["status"] == "added" + assert row["updated_at"] is not None + + def test_sync_projects_pk_is_git_identity(self, conn): + conn.execute("INSERT INTO sync_teams (name, leader_device_id, leader_member_tag) VALUES ('t', 'D', 'j.m')") + conn.execute( + "INSERT INTO sync_projects (team_name, git_identity, folder_suffix) " + "VALUES ('t', 'owner/repo', 'owner-repo')" + ) + row = conn.execute("SELECT * FROM sync_projects WHERE git_identity='owner/repo'").fetchone() + assert row["encoded_name"] is None # nullable + assert row["status"] == "shared" + + def test_sync_subscriptions_exists(self, conn): + conn.execute("INSERT INTO sync_teams (name, leader_device_id, leader_member_tag) VALUES ('t', 'D', 'j.m')") + conn.execute( + "INSERT INTO sync_members (team_name, member_tag, device_id, user_id, machine_tag) " + "VALUES ('t', 'a.l', 'D2', 'a', 'l')" + ) + conn.execute( + "INSERT INTO sync_projects (team_name, git_identity, folder_suffix) " + "VALUES ('t', 'o/r', 'o-r')" + ) + conn.execute( + "INSERT INTO sync_subscriptions (member_tag, team_name, project_git_identity) " + "VALUES ('a.l', 't', 'o/r')" + ) + row = conn.execute("SELECT * FROM sync_subscriptions").fetchone() + assert row["status"] == "offered" + assert row["direction"] == "both" + + def test_sync_events_uses_git_identity_column(self, conn): + conn.execute( + "INSERT INTO sync_events (event_type, team_name, project_git_identity) " + "VALUES ('team_created', 't', 'o/r')" + ) + row = conn.execute("SELECT * FROM sync_events").fetchone() + assert row["project_git_identity"] == "o/r" + + +class TestV19Cascades: + def test_delete_team_cascades_members(self, conn): + conn.execute("INSERT INTO sync_teams (name, leader_device_id, leader_member_tag) VALUES ('t', 'D', 'j.m')") + conn.execute( + "INSERT INTO sync_members (team_name, member_tag, device_id, user_id, machine_tag) " + "VALUES ('t', 'a.l', 'D2', 'a', 'l')" + ) + conn.execute("DELETE FROM sync_teams WHERE name='t'") + assert conn.execute("SELECT COUNT(*) FROM sync_members").fetchone()[0] == 0 + + def test_delete_team_cascades_subscriptions(self, conn): + conn.execute("INSERT INTO sync_teams (name, leader_device_id, leader_member_tag) VALUES ('t', 'D', 'j.m')") + conn.execute( + "INSERT INTO sync_members (team_name, member_tag, device_id, user_id, machine_tag) " + "VALUES ('t', 'a.l', 'D2', 'a', 'l')" + ) + conn.execute( + "INSERT INTO sync_projects (team_name, git_identity, folder_suffix) VALUES ('t', 'o/r', 'o-r')" + ) + conn.execute( + "INSERT INTO sync_subscriptions (member_tag, team_name, project_git_identity) " + "VALUES ('a.l', 't', 'o/r')" + ) + conn.execute("DELETE FROM sync_teams WHERE name='t'") + assert conn.execute("SELECT COUNT(*) FROM sync_subscriptions").fetchone()[0] == 0 + + +class TestV19Constraints: + def test_team_status_check(self, conn): + with pytest.raises(sqlite3.IntegrityError): + conn.execute( + "INSERT INTO sync_teams (name, leader_device_id, leader_member_tag, status) " + "VALUES ('t', 'D', 'j.m', 'invalid')" + ) + + def test_member_status_check(self, conn): + conn.execute("INSERT INTO sync_teams (name, leader_device_id, leader_member_tag) VALUES ('t', 'D', 'j.m')") + with pytest.raises(sqlite3.IntegrityError): + conn.execute( + "INSERT INTO sync_members (team_name, member_tag, device_id, user_id, machine_tag, status) " + "VALUES ('t', 'a.l', 'D2', 'a', 'l', 'invalid')" + ) + + def test_subscription_direction_check(self, conn): + conn.execute("INSERT INTO sync_teams (name, leader_device_id, leader_member_tag) VALUES ('t', 'D', 'j.m')") + conn.execute( + "INSERT INTO sync_members (team_name, member_tag, device_id, user_id, machine_tag) " + "VALUES ('t', 'a.l', 'D2', 'a', 'l')" + ) + conn.execute( + "INSERT INTO sync_projects (team_name, git_identity, folder_suffix) VALUES ('t', 'o/r', 'o-r')" + ) + with pytest.raises(sqlite3.IntegrityError): + conn.execute( + "INSERT INTO sync_subscriptions (member_tag, team_name, project_git_identity, direction) " + "VALUES ('a.l', 't', 'o/r', 'invalid')" + ) +``` + +- [ ] **Step 2: Run tests to verify they fail** + +Run: `cd api && pytest tests/test_schema_v19.py -v` +Expected: FAIL — v19 tables don't exist yet + +- [ ] **Step 3: Add v19 migration to schema.py** + +Add the following migration block to `api/db/schema.py` inside the `ensure_schema()` function, after the v18 migration block. Read the file first to find the exact insertion point. + +```python +# v19: Sync v4 — domain model rewrite. Clean slate for sync tables. +if version < 19: + # Drop all v3 sync tables + cur.execute("DROP TABLE IF EXISTS sync_subscriptions") + cur.execute("DROP TABLE IF EXISTS sync_rejected_folders") + cur.execute("DROP TABLE IF EXISTS sync_settings") + cur.execute("DROP TABLE IF EXISTS sync_removed_members") + cur.execute("DROP TABLE IF EXISTS sync_events") + cur.execute("DROP TABLE IF EXISTS sync_team_projects") + cur.execute("DROP TABLE IF EXISTS sync_members") + cur.execute("DROP TABLE IF EXISTS sync_teams") + + # Recreate with v4 schema + cur.execute(""" + CREATE TABLE sync_teams ( + name TEXT PRIMARY KEY, + leader_device_id TEXT NOT NULL, + leader_member_tag TEXT NOT NULL, + status TEXT NOT NULL DEFAULT 'active' + CHECK(status IN ('active', 'dissolved')), + created_at TEXT NOT NULL DEFAULT (datetime('now')) + ) + """) + cur.execute(""" + CREATE TABLE sync_members ( + team_name TEXT NOT NULL REFERENCES sync_teams(name) ON DELETE CASCADE, + member_tag TEXT NOT NULL, + device_id TEXT NOT NULL, + user_id TEXT NOT NULL, + machine_tag TEXT NOT NULL, + status TEXT NOT NULL DEFAULT 'added' + CHECK(status IN ('added', 'active', 'removed')), + added_at TEXT NOT NULL DEFAULT (datetime('now')), + updated_at TEXT NOT NULL DEFAULT (datetime('now')), + PRIMARY KEY (team_name, member_tag) + ) + """) + cur.execute(""" + CREATE TABLE sync_projects ( + team_name TEXT NOT NULL REFERENCES sync_teams(name) ON DELETE CASCADE, + git_identity TEXT NOT NULL, + encoded_name TEXT, + folder_suffix TEXT NOT NULL, + status TEXT NOT NULL DEFAULT 'shared' + CHECK(status IN ('shared', 'removed')), + shared_at TEXT NOT NULL DEFAULT (datetime('now')), + PRIMARY KEY (team_name, git_identity) + ) + """) + cur.execute(""" + CREATE TABLE sync_subscriptions ( + member_tag TEXT NOT NULL, + team_name TEXT NOT NULL, + project_git_identity TEXT NOT NULL, + status TEXT NOT NULL DEFAULT 'offered' + CHECK(status IN ('offered', 'accepted', 'paused', 'declined')), + direction TEXT NOT NULL DEFAULT 'both' + CHECK(direction IN ('receive', 'send', 'both')), + updated_at TEXT NOT NULL DEFAULT (datetime('now')), + PRIMARY KEY (member_tag, team_name, project_git_identity), + FOREIGN KEY (team_name, member_tag) + REFERENCES sync_members(team_name, member_tag) ON DELETE CASCADE, + FOREIGN KEY (team_name, project_git_identity) + REFERENCES sync_projects(team_name, git_identity) ON DELETE CASCADE + ) + """) + cur.execute(""" + CREATE TABLE sync_events ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + event_type TEXT NOT NULL, + team_name TEXT, + member_tag TEXT, + project_git_identity TEXT, + session_uuid TEXT, + detail TEXT, + created_at TEXT NOT NULL DEFAULT (datetime('now')) + ) + """) + cur.execute(""" + CREATE TABLE sync_removed_members ( + team_name TEXT NOT NULL REFERENCES sync_teams(name) ON DELETE CASCADE, + device_id TEXT NOT NULL, + member_tag TEXT, + removed_at TEXT NOT NULL DEFAULT (datetime('now')), + PRIMARY KEY (team_name, device_id) + ) + """) + # Indexes + cur.execute("CREATE INDEX idx_members_device ON sync_members(device_id)") + cur.execute("CREATE INDEX idx_members_status ON sync_members(team_name, status)") + cur.execute("CREATE INDEX idx_projects_suffix ON sync_projects(folder_suffix)") + cur.execute("CREATE INDEX idx_projects_git ON sync_projects(git_identity)") + cur.execute("CREATE INDEX idx_subs_member ON sync_subscriptions(member_tag)") + cur.execute("CREATE INDEX idx_subs_status ON sync_subscriptions(status)") + cur.execute("CREATE INDEX idx_subs_project ON sync_subscriptions(project_git_identity)") + cur.execute("CREATE INDEX idx_events_type ON sync_events(event_type)") + cur.execute("CREATE INDEX idx_events_team ON sync_events(team_name)") + cur.execute("CREATE INDEX idx_events_time ON sync_events(created_at)") + + cur.execute("PRAGMA user_version = 19") +``` + +Also update the `CURRENT_VERSION` constant at the top of schema.py to `19`. + +- [ ] **Step 4: Run tests to verify they pass** + +Run: `cd api && pytest tests/test_schema_v19.py -v` +Expected: ALL PASS + +- [ ] **Step 5: Run existing tests to verify no regressions** + +Run: `cd api && pytest tests/test_db.py -v` +Expected: ALL PASS (existing tests should still work) + +- [ ] **Step 6: Commit** + +```bash +git add api/db/schema.py api/tests/test_schema_v19.py +git commit -m "feat(sync-v4): add v19 schema migration — clean slate sync tables" +``` + +--- + +### Task 7: Repositories + +**Files:** +- Create: `api/repositories/__init__.py` +- Create: `api/repositories/team_repo.py` +- Create: `api/repositories/member_repo.py` +- Create: `api/repositories/project_repo.py` +- Create: `api/repositories/subscription_repo.py` +- Create: `api/repositories/event_repo.py` +- Test: `api/tests/test_repo_team.py` +- Test: `api/tests/test_repo_member.py` +- Test: `api/tests/test_repo_project.py` +- Test: `api/tests/test_repo_subscription.py` +- Test: `api/tests/test_repo_event.py` + +**SEQUENTIAL — after Task 6 (needs schema). But 5 repos can be written in parallel.** + +Each repo follows the same pattern. I'll show TeamRepo in full; others follow the same structure. + +- [ ] **Step 1: Create repo package + write TeamRepo failing tests** + +```python +# api/repositories/__init__.py +"""Sync v4 repositories — thin SQLite persistence layer.""" + +# api/tests/test_repo_team.py +import sys +from pathlib import Path +sys.path.insert(0, str(Path(__file__).parent.parent)) + +import sqlite3 +import pytest +from db.schema import ensure_schema +from domain.team import Team, TeamStatus +from repositories.team_repo import TeamRepository + + +@pytest.fixture +def conn(): + c = sqlite3.connect(":memory:") + c.row_factory = sqlite3.Row + c.execute("PRAGMA foreign_keys=ON") + ensure_schema(c) + return c + + +@pytest.fixture +def repo(): + return TeamRepository() + + +class TestTeamRepoSave: + def test_save_new_team(self, conn, repo): + team = Team(name="t", leader_device_id="D", leader_member_tag="j.m") + repo.save(conn, team) + result = repo.get(conn, "t") + assert result is not None + assert result.name == "t" + assert result.status == TeamStatus.ACTIVE + + def test_save_updates_existing(self, conn, repo): + team = Team(name="t", leader_device_id="D", leader_member_tag="j.m") + repo.save(conn, team) + dissolved = team.dissolve(by_device="D") + repo.save(conn, dissolved) + result = repo.get(conn, "t") + assert result.status == TeamStatus.DISSOLVED + + +class TestTeamRepoGet: + def test_get_nonexistent_returns_none(self, conn, repo): + assert repo.get(conn, "nope") is None + + +class TestTeamRepoList: + def test_list_all(self, conn, repo): + repo.save(conn, Team(name="a", leader_device_id="D1", leader_member_tag="j.m1")) + repo.save(conn, Team(name="b", leader_device_id="D2", leader_member_tag="j.m2")) + teams = repo.list_all(conn) + assert len(teams) == 2 + names = {t.name for t in teams} + assert names == {"a", "b"} + + +class TestTeamRepoDelete: + def test_delete_team(self, conn, repo): + repo.save(conn, Team(name="t", leader_device_id="D", leader_member_tag="j.m")) + repo.delete(conn, "t") + assert repo.get(conn, "t") is None + + +class TestTeamRepoGetByLeader: + def test_get_by_leader(self, conn, repo): + repo.save(conn, Team(name="t1", leader_device_id="D", leader_member_tag="j.m")) + repo.save(conn, Team(name="t2", leader_device_id="D", leader_member_tag="j.m")) + repo.save(conn, Team(name="t3", leader_device_id="OTHER", leader_member_tag="a.l")) + teams = repo.get_by_leader(conn, "D") + assert len(teams) == 2 +``` + +- [ ] **Step 2: Run tests to verify they fail** + +Run: `cd api && pytest tests/test_repo_team.py -v` +Expected: FAIL + +- [ ] **Step 3: Implement TeamRepository** + +```python +# api/repositories/team_repo.py +"""Team repository — SQLite persistence for Team domain model.""" +from __future__ import annotations + +import sqlite3 +from datetime import datetime, timezone + +from domain.team import Team, TeamStatus + + +class TeamRepository: + def get(self, conn: sqlite3.Connection, name: str) -> Team | None: + row = conn.execute( + "SELECT * FROM sync_teams WHERE name = ?", (name,) + ).fetchone() + if row is None: + return None + return self._row_to_team(row) + + def get_by_leader(self, conn: sqlite3.Connection, device_id: str) -> list[Team]: + rows = conn.execute( + "SELECT * FROM sync_teams WHERE leader_device_id = ?", (device_id,) + ).fetchall() + return [self._row_to_team(r) for r in rows] + + def save(self, conn: sqlite3.Connection, team: Team) -> None: + conn.execute( + """INSERT INTO sync_teams (name, leader_device_id, leader_member_tag, status, created_at) + VALUES (?, ?, ?, ?, ?) + ON CONFLICT(name) DO UPDATE SET + leader_device_id = excluded.leader_device_id, + leader_member_tag = excluded.leader_member_tag, + status = excluded.status""", + (team.name, team.leader_device_id, team.leader_member_tag, + team.status.value, team.created_at.isoformat()), + ) + conn.commit() + + def delete(self, conn: sqlite3.Connection, name: str) -> None: + conn.execute("DELETE FROM sync_teams WHERE name = ?", (name,)) + conn.commit() + + def list_all(self, conn: sqlite3.Connection) -> list[Team]: + rows = conn.execute("SELECT * FROM sync_teams").fetchall() + return [self._row_to_team(r) for r in rows] + + @staticmethod + def _row_to_team(row: sqlite3.Row) -> Team: + return Team( + name=row["name"], + leader_device_id=row["leader_device_id"], + leader_member_tag=row["leader_member_tag"], + status=TeamStatus(row["status"]), + created_at=datetime.fromisoformat(row["created_at"]), + ) +``` + +- [ ] **Step 4: Run tests to verify they pass** + +Run: `cd api && pytest tests/test_repo_team.py -v` +Expected: ALL PASS + +- [ ] **Step 5: Write and implement remaining 4 repos (parallel)** + +Each repo follows the same pattern as TeamRepository. Key method signatures: + +**MemberRepository** (`api/repositories/member_repo.py`): +```python +class MemberRepository: + def get(self, conn, team_name: str, member_tag: str) -> Member | None + def get_by_device(self, conn, device_id: str) -> list[Member] + def save(self, conn, member: Member) -> None # UPSERT on (team_name, member_tag) + def list_for_team(self, conn, team_name: str) -> list[Member] + def was_removed(self, conn, team_name: str, device_id: str) -> bool + def record_removal(self, conn, team_name: str, device_id: str, member_tag: str = None) -> None +``` + +**ProjectRepository** (`api/repositories/project_repo.py`): +```python +class ProjectRepository: + def get(self, conn, team_name: str, git_identity: str) -> SharedProject | None + def save(self, conn, project: SharedProject) -> None # UPSERT on (team_name, git_identity) + def list_for_team(self, conn, team_name: str) -> list[SharedProject] + def find_by_suffix(self, conn, suffix: str) -> list[SharedProject] + def find_by_git_identity(self, conn, git_identity: str) -> list[SharedProject] +``` + +**SubscriptionRepository** (`api/repositories/subscription_repo.py`): +```python +class SubscriptionRepository: + def get(self, conn, member_tag: str, team_name: str, git_identity: str) -> Subscription | None + def save(self, conn, sub: Subscription) -> None # UPSERT on (member_tag, team_name, project_git_identity) + def list_for_member(self, conn, member_tag: str) -> list[Subscription] + def list_for_project(self, conn, team_name: str, git_identity: str) -> list[Subscription] + def list_accepted_for_suffix(self, conn, suffix: str) -> list[Subscription] +``` + +**EventRepository** (`api/repositories/event_repo.py`): +```python +class EventRepository: + def log(self, conn, event: SyncEvent) -> int # returns event id + def query(self, conn, *, team: str = None, event_type: str = None, limit: int = 50) -> list[SyncEvent] +``` + +Write test files: `test_repo_member.py`, `test_repo_project.py`, `test_repo_subscription.py`, `test_repo_event.py`. Follow the same test patterns as `test_repo_team.py`: fixture creates in-memory SQLite + `ensure_schema()`, tests cover save/get/list/edge cases. + +- [ ] **Step 6: Run all repo tests** + +Run: `cd api && pytest tests/test_repo_*.py -v` +Expected: ALL PASS + +- [ ] **Step 7: Commit** + +```bash +git add api/repositories/ api/tests/test_repo_*.py +git commit -m "feat(sync-v4): add repositories for all domain models" +``` + +--- + +### Task 8: Phase 1 Integration Test + +**Files:** +- Test: `api/tests/test_sync_v4_foundation.py` + +**SEQUENTIAL — after Task 7. Verifies the full domain→repo stack works together.** + +- [ ] **Step 1: Write integration test** + +```python +# api/tests/test_sync_v4_foundation.py +"""Integration test: domain models + repositories working together.""" +import sys +from pathlib import Path +sys.path.insert(0, str(Path(__file__).parent.parent)) + +import sqlite3 +import pytest +from db.schema import ensure_schema +from domain.team import Team, AuthorizationError +from domain.member import Member, MemberStatus +from domain.project import SharedProject, derive_folder_suffix +from domain.subscription import Subscription, SubscriptionStatus, SyncDirection +from domain.events import SyncEvent, SyncEventType +from repositories.team_repo import TeamRepository +from repositories.member_repo import MemberRepository +from repositories.project_repo import ProjectRepository +from repositories.subscription_repo import SubscriptionRepository +from repositories.event_repo import EventRepository + + +@pytest.fixture +def conn(): + c = sqlite3.connect(":memory:") + c.row_factory = sqlite3.Row + c.execute("PRAGMA foreign_keys=ON") + ensure_schema(c) + return c + + +class TestFullWorkflow: + """Simulates: create team → add member → share project → accept subscription.""" + + def test_leader_creates_team_and_adds_member(self, conn): + teams = TeamRepository() + members = MemberRepository() + projects = ProjectRepository() + subs = SubscriptionRepository() + events = EventRepository() + + # 1. Leader creates team + team = Team(name="karma", leader_device_id="DEV-L", leader_member_tag="jayant.macbook") + teams.save(conn, team) + leader = Member( + member_tag="jayant.macbook", team_name="karma", + device_id="DEV-L", user_id="jayant", machine_tag="macbook", + status=MemberStatus.ACTIVE, + ) + members.save(conn, leader) + + # 2. Leader adds member + new_member = Member.from_member_tag( + member_tag="ayush.laptop", team_name="karma", device_id="DEV-A", + ) + added = team.add_member(new_member, by_device="DEV-L") + members.save(conn, added) + + # Verify member persisted + loaded = members.get(conn, "karma", "ayush.laptop") + assert loaded is not None + assert loaded.status == MemberStatus.ADDED + + # 3. Leader shares project + project = SharedProject( + team_name="karma", + git_identity="jayantdevkar/claude-karma", + folder_suffix=derive_folder_suffix("jayantdevkar/claude-karma"), + ) + projects.save(conn, project) + + # 4. Create subscription for new member + sub = Subscription( + member_tag="ayush.laptop", team_name="karma", + project_git_identity="jayantdevkar/claude-karma", + ) + subs.save(conn, sub) + + # 5. Member activates (device acknowledged) + loaded_member = members.get(conn, "karma", "ayush.laptop") + activated = loaded_member.activate() + members.save(conn, activated) + assert members.get(conn, "karma", "ayush.laptop").status == MemberStatus.ACTIVE + + # 6. Member accepts subscription + loaded_sub = subs.get(conn, "ayush.laptop", "karma", "jayantdevkar/claude-karma") + accepted = loaded_sub.accept(SyncDirection.BOTH) + subs.save(conn, accepted) + final_sub = subs.get(conn, "ayush.laptop", "karma", "jayantdevkar/claude-karma") + assert final_sub.status == SubscriptionStatus.ACCEPTED + assert final_sub.direction == SyncDirection.BOTH + + # 7. Log events + events.log(conn, SyncEvent( + event_type=SyncEventType.TEAM_CREATED, team_name="karma", + )) + events.log(conn, SyncEvent( + event_type=SyncEventType.MEMBER_ADDED, team_name="karma", + member_tag="ayush.laptop", + detail={"device_id": "DEV-A", "added_by": "jayant.macbook"}, + )) + logged = events.query(conn, team="karma") + assert len(logged) == 2 + + def test_non_leader_cannot_remove_member(self, conn): + teams = TeamRepository() + team = Team(name="t", leader_device_id="DEV-L", leader_member_tag="j.m") + teams.save(conn, team) + + member = Member( + member_tag="a.l", team_name="t", device_id="DEV-A", + user_id="a", machine_tag="l", status=MemberStatus.ACTIVE, + ) + with pytest.raises(AuthorizationError): + team.remove_member(member, by_device="DEV-A") # member tries to remove self + + def test_cascade_on_team_delete(self, conn): + teams = TeamRepository() + members = MemberRepository() + projects = ProjectRepository() + subs = SubscriptionRepository() + + team = Team(name="t", leader_device_id="D", leader_member_tag="j.m") + teams.save(conn, team) + members.save(conn, Member( + member_tag="a.l", team_name="t", device_id="D2", + user_id="a", machine_tag="l", + )) + projects.save(conn, SharedProject( + team_name="t", git_identity="o/r", folder_suffix="o-r", + )) + subs.save(conn, Subscription( + member_tag="a.l", team_name="t", project_git_identity="o/r", + )) + + teams.delete(conn, "t") + + assert members.list_for_team(conn, "t") == [] + assert projects.list_for_team(conn, "t") == [] + assert subs.list_for_member(conn, "a.l") == [] +``` + +- [ ] **Step 2: Run integration test** + +Run: `cd api && pytest tests/test_sync_v4_foundation.py -v` +Expected: ALL PASS + +- [ ] **Step 3: Run full Phase 1 test suite** + +Run: `cd api && pytest tests/test_domain_*.py tests/test_schema_v19.py tests/test_repo_*.py tests/test_sync_v4_foundation.py -v` +Expected: ALL PASS + +- [ ] **Step 4: Commit** + +```bash +git add api/tests/test_sync_v4_foundation.py +git commit -m "test(sync-v4): add Phase 1 integration test — full domain+repo workflow" +``` + +--- + +## Phase 1 Completion Checklist + +- [ ] All 5 domain models implemented with state machines +- [ ] v19 schema migration applied +- [ ] All 5 repositories implemented +- [ ] Integration test passes +- [ ] No regressions in existing test suite: `cd api && pytest -v` +- [ ] All Phase 1 code committed diff --git a/docs/superpowers/plans/2026-03-17-sync-v4-phase2-infrastructure.md b/docs/superpowers/plans/2026-03-17-sync-v4-phase2-infrastructure.md new file mode 100644 index 00000000..c390cff2 --- /dev/null +++ b/docs/superpowers/plans/2026-03-17-sync-v4-phase2-infrastructure.md @@ -0,0 +1,908 @@ +# Sync v4 Phase 2: Infrastructure — Syncthing Abstraction + Pairing + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. +> +> **TDD SKILL:** Use `oh-my-claudecode:tdd` or `superpowers:test-driven-development` for every task. + +**Goal:** Build the Syncthing HTTP abstraction (client, device manager, folder manager) and the pairing code service. + +**Architecture:** SyncthingClient is a pure HTTP wrapper (no business logic). DeviceManager and FolderManager use SyncthingClient for device/folder operations. PairingService encodes/decodes member identity into shareable codes. + +**Tech Stack:** Python 3.9+, httpx (async HTTP), pytest, base32 encoding + +**Spec:** `docs/superpowers/specs/2026-03-17-sync-v4-domain-models-design.md` (sections: Syncthing Abstraction, Pairing Codes) + +**Parent Plan:** `docs/superpowers/plans/2026-03-17-sync-v4-master.md` + +**CAN RUN IN PARALLEL WITH PHASE 1** — no shared dependencies. + +--- + +## Task Dependency Graph + +``` +Task 1 (SyncthingClient) ──→ Task 2 (DeviceManager) ──→ Task 5 (Integration) + ──→ Task 3 (FolderManager) ──↗ +Task 4 (PairingService) ─── INDEPENDENT ────────────────↗ +``` + +--- + +### Task 1: SyncthingClient — Pure HTTP Wrapper + +**Files:** +- Create: `api/services/syncthing/__init__.py` +- Create: `api/services/syncthing/client.py` +- Test: `api/tests/test_syncthing_client.py` + +**Reference:** Existing `api/services/syncthing_proxy.py` for Syncthing REST API patterns. The new client extracts ONLY the HTTP calls — no business logic. + +- [ ] **Step 1: Write failing tests** + +```python +# api/tests/test_syncthing_client.py +import sys +from pathlib import Path +sys.path.insert(0, str(Path(__file__).parent.parent)) + +import pytest +from unittest.mock import AsyncMock, patch, MagicMock +from services.syncthing.client import SyncthingClient + + +@pytest.fixture +def client(): + return SyncthingClient(api_url="http://localhost:8384", api_key="test-key") + + +class TestSyncthingClientConfig: + def test_init(self, client): + assert client.api_url == "http://localhost:8384" + assert client.api_key == "test-key" + + def test_headers_include_api_key(self, client): + headers = client._headers() + assert headers["X-API-Key"] == "test-key" + + +class TestSyncthingClientSystemEndpoints: + @pytest.mark.asyncio + async def test_get_system_status(self, client): + mock_response = MagicMock() + mock_response.status_code = 200 + mock_response.json.return_value = {"myID": "DEVICE-ID-123"} + + with patch.object(client, "_get", new_callable=AsyncMock, return_value=mock_response.json.return_value): + result = await client.get_system_status() + assert result["myID"] == "DEVICE-ID-123" + + @pytest.mark.asyncio + async def test_get_connections(self, client): + with patch.object(client, "_get", new_callable=AsyncMock, return_value={"connections": {}}): + result = await client.get_connections() + assert "connections" in result + + +class TestSyncthingClientConfigEndpoints: + @pytest.mark.asyncio + async def test_get_config(self, client): + mock_config = {"devices": [], "folders": []} + with patch.object(client, "_get", new_callable=AsyncMock, return_value=mock_config): + result = await client.get_config() + assert "devices" in result + assert "folders" in result + + @pytest.mark.asyncio + async def test_post_config(self, client): + with patch.object(client, "_put", new_callable=AsyncMock) as mock_put: + await client.post_config({"devices": [], "folders": []}) + mock_put.assert_called_once() + + +class TestSyncthingClientPendingEndpoints: + @pytest.mark.asyncio + async def test_get_pending_devices(self, client): + with patch.object(client, "_get", new_callable=AsyncMock, return_value={}): + result = await client.get_pending_devices() + assert isinstance(result, dict) + + @pytest.mark.asyncio + async def test_get_pending_folders(self, client): + with patch.object(client, "_get", new_callable=AsyncMock, return_value={}): + result = await client.get_pending_folders() + assert isinstance(result, dict) +``` + +- [ ] **Step 2: Run tests to verify they fail** + +Run: `cd api && pytest tests/test_syncthing_client.py -v` +Expected: FAIL — `No module named 'services.syncthing'` + +- [ ] **Step 3: Implement SyncthingClient** + +```python +# api/services/syncthing/__init__.py +"""Syncthing abstraction layer — HTTP client, device manager, folder manager.""" + +# api/services/syncthing/client.py +"""Pure HTTP wrapper for Syncthing REST API. No business logic.""" +from __future__ import annotations + +import httpx + + +class SyncthingClient: + """Maps 1:1 to Syncthing REST API endpoints.""" + + def __init__(self, api_url: str, api_key: str, timeout: float = 30.0): + self.api_url = api_url.rstrip("/") + self.api_key = api_key + self.timeout = timeout + + def _headers(self) -> dict[str, str]: + return {"X-API-Key": self.api_key} + + async def _get(self, path: str) -> dict: + async with httpx.AsyncClient(timeout=self.timeout) as client: + resp = await client.get( + f"{self.api_url}{path}", headers=self._headers() + ) + resp.raise_for_status() + return resp.json() + + async def _put(self, path: str, data: dict) -> None: + async with httpx.AsyncClient(timeout=self.timeout) as client: + resp = await client.put( + f"{self.api_url}{path}", headers=self._headers(), json=data + ) + resp.raise_for_status() + + async def _post(self, path: str, data: dict = None) -> dict | None: + async with httpx.AsyncClient(timeout=self.timeout) as client: + resp = await client.post( + f"{self.api_url}{path}", headers=self._headers(), json=data + ) + resp.raise_for_status() + if resp.content: + return resp.json() + return None + + async def _delete(self, path: str, params: dict = None) -> None: + async with httpx.AsyncClient(timeout=self.timeout) as client: + resp = await client.delete( + f"{self.api_url}{path}", headers=self._headers(), params=params + ) + resp.raise_for_status() + + # --- System endpoints --- + async def get_system_status(self) -> dict: + return await self._get("/rest/system/status") + + async def get_connections(self) -> dict: + return await self._get("/rest/system/connections") + + # --- Config endpoints --- + async def get_config(self) -> dict: + return await self._get("/rest/config") + + async def post_config(self, config: dict) -> None: + await self._put("/rest/config", config) + + async def get_config_devices(self) -> list[dict]: + return await self._get("/rest/config/devices") + + async def put_config_device(self, device: dict) -> None: + await self._put(f"/rest/config/devices/{device['deviceID']}", device) + + async def delete_config_device(self, device_id: str) -> None: + await self._delete(f"/rest/config/devices/{device_id}") + + async def get_config_folders(self) -> list[dict]: + return await self._get("/rest/config/folders") + + async def put_config_folder(self, folder: dict) -> None: + await self._put(f"/rest/config/folders/{folder['id']}", folder) + + async def delete_config_folder(self, folder_id: str) -> None: + await self._delete(f"/rest/config/folders/{folder_id}") + + # --- Pending endpoints --- + async def get_pending_devices(self) -> dict: + return await self._get("/rest/cluster/pending/devices") + + async def get_pending_folders(self) -> dict: + return await self._get("/rest/cluster/pending/folders") + + # --- Folder status --- + async def get_folder_status(self, folder_id: str) -> dict: + return await self._get(f"/rest/db/status?folder={folder_id}") + + async def post_folder_rescan(self, folder_id: str) -> None: + await self._post(f"/rest/db/scan?folder={folder_id}") + + # --- Bandwidth --- + async def get_system_connections(self) -> dict: + return await self._get("/rest/system/connections") +``` + +- [ ] **Step 4: Run tests to verify they pass** + +Run: `cd api && pytest tests/test_syncthing_client.py -v` +Expected: ALL PASS + +- [ ] **Step 5: Commit** + +```bash +git add api/services/syncthing/__init__.py api/services/syncthing/client.py api/tests/test_syncthing_client.py +git commit -m "feat(sync-v4): add SyncthingClient — pure HTTP wrapper" +``` + +--- + +### Task 2: DeviceManager + +**Files:** +- Create: `api/services/syncthing/device_manager.py` +- Test: `api/tests/test_device_manager.py` + +**CAN PARALLEL with Task 3. Depends on Task 1.** + +- [ ] **Step 1: Write failing tests** + +```python +# api/tests/test_device_manager.py +import sys +from pathlib import Path +sys.path.insert(0, str(Path(__file__).parent.parent)) + +import pytest +from unittest.mock import AsyncMock, MagicMock +from services.syncthing.device_manager import DeviceManager + + +@pytest.fixture +def mock_client(): + client = MagicMock() + client.get_config = AsyncMock(return_value={ + "devices": [ + {"deviceID": "DEV-1", "name": "jayant-macbook"}, + {"deviceID": "DEV-2", "name": "ayush-laptop"}, + ], + "folders": [], + }) + client.put_config_device = AsyncMock() + client.delete_config_device = AsyncMock() + client.get_connections = AsyncMock(return_value={ + "connections": { + "DEV-1": {"connected": True}, + "DEV-2": {"connected": False}, + } + }) + return client + + +@pytest.fixture +def manager(mock_client): + return DeviceManager(mock_client) + + +class TestDevicePairing: + @pytest.mark.asyncio + async def test_pair_adds_device(self, manager, mock_client): + mock_client.get_config = AsyncMock(return_value={"devices": [], "folders": []}) + await manager.pair("DEV-NEW") + mock_client.put_config_device.assert_called_once() + call_data = mock_client.put_config_device.call_args[0][0] + assert call_data["deviceID"] == "DEV-NEW" + + @pytest.mark.asyncio + async def test_ensure_paired_skips_existing(self, manager, mock_client): + await manager.ensure_paired("DEV-1") # already in config + mock_client.put_config_device.assert_not_called() + + @pytest.mark.asyncio + async def test_ensure_paired_adds_missing(self, manager, mock_client): + await manager.ensure_paired("DEV-NEW") + mock_client.put_config_device.assert_called_once() + + +class TestDeviceUnpairing: + @pytest.mark.asyncio + async def test_unpair_removes_device(self, manager, mock_client): + await manager.unpair("DEV-1") + mock_client.delete_config_device.assert_called_once_with("DEV-1") + + +class TestDeviceConnection: + @pytest.mark.asyncio + async def test_is_connected_true(self, manager): + assert await manager.is_connected("DEV-1") is True + + @pytest.mark.asyncio + async def test_is_connected_false(self, manager): + assert await manager.is_connected("DEV-2") is False + + @pytest.mark.asyncio + async def test_is_connected_unknown(self, manager): + assert await manager.is_connected("DEV-UNKNOWN") is False + + @pytest.mark.asyncio + async def test_list_connected(self, manager): + connected = await manager.list_connected() + assert connected == ["DEV-1"] +``` + +- [ ] **Step 2: Run tests to verify they fail** + +Run: `cd api && pytest tests/test_device_manager.py -v` +Expected: FAIL + +- [ ] **Step 3: Implement DeviceManager** + +```python +# api/services/syncthing/device_manager.py +"""Device pairing operations using SyncthingClient.""" +from __future__ import annotations + +from services.syncthing.client import SyncthingClient + + +class DeviceManager: + def __init__(self, client: SyncthingClient): + self.client = client + + async def _get_device_ids(self) -> set[str]: + config = await self.client.get_config() + return {d["deviceID"] for d in config.get("devices", [])} + + async def pair(self, device_id: str, name: str = "") -> None: + """Add a device to Syncthing config.""" + await self.client.put_config_device({ + "deviceID": device_id, + "name": name, + "addresses": ["dynamic"], + "autoAcceptFolders": False, + }) + + async def unpair(self, device_id: str) -> None: + """Remove a device from Syncthing config.""" + await self.client.delete_config_device(device_id) + + async def ensure_paired(self, device_id: str, name: str = "") -> None: + """Pair if not already paired. Idempotent.""" + known = await self._get_device_ids() + if device_id not in known: + await self.pair(device_id, name) + + async def is_connected(self, device_id: str) -> bool: + """Check if a device is currently connected.""" + conns = await self.client.get_connections() + device_info = conns.get("connections", {}).get(device_id, {}) + return device_info.get("connected", False) + + async def list_connected(self) -> list[str]: + """List all currently connected device IDs.""" + conns = await self.client.get_connections() + return [ + did for did, info in conns.get("connections", {}).items() + if info.get("connected", False) + ] +``` + +- [ ] **Step 4: Run tests to verify they pass** + +Run: `cd api && pytest tests/test_device_manager.py -v` +Expected: ALL PASS + +- [ ] **Step 5: Commit** + +```bash +git add api/services/syncthing/device_manager.py api/tests/test_device_manager.py +git commit -m "feat(sync-v4): add DeviceManager — pair/unpair/connection status" +``` + +--- + +### Task 3: FolderManager + +**Files:** +- Create: `api/services/syncthing/folder_manager.py` +- Test: `api/tests/test_folder_manager.py` + +**CAN PARALLEL with Task 2. Depends on Task 1.** + +- [ ] **Step 1: Write failing tests** + +```python +# api/tests/test_folder_manager.py +import sys +from pathlib import Path +sys.path.insert(0, str(Path(__file__).parent.parent)) + +import pytest +from unittest.mock import AsyncMock, MagicMock +from services.syncthing.folder_manager import FolderManager + + +@pytest.fixture +def mock_client(): + client = MagicMock() + client.get_config = AsyncMock(return_value={ + "devices": [], + "folders": [ + {"id": "karma-out--jayant.macbook--owner-repo", "devices": [{"deviceID": "DEV-1"}]}, + ], + }) + client.put_config_folder = AsyncMock() + client.delete_config_folder = AsyncMock() + client.get_config_folders = AsyncMock(return_value=[ + {"id": "karma-out--jayant.macbook--owner-repo", "devices": [{"deviceID": "DEV-1"}]}, + ]) + return client + + +@pytest.fixture +def manager(mock_client): + return FolderManager(mock_client, karma_base=Path("/tmp/test-karma")) + + +class TestEnsureOutboxFolder: + @pytest.mark.asyncio + async def test_creates_outbox_folder(self, manager, mock_client): + mock_client.get_config_folders = AsyncMock(return_value=[]) + await manager.ensure_outbox_folder( + member_tag="jayant.macbook", + folder_suffix="owner-repo", + ) + mock_client.put_config_folder.assert_called_once() + folder = mock_client.put_config_folder.call_args[0][0] + assert folder["id"] == "karma-out--jayant.macbook--owner-repo" + assert folder["type"] == "sendonly" + + @pytest.mark.asyncio + async def test_skips_existing_outbox(self, manager, mock_client): + await manager.ensure_outbox_folder( + member_tag="jayant.macbook", + folder_suffix="owner-repo", + ) + mock_client.put_config_folder.assert_not_called() + + +class TestEnsureInboxFolder: + @pytest.mark.asyncio + async def test_creates_inbox_folder(self, manager, mock_client): + mock_client.get_config_folders = AsyncMock(return_value=[]) + await manager.ensure_inbox_folder( + remote_member_tag="ayush.laptop", + folder_suffix="owner-repo", + remote_device_id="DEV-A", + ) + mock_client.put_config_folder.assert_called_once() + folder = mock_client.put_config_folder.call_args[0][0] + assert folder["id"] == "karma-out--ayush.laptop--owner-repo" + assert folder["type"] == "receiveonly" + + +class TestSetFolderDevices: + @pytest.mark.asyncio + async def test_set_folder_devices_replaces_list(self, manager, mock_client): + await manager.set_folder_devices( + "karma-out--jayant.macbook--owner-repo", + {"DEV-1", "DEV-2", "DEV-3"}, + ) + mock_client.put_config_folder.assert_called_once() + folder = mock_client.put_config_folder.call_args[0][0] + device_ids = {d["deviceID"] for d in folder["devices"]} + assert device_ids == {"DEV-1", "DEV-2", "DEV-3"} + + +class TestRemoveOutboxFolder: + @pytest.mark.asyncio + async def test_removes_folder(self, manager, mock_client): + await manager.remove_outbox_folder( + member_tag="jayant.macbook", + folder_suffix="owner-repo", + ) + mock_client.delete_config_folder.assert_called_once_with( + "karma-out--jayant.macbook--owner-repo" + ) + + +class TestCleanupTeamFolders: + @pytest.mark.asyncio + async def test_cleanup_removes_matching_folders(self, manager, mock_client): + mock_client.get_config_folders = AsyncMock(return_value=[ + {"id": "karma-out--jayant.macbook--owner-repo"}, + {"id": "karma-meta--karma-team"}, + {"id": "unrelated-folder"}, + ]) + await manager.cleanup_team_folders( + folder_suffixes=["owner-repo"], + member_tags=["jayant.macbook"], + team_name="karma-team", + ) + # Should delete karma-out and karma-meta folders, not unrelated + assert mock_client.delete_config_folder.call_count >= 2 +``` + +- [ ] **Step 2: Run tests to verify they fail** + +Run: `cd api && pytest tests/test_folder_manager.py -v` +Expected: FAIL + +- [ ] **Step 3: Implement FolderManager** + +```python +# api/services/syncthing/folder_manager.py +"""Folder lifecycle management using SyncthingClient.""" +from __future__ import annotations + +from pathlib import Path + +from services.syncthing.client import SyncthingClient + + +def build_outbox_folder_id(member_tag: str, folder_suffix: str) -> str: + return f"karma-out--{member_tag}--{folder_suffix}" + + +def build_metadata_folder_id(team_name: str) -> str: + return f"karma-meta--{team_name}" + + +class FolderManager: + def __init__(self, client: SyncthingClient, karma_base: Path): + self.client = client + self.karma_base = karma_base + + async def _get_folder_ids(self) -> set[str]: + folders = await self.client.get_config_folders() + return {f["id"] for f in folders} + + async def _get_folder(self, folder_id: str) -> dict | None: + folders = await self.client.get_config_folders() + for f in folders: + if f["id"] == folder_id: + return f + return None + + async def ensure_outbox_folder(self, member_tag: str, folder_suffix: str) -> None: + """Create sendonly outbox folder if not exists.""" + folder_id = build_outbox_folder_id(member_tag, folder_suffix) + if folder_id in await self._get_folder_ids(): + return + folder_path = self.karma_base / "outboxes" / folder_id + await self.client.put_config_folder({ + "id": folder_id, + "path": str(folder_path), + "type": "sendonly", + "devices": [], + "rescanIntervalS": 60, + }) + + async def ensure_inbox_folder( + self, remote_member_tag: str, folder_suffix: str, remote_device_id: str + ) -> None: + """Create receiveonly inbox folder for a remote member's outbox.""" + folder_id = build_outbox_folder_id(remote_member_tag, folder_suffix) + if folder_id in await self._get_folder_ids(): + return + folder_path = self.karma_base / "inboxes" / folder_id + await self.client.put_config_folder({ + "id": folder_id, + "path": str(folder_path), + "type": "receiveonly", + "devices": [{"deviceID": remote_device_id}], + "rescanIntervalS": 0, # receive-only, no scanning needed + }) + + async def remove_outbox_folder(self, member_tag: str, folder_suffix: str) -> None: + """Remove an outbox folder.""" + folder_id = build_outbox_folder_id(member_tag, folder_suffix) + await self.client.delete_config_folder(folder_id) + + async def set_folder_devices(self, folder_id: str, device_ids: set[str]) -> None: + """Declaratively set the device list for a folder. Replaces entire list.""" + folder = await self._get_folder(folder_id) + if folder is None: + return + folder["devices"] = [{"deviceID": did} for did in device_ids] + await self.client.put_config_folder(folder) + + async def remove_device_from_team_folders( + self, folder_suffixes: list[str], member_tags: list[str], device_id: str + ) -> None: + """Remove a device from all folders matching the given suffixes and member_tags.""" + folders = await self.client.get_config_folders() + for folder in folders: + fid = folder["id"] + # Check if this folder belongs to any of the team's projects + is_team_folder = any( + fid == build_outbox_folder_id(mt, fs) + for mt in member_tags + for fs in folder_suffixes + ) + if is_team_folder: + folder["devices"] = [ + d for d in folder.get("devices", []) + if d["deviceID"] != device_id + ] + await self.client.put_config_folder(folder) + + async def cleanup_team_folders( + self, folder_suffixes: list[str], member_tags: list[str], team_name: str + ) -> None: + """Remove all Syncthing folders related to a team.""" + folders = await self.client.get_config_folders() + meta_id = build_metadata_folder_id(team_name) + for folder in folders: + fid = folder["id"] + is_outbox = any( + fid == build_outbox_folder_id(mt, fs) + for mt in member_tags + for fs in folder_suffixes + ) + is_meta = fid == meta_id + if is_outbox or is_meta: + await self.client.delete_config_folder(fid) + + async def cleanup_project_folders( + self, folder_suffix: str, member_tags: list[str] + ) -> None: + """Remove all folders for a specific project suffix.""" + folders = await self.client.get_config_folders() + for folder in folders: + fid = folder["id"] + if any(fid == build_outbox_folder_id(mt, folder_suffix) for mt in member_tags): + await self.client.delete_config_folder(fid) +``` + +- [ ] **Step 4: Run tests to verify they pass** + +Run: `cd api && pytest tests/test_folder_manager.py -v` +Expected: ALL PASS + +- [ ] **Step 5: Commit** + +```bash +git add api/services/syncthing/folder_manager.py api/tests/test_folder_manager.py +git commit -m "feat(sync-v4): add FolderManager — outbox/inbox/device list management" +``` + +--- + +### Task 4: PairingService + +**Files:** +- Create: `api/services/sync/pairing_service.py` +- Create: `api/services/sync/__init__.py` +- Test: `api/tests/test_pairing_service.py` + +**INDEPENDENT — can run parallel with Tasks 1-3** + +- [ ] **Step 1: Write failing tests** + +```python +# api/tests/test_pairing_service.py +import sys +from pathlib import Path +sys.path.insert(0, str(Path(__file__).parent.parent)) + +import pytest +from services.sync.pairing_service import PairingService, PairingInfo + + +@pytest.fixture +def service(): + return PairingService() + + +class TestGenerateCode: + def test_generates_non_empty_code(self, service): + code = service.generate_code("jayant.macbook", "ABCDEFG-1234567-HIJKLMN-OPQRSTU-VWXYZ12-3456789-0ABCDEF") + assert len(code) > 0 + + def test_code_is_uppercase_with_dashes(self, service): + code = service.generate_code("jayant.macbook", "DEV-ID-123") + # Format: groups of 4 chars separated by dashes + parts = code.split("-") + assert all(len(p) == 4 for p in parts) + assert all(c.isalnum() or c == "-" for c in code) + + def test_same_input_same_code(self, service): + code1 = service.generate_code("jayant.macbook", "DEV-ID") + code2 = service.generate_code("jayant.macbook", "DEV-ID") + assert code1 == code2 # permanent, deterministic + + def test_different_input_different_code(self, service): + code1 = service.generate_code("jayant.macbook", "DEV-1") + code2 = service.generate_code("ayush.laptop", "DEV-2") + assert code1 != code2 + + +class TestValidateCode: + def test_roundtrip(self, service): + code = service.generate_code("jayant.macbook", "DEVICE-ABC-123") + info = service.validate_code(code) + assert info.member_tag == "jayant.macbook" + assert info.device_id == "DEVICE-ABC-123" + + def test_invalid_code_raises(self, service): + with pytest.raises(ValueError, match="Invalid pairing code"): + service.validate_code("XXXX-INVALID") + + +class TestPairingInfo: + def test_pairing_info_fields(self): + info = PairingInfo(member_tag="jayant.macbook", device_id="DEV-1") + assert info.member_tag == "jayant.macbook" + assert info.device_id == "DEV-1" +``` + +- [ ] **Step 2: Run tests to verify they fail** + +Run: `cd api && pytest tests/test_pairing_service.py -v` +Expected: FAIL + +- [ ] **Step 3: Implement PairingService** + +```python +# api/services/sync/__init__.py +"""Sync v4 business services.""" + +# api/services/sync/pairing_service.py +"""Pairing code generation and validation. + +Encodes member_tag + device_id into a short shareable code. +Format: base32-encoded "{member_tag}:{device_id}", grouped into 4-char blocks with dashes. +Permanent — same input always produces same code. +""" +from __future__ import annotations + +import base64 + +from pydantic import BaseModel + + +class PairingInfo(BaseModel): + member_tag: str + device_id: str + + +class PairingService: + SEPARATOR = ":" + + def generate_code(self, member_tag: str, device_id: str) -> str: + """Encode member_tag + device_id into a shareable pairing code.""" + payload = f"{member_tag}{self.SEPARATOR}{device_id}" + encoded = base64.b32encode(payload.encode("utf-8")).decode("ascii") + # Remove padding + encoded = encoded.rstrip("=") + # Group into 4-char blocks with dashes + groups = [encoded[i:i+4] for i in range(0, len(encoded), 4)] + return "-".join(groups) + + def validate_code(self, code: str) -> PairingInfo: + """Decode a pairing code back to PairingInfo.""" + try: + # Remove dashes and re-add padding + raw = code.replace("-", "") + padding = (8 - len(raw) % 8) % 8 + raw += "=" * padding + decoded = base64.b32decode(raw.upper()).decode("utf-8") + if self.SEPARATOR not in decoded: + raise ValueError("Missing separator") + member_tag, device_id = decoded.split(self.SEPARATOR, 1) + return PairingInfo(member_tag=member_tag, device_id=device_id) + except Exception as e: + raise ValueError(f"Invalid pairing code: {e}") from e +``` + +- [ ] **Step 4: Run tests to verify they pass** + +Run: `cd api && pytest tests/test_pairing_service.py -v` +Expected: ALL PASS + +- [ ] **Step 5: Commit** + +```bash +git add api/services/sync/__init__.py api/services/sync/pairing_service.py api/tests/test_pairing_service.py +git commit -m "feat(sync-v4): add PairingService — permanent pairing code encode/decode" +``` + +--- + +### Task 5: Phase 2 Integration Test + +**Files:** +- Test: `api/tests/test_sync_v4_infrastructure.py` + +**SEQUENTIAL — after Tasks 1-4** + +- [ ] **Step 1: Write integration test** + +```python +# api/tests/test_sync_v4_infrastructure.py +"""Integration test: Syncthing abstraction layer works together.""" +import sys +from pathlib import Path +sys.path.insert(0, str(Path(__file__).parent.parent)) + +import pytest +from unittest.mock import AsyncMock, MagicMock +from services.syncthing.client import SyncthingClient +from services.syncthing.device_manager import DeviceManager +from services.syncthing.folder_manager import FolderManager, build_outbox_folder_id +from services.sync.pairing_service import PairingService + + +class TestInfrastructureStack: + """Simulates: pair device → create outbox → set device list.""" + + @pytest.mark.asyncio + async def test_pair_and_share(self): + client = MagicMock(spec=SyncthingClient) + client.get_config = AsyncMock(return_value={"devices": [], "folders": []}) + client.put_config_device = AsyncMock() + client.get_config_folders = AsyncMock(return_value=[]) + client.put_config_folder = AsyncMock() + + devices = DeviceManager(client) + folders = FolderManager(client, karma_base=Path("/tmp/test")) + + # 1. Pair with new device + await devices.pair("DEV-AYUSH") + client.put_config_device.assert_called_once() + + # 2. Create outbox folder + await folders.ensure_outbox_folder("jayant.macbook", "owner-repo") + client.put_config_folder.assert_called_once() + folder = client.put_config_folder.call_args[0][0] + assert folder["type"] == "sendonly" + + # 3. Set device list on folder + client.put_config_folder.reset_mock() + folder_id = build_outbox_folder_id("jayant.macbook", "owner-repo") + client.get_config_folders = AsyncMock(return_value=[ + {"id": folder_id, "devices": [], "type": "sendonly"}, + ]) + await folders.set_folder_devices(folder_id, {"DEV-AYUSH", "DEV-JAYANT"}) + updated = client.put_config_folder.call_args[0][0] + device_ids = {d["deviceID"] for d in updated["devices"]} + assert device_ids == {"DEV-AYUSH", "DEV-JAYANT"} + + def test_pairing_code_roundtrip(self): + svc = PairingService() + code = svc.generate_code("ayush.laptop", "DEV-AYUSH-FULL-ID") + info = svc.validate_code(code) + assert info.member_tag == "ayush.laptop" + assert info.device_id == "DEV-AYUSH-FULL-ID" +``` + +- [ ] **Step 2: Run integration test** + +Run: `cd api && pytest tests/test_sync_v4_infrastructure.py -v` +Expected: ALL PASS + +- [ ] **Step 3: Run full Phase 2 suite** + +Run: `cd api && pytest tests/test_syncthing_client.py tests/test_device_manager.py tests/test_folder_manager.py tests/test_pairing_service.py tests/test_sync_v4_infrastructure.py -v` +Expected: ALL PASS + +- [ ] **Step 4: Commit** + +```bash +git add api/tests/test_sync_v4_infrastructure.py +git commit -m "test(sync-v4): add Phase 2 integration test — infrastructure stack" +``` + +--- + +## Phase 2 Completion Checklist + +- [ ] SyncthingClient wraps all needed REST endpoints +- [ ] DeviceManager handles pair/unpair/connection status +- [ ] FolderManager handles outbox/inbox/device list/cleanup +- [ ] PairingService encodes/decodes permanent pairing codes +- [ ] Integration test passes +- [ ] All Phase 2 code committed diff --git a/docs/superpowers/plans/2026-03-17-sync-v4-phase3-services.md b/docs/superpowers/plans/2026-03-17-sync-v4-phase3-services.md new file mode 100644 index 00000000..ba39c813 --- /dev/null +++ b/docs/superpowers/plans/2026-03-17-sync-v4-phase3-services.md @@ -0,0 +1,1251 @@ +# Sync v4 Phase 3: Business Logic — Services + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. +> +> **TDD SKILL:** Use `oh-my-claudecode:tdd` or `superpowers:test-driven-development` for every task. + +**Goal:** Build the service layer that orchestrates domain models + repositories + Syncthing abstraction. + +**Architecture:** Services are the only layer that combines domain models, repos, and Syncthing. Routers call services. Services call domain model methods for validation, repos for persistence, and Syncthing managers for P2P operations. + +**Tech Stack:** Python 3.9+, Pydantic 2.x, SQLite, pytest, asyncio + +**Spec:** `docs/superpowers/specs/2026-03-17-sync-v4-domain-models-design.md` (sections: Service Layer, Metadata Folder Structure, Session Packaging Integration, Cleanup Logic) + +**Parent Plan:** `docs/superpowers/plans/2026-03-17-sync-v4-master.md` + +**Depends on:** Phase 1 (domain + repos) + Phase 2 (Syncthing abstraction) + +--- + +## Task Dependency Graph + +``` +Task 1 (MetadataService) ──→ Task 2 (TeamService) ──→ Task 4 (ReconciliationService) + ──→ Task 3 (ProjectService) ──↗ │ + ▼ + Task 5 (WatcherManager) + │ + ▼ + Task 6 (Integration) +``` + +--- + +### Task 1: MetadataService + +**Files:** +- Create: `api/services/sync/metadata_service.py` +- Test: `api/tests/test_metadata_service.py` + +**FIRST — other services depend on metadata read/write** + +- [ ] **Step 1: Write failing tests** + +```python +# api/tests/test_metadata_service.py +import sys +from pathlib import Path +sys.path.insert(0, str(Path(__file__).parent.parent)) + +import json +import pytest +from domain.team import Team +from domain.member import Member, MemberStatus +from domain.project import SharedProject +from domain.subscription import Subscription, SubscriptionStatus, SyncDirection +from services.sync.metadata_service import MetadataService + + +@pytest.fixture +def meta_base(tmp_path): + return tmp_path / "karma-metadata" + + +@pytest.fixture +def service(meta_base): + return MetadataService(meta_base=meta_base) + + +@pytest.fixture +def team(): + return Team(name="karma-team", leader_device_id="DEV-L", leader_member_tag="jayant.macbook") + + +@pytest.fixture +def leader(): + return Member( + member_tag="jayant.macbook", team_name="karma-team", + device_id="DEV-L", user_id="jayant", machine_tag="macbook", + status=MemberStatus.ACTIVE, + ) + + +@pytest.fixture +def member(): + return Member( + member_tag="ayush.laptop", team_name="karma-team", + device_id="DEV-A", user_id="ayush", machine_tag="laptop", + status=MemberStatus.ACTIVE, + ) + + +class TestWriteTeamState: + def test_creates_team_json(self, service, team, leader): + service.write_team_state(team, [leader]) + team_file = service._team_dir(team.name) / "team.json" + assert team_file.exists() + data = json.loads(team_file.read_text()) + assert data["name"] == "karma-team" + assert data["created_by"] == "jayant.macbook" + assert data["leader_device_id"] == "DEV-L" + + def test_creates_member_state_file(self, service, team, leader): + service.write_team_state(team, [leader]) + member_file = service._team_dir(team.name) / "members" / "jayant.macbook.json" + assert member_file.exists() + data = json.loads(member_file.read_text()) + assert data["member_tag"] == "jayant.macbook" + assert data["device_id"] == "DEV-L" + + +class TestWriteOwnState: + def test_writes_projects_and_subscriptions(self, service, member): + projects = [SharedProject( + team_name="karma-team", git_identity="o/r", folder_suffix="o-r", + )] + subs = [Subscription( + member_tag="ayush.laptop", team_name="karma-team", + project_git_identity="o/r", + status=SubscriptionStatus.ACCEPTED, direction=SyncDirection.BOTH, + )] + service.write_own_state("karma-team", "ayush.laptop", projects, subs) + state_file = service._team_dir("karma-team") / "members" / "ayush.laptop.json" + data = json.loads(state_file.read_text()) + assert len(data["projects"]) == 1 + assert data["projects"][0]["git_identity"] == "o/r" + assert data["subscriptions"]["o/r"]["status"] == "accepted" + assert data["subscriptions"]["o/r"]["direction"] == "both" + + +class TestWriteRemovalSignal: + def test_creates_removal_file(self, service): + service.write_removal_signal("karma-team", "ayush.laptop", removed_by="jayant.macbook") + removal_file = service._team_dir("karma-team") / "removed" / "ayush.laptop.json" + assert removal_file.exists() + data = json.loads(removal_file.read_text()) + assert data["member_tag"] == "ayush.laptop" + assert data["removed_by"] == "jayant.macbook" + + +class TestReadTeamMetadata: + def test_reads_all_member_states(self, service, team, leader, member): + service.write_team_state(team, [leader, member]) + states = service.read_team_metadata("karma-team") + assert "jayant.macbook" in states + assert "ayush.laptop" in states + assert states["jayant.macbook"]["device_id"] == "DEV-L" + + def test_reads_removal_signals(self, service, team, leader): + service.write_team_state(team, [leader]) + service.write_removal_signal("karma-team", "ayush.laptop", removed_by="jayant.macbook") + states = service.read_team_metadata("karma-team") + assert states.get("__removals", {}).get("ayush.laptop") is not None + + def test_empty_team_returns_empty(self, service): + states = service.read_team_metadata("nonexistent") + assert states == {} +``` + +- [ ] **Step 2: Run tests to verify they fail** + +Run: `cd api && pytest tests/test_metadata_service.py -v` +Expected: FAIL + +- [ ] **Step 3: Implement MetadataService** + +```python +# api/services/sync/metadata_service.py +"""Metadata folder read/write for P2P team state synchronization. + +Each team has a metadata folder (karma-meta--{team}). Members write their +own state files. Leader writes team.json and removal signals. +""" +from __future__ import annotations + +import json +from datetime import datetime, timezone +from pathlib import Path +from typing import TYPE_CHECKING + +if TYPE_CHECKING: + from domain.member import Member + from domain.project import SharedProject + from domain.subscription import Subscription + from domain.team import Team + + +class MetadataService: + def __init__(self, meta_base: Path): + self.meta_base = meta_base + + def _team_dir(self, team_name: str) -> Path: + return self.meta_base / f"karma-meta--{team_name}" + + def write_team_state(self, team: "Team", members: list["Member"]) -> None: + """Write team.json + member state files to metadata folder.""" + team_dir = self._team_dir(team.name) + team_dir.mkdir(parents=True, exist_ok=True) + (team_dir / "members").mkdir(exist_ok=True) + (team_dir / "removed").mkdir(exist_ok=True) + + # Write team.json + team_data = { + "name": team.name, + "created_by": team.leader_member_tag, + "leader_device_id": team.leader_device_id, + "created_at": team.created_at.isoformat(), + } + (team_dir / "team.json").write_text(json.dumps(team_data, indent=2)) + + # Write member state files + for member in members: + member_data = { + "member_tag": member.member_tag, + "device_id": member.device_id, + "user_id": member.user_id, + "machine_tag": member.machine_tag, + "status": member.status.value, + "updated_at": datetime.now(timezone.utc).isoformat(), + } + member_file = team_dir / "members" / f"{member.member_tag}.json" + member_file.write_text(json.dumps(member_data, indent=2)) + + def write_own_state( + self, + team_name: str, + member_tag: str, + projects: list["SharedProject"], + subscriptions: list["Subscription"], + ) -> None: + """Write own member state with projects and subscriptions.""" + team_dir = self._team_dir(team_name) + (team_dir / "members").mkdir(parents=True, exist_ok=True) + + projects_data = [ + { + "git_identity": p.git_identity, + "folder_suffix": p.folder_suffix, + } + for p in projects + ] + subs_data = { + s.project_git_identity: { + "status": s.status.value, + "direction": s.direction.value, + } + for s in subscriptions + } + state = { + "member_tag": member_tag, + "projects": projects_data, + "subscriptions": subs_data, + "updated_at": datetime.now(timezone.utc).isoformat(), + } + state_file = team_dir / "members" / f"{member_tag}.json" + state_file.write_text(json.dumps(state, indent=2)) + + def write_removal_signal( + self, team_name: str, member_tag: str, *, removed_by: str + ) -> None: + """Write removal signal to metadata folder.""" + team_dir = self._team_dir(team_name) + (team_dir / "removed").mkdir(parents=True, exist_ok=True) + + removal_data = { + "member_tag": member_tag, + "removed_by": removed_by, + "removed_at": datetime.now(timezone.utc).isoformat(), + } + removal_file = team_dir / "removed" / f"{member_tag}.json" + removal_file.write_text(json.dumps(removal_data, indent=2)) + + def read_team_metadata(self, team_name: str) -> dict[str, dict]: + """Read all member states and removal signals from metadata folder. + + Returns dict keyed by member_tag. Special key '__removals' contains removal signals. + """ + team_dir = self._team_dir(team_name) + if not team_dir.exists(): + return {} + + result: dict[str, dict] = {} + + # Read member states + members_dir = team_dir / "members" + if members_dir.exists(): + for f in members_dir.glob("*.json"): + try: + data = json.loads(f.read_text()) + tag = data.get("member_tag", f.stem) + result[tag] = data + except (json.JSONDecodeError, KeyError): + continue + + # Read removal signals + removed_dir = team_dir / "removed" + if removed_dir.exists(): + removals = {} + for f in removed_dir.glob("*.json"): + try: + data = json.loads(f.read_text()) + tag = data.get("member_tag", f.stem) + removals[tag] = data + except (json.JSONDecodeError, KeyError): + continue + if removals: + result["__removals"] = removals + + return result +``` + +- [ ] **Step 4: Run tests to verify they pass** + +Run: `cd api && pytest tests/test_metadata_service.py -v` +Expected: ALL PASS + +- [ ] **Step 5: Commit** + +```bash +git add api/services/sync/metadata_service.py api/tests/test_metadata_service.py +git commit -m "feat(sync-v4): add MetadataService — read/write team metadata folders" +``` + +--- + +### Task 2: TeamService + +**Files:** +- Create: `api/services/sync/team_service.py` +- Test: `api/tests/test_team_service.py` + +**CAN PARALLEL with Task 3. Depends on Task 1.** + +- [ ] **Step 1: Write failing tests** + +Tests use in-memory SQLite + mocked Syncthing managers. Key test scenarios: + +```python +# api/tests/test_team_service.py +import sys +from pathlib import Path +sys.path.insert(0, str(Path(__file__).parent.parent)) + +import sqlite3 +import pytest +from unittest.mock import MagicMock, AsyncMock +from db.schema import ensure_schema +from domain.team import Team, TeamStatus, AuthorizationError +from domain.member import Member, MemberStatus +from domain.subscription import SubscriptionStatus +from repositories.team_repo import TeamRepository +from repositories.member_repo import MemberRepository +from repositories.project_repo import ProjectRepository +from repositories.subscription_repo import SubscriptionRepository +from repositories.event_repo import EventRepository +from services.sync.team_service import TeamService + + +@pytest.fixture +def conn(): + c = sqlite3.connect(":memory:") + c.row_factory = sqlite3.Row + c.execute("PRAGMA foreign_keys=ON") + ensure_schema(c) + return c + + +@pytest.fixture +def mock_devices(): + m = MagicMock() + m.pair = AsyncMock() + m.unpair = AsyncMock() + return m + + +@pytest.fixture +def mock_metadata(tmp_path): + from services.sync.metadata_service import MetadataService + return MetadataService(meta_base=tmp_path / "meta") + + +@pytest.fixture +def mock_folders(): + m = MagicMock() + m.remove_device_from_team_folders = AsyncMock() + m.cleanup_team_folders = AsyncMock() + return m + + +@pytest.fixture +def service(conn, mock_devices, mock_metadata, mock_folders): + return TeamService( + teams=TeamRepository(), + members=MemberRepository(), + projects=ProjectRepository(), + subs=SubscriptionRepository(), + events=EventRepository(), + devices=mock_devices, + metadata=mock_metadata, + folders=mock_folders, + ) + + +class TestCreateTeam: + @pytest.mark.asyncio + async def test_creates_team_and_leader(self, service, conn): + team = await service.create_team( + conn, name="karma", leader_member_tag="jayant.macbook", leader_device_id="DEV-L", + ) + assert team.status == TeamStatus.ACTIVE + assert team.leader_member_tag == "jayant.macbook" + + # Leader is auto-active + leader = service.members.get(conn, "karma", "jayant.macbook") + assert leader is not None + assert leader.status == MemberStatus.ACTIVE + + @pytest.mark.asyncio + async def test_logs_team_created_event(self, service, conn): + await service.create_team( + conn, name="t", leader_member_tag="j.m", leader_device_id="D", + ) + events = service.events.query(conn, team="t") + assert any(e.event_type.value == "team_created" for e in events) + + +class TestAddMember: + @pytest.mark.asyncio + async def test_adds_member_and_pairs(self, service, conn, mock_devices): + await service.create_team( + conn, name="t", leader_member_tag="j.m", leader_device_id="DEV-L", + ) + member = await service.add_member( + conn, team_name="t", by_device="DEV-L", + new_member_tag="a.l", new_device_id="DEV-A", + ) + assert member.status == MemberStatus.ADDED + mock_devices.pair.assert_called_once_with("DEV-A") + + @pytest.mark.asyncio + async def test_creates_offered_subscriptions(self, service, conn): + await service.create_team( + conn, name="t", leader_member_tag="j.m", leader_device_id="DEV-L", + ) + # Share a project first + from domain.project import SharedProject + project = SharedProject(team_name="t", git_identity="o/r", folder_suffix="o-r") + service.projects.save(conn, project) + + await service.add_member( + conn, team_name="t", by_device="DEV-L", + new_member_tag="a.l", new_device_id="DEV-A", + ) + subs = service.subs.list_for_member(conn, "a.l") + assert len(subs) == 1 + assert subs[0].status == SubscriptionStatus.OFFERED + + @pytest.mark.asyncio + async def test_non_leader_cannot_add(self, service, conn): + await service.create_team( + conn, name="t", leader_member_tag="j.m", leader_device_id="DEV-L", + ) + with pytest.raises(AuthorizationError): + await service.add_member( + conn, team_name="t", by_device="DEV-OTHER", + new_member_tag="a.l", new_device_id="DEV-A", + ) + + +class TestRemoveMember: + @pytest.mark.asyncio + async def test_removes_and_records(self, service, conn): + await service.create_team( + conn, name="t", leader_member_tag="j.m", leader_device_id="DEV-L", + ) + await service.add_member( + conn, team_name="t", by_device="DEV-L", + new_member_tag="a.l", new_device_id="DEV-A", + ) + removed = await service.remove_member( + conn, team_name="t", by_device="DEV-L", member_tag="a.l", + ) + assert removed.status == MemberStatus.REMOVED + assert service.members.was_removed(conn, "t", "DEV-A") + + +class TestDissolveTeam: + @pytest.mark.asyncio + async def test_dissolves_and_cleans_up(self, service, conn, mock_folders): + await service.create_team( + conn, name="t", leader_member_tag="j.m", leader_device_id="DEV-L", + ) + dissolved = await service.dissolve_team(conn, team_name="t", by_device="DEV-L") + assert dissolved.status == TeamStatus.DISSOLVED + mock_folders.cleanup_team_folders.assert_called_once() + # Team deleted from DB + assert service.teams.get(conn, "t") is None +``` + +- [ ] **Step 2: Run tests to verify they fail** + +Run: `cd api && pytest tests/test_team_service.py -v` +Expected: FAIL + +- [ ] **Step 3: Implement TeamService** + +```python +# api/services/sync/team_service.py +"""TeamService — team lifecycle + member management orchestration.""" +from __future__ import annotations + +import sqlite3 +from typing import TYPE_CHECKING + +from domain.team import Team +from domain.member import Member, MemberStatus +from domain.subscription import Subscription +from domain.events import SyncEvent, SyncEventType + +if TYPE_CHECKING: + from repositories.team_repo import TeamRepository + from repositories.member_repo import MemberRepository + from repositories.project_repo import ProjectRepository + from repositories.subscription_repo import SubscriptionRepository + from repositories.event_repo import EventRepository + from services.syncthing.device_manager import DeviceManager + from services.syncthing.folder_manager import FolderManager + from services.sync.metadata_service import MetadataService + + +class TeamService: + def __init__( + self, + teams: "TeamRepository", + members: "MemberRepository", + projects: "ProjectRepository", + subs: "SubscriptionRepository", + events: "EventRepository", + devices: "DeviceManager", + metadata: "MetadataService", + folders: "FolderManager", + ): + self.teams = teams + self.members = members + self.projects = projects + self.subs = subs + self.events = events + self.devices = devices + self.metadata = metadata + self.folders = folders + + async def create_team( + self, + conn: sqlite3.Connection, + *, + name: str, + leader_member_tag: str, + leader_device_id: str, + ) -> Team: + team = Team( + name=name, + leader_device_id=leader_device_id, + leader_member_tag=leader_member_tag, + ) + # Parse member_tag + user_id, machine_tag = leader_member_tag.split(".", 1) + leader = Member( + member_tag=leader_member_tag, + team_name=name, + device_id=leader_device_id, + user_id=user_id, + machine_tag=machine_tag, + status=MemberStatus.ACTIVE, + ) + self.teams.save(conn, team) + self.members.save(conn, leader) + self.metadata.write_team_state(team, [leader]) + self.events.log(conn, SyncEvent( + event_type=SyncEventType.TEAM_CREATED, team_name=name, + )) + return team + + async def add_member( + self, + conn: sqlite3.Connection, + *, + team_name: str, + by_device: str, + new_member_tag: str, + new_device_id: str, + ) -> Member: + team = self.teams.get(conn, team_name) + if team is None: + raise ValueError(f"Team '{team_name}' not found") + + member = Member.from_member_tag( + member_tag=new_member_tag, + team_name=team_name, + device_id=new_device_id, + ) + added = team.add_member(member, by_device=by_device) # auth check + self.members.save(conn, added) + await self.devices.pair(new_device_id) + + # Write metadata + all_members = self.members.list_for_team(conn, team_name) + self.metadata.write_team_state(team, all_members) + + # Create OFFERED subscriptions for all shared projects + projects = self.projects.list_for_team(conn, team_name) + for project in projects: + if project.status.value == "shared": + sub = Subscription( + member_tag=new_member_tag, + team_name=team_name, + project_git_identity=project.git_identity, + ) + self.subs.save(conn, sub) + + self.events.log(conn, SyncEvent( + event_type=SyncEventType.MEMBER_ADDED, + team_name=team_name, + member_tag=new_member_tag, + detail={"device_id": new_device_id, "added_by": team.leader_member_tag}, + )) + return added + + async def remove_member( + self, + conn: sqlite3.Connection, + *, + team_name: str, + by_device: str, + member_tag: str, + ) -> Member: + team = self.teams.get(conn, team_name) + if team is None: + raise ValueError(f"Team '{team_name}' not found") + + member = self.members.get(conn, team_name, member_tag) + if member is None: + raise ValueError(f"Member '{member_tag}' not found in team '{team_name}'") + + removed = team.remove_member(member, by_device=by_device) # auth check + self.members.save(conn, removed) + self.members.record_removal(conn, team_name, removed.device_id, member_tag=member_tag) + + # Write removal signal + self.metadata.write_removal_signal(team_name, member_tag, removed_by=team.leader_member_tag) + + # Remove device from folder device lists + projects = self.projects.list_for_team(conn, team_name) + suffixes = [p.folder_suffix for p in projects if p.status.value == "shared"] + members = self.members.list_for_team(conn, team_name) + tags = [m.member_tag for m in members] + await self.folders.remove_device_from_team_folders(suffixes, tags, removed.device_id) + + # Check cross-team: only unpair if device not in other teams + other_memberships = self.members.get_by_device(conn, removed.device_id) + active_others = [m for m in other_memberships if m.team_name != team_name and m.is_active] + if not active_others: + await self.devices.unpair(removed.device_id) + + self.events.log(conn, SyncEvent( + event_type=SyncEventType.MEMBER_REMOVED, + team_name=team_name, + member_tag=member_tag, + detail={"device_id": removed.device_id, "removed_by": team.leader_member_tag}, + )) + return removed + + async def dissolve_team( + self, + conn: sqlite3.Connection, + *, + team_name: str, + by_device: str, + ) -> Team: + team = self.teams.get(conn, team_name) + if team is None: + raise ValueError(f"Team '{team_name}' not found") + + dissolved = team.dissolve(by_device=by_device) # auth check + + # Cleanup Syncthing folders + projects = self.projects.list_for_team(conn, team_name) + members = self.members.list_for_team(conn, team_name) + suffixes = [p.folder_suffix for p in projects] + tags = [m.member_tag for m in members] + await self.folders.cleanup_team_folders(suffixes, tags, team_name) + + # Delete team (CASCADE handles members, projects, subs) + self.teams.delete(conn, team_name) + + self.events.log(conn, SyncEvent( + event_type=SyncEventType.TEAM_DISSOLVED, team_name=team_name, + )) + return dissolved +``` + +- [ ] **Step 4: Run tests to verify they pass** + +Run: `cd api && pytest tests/test_team_service.py -v` +Expected: ALL PASS + +- [ ] **Step 5: Commit** + +```bash +git add api/services/sync/team_service.py api/tests/test_team_service.py +git commit -m "feat(sync-v4): add TeamService — team lifecycle + member management" +``` + +--- + +### Task 3: ProjectService + +**Files:** +- Create: `api/services/sync/project_service.py` +- Test: `api/tests/test_project_service.py` + +**CAN PARALLEL with Task 2. Depends on Task 1.** + +- [ ] **Step 1: Write failing tests** + +Key test scenarios: + +```python +# api/tests/test_project_service.py +# Follow same fixture pattern as test_team_service.py + +class TestShareProject: + @pytest.mark.asyncio + async def test_shares_project_and_creates_subscriptions(self, service, conn): + # Setup: create team + add member first + # Share project → SharedProject(SHARED) + Subscription(OFFERED) for each member + + @pytest.mark.asyncio + async def test_non_leader_cannot_share(self, service, conn): + # AuthorizationError + + @pytest.mark.asyncio + async def test_requires_git_identity(self, service, conn): + # ValueError if git_identity missing + + +class TestAcceptSubscription: + @pytest.mark.asyncio + async def test_accept_with_both_direction(self, service, conn): + # sub OFFERED → ACCEPTED, direction=BOTH + # FolderManager.ensure_outbox_folder called + # FolderManager.ensure_inbox_folders called + + @pytest.mark.asyncio + async def test_accept_receive_only(self, service, conn): + # No outbox folder created, only inbox + + +class TestPauseResumeDecline: + @pytest.mark.asyncio + async def test_pause_subscription(self, service, conn): + # ACCEPTED → PAUSED + + @pytest.mark.asyncio + async def test_resume_subscription(self, service, conn): + # PAUSED → ACCEPTED + + @pytest.mark.asyncio + async def test_decline_subscription(self, service, conn): + # any → DECLINED + + +class TestChangeDirection: + @pytest.mark.asyncio + async def test_change_to_receive_removes_outbox(self, service, conn): + # direction BOTH → RECEIVE, FolderManager.remove_outbox_folder called + + @pytest.mark.asyncio + async def test_change_to_send_only(self, service, conn): + # direction BOTH → SEND + + +class TestRemoveProject: + @pytest.mark.asyncio + async def test_removes_project_and_declines_all_subs(self, service, conn): + # SharedProject → REMOVED, all subs → DECLINED + # FolderManager.cleanup_project_folders called +``` + +- [ ] **Step 2: Run tests to verify they fail** + +- [ ] **Step 3: Implement ProjectService** + +```python +# api/services/sync/project_service.py +"""ProjectService — project sharing + subscription management.""" +from __future__ import annotations + +import sqlite3 +from typing import TYPE_CHECKING + +from domain.project import SharedProject, derive_folder_suffix +from domain.subscription import Subscription, SyncDirection +from domain.events import SyncEvent, SyncEventType +from domain.team import AuthorizationError + +if TYPE_CHECKING: + from repositories.project_repo import ProjectRepository + from repositories.subscription_repo import SubscriptionRepository + from repositories.member_repo import MemberRepository + from repositories.team_repo import TeamRepository + from repositories.event_repo import EventRepository + from services.syncthing.folder_manager import FolderManager + from services.sync.metadata_service import MetadataService + + +class ProjectService: + def __init__(self, projects, subs, members, teams, folders, metadata, events): + self.projects = projects + self.subs = subs + self.members = members + self.teams = teams + self.folders = folders + self.metadata = metadata + self.events = events + + async def share_project( + self, conn, *, team_name, by_device, git_identity, encoded_name=None, + ) -> SharedProject: + team = self.teams.get(conn, team_name) + if not team or not team.is_leader(by_device): + raise AuthorizationError("Only leader can share projects") + if not git_identity: + raise ValueError("git_identity is required (git-only projects)") + + project = SharedProject( + team_name=team_name, + git_identity=git_identity, + encoded_name=encoded_name, + folder_suffix=derive_folder_suffix(git_identity), + ) + self.projects.save(conn, project) + + # Create OFFERED subscription for each active non-leader member + for member in self.members.list_for_team(conn, team_name): + if member.is_active and not team.is_leader(member.device_id): + sub = Subscription( + member_tag=member.member_tag, + team_name=team_name, + project_git_identity=git_identity, + ) + self.subs.save(conn, sub) + + # Create leader's outbox if they have the repo + if encoded_name: + await self.folders.ensure_outbox_folder( + team.leader_member_tag, project.folder_suffix, + ) + + self.events.log(conn, SyncEvent( + event_type=SyncEventType.PROJECT_SHARED, + team_name=team_name, + project_git_identity=git_identity, + )) + return project + + async def accept_subscription( + self, conn, *, member_tag, team_name, git_identity, direction=SyncDirection.BOTH, + ) -> Subscription: + sub = self.subs.get(conn, member_tag, team_name, git_identity) + if sub is None: + raise ValueError("Subscription not found") + + accepted = sub.accept(direction) + self.subs.save(conn, accepted) + await self._apply_sync_direction(conn, accepted) + + self.events.log(conn, SyncEvent( + event_type=SyncEventType.SUBSCRIPTION_ACCEPTED, + team_name=team_name, member_tag=member_tag, + project_git_identity=git_identity, + detail={"direction": direction.value}, + )) + return accepted + + async def _apply_sync_direction(self, conn, sub: Subscription) -> None: + project = self.projects.get(conn, sub.team_name, sub.project_git_identity) + if not project: + return + if sub.direction in (SyncDirection.SEND, SyncDirection.BOTH): + await self.folders.ensure_outbox_folder(sub.member_tag, project.folder_suffix) + if sub.direction in (SyncDirection.RECEIVE, SyncDirection.BOTH): + # Accept inbox from each teammate who sends + members = self.members.list_for_team(conn, sub.team_name) + for m in members: + if m.member_tag != sub.member_tag and m.is_active: + await self.folders.ensure_inbox_folder( + m.member_tag, project.folder_suffix, m.device_id, + ) + + async def pause_subscription(self, conn, *, member_tag, team_name, git_identity): + sub = self.subs.get(conn, member_tag, team_name, git_identity) + paused = sub.pause() + self.subs.save(conn, paused) + self.events.log(conn, SyncEvent( + event_type=SyncEventType.SUBSCRIPTION_PAUSED, + team_name=team_name, member_tag=member_tag, + project_git_identity=git_identity, + )) + return paused + + async def resume_subscription(self, conn, *, member_tag, team_name, git_identity): + sub = self.subs.get(conn, member_tag, team_name, git_identity) + resumed = sub.resume() + self.subs.save(conn, resumed) + await self._apply_sync_direction(conn, resumed) + self.events.log(conn, SyncEvent( + event_type=SyncEventType.SUBSCRIPTION_RESUMED, + team_name=team_name, member_tag=member_tag, + project_git_identity=git_identity, + )) + return resumed + + async def decline_subscription(self, conn, *, member_tag, team_name, git_identity): + sub = self.subs.get(conn, member_tag, team_name, git_identity) + declined = sub.decline() + self.subs.save(conn, declined) + self.events.log(conn, SyncEvent( + event_type=SyncEventType.SUBSCRIPTION_DECLINED, + team_name=team_name, member_tag=member_tag, + project_git_identity=git_identity, + )) + return declined + + async def change_direction(self, conn, *, member_tag, team_name, git_identity, direction): + sub = self.subs.get(conn, member_tag, team_name, git_identity) + old_direction = sub.direction + changed = sub.change_direction(direction) + self.subs.save(conn, changed) + + project = self.projects.get(conn, team_name, git_identity) + # Remove outbox if no longer sending + if old_direction in (SyncDirection.SEND, SyncDirection.BOTH) and direction == SyncDirection.RECEIVE: + await self.folders.remove_outbox_folder(member_tag, project.folder_suffix) + # Ensure outbox if now sending + if direction in (SyncDirection.SEND, SyncDirection.BOTH) and old_direction == SyncDirection.RECEIVE: + await self.folders.ensure_outbox_folder(member_tag, project.folder_suffix) + + self.events.log(conn, SyncEvent( + event_type=SyncEventType.DIRECTION_CHANGED, + team_name=team_name, member_tag=member_tag, + project_git_identity=git_identity, + detail={"old_direction": old_direction.value, "new_direction": direction.value}, + )) + return changed + + async def remove_project(self, conn, *, team_name, by_device, git_identity): + team = self.teams.get(conn, team_name) + if not team or not team.is_leader(by_device): + raise AuthorizationError("Only leader can remove projects") + + project = self.projects.get(conn, team_name, git_identity) + if not project: + raise ValueError("Project not found") + + removed = project.remove() + self.projects.save(conn, removed) + + # Decline all subscriptions + subs = self.subs.list_for_project(conn, team_name, git_identity) + for sub in subs: + if sub.status.value != "declined": + self.subs.save(conn, sub.decline()) + + # Cleanup folders + members = self.members.list_for_team(conn, team_name) + tags = [m.member_tag for m in members] + await self.folders.cleanup_project_folders(project.folder_suffix, tags) + + self.events.log(conn, SyncEvent( + event_type=SyncEventType.PROJECT_REMOVED, + team_name=team_name, project_git_identity=git_identity, + )) + return removed +``` + +- [ ] **Step 4: Run tests, iterate, commit** + +Run: `cd api && pytest tests/test_project_service.py -v` + +```bash +git add api/services/sync/project_service.py api/tests/test_project_service.py +git commit -m "feat(sync-v4): add ProjectService — sharing + subscriptions" +``` + +--- + +### Task 4: ReconciliationService + +**Files:** +- Create: `api/services/sync/reconciliation_service.py` +- Test: `api/tests/test_reconciliation_service.py` + +**SEQUENTIAL — after Tasks 2+3** + +- [ ] **Step 1: Write failing tests** + +Key test scenarios: + +```python +# api/tests/test_reconciliation_service.py + +class TestPhaseMetadata: + def test_detects_removal_signal_and_auto_leaves(self): + # Write removal signal for own member_tag in metadata + # Run phase_metadata → team deleted from local DB + + def test_discovers_new_member_from_metadata(self): + # Write unknown member state to metadata + # Run phase_metadata → member registered as ADDED + + def test_discovers_new_project_creates_offered_sub(self): + # Leader's metadata has project not in local DB + # Run phase_metadata → SharedProject created + Subscription(OFFERED) + + def test_detects_removed_project_declines_sub(self): + # Local DB has project, leader's metadata doesn't + # Run phase_metadata → Subscription DECLINED + + +class TestPhaseMeshPair: + def test_pairs_with_unpaired_active_members(self): + # Active member with device not paired + # Run phase_mesh_pair → DeviceManager.ensure_paired called + + def test_skips_removed_members(self): + # Removed member + # Run phase_mesh_pair → ensure_paired NOT called + + +class TestPhaseDeviceLists: + def test_computes_union_and_applies(self): + # 2 accepted subs for same suffix + # Run phase_device_lists → FolderManager.set_folder_devices with both devices + + def test_excludes_receive_only_from_outbox_device_list(self): + # Member with direction=RECEIVE should not get their device in others' outbox folders +``` + +- [ ] **Step 2-4: Implement and test** + +```python +# api/services/sync/reconciliation_service.py +"""3-phase reconciliation pipeline. Runs every 60s.""" +from __future__ import annotations + +import sqlite3 +from typing import TYPE_CHECKING + +from domain.member import Member, MemberStatus +from domain.subscription import Subscription, SubscriptionStatus, SyncDirection +from domain.events import SyncEvent, SyncEventType + +if TYPE_CHECKING: + from repositories.team_repo import TeamRepository + from repositories.member_repo import MemberRepository + from repositories.project_repo import ProjectRepository + from repositories.subscription_repo import SubscriptionRepository + from repositories.event_repo import EventRepository + from services.syncthing.device_manager import DeviceManager + from services.syncthing.folder_manager import FolderManager + from services.sync.metadata_service import MetadataService + + +class ReconciliationService: + def __init__(self, teams, members, projects, subs, events, + devices, folders, metadata, my_member_tag: str): + self.teams = teams + self.members = members + self.projects = projects + self.subs = subs + self.events = events + self.devices = devices + self.folders = folders + self.metadata = metadata + self.my_member_tag = my_member_tag + + async def run_cycle(self, conn: sqlite3.Connection) -> None: + """Run full 3-phase reconciliation for all teams.""" + for team in self.teams.list_all(conn): + await self.phase_metadata(conn, team) + await self.phase_mesh_pair(conn, team) + await self.phase_device_lists(conn, team) + + async def phase_metadata(self, conn, team): + """Phase 1: Read metadata, detect removals, discover members/projects.""" + states = self.metadata.read_team_metadata(team.name) + if not states: + return + + # Check removal signals + removals = states.pop("__removals", {}) + if self.my_member_tag in removals: + await self._auto_leave(conn, team) + return + + # Discover new members + for tag, state in states.items(): + existing = self.members.get(conn, team.name, tag) + if existing is None and tag != self.my_member_tag: + device_id = state.get("device_id") + if device_id and not self.members.was_removed(conn, team.name, device_id): + new_member = Member.from_member_tag( + member_tag=tag, team_name=team.name, device_id=device_id, + ) + activated = new_member.activate() + self.members.save(conn, activated) + elif existing and existing.status == MemberStatus.ADDED: + # Activate if we can see them in metadata (they've acknowledged) + self.members.save(conn, existing.activate()) + + # Discover/remove projects from leader's state + leader_state = states.get(team.leader_member_tag, {}) + leader_projects = {p["git_identity"] for p in leader_state.get("projects", [])} + local_projects = self.projects.list_for_team(conn, team.name) + + for lp in local_projects: + if lp.git_identity not in leader_projects and lp.status.value == "shared": + # Project removed by leader + removed = lp.remove() + self.projects.save(conn, removed) + for sub in self.subs.list_for_project(conn, team.name, lp.git_identity): + if sub.status != SubscriptionStatus.DECLINED: + self.subs.save(conn, sub.decline()) + + async def phase_mesh_pair(self, conn, team): + """Phase 2: Pair with undiscovered team members.""" + members = self.members.list_for_team(conn, team.name) + for member in members: + if member.is_active and member.member_tag != self.my_member_tag: + await self.devices.ensure_paired(member.device_id) + + async def phase_device_lists(self, conn, team): + """Phase 3: Declarative device list sync for all project folders.""" + projects = self.projects.list_for_team(conn, team.name) + for project in projects: + if project.status.value != "shared": + continue + accepted = self.subs.list_accepted_for_suffix(conn, project.folder_suffix) + # Devices that should have access: members with send|both direction + desired = set() + for sub in accepted: + if sub.direction in (SyncDirection.SEND, SyncDirection.BOTH): + member = self.members.get(conn, sub.team_name, sub.member_tag) + if member and member.is_active: + desired.add(member.device_id) + # Apply to all folders with this suffix + # (both outbox and inbox folders for this project) + from services.syncthing.folder_manager import build_outbox_folder_id + members = self.members.list_for_team(conn, team.name) + for m in members: + folder_id = build_outbox_folder_id(m.member_tag, project.folder_suffix) + await self.folders.set_folder_devices(folder_id, desired) + + async def _auto_leave(self, conn, team): + """Clean up everything for this team on the local machine.""" + projects = self.projects.list_for_team(conn, team.name) + members = self.members.list_for_team(conn, team.name) + suffixes = [p.folder_suffix for p in projects] + tags = [m.member_tag for m in members] + await self.folders.cleanup_team_folders(suffixes, tags, team.name) + + # Unpair devices not in other teams + for member in members: + if member.member_tag == self.my_member_tag: + continue + others = self.members.get_by_device(conn, member.device_id) + if len([o for o in others if o.team_name != team.name]) == 0: + await self.devices.unpair(member.device_id) + + self.teams.delete(conn, team.name) + self.events.log(conn, SyncEvent( + event_type=SyncEventType.MEMBER_AUTO_LEFT, team_name=team.name, + )) +``` + +- [ ] **Step 5: Commit** + +```bash +git add api/services/sync/reconciliation_service.py api/tests/test_reconciliation_service.py +git commit -m "feat(sync-v4): add ReconciliationService — 3-phase pipeline" +``` + +--- + +### Task 5: WatcherManager Rewrite + +**Files:** +- Modify: `api/services/watcher_manager.py` (rewrite sync-related portions) +- Test: `api/tests/test_watcher_manager_v4.py` + +**SEQUENTIAL — after Task 4** + +The WatcherManager runs the reconciliation service on a 60s timer and packages sessions based on subscriptions. Key changes from v3: +- Uses `ReconciliationService.run_cycle()` instead of 6 inline phases +- Session packaging gated by subscription direction (send|both only) +- Uses dedicated SQLite connection per timer thread (preserved from v3) + +- [ ] **Step 1-5: Write tests, implement, commit** + +Follow TDD pattern. Test that: +- Timer calls `reconciliation_service.run_cycle()` on tick +- Session packaging only runs for ACCEPTED subscriptions with send/both direction +- Thread-safe SQLite connection handling + +```bash +git commit -m "feat(sync-v4): rewrite WatcherManager — uses ReconciliationService" +``` + +--- + +### Task 6: Phase 3 Integration Test + +**Files:** +- Test: `api/tests/test_sync_v4_services.py` + +**SEQUENTIAL — after all services** + +- [ ] **Step 1: Write end-to-end service integration test** + +Test the full flow: create team → add member → share project → accept subscription → run reconciliation → verify device lists. + +Use in-memory SQLite + mocked Syncthing (DeviceManager, FolderManager). Verify domain model transitions, repo persistence, metadata file writes, and event logging all work together. + +- [ ] **Step 2: Run and commit** + +```bash +git add api/tests/test_sync_v4_services.py +git commit -m "test(sync-v4): add Phase 3 integration test — full service workflow" +``` + +--- + +## Phase 3 Completion Checklist + +- [ ] MetadataService reads/writes team metadata folders +- [ ] TeamService handles create/add/remove/dissolve with auth +- [ ] ProjectService handles share/accept/pause/resume/decline/change-direction/remove +- [ ] ReconciliationService runs 3-phase pipeline +- [ ] WatcherManager rewritten to use ReconciliationService +- [ ] Integration test passes +- [ ] No regressions: `cd api && pytest -v` diff --git a/docs/superpowers/plans/2026-03-17-sync-v4-phase4-api.md b/docs/superpowers/plans/2026-03-17-sync-v4-phase4-api.md new file mode 100644 index 00000000..53943802 --- /dev/null +++ b/docs/superpowers/plans/2026-03-17-sync-v4-phase4-api.md @@ -0,0 +1,607 @@ +# Sync v4 Phase 4: API + Integration — Routers, Cleanup, E2E + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. +> +> **TDD SKILL:** Use `oh-my-claudecode:tdd` or `superpowers:test-driven-development` for every task. + +**Goal:** Build thin FastAPI routers, delete old v3 files, and run end-to-end smoke tests. + +**Architecture:** Routers validate input and delegate to services. No business logic in routers. 4 routers replace 7 from v3. + +**Tech Stack:** FastAPI, pytest, httpx (TestClient) + +**Spec:** `docs/superpowers/specs/2026-03-17-sync-v4-domain-models-design.md` (sections: API Endpoints, File Layout, Deleted Files) + +**Parent Plan:** `docs/superpowers/plans/2026-03-17-sync-v4-master.md` + +**Depends on:** Phase 3 (all services) + +--- + +## Task Dependency Graph + +``` +Tasks 1-4 (Routers) ─── ALL PARALLEL ───→ Task 5 (Registration) → Task 6 (Delete old) → Task 7 (E2E) +``` + +--- + +### Task 1: sync_teams Router + +**Files:** +- Rewrite: `api/routers/sync_teams.py` +- Test: `api/tests/api/test_sync_teams_router.py` + +**CAN PARALLEL with Tasks 2-4** + +- [ ] **Step 1: Write failing tests** + +```python +# api/tests/api/test_sync_teams_router.py +import sys +from pathlib import Path +sys.path.insert(0, str(Path(__file__).parent.parent.parent)) + +import sqlite3 +import pytest +from unittest.mock import MagicMock, AsyncMock, patch +from fastapi.testclient import TestClient + + +@pytest.fixture +def mock_services(): + """Mock all service dependencies.""" + team_svc = MagicMock() + team_svc.create_team = AsyncMock() + team_svc.add_member = AsyncMock() + team_svc.remove_member = AsyncMock() + team_svc.dissolve_team = AsyncMock() + return {"team_service": team_svc} + + +class TestCreateTeam: + def test_create_team_returns_201(self, mock_services): + from domain.team import Team + mock_services["team_service"].create_team.return_value = Team( + name="karma", leader_device_id="D", leader_member_tag="j.m", + ) + # Test via TestClient against the router + # Assert 201 status, response body has team name + + def test_create_team_missing_name_returns_422(self, mock_services): + # Missing required field → 422 + + +class TestListTeams: + def test_list_returns_all_teams(self, mock_services): + # GET /sync/teams → list of teams + + +class TestGetTeam: + def test_get_team_returns_detail(self, mock_services): + # GET /sync/teams/{name} → team with members, projects, subs + + def test_get_nonexistent_returns_404(self, mock_services): + # 404 + + +class TestAddMember: + def test_add_member_with_pairing_code(self, mock_services): + # POST /sync/teams/{name}/members { pairing_code: "..." } + # PairingService.validate_code called + # TeamService.add_member called + + def test_add_member_non_leader_returns_403(self, mock_services): + # AuthorizationError → 403 + + +class TestRemoveMember: + def test_remove_member_returns_200(self, mock_services): + # DELETE /sync/teams/{name}/members/{tag} + + def test_remove_non_leader_returns_403(self, mock_services): + # 403 + + +class TestDissolveTeam: + def test_dissolve_returns_200(self, mock_services): + # DELETE /sync/teams/{name} + + def test_dissolve_non_leader_returns_403(self, mock_services): + # 403 +``` + +- [ ] **Step 2: Run tests to verify they fail** + +- [ ] **Step 3: Implement router** + +```python +# api/routers/sync_teams.py +"""Sync Teams + Members router — thin delegation to TeamService.""" +from __future__ import annotations + +from fastapi import APIRouter, Depends, HTTPException +from pydantic import BaseModel + +from domain.team import AuthorizationError + +router = APIRouter(prefix="/sync", tags=["sync-teams"]) + + +# --- Request/Response schemas --- + +class CreateTeamRequest(BaseModel): + name: str + +class AddMemberRequest(BaseModel): + pairing_code: str + +class TeamResponse(BaseModel): + name: str + leader_member_tag: str + status: str + created_at: str + +class MemberResponse(BaseModel): + member_tag: str + device_id: str + status: str + connected: bool = False + + +# --- Endpoints --- + +@router.post("/teams", status_code=201) +async def create_team(req: CreateTeamRequest): + """Create a new team. Caller becomes the leader.""" + # Get identity from SyncConfig + # Call team_service.create_team() + # Return TeamResponse + ... + +@router.get("/teams") +async def list_teams(): + """List all teams.""" + ... + +@router.get("/teams/{name}") +async def get_team(name: str): + """Team detail with members, projects, subscriptions.""" + ... + +@router.delete("/teams/{name}") +async def dissolve_team(name: str): + """Dissolve a team. Leader only.""" + ... + +@router.post("/teams/{name}/members") +async def add_member(name: str, req: AddMemberRequest): + """Add member via pairing code. Leader only.""" + # PairingService.validate_code(req.pairing_code) + # TeamService.add_member() + ... + +@router.delete("/teams/{name}/members/{tag}") +async def remove_member(name: str, tag: str): + """Remove a member. Leader only.""" + ... + +@router.get("/teams/{name}/members") +async def list_members(name: str): + """List team members with connection status.""" + ... +``` + +- [ ] **Step 4: Run tests, iterate, commit** + +```bash +git add api/routers/sync_teams.py api/tests/api/test_sync_teams_router.py +git commit -m "feat(sync-v4): rewrite sync_teams router — teams + members" +``` + +--- + +### Task 2: sync_projects Router + +**Files:** +- Rewrite: `api/routers/sync_projects.py` +- Test: `api/tests/api/test_sync_projects_router.py` + +**CAN PARALLEL with Tasks 1, 3-4** + +Endpoints: +- `POST /sync/teams/{name}/projects` — share project +- `DELETE /sync/teams/{name}/projects/{git_identity}` — remove project +- `GET /sync/teams/{name}/projects` — list team projects +- `POST /sync/subscriptions/{team}/{project}/accept` — accept with direction +- `POST /sync/subscriptions/{team}/{project}/pause` — pause +- `POST /sync/subscriptions/{team}/{project}/resume` — resume +- `POST /sync/subscriptions/{team}/{project}/decline` — decline +- `PATCH /sync/subscriptions/{team}/{project}/direction` — change direction +- `GET /sync/subscriptions` — list my subscriptions + +- [ ] **Step 1-4: Write tests, implement, commit** + +Follow same pattern as Task 1. Router delegates to `ProjectService`. + +```bash +git commit -m "feat(sync-v4): rewrite sync_projects router — sharing + subscriptions" +``` + +--- + +### Task 3: sync_pairing Router + +**Files:** +- Create: `api/routers/sync_pairing.py` +- Test: `api/tests/api/test_sync_pairing_router.py` + +**CAN PARALLEL with Tasks 1-2, 4** + +Endpoints: +- `GET /sync/pairing/code` — generate my pairing code +- `POST /sync/pairing/validate` — validate a code (preview) +- `GET /sync/devices` — connected devices with status + +- [ ] **Step 1-4: Write tests, implement, commit** + +```bash +git commit -m "feat(sync-v4): add sync_pairing router — pairing codes + device status" +``` + +--- + +### Task 4: sync_system Router + +**Files:** +- Simplify: `api/routers/sync_system.py` +- Test: `api/tests/api/test_sync_system_router.py` + +**CAN PARALLEL with Tasks 1-3** + +Endpoints: +- `GET /sync/status` — Syncthing running, version, device_id +- `POST /sync/initialize` — first-time setup +- `POST /sync/reconcile` — trigger manual reconciliation + +- [ ] **Step 1-4: Write tests, implement, commit** + +```bash +git commit -m "feat(sync-v4): simplify sync_system router" +``` + +--- + +### Task 5: Router Registration + Test Conftest + +**Files:** +- Modify: `api/main.py` (register new routers, remove old) +- Create/Modify: `api/tests/api/conftest.py` (shared fixtures for router tests) + +**SEQUENTIAL — after Tasks 1-4** + +- [ ] **Step 1: Update main.py** + +Remove old router imports: +```python +# DELETE these imports: +# from routers.sync_members import router as sync_members_router +# from routers.sync_pending import router as sync_pending_router +# from routers.sync_devices import router as sync_devices_router +# from routers.sync_operations import router as sync_operations_router + +# KEEP/UPDATE these: +from routers.sync_teams import router as sync_teams_router +from routers.sync_projects import router as sync_projects_router +from routers.sync_pairing import router as sync_pairing_router +from routers.sync_system import router as sync_system_router +``` + +Register new routers, remove old `app.include_router()` calls. + +- [ ] **Step 2: Create shared test conftest** + +```python +# api/tests/api/conftest.py additions +@pytest.fixture +def mock_sync_config(): + """Mock SyncConfig for router tests.""" + config = MagicMock() + config.user_id = "jayant" + config.machine_tag = "macbook" + config.member_tag = "jayant.macbook" + config.syncthing_api_key = "test-key" + config.syncthing_api_url = "http://localhost:8384" + return config +``` + +- [ ] **Step 3: Verify all routers load** + +Run: `cd api && python -c "from main import app; print('OK')"` +Expected: `OK` + +- [ ] **Step 4: Commit** + +```bash +git add api/main.py api/tests/api/conftest.py +git commit -m "feat(sync-v4): register v4 routers, remove v3 router imports" +``` + +--- + +### Task 6: Delete Old v3 Files + +**SEQUENTIAL — after Task 5 (routers confirmed working)** + +- [ ] **Step 1: Delete old router files** + +```bash +cd api +rm -f routers/sync_members.py +rm -f routers/sync_pending.py +rm -f routers/sync_devices.py +rm -f routers/sync_operations.py +``` + +- [ ] **Step 2: Delete old service files** + +```bash +rm -f services/sync_queries.py +rm -f services/sync_reconciliation.py +rm -f services/sync_folders.py +rm -f services/sync_metadata_reconciler.py +rm -f services/sync_metadata_writer.py +rm -f services/sync_identity.py +rm -f services/sync_policy.py +rm -f services/syncthing_proxy.py +rm -f db/sync_queries.py +``` + +- [ ] **Step 3: Delete old test files that test deleted code** + +```bash +rm -f tests/test_sync_metadata_creation.py +rm -f tests/test_sync_settings_cleanup.py +rm -f tests/test_auto_share_folders.py +rm -f tests/test_sync_handshake_reconciliation.py +rm -f tests/test_phase4.py +rm -f tests/test_folder_id.py +rm -f tests/test_folder_id_v2.py +``` + +- [ ] **Step 4: Run full test suite to verify no import errors** + +Run: `cd api && pytest -v` +Expected: ALL PASS (some old tests removed, new tests should all pass) + +- [ ] **Step 5: Commit** + +```bash +git add -A +git commit -m "chore(sync-v4): delete v3 sync files — replaced by domain model architecture" +``` + +--- + +### Task 7: End-to-End Smoke Test + +**Files:** +- Test: `api/tests/test_sync_v4_e2e.py` + +**SEQUENTIAL — final task** + +- [ ] **Step 1: Write E2E smoke test** + +```python +# api/tests/test_sync_v4_e2e.py +"""End-to-end smoke test: full sync v4 stack from router to domain model.""" +import sys +from pathlib import Path +sys.path.insert(0, str(Path(__file__).parent.parent)) + +import sqlite3 +import pytest +from unittest.mock import MagicMock, AsyncMock +from db.schema import ensure_schema + +# Import all layers to verify they connect +from domain.team import Team, TeamStatus +from domain.member import Member, MemberStatus +from domain.project import SharedProject, derive_folder_suffix +from domain.subscription import Subscription, SubscriptionStatus, SyncDirection +from domain.events import SyncEvent, SyncEventType +from repositories.team_repo import TeamRepository +from repositories.member_repo import MemberRepository +from repositories.project_repo import ProjectRepository +from repositories.subscription_repo import SubscriptionRepository +from repositories.event_repo import EventRepository +from services.sync.team_service import TeamService +from services.sync.project_service import ProjectService +from services.sync.pairing_service import PairingService +from services.sync.metadata_service import MetadataService +from services.sync.reconciliation_service import ReconciliationService + + +@pytest.fixture +def conn(): + c = sqlite3.connect(":memory:") + c.row_factory = sqlite3.Row + c.execute("PRAGMA foreign_keys=ON") + ensure_schema(c) + return c + + +@pytest.fixture +def meta_base(tmp_path): + return tmp_path / "meta" + + +@pytest.fixture +def stack(conn, meta_base): + """Build full service stack with mocked Syncthing.""" + devices = MagicMock() + devices.pair = AsyncMock() + devices.unpair = AsyncMock() + devices.ensure_paired = AsyncMock() + + folders = MagicMock() + folders.ensure_outbox_folder = AsyncMock() + folders.ensure_inbox_folder = AsyncMock() + folders.set_folder_devices = AsyncMock() + folders.remove_outbox_folder = AsyncMock() + folders.remove_device_from_team_folders = AsyncMock() + folders.cleanup_team_folders = AsyncMock() + folders.cleanup_project_folders = AsyncMock() + + repos = { + "teams": TeamRepository(), + "members": MemberRepository(), + "projects": ProjectRepository(), + "subs": SubscriptionRepository(), + "events": EventRepository(), + } + metadata = MetadataService(meta_base=meta_base) + + team_svc = TeamService( + **repos, devices=devices, metadata=metadata, folders=folders, + ) + project_svc = ProjectService( + **repos, folders=folders, metadata=metadata, + ) + recon_svc = ReconciliationService( + **repos, devices=devices, folders=folders, + metadata=metadata, my_member_tag="jayant.macbook", + ) + pairing_svc = PairingService() + + return { + "team_svc": team_svc, + "project_svc": project_svc, + "recon_svc": recon_svc, + "pairing_svc": pairing_svc, + "devices": devices, + "folders": folders, + **repos, + } + + +class TestFullE2EFlow: + """Tests the complete user journey from spec Flow 1-5.""" + + @pytest.mark.asyncio + async def test_complete_sync_lifecycle(self, conn, stack): + team_svc = stack["team_svc"] + project_svc = stack["project_svc"] + pairing_svc = stack["pairing_svc"] + + # Flow 1: Leader creates team + team = await team_svc.create_team( + conn, name="karma", leader_member_tag="jayant.macbook", + leader_device_id="DEV-L", + ) + assert team.status == TeamStatus.ACTIVE + + # Leader shares project + project = await project_svc.share_project( + conn, team_name="karma", by_device="DEV-L", + git_identity="jayantdevkar/claude-karma", + encoded_name="-Users-jayant-GitHub-claude-karma", + ) + assert project.git_identity == "jayantdevkar/claude-karma" + + # Flow 2: Member generates pairing code, leader adds them + code = pairing_svc.generate_code("ayush.laptop", "DEV-A") + info = pairing_svc.validate_code(code) + assert info.member_tag == "ayush.laptop" + + member = await team_svc.add_member( + conn, team_name="karma", by_device="DEV-L", + new_member_tag=info.member_tag, new_device_id=info.device_id, + ) + assert member.status == MemberStatus.ADDED + stack["devices"].pair.assert_called_with("DEV-A") + + # Verify subscription was auto-created + subs = stack["subs"].list_for_member(conn, "ayush.laptop") + assert len(subs) == 1 + assert subs[0].status == SubscriptionStatus.OFFERED + + # Flow 3: Member accepts project + accepted = await project_svc.accept_subscription( + conn, member_tag="ayush.laptop", team_name="karma", + git_identity="jayantdevkar/claude-karma", direction=SyncDirection.BOTH, + ) + assert accepted.status == SubscriptionStatus.ACCEPTED + assert accepted.direction == SyncDirection.BOTH + stack["folders"].ensure_outbox_folder.assert_called() + stack["folders"].ensure_inbox_folder.assert_called() + + # Flow 5: Member changes to receive-only + changed = await project_svc.change_direction( + conn, member_tag="ayush.laptop", team_name="karma", + git_identity="jayantdevkar/claude-karma", + direction=SyncDirection.RECEIVE, + ) + assert changed.direction == SyncDirection.RECEIVE + stack["folders"].remove_outbox_folder.assert_called() + + # Flow 4: Leader removes member + removed = await team_svc.remove_member( + conn, team_name="karma", by_device="DEV-L", member_tag="ayush.laptop", + ) + assert removed.status == MemberStatus.REMOVED + + # Verify events logged + events = stack["events"].query(conn, team="karma") + event_types = [e.event_type.value for e in events] + assert "team_created" in event_types + assert "project_shared" in event_types + assert "member_added" in event_types + assert "subscription_accepted" in event_types + assert "direction_changed" in event_types + assert "member_removed" in event_types +``` + +- [ ] **Step 2: Run E2E test** + +Run: `cd api && pytest tests/test_sync_v4_e2e.py -v` +Expected: ALL PASS + +- [ ] **Step 3: Run full test suite** + +Run: `cd api && pytest -v` +Expected: ALL PASS + +- [ ] **Step 4: Commit** + +```bash +git add api/tests/test_sync_v4_e2e.py +git commit -m "test(sync-v4): add E2E smoke test — complete sync lifecycle" +``` + +--- + +## Phase 4 Completion Checklist + +- [ ] 4 routers implemented (sync_teams, sync_projects, sync_pairing, sync_system) +- [ ] Routers registered in main.py +- [ ] Old v3 files deleted (13 files) +- [ ] Old v3 tests deleted +- [ ] E2E smoke test passes +- [ ] Full test suite passes: `cd api && pytest -v` +- [ ] All Phase 4 code committed + +--- + +## v4 Implementation Complete Checklist + +After all 4 phases: + +- [ ] **Phase 1:** Domain models + schema v19 + repositories +- [ ] **Phase 2:** Syncthing client + device/folder managers + pairing service +- [ ] **Phase 3:** TeamService + ProjectService + MetadataService + ReconciliationService + WatcherManager +- [ ] **Phase 4:** Routers + cleanup + E2E test +- [ ] **Full test suite green:** `cd api && pytest -v` +- [ ] **No v3 sync code remains** (all replaced or deleted) +- [ ] **Code review passed:** Use `superpowers:requesting-code-review` +- [ ] **Ready for PR:** Use `commit-commands:commit-push-pr` to open PR against main diff --git a/docs/superpowers/plans/2026-03-18-sync-v4-cleanup-and-cross-team-safety.md b/docs/superpowers/plans/2026-03-18-sync-v4-cleanup-and-cross-team-safety.md new file mode 100644 index 00000000..01a12e54 --- /dev/null +++ b/docs/superpowers/plans/2026-03-18-sync-v4-cleanup-and-cross-team-safety.md @@ -0,0 +1,838 @@ +# Sync v4 Cleanup & Cross-Team Safety Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Fix cross-team folder cleanup destructiveness, remove dead CLI sync code, and add folder existence guarantees to reconciliation — making v4 safe for multi-team, multi-member, multi-project setups. + +**Architecture:** Three workstreams: (1) Add cross-team reference counting to FolderManager cleanup methods so leaving/dissolving a team doesn't destroy folders needed by other teams, (2) Delete all dead CLI sync code that imports from the deleted `db/sync_queries.py`, (3) Add folder existence checks to Phase 3 reconciliation so it can recover from accidentally deleted folders. + +**Tech Stack:** Python 3.9+, FastAPI, Pydantic 2.x, SQLite, pytest, async/await + +--- + +## Background + +### The Problem + +v4's `cleanup_team_folders()` and `cleanup_project_folders()` delete Syncthing folders by matching `(member_tag × folder_suffix)`. Since folder IDs have no team scope (`karma-out--{member_tag}--{suffix}`), leaving Team A destroys folders that Team B also needs if they share the same member+project combination. This is the same root cause as v3's BP-3/BP-4 (documented in `docs/design/sync-v3-audit-findings.md`). + +Additionally, the entire CLI sync module (`cli/karma/main.py`, `cli/karma/pending.py`, etc.) imports from `db/sync_queries.py` which was deleted in v4. Since the user is fully on API endpoints, this is dead code that should be removed. + +### Files Involved + +**Modify:** +- `api/services/syncthing/folder_manager.py` — add cross-team safety to cleanup methods +- `api/services/sync/reconciliation_service.py` — add folder existence check in Phase 3 +- `api/services/sync/team_service.py` — pass `conn` to cleanup methods for DB queries + +**Delete (dead CLI sync code):** +- `cli/karma/pending.py` — imports from deleted `db.sync_queries` +- `cli/karma/watcher.py` — `_maybe_check_peers()` imports from deleted modules +- Sync commands in `cli/karma/main.py` — `team`, `share`, `unshare`, `watch`, `status`, `nuke`, `join`, `leave`, `pair` + +**Create (tests):** +- `api/tests/test_cross_team_cleanup.py` — multi-team overlap safety tests +- `api/tests/test_phase3_folder_recovery.py` — folder existence + recovery tests + +**Reference (read-only, for context):** +- `docs/design/sync-v3-audit-findings.md` — BP-3, BP-4 (cross-team cleanup bugs) +- `docs/superpowers/specs/2026-03-17-sync-v4-domain-models-design.md` — v4 design spec +- `api/db/schema.py` — v19 schema (sync_projects, sync_subscriptions) + +--- + +## Task 1: Add Cross-Team Folder Reference Counting to FolderManager + +The core fix. Before deleting a folder, check if any other team's active subscriptions reference the same `(member_tag, folder_suffix)` pair. + +**Files:** +- Modify: `api/services/syncthing/folder_manager.py` +- Modify: `api/services/sync/team_service.py` (pass `conn` through) +- Modify: `api/services/sync/reconciliation_service.py` (pass `conn` through) +- Test: `api/tests/test_cross_team_cleanup.py` + +### Approach + +`cleanup_team_folders()` and `cleanup_project_folders()` currently take `folder_suffixes` and `member_tags` as lists and delete the Cartesian product. The fix adds a `conn` parameter and a pre-deletion query: + +```sql +-- For each candidate folder_id = karma-out--{member_tag}--{suffix}: +-- Check if any OTHER team has an active subscription for this suffix +SELECT COUNT(*) FROM sync_subscriptions s +JOIN sync_projects p ON s.team_name = p.team_name AND s.project_git_identity = p.git_identity +WHERE p.folder_suffix = ? + AND s.member_tag = ? + AND s.status IN ('offered', 'accepted', 'paused') + AND s.team_name != ? +``` + +If count > 0, skip deletion (another team needs this folder). If count == 0, safe to delete. + +- [ ] **Step 1: Write failing test — multi-team folder cleanup safety** + +Create `api/tests/test_cross_team_cleanup.py`: + +```python +"""Tests for cross-team safe folder cleanup. + +Scenario: M1 is in T1 and T2, both sharing project P1. +Leaving T1 must NOT delete M1's P1 outbox folder because T2 still needs it. +""" +import sqlite3 +import pytest +from unittest.mock import AsyncMock, MagicMock + +from db.schema import ensure_schema +from domain.team import Team +from domain.member import Member, MemberStatus +from domain.project import SharedProject, derive_folder_suffix +from domain.subscription import Subscription, SubscriptionStatus, SyncDirection +from repositories.team_repo import TeamRepository +from repositories.member_repo import MemberRepository +from repositories.project_repo import ProjectRepository +from repositories.subscription_repo import SubscriptionRepository +from services.syncthing.folder_manager import FolderManager, build_outbox_folder_id + + +@pytest.fixture +def conn(): + db = sqlite3.connect(":memory:") + db.execute("PRAGMA foreign_keys = ON") + ensure_schema(db) + return db + + +@pytest.fixture +def repos(): + return { + "teams": TeamRepository(), + "members": MemberRepository(), + "projects": ProjectRepository(), + "subs": SubscriptionRepository(), + } + + +@pytest.fixture +def mock_client(): + client = AsyncMock() + client.get_config_folders = AsyncMock(return_value=[ + {"id": "karma-out--alice.laptop--owner-repo", "devices": []}, + {"id": "karma-meta--team-1", "devices": []}, + {"id": "karma-meta--team-2", "devices": []}, + ]) + client.delete_config_folder = AsyncMock() + return client + + +def _setup_two_teams_one_project(conn, repos): + """Create T1 and T2, both sharing the same project, M1 in both.""" + git_id = "owner/repo" + suffix = derive_folder_suffix(git_id) + + # Team 1 + t1 = Team(name="team-1", leader_device_id="DEV-LEADER1", leader_member_tag="leader1.mac") + repos["teams"].save(conn, t1) + m1_t1 = Member.from_member_tag( + member_tag="alice.laptop", team_name="team-1", + device_id="DEV-ALICE", status=MemberStatus.ACTIVE, + ) + repos["members"].save(conn, m1_t1) + p1_t1 = SharedProject(team_name="team-1", git_identity=git_id, folder_suffix=suffix) + repos["projects"].save(conn, p1_t1) + s1 = Subscription( + member_tag="alice.laptop", team_name="team-1", + project_git_identity=git_id, status=SubscriptionStatus.ACCEPTED, + direction=SyncDirection.BOTH, + ) + repos["subs"].save(conn, s1) + + # Team 2 + t2 = Team(name="team-2", leader_device_id="DEV-LEADER2", leader_member_tag="leader2.mac") + repos["teams"].save(conn, t2) + m1_t2 = Member.from_member_tag( + member_tag="alice.laptop", team_name="team-2", + device_id="DEV-ALICE", status=MemberStatus.ACTIVE, + ) + repos["members"].save(conn, m1_t2) + p1_t2 = SharedProject(team_name="team-2", git_identity=git_id, folder_suffix=suffix) + repos["projects"].save(conn, p1_t2) + s2 = Subscription( + member_tag="alice.laptop", team_name="team-2", + project_git_identity=git_id, status=SubscriptionStatus.ACCEPTED, + direction=SyncDirection.BOTH, + ) + repos["subs"].save(conn, s2) + + return suffix + + +class TestCrossTeamCleanup: + + @pytest.mark.asyncio + async def test_cleanup_skips_folder_needed_by_other_team(self, conn, repos, mock_client): + """Leaving T1 must NOT delete alice's outbox for owner/repo — T2 still needs it.""" + from pathlib import Path + + suffix = _setup_two_teams_one_project(conn, repos) + mgr = FolderManager(mock_client, karma_base=Path("/tmp/karma")) + + await mgr.cleanup_team_folders( + conn=conn, + folder_suffixes=[suffix], + member_tags=["alice.laptop", "leader1.mac"], + team_name="team-1", + ) + + # The outbox folder for alice should NOT have been deleted + deleted_ids = [call.args[0] for call in mock_client.delete_config_folder.call_args_list] + assert "karma-out--alice.laptop--owner-repo" not in deleted_ids + # But the metadata folder for team-1 SHOULD be deleted + assert "karma-meta--team-1" in deleted_ids + + @pytest.mark.asyncio + async def test_cleanup_deletes_folder_when_no_other_team(self, conn, repos, mock_client): + """Leaving T1 when alice is NOT in T2 SHOULD delete alice's outbox.""" + from pathlib import Path + + git_id = "owner/repo" + suffix = derive_folder_suffix(git_id) + + # Only Team 1 — no Team 2 + t1 = Team(name="team-1", leader_device_id="DEV-LEADER1", leader_member_tag="leader1.mac") + repos["teams"].save(conn, t1) + m1 = Member.from_member_tag( + member_tag="alice.laptop", team_name="team-1", + device_id="DEV-ALICE", status=MemberStatus.ACTIVE, + ) + repos["members"].save(conn, m1) + p1 = SharedProject(team_name="team-1", git_identity=git_id, folder_suffix=suffix) + repos["projects"].save(conn, p1) + s1 = Subscription( + member_tag="alice.laptop", team_name="team-1", + project_git_identity=git_id, status=SubscriptionStatus.ACCEPTED, + direction=SyncDirection.BOTH, + ) + repos["subs"].save(conn, s1) + + mgr = FolderManager(mock_client, karma_base=Path("/tmp/karma")) + await mgr.cleanup_team_folders( + conn=conn, + folder_suffixes=[suffix], + member_tags=["alice.laptop", "leader1.mac"], + team_name="team-1", + ) + + deleted_ids = [call.args[0] for call in mock_client.delete_config_folder.call_args_list] + assert "karma-out--alice.laptop--owner-repo" in deleted_ids + + @pytest.mark.asyncio + async def test_cleanup_project_skips_cross_team_folder(self, conn, repos, mock_client): + """Removing P1 from T1 must NOT delete alice's outbox if T2 shares P1.""" + from pathlib import Path + + suffix = _setup_two_teams_one_project(conn, repos) + mgr = FolderManager(mock_client, karma_base=Path("/tmp/karma")) + + await mgr.cleanup_project_folders( + conn=conn, + folder_suffix=suffix, + member_tags=["alice.laptop", "leader1.mac"], + team_name="team-1", + ) + + deleted_ids = [call.args[0] for call in mock_client.delete_config_folder.call_args_list] + assert "karma-out--alice.laptop--owner-repo" not in deleted_ids +``` + +- [ ] **Step 2: Run tests to verify they fail** + +Run: `cd api && python -m pytest tests/test_cross_team_cleanup.py -v` +Expected: FAIL — `cleanup_team_folders()` doesn't accept `conn` or `team_name` parameters yet. + +- [ ] **Step 3: Update FolderManager with cross-team safe cleanup** + +Modify `api/services/syncthing/folder_manager.py`: + +```python +# Add conn and team_name parameters to cleanup_team_folders +async def cleanup_team_folders( + self, + folder_suffixes: List[str], + member_tags: List[str], + team_name: str, + conn: "sqlite3.Connection | None" = None, +) -> None: + """Delete team folders, skipping outbox folders needed by other teams. + + For each candidate outbox folder (member_tag × suffix), checks if any + other team has an active subscription for the same (member_tag, suffix). + If so, skips deletion (another team needs the folder). + + The metadata folder (karma-meta--{team_name}) is always deleted since + metadata folders ARE team-scoped. + """ + target_ids = { + build_outbox_folder_id(mt, suffix) + for mt in member_tags + for suffix in folder_suffixes + } + meta_id = build_metadata_folder_id(team_name) + + # Determine which outbox folders are safe to delete + safe_to_delete = set() + if conn is not None: + for mt in member_tags: + for suffix in folder_suffixes: + folder_id = build_outbox_folder_id(mt, suffix) + if folder_id not in target_ids: + continue + # Check if any OTHER team has an active subscription + # for this member_tag + folder_suffix combination + row = conn.execute( + """ + SELECT COUNT(*) FROM sync_subscriptions s + JOIN sync_projects p + ON s.team_name = p.team_name + AND s.project_git_identity = p.git_identity + WHERE p.folder_suffix = ? + AND s.member_tag = ? + AND s.status IN ('offered', 'accepted', 'paused') + AND s.team_name != ? + """, + (suffix, mt, team_name), + ).fetchone() + if row[0] == 0: + safe_to_delete.add(folder_id) + else: + # No DB connection — fall back to deleting all (legacy behavior) + safe_to_delete = target_ids + + # Always delete the metadata folder (it IS team-scoped) + safe_to_delete.add(meta_id) + + all_folders = await self._client.get_config_folders() + for folder in all_folders: + if folder["id"] in safe_to_delete: + await self._client.delete_config_folder(folder["id"]) + + +# Same pattern for cleanup_project_folders +async def cleanup_project_folders( + self, + folder_suffix: str, + member_tags: List[str], + conn: "sqlite3.Connection | None" = None, + team_name: str = "", +) -> None: + """Delete outbox/inbox folders for a project, skipping cross-team shared ones.""" + target_ids = { + build_outbox_folder_id(mt, folder_suffix) for mt in member_tags + } + + safe_to_delete = set() + if conn is not None and team_name: + for mt in member_tags: + folder_id = build_outbox_folder_id(mt, folder_suffix) + row = conn.execute( + """ + SELECT COUNT(*) FROM sync_subscriptions s + JOIN sync_projects p + ON s.team_name = p.team_name + AND s.project_git_identity = p.git_identity + WHERE p.folder_suffix = ? + AND s.member_tag = ? + AND s.status IN ('offered', 'accepted', 'paused') + AND s.team_name != ? + """, + (folder_suffix, mt, team_name), + ).fetchone() + if row[0] == 0: + safe_to_delete.add(folder_id) + else: + safe_to_delete = target_ids + + all_folders = await self._client.get_config_folders() + for folder in all_folders: + if folder["id"] in safe_to_delete: + await self._client.delete_config_folder(folder["id"]) +``` + +- [ ] **Step 4: Update callers to pass `conn` and `team_name`** + +In `api/services/sync/team_service.py`, update `leave_team()` and `dissolve_team()`: + +```python +# leave_team — line ~234 +await self.folders.cleanup_team_folders(suffixes, tags, team_name, conn=conn) + +# dissolve_team — line ~274 +await self.folders.cleanup_team_folders(suffixes, tags, team_name, conn=conn) +``` + +In `api/services/sync/reconciliation_service.py`, update `_auto_leave()`: + +```python +# _auto_leave — line ~344 +await self.folders.cleanup_team_folders(suffixes, tags, team.name, conn=conn) +``` + +In `api/services/sync/project_service.py`, update `remove_project()`: + +```python +# remove_project — line ~141 +await self.folders.cleanup_project_folders( + removed.folder_suffix, tags, conn=conn, team_name=name, +) +``` + +- [ ] **Step 5: Run tests to verify they pass** + +Run: `cd api && python -m pytest tests/test_cross_team_cleanup.py -v` +Expected: PASS — all 3 tests green. + +- [ ] **Step 6: Run existing tests to verify no regressions** + +Run: `cd api && python -m pytest tests/test_folder_manager.py tests/test_team_service.py tests/test_reconciliation_service.py tests/test_project_service.py tests/test_sync_v4_e2e.py -v` +Expected: Existing tests may need minor updates for the new `conn` parameter (use `conn=None` for backward compat). + +- [ ] **Step 7: Commit** + +```bash +git add api/services/syncthing/folder_manager.py api/services/sync/team_service.py \ + api/services/sync/reconciliation_service.py api/services/sync/project_service.py \ + api/tests/test_cross_team_cleanup.py +git commit -m "fix(sync-v4): add cross-team safety to folder cleanup — skip folders needed by other teams" +``` + +--- + +## Task 2: Add Folder Existence Recovery to Phase 3 + +Phase 3 (`phase_device_lists`) calls `set_folder_devices()` which is a no-op if the folder doesn't exist. If a folder was accidentally deleted, Phase 3 can never recover it. Fix: ensure outbox folders exist before setting device lists. + +**Files:** +- Modify: `api/services/sync/reconciliation_service.py` +- Test: `api/tests/test_phase3_folder_recovery.py` + +- [ ] **Step 1: Write failing test — Phase 3 creates missing outbox folder** + +Create `api/tests/test_phase3_folder_recovery.py`: + +```python +"""Tests for Phase 3 folder existence recovery.""" +import sqlite3 +import pytest +from unittest.mock import AsyncMock + +from db.schema import ensure_schema +from domain.team import Team +from domain.member import Member, MemberStatus +from domain.project import SharedProject, derive_folder_suffix +from domain.subscription import Subscription, SubscriptionStatus, SyncDirection +from repositories.team_repo import TeamRepository +from repositories.member_repo import MemberRepository +from repositories.project_repo import ProjectRepository +from repositories.subscription_repo import SubscriptionRepository +from repositories.event_repo import EventRepository +from services.sync.reconciliation_service import ReconciliationService + + +@pytest.fixture +def conn(): + db = sqlite3.connect(":memory:") + db.execute("PRAGMA foreign_keys = ON") + ensure_schema(db) + return db + + +@pytest.fixture +def mock_folders(): + m = AsyncMock() + m.get_configured_folders = AsyncMock(return_value=[]) # No folders exist! + m.set_folder_devices = AsyncMock() + m.ensure_outbox_folder = AsyncMock() + return m + + +class TestPhase3FolderRecovery: + + @pytest.mark.asyncio + async def test_phase3_ensures_outbox_exists_for_accepted_send_sub(self, conn, mock_folders): + """Phase 3 should create missing outbox folders for members with send|both subs.""" + repos = { + "teams": TeamRepository(), + "members": MemberRepository(), + "projects": ProjectRepository(), + "subs": SubscriptionRepository(), + "events": EventRepository(), + } + + git_id = "owner/repo" + suffix = derive_folder_suffix(git_id) + + team = Team(name="team-1", leader_device_id="DEV-L", leader_member_tag="leader.mac") + repos["teams"].save(conn, team) + + m1 = Member.from_member_tag( + member_tag="alice.laptop", team_name="team-1", + device_id="DEV-ALICE", status=MemberStatus.ACTIVE, + ) + repos["members"].save(conn, m1) + + p1 = SharedProject(team_name="team-1", git_identity=git_id, folder_suffix=suffix) + repos["projects"].save(conn, p1) + + sub = Subscription( + member_tag="alice.laptop", team_name="team-1", + project_git_identity=git_id, status=SubscriptionStatus.ACCEPTED, + direction=SyncDirection.BOTH, + ) + repos["subs"].save(conn, sub) + + svc = ReconciliationService( + **repos, + devices=AsyncMock(), + folders=mock_folders, + metadata=AsyncMock(), + my_member_tag="alice.laptop", + my_device_id="DEV-ALICE", + ) + + await svc.phase_device_lists(conn, team) + + # Should have called ensure_outbox_folder for alice + mock_folders.ensure_outbox_folder.assert_called_once_with( + "alice.laptop", suffix, + ) +``` + +- [ ] **Step 2: Run test to verify it fails** + +Run: `cd api && python -m pytest tests/test_phase3_folder_recovery.py -v` +Expected: FAIL — `ensure_outbox_folder` never called. + +- [ ] **Step 3: Add folder existence check to phase_device_lists** + +In `api/services/sync/reconciliation_service.py`, update `phase_device_lists()`: + +```python +async def phase_device_lists(self, conn: sqlite3.Connection, team) -> None: + """Phase 3: Declarative device list sync + folder existence recovery.""" + from services.syncthing.folder_manager import build_outbox_folder_id + + projects = self.projects.list_for_team(conn, team.name) + team_members = self.members.list_for_team(conn, team.name) + + for project in projects: + if project.status.value != "shared": + continue + + accepted = self.subs.list_accepted_for_suffix(conn, project.folder_suffix) + + # Compute desired device set: members with send|both direction + desired: set[str] = set() + for sub in accepted: + if sub.direction in (SyncDirection.SEND, SyncDirection.BOTH): + member = self.members.get(conn, sub.team_name, sub.member_tag) + if member and member.is_active: + desired.add(member.device_id) + + # Ensure outbox folders exist for members with send|both subs + # in THIS team (recovery from accidental deletion) + for sub in accepted: + if sub.team_name != team.name: + continue + if sub.direction in (SyncDirection.SEND, SyncDirection.BOTH): + member = self.members.get(conn, sub.team_name, sub.member_tag) + if member and member.is_active: + await self.folders.ensure_outbox_folder( + sub.member_tag, project.folder_suffix, + ) + + # Apply declaratively to all outbox folders with this suffix + for m in team_members: + folder_id = build_outbox_folder_id(m.member_tag, project.folder_suffix) + await self.folders.set_folder_devices(folder_id, desired) +``` + +- [ ] **Step 4: Run tests to verify they pass** + +Run: `cd api && python -m pytest tests/test_phase3_folder_recovery.py tests/test_reconciliation_service.py -v` +Expected: PASS + +- [ ] **Step 5: Commit** + +```bash +git add api/services/sync/reconciliation_service.py api/tests/test_phase3_folder_recovery.py +git commit -m "fix(sync-v4): Phase 3 ensures outbox folders exist before setting device lists" +``` + +--- + +## Task 3: Delete Dead CLI Sync Code + +The CLI sync commands all import from `db.sync_queries` which doesn't exist in v4. Since the user is fully on API endpoints, delete all dead sync code from the CLI. + +**Files:** +- Delete: `cli/karma/pending.py` (entire file — all imports from deleted module) +- Modify: `cli/karma/watcher.py` (remove `_maybe_check_peers` and its imports) +- Modify: `cli/karma/main.py` (remove sync CLI commands, keep non-sync commands) +- Modify: `cli/karma/project_resolution.py` (remove sync_queries imports, keep non-sync functions) + +- [ ] **Step 1: Identify which CLI commands are sync-specific** + +Run: `cd cli && grep -n "def.*cmd\|@click.command\|@click.group" karma/main.py` +Identify sync commands: `team`, `share`, `unshare`, `watch`, `status`, `nuke`, `join`, `leave`, `pair`, `pending`, `overview` + +- [ ] **Step 2: Delete `cli/karma/pending.py`** + +This entire file imports from `db.sync_queries`. All its functionality is now in `api/routers/sync_pending.py`. + +```bash +git rm cli/karma/pending.py +``` + +- [ ] **Step 3: Clean `cli/karma/watcher.py`** + +Remove `_maybe_check_peers()` method and its peer check timer. Keep the basic `SessionWatcher` class (filesystem watching) since it's used by the API's `WatcherManager`. + +Remove lines 66-104 (`_maybe_check_peers`, `_schedule_peer_check`, `_run_peer_check`) and the peer timer from `start()` and `stop()`. + +- [ ] **Step 4: Clean `cli/karma/main.py`** + +Remove all sync CLI commands that import from `db.sync_queries`. Keep non-sync utilities (e.g., `init`, basic config commands if any exist without sync_queries deps). + +For each function that has `from db.sync_queries import ...`, either: +- Delete the entire command if it's sync-only +- Or rewrite to use API endpoints if still needed (unlikely per user's answer) + +- [ ] **Step 5: Clean `cli/karma/project_resolution.py`** + +Remove functions that import from `db.sync_queries`. Keep `resolve_local_project()` if it's used by non-CLI code (check imports first). + +- [ ] **Step 6: Verify no remaining imports from deleted module** + +Run: `grep -r "from db.sync_queries" cli/ --include="*.py"` +Expected: No matches. + +- [ ] **Step 7: Run API tests to verify no regressions** + +Run: `cd api && python -m pytest -x -q` +Expected: All tests pass (CLI code is not imported by API). + +- [ ] **Step 8: Commit** + +```bash +git add -A cli/ +git commit -m "refactor(sync-v4): remove dead CLI sync code — all sync operations via API now" +``` + +--- + +## Task 4: Multi-Team E2E Integration Test + +Add a comprehensive test that exercises the exact scenario from the v3 audit: M1 in T1 and T2, both sharing project P1, verify leaving T1 doesn't break T2's sync. + +**Files:** +- Create: `api/tests/test_sync_v4_multi_team_e2e.py` + +- [ ] **Step 1: Write the multi-team E2E test** + +```python +"""Multi-team overlap E2E test. + +Scenario from v3 audit (docs/design/sync-v3-audit-findings.md): +- T1: Leader L1, Member Alice — shares P1 +- T2: Leader L2, Member Alice — shares P1 +- Alice accepts P1 in both teams +- Alice leaves T1 +- Verify: Alice's P1 outbox still works for T2 +- Verify: T2's reconciliation Phase 3 still manages device lists correctly +""" +import sqlite3 +import pytest +from unittest.mock import AsyncMock, patch +from pathlib import Path + +from db.schema import ensure_schema +from repositories.team_repo import TeamRepository +from repositories.member_repo import MemberRepository +from repositories.project_repo import ProjectRepository +from repositories.subscription_repo import SubscriptionRepository +from repositories.event_repo import EventRepository +from services.sync.team_service import TeamService +from services.sync.project_service import ProjectService +from services.sync.reconciliation_service import ReconciliationService +from services.syncthing.folder_manager import build_outbox_folder_id + + +@pytest.fixture +def conn(): + db = sqlite3.connect(":memory:") + db.execute("PRAGMA foreign_keys = ON") + ensure_schema(db) + return db + + +@pytest.fixture +def mock_infra(): + """Mock Syncthing infrastructure.""" + devices = AsyncMock() + folders = AsyncMock() + folders.ensure_metadata_folder = AsyncMock() + folders.ensure_outbox_folder = AsyncMock() + folders.ensure_inbox_folder = AsyncMock() + folders.set_folder_devices = AsyncMock() + folders.cleanup_team_folders = AsyncMock() + folders.cleanup_project_folders = AsyncMock() + folders.remove_device_from_team_folders = AsyncMock() + folders.remove_outbox_folder = AsyncMock() + folders.get_configured_folders = AsyncMock(return_value=[]) + metadata = AsyncMock() + metadata.write_team_state = AsyncMock() + metadata.write_member_state = AsyncMock() + metadata.write_removal_signal = AsyncMock() + return devices, folders, metadata + + +class TestMultiTeamOverlapE2E: + + @pytest.mark.asyncio + async def test_leave_team1_preserves_team2_subscriptions(self, conn, mock_infra): + """Full lifecycle: create 2 teams, share same project, leave one, verify other intact.""" + devices, folders, metadata = mock_infra + repos = dict( + teams=TeamRepository(), members=MemberRepository(), + projects=ProjectRepository(), subs=SubscriptionRepository(), + events=EventRepository(), + ) + + team_svc = TeamService(**repos, devices=devices, metadata=metadata, folders=folders) + proj_svc = ProjectService(**repos, folders=folders, metadata=metadata) + + # 1. Create Team 1 (leader: L1) + t1 = await team_svc.create_team( + conn, name="team-1", + leader_member_tag="leader1.mac", leader_device_id="DEV-L1", + ) + + # 2. Create Team 2 (leader: L2) + t2 = await team_svc.create_team( + conn, name="team-2", + leader_member_tag="leader2.mac", leader_device_id="DEV-L2", + ) + + # 3. Both leaders share the same project + p1_t1 = await proj_svc.share_project( + conn, team_name="team-1", by_device="DEV-L1", + git_identity="owner/repo", encoded_name="-Users-me-repo", + ) + p1_t2 = await proj_svc.share_project( + conn, team_name="team-2", by_device="DEV-L2", + git_identity="owner/repo", encoded_name="-Users-me-repo", + ) + + # 4. Add Alice to both teams + m1_t1 = await team_svc.add_member( + conn, team_name="team-1", by_device="DEV-L1", + new_member_tag="alice.laptop", new_device_id="DEV-ALICE", + ) + m1_t2 = await team_svc.add_member( + conn, team_name="team-2", by_device="DEV-L2", + new_member_tag="alice.laptop", new_device_id="DEV-ALICE", + ) + + # 5. Alice accepts P1 in both teams + from domain.subscription import SyncDirection + sub_t1 = await proj_svc.accept_subscription( + conn, member_tag="alice.laptop", team_name="team-1", + git_identity="owner/repo", direction=SyncDirection.BOTH, + ) + sub_t2 = await proj_svc.accept_subscription( + conn, member_tag="alice.laptop", team_name="team-2", + git_identity="owner/repo", direction=SyncDirection.BOTH, + ) + + # Verify: Alice has ACCEPTED subs in both teams + all_subs = repos["subs"].list_for_member(conn, "alice.laptop") + accepted = [s for s in all_subs if s.status.value == "accepted"] + assert len(accepted) == 2 + + # 6. Alice leaves Team 1 + await team_svc.leave_team( + conn, team_name="team-1", member_tag="alice.laptop", + ) + + # 7. Verify: Alice's T2 subscription is still ACCEPTED + t2_subs = repos["subs"].list_for_member(conn, "alice.laptop") + t2_accepted = [s for s in t2_subs if s.team_name == "team-2" and s.status.value == "accepted"] + assert len(t2_accepted) == 1 + assert t2_accepted[0].direction.value == "both" + + # 8. Verify: T1 data is cleaned up + t1_check = repos["teams"].get(conn, "team-1") + assert t1_check is None # Deleted by leave_team + + # 9. Run Phase 3 for T2 — should still work + recon = ReconciliationService( + **repos, devices=devices, folders=folders, + metadata=metadata, my_member_tag="alice.laptop", + my_device_id="DEV-ALICE", + ) + t2_reloaded = repos["teams"].get(conn, "team-2") + await recon.phase_device_lists(conn, t2_reloaded) + + # Phase 3 should have called set_folder_devices for alice's outbox + assert folders.set_folder_devices.called +``` + +- [ ] **Step 2: Run the test** + +Run: `cd api && python -m pytest tests/test_sync_v4_multi_team_e2e.py -v` +Expected: PASS (after Tasks 1-2 are implemented). + +- [ ] **Step 3: Commit** + +```bash +git add api/tests/test_sync_v4_multi_team_e2e.py +git commit -m "test(sync-v4): add multi-team overlap E2E test — verifies cross-team safety" +``` + +--- + +## Task 5: Run Full Test Suite & Final Cleanup + +- [ ] **Step 1: Run all sync v4 tests** + +Run: `cd api && python -m pytest tests/test_sync_v4*.py tests/test_cross_team*.py tests/test_phase3*.py tests/test_team_service.py tests/test_folder_manager.py tests/test_reconciliation_service.py tests/test_project_service.py -v` +Expected: All green. + +- [ ] **Step 2: Run full API test suite** + +Run: `cd api && python -m pytest -x -q` +Expected: All green. + +- [ ] **Step 3: Verify no remaining dead imports** + +Run: `grep -r "sync_queries\|sync_rejected_folders\|sync_settings\|sync_team_projects" api/ cli/ --include="*.py" -l` +Expected: Only docs/plans files, no source code. + +- [ ] **Step 4: Final commit** + +```bash +git commit -m "chore(sync-v4): verify all tests pass after cross-team safety + dead code cleanup" +``` + +--- + +## Execution Order + +| Task | Depends On | Description | +|------|-----------|-------------| +| 1 | — | Cross-team safe cleanup in FolderManager | +| 2 | — | Phase 3 folder existence recovery | +| 3 | — | Delete dead CLI sync code | +| 4 | 1, 2 | Multi-team E2E integration test | +| 5 | 1, 2, 3, 4 | Full test suite verification | + +Tasks 1, 2, and 3 are independent and can be done in parallel. diff --git a/docs/superpowers/plans/2026-03-19-member-page-improvements.md b/docs/superpowers/plans/2026-03-19-member-page-improvements.md new file mode 100644 index 00000000..57e15ca6 --- /dev/null +++ b/docs/superpowers/plans/2026-03-19-member-page-improvements.md @@ -0,0 +1,1045 @@ +# Member Page Improvements Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Fix session visibility for remote members, switch to member_tag URLs, add sync health to member pages, and link team members tab to member detail pages. + +**Architecture:** Normalize `remote_user_id` in the indexer to always store `member_tag` (schema v20 migration for existing data). Switch API member lookup from `device_id` to `member_tag` with strict regex fallback for device_id. Add `project_sync` data to profile response to eliminate N+1 API calls. Frontend route rename + session query fix + sync health UI. + +**Tech Stack:** Python/FastAPI (backend), Svelte 5 (frontend), SQLite + +**Spec:** `docs/superpowers/specs/2026-03-19-member-page-improvements-design.md` + +--- + +### Task 1: Add `get_all_by_member_tag` to MemberRepository + +**Files:** +- Modify: `api/repositories/member_repo.py` +- Test: `api/tests/test_repo_member.py` + +- [ ] **Step 1: Write the failing test** + +Add to `api/tests/test_repo_member.py`: + +```python +class TestMemberRepoGetAllByMemberTag: + def test_returns_members_across_teams(self, conn, repo): + # Setup: two teams, same member_tag in both + from repositories.team_repo import TeamRepository + TeamRepository().save(conn, Team(name="t1", leader_device_id="D1", leader_member_tag="jay.mac")) + TeamRepository().save(conn, Team(name="t2", leader_device_id="D1", leader_member_tag="jay.mac")) + m1 = Member(team_name="t1", member_tag="jay.mac", device_id="D1", user_id="jay", machine_tag="mac") + m2 = Member(team_name="t2", member_tag="jay.mac", device_id="D1", user_id="jay", machine_tag="mac") + repo.save(conn, m1) + repo.save(conn, m2) + results = repo.get_all_by_member_tag(conn, "jay.mac") + assert len(results) == 2 + assert {r.team_name for r in results} == {"t1", "t2"} + + def test_returns_empty_for_unknown_tag(self, conn, repo): + assert repo.get_all_by_member_tag(conn, "nobody.nope") == [] +``` + +- [ ] **Step 2: Run test to verify it fails** + +Run: `cd api && python -m pytest tests/test_repo_member.py::TestMemberRepoGetAllByMemberTag -v` +Expected: FAIL — `AttributeError: 'MemberRepository' object has no attribute 'get_all_by_member_tag'` + +- [ ] **Step 3: Implement the method** + +Add to `api/repositories/member_repo.py` after `get_by_device`: + +```python + def get_all_by_member_tag( + self, conn: sqlite3.Connection, member_tag: str + ) -> list[Member]: + rows = conn.execute( + "SELECT * FROM sync_members WHERE member_tag = ?", (member_tag,) + ).fetchall() + return [self._row_to_member(r) for r in rows] + + def get_by_user_id( + self, conn: sqlite3.Connection, user_id: str + ) -> list[Member]: + rows = conn.execute( + "SELECT * FROM sync_members WHERE user_id = ?", (user_id,) + ).fetchall() + return [self._row_to_member(r) for r in rows] +``` + +- [ ] **Step 4: Run tests** + +Run: `cd api && python -m pytest tests/test_repo_member.py -v` +Expected: All PASS + +- [ ] **Step 5: Commit** + +```bash +cd /Users/jayantdevkar/Documents/GitHub/claude-karma/.claude/worktrees/syncthing-sync-design +git add api/repositories/member_repo.py api/tests/test_repo_member.py +git commit -m "feat(sync): add get_all_by_member_tag and get_by_user_id to MemberRepository + +Co-Authored-By: Claude Opus 4.6 (1M context) " +``` + +--- + +### Task 2: Normalize `remote_user_id` in indexer + schema v20 migration + +**Files:** +- Modify: `api/services/remote_sessions.py:298-387` +- Modify: `api/db/schema.py` (SCHEMA_VERSION + migration) +- Test: `api/tests/test_remote_user_id_normalization.py` + +- [ ] **Step 1: Write the failing test** + +Create `api/tests/test_remote_user_id_normalization.py`: + +```python +import sys +from pathlib import Path +sys.path.insert(0, str(Path(__file__).parent.parent)) + +import json +import sqlite3 +import pytest +from db.schema import ensure_schema +from domain.team import Team +from domain.member import Member, MemberStatus +from repositories.team_repo import TeamRepository +from repositories.member_repo import MemberRepository + + +@pytest.fixture +def conn(): + c = sqlite3.connect(":memory:") + c.row_factory = sqlite3.Row + c.execute("PRAGMA foreign_keys=ON") + ensure_schema(c) + return c + + +@pytest.fixture +def seeded_conn(conn): + TeamRepository().save(conn, Team(name="t1", leader_device_id="D1", leader_member_tag="jay.mac")) + MemberRepository().save(conn, Member( + team_name="t1", member_tag="jay.mac", device_id="D1", + user_id="jay", machine_tag="mac", status=MemberStatus.ACTIVE, + )) + return conn + + +class TestResolveUserIdNormalization: + def test_priority2_resolves_to_member_tag(self, seeded_conn, tmp_path): + """When manifest has user_id but no device_id match, resolve to member_tag via DB.""" + from services.remote_sessions import _resolve_user_id + # Clear cache + from services.remote_sessions import _resolved_user_cache + _resolved_user_cache.clear() + + user_dir = tmp_path / "jay" + user_dir.mkdir() + proj_dir = user_dir / "project1" + proj_dir.mkdir() + manifest = {"user_id": "jay"} # No device_id + (proj_dir / "manifest.json").write_text(json.dumps(manifest)) + + result = _resolve_user_id(user_dir, conn=seeded_conn) + assert result == "jay.mac" # Should resolve to member_tag, not bare "jay" + + def test_priority3_resolves_dir_name_to_member_tag(self, seeded_conn, tmp_path): + """When no manifest exists and dir_name is a bare user_id, resolve via DB.""" + from services.remote_sessions import _resolve_user_id + from services.remote_sessions import _resolved_user_cache + _resolved_user_cache.clear() + + user_dir = tmp_path / "jay" + user_dir.mkdir() + # No manifest — falls through to dir_name resolution + + result = _resolve_user_id(user_dir, conn=seeded_conn) + assert result == "jay.mac" + + def test_unknown_user_id_stays_as_is(self, seeded_conn, tmp_path): + """When user_id has no DB match, keep as-is.""" + from services.remote_sessions import _resolve_user_id + from services.remote_sessions import _resolved_user_cache + _resolved_user_cache.clear() + + user_dir = tmp_path / "unknown" + user_dir.mkdir() + proj_dir = user_dir / "project1" + proj_dir.mkdir() + manifest = {"user_id": "unknown"} + (proj_dir / "manifest.json").write_text(json.dumps(manifest)) + + result = _resolve_user_id(user_dir, conn=seeded_conn) + assert result == "unknown" # No DB match, stays as bare user_id + + +class TestV20Migration: + def test_stale_remote_user_id_fixed(self, seeded_conn): + """v20 migration SQL normalizes bare user_id to member_tag.""" + # Insert a session with stale remote_user_id = "jay" (bare user_id) + seeded_conn.execute( + "INSERT INTO sessions (uuid, project_encoded_name, jsonl_mtime, source, remote_user_id) " + "VALUES ('s1', '-Users-me-repo', 1.0, 'remote', 'jay')" + ) + seeded_conn.commit() + + # Run the v20 migration SQL directly (ensure_schema already ran, + # so we test the migration logic independently) + seeded_conn.execute(""" + UPDATE sessions SET remote_user_id = ( + SELECT m.member_tag FROM sync_members m + WHERE m.user_id = sessions.remote_user_id + LIMIT 1 + ) WHERE source = 'remote' + AND remote_user_id IS NOT NULL + AND remote_user_id NOT LIKE '%.%' + AND EXISTS ( + SELECT 1 FROM sync_members m + WHERE m.user_id = sessions.remote_user_id + ) + """) + seeded_conn.commit() + + row = seeded_conn.execute( + "SELECT remote_user_id FROM sessions WHERE uuid = 's1'" + ).fetchone() + assert row[0] == "jay.mac" + + def test_already_normalized_not_touched(self, seeded_conn): + """Sessions with member_tag format remote_user_id are left unchanged.""" + seeded_conn.execute( + "INSERT INTO sessions (uuid, project_encoded_name, jsonl_mtime, source, remote_user_id) " + "VALUES ('s2', '-Users-me-repo', 1.0, 'remote', 'jay.mac')" + ) + seeded_conn.commit() + + seeded_conn.execute(""" + UPDATE sessions SET remote_user_id = ( + SELECT m.member_tag FROM sync_members m + WHERE m.user_id = sessions.remote_user_id + LIMIT 1 + ) WHERE source = 'remote' + AND remote_user_id IS NOT NULL + AND remote_user_id NOT LIKE '%.%' + AND EXISTS ( + SELECT 1 FROM sync_members m + WHERE m.user_id = sessions.remote_user_id + ) + """) + + row = seeded_conn.execute( + "SELECT remote_user_id FROM sessions WHERE uuid = 's2'" + ).fetchone() + assert row[0] == "jay.mac" # unchanged +``` + +- [ ] **Step 2: Run tests to verify they fail** + +Run: `cd api && python -m pytest tests/test_remote_user_id_normalization.py -v` +Expected: FAIL — test_priority2 returns "jay" not "jay.mac" + +- [ ] **Step 3: Fix `_resolve_user_id` in `api/services/remote_sessions.py`** + +The key changes to `_resolve_user_id` (lines 298-387): + +1. Add comment at top: `# NOTE: remote_user_id should always be member_tag format (e.g., "jay.mac"), not bare user_id.` + +2. After Priority 2 (line 362-364), add DB normalization: + +```python + # Priority 2: manifest user_id (no DB match) + if manifest_uid: + resolved = manifest_uid + # Normalize bare user_id to member_tag via DB + if conn is not None and "." not in manifest_uid: + try: + members = MemberRepository().get_by_user_id(conn, manifest_uid) + if members: + resolved = members[0].member_tag + except Exception: + pass + break +``` + +3. **IMPORTANT**: Add a final normalization block BEFORE the cache write (line 386). Move the cache write after this block: + +```python + # Final normalization: if resolved is a bare user_id (no dot), + # attempt to resolve to full member_tag via DB lookup. + # This handles Priority 3 dir_name fallback and any other bare user_id. + if conn is not None and "." not in resolved: + try: + from repositories.member_repo import MemberRepository + members = MemberRepository().get_by_user_id(conn, resolved) + if members: + resolved = members[0].member_tag + except Exception: + pass + + # Cache the FINAL resolved value (after all normalization) + _resolved_user_cache[dir_name] = (now, resolved) + return resolved +``` + +This replaces the existing lines 386-387. The cache now stores the normalized value. + +- [ ] **Step 4: Add v20 migration to `api/db/schema.py`** + +Bump `SCHEMA_VERSION = 20` (line 13). + +Add after the v19 migration block: + +```python + if current_version < 20: + logger.info( + "Migrating → v20: normalize remote_user_id from bare user_id to member_tag" + ) + # Update sessions where remote_user_id is a bare user_id (no dot) + # and a matching sync_members entry exists. + conn.execute(""" + UPDATE sessions SET remote_user_id = ( + SELECT m.member_tag FROM sync_members m + WHERE m.user_id = sessions.remote_user_id + LIMIT 1 + ) WHERE source = 'remote' + AND remote_user_id IS NOT NULL + AND remote_user_id NOT LIKE '%.%' + AND EXISTS ( + SELECT 1 FROM sync_members m + WHERE m.user_id = sessions.remote_user_id + ) + """) +``` + +- [ ] **Step 5: Run tests** + +Run: `cd api && python -m pytest tests/test_remote_user_id_normalization.py -v` +Expected: All PASS + +- [ ] **Step 6: Run full test suite for regressions** + +Run: `cd api && python -m pytest tests/ -v --timeout=30 -x` +Expected: All PASS + +- [ ] **Step 7: Commit** + +```bash +git add api/services/remote_sessions.py api/db/schema.py api/tests/test_remote_user_id_normalization.py api/repositories/member_repo.py +git commit -m "fix(sync): normalize remote_user_id to always store member_tag + +_resolve_user_id() Priority 2/3 now resolves bare user_id to full +member_tag via DB lookup. Schema v20 migration fixes existing stale +values. This ensures MemberSessionsTab can query by member_tag reliably. + +Co-Authored-By: Claude Opus 4.6 (1M context) " +``` + +--- + +### Task 3: Switch member API endpoint from `device_id` to `identifier` + +**Files:** +- Modify: `api/routers/sync_members.py:122-295` +- Test: `api/tests/test_member_identifier.py` + +- [ ] **Step 1: Write the failing test** + +Create `api/tests/test_member_identifier.py`: + +```python +import sys +from pathlib import Path +sys.path.insert(0, str(Path(__file__).parent.parent)) + +import re +import pytest + +# Test the identifier detection regex +DEVICE_ID_RE = re.compile(r"^[A-Z2-7]{7}(-[A-Z2-7]{7}){7}$") + + +class TestDeviceIdDetection: + def test_real_device_id_matches(self): + assert DEVICE_ID_RE.match("VRE7WLU-CXIVLS5-ARODGO7-22PNRQ3-7AAQ3ET-5CHXGA4-T5FKVKU-UM5QLQW") + + def test_member_tag_does_not_match(self): + assert not DEVICE_ID_RE.match("jay.mac") + + def test_short_string_does_not_match(self): + assert not DEVICE_ID_RE.match("ABCDEFG") + + def test_lowercase_does_not_match(self): + assert not DEVICE_ID_RE.match("vre7wlu-cxivls5-arodgo7-22pnrq3-7aaq3et-5chxga4-t5fkvku-um5qlqw") +``` + +- [ ] **Step 2: Run test to verify it passes** (regex is standalone) + +Run: `cd api && python -m pytest tests/test_member_identifier.py -v` +Expected: All PASS + +- [ ] **Step 3: Refactor `get_member_profile` endpoint** + +In `api/routers/sync_members.py`, add the regex constant near the top: + +```python +import re + +DEVICE_ID_RE = re.compile(r"^[A-Z2-7]{7}(-[A-Z2-7]{7}){7}$") +``` + +Change the endpoint signature and lookup logic (lines 122-150): + +```python +@router.get("/members/{identifier}") +async def get_member_profile( + identifier: str, + conn: sqlite3.Connection = Depends(get_conn), + config=Depends(get_optional_config), +): + """Full member profile. Accepts member_tag or device_id (auto-detected).""" + if not identifier or not identifier.strip(): + raise HTTPException(400, "identifier must not be empty") + repos = make_repos() + + # Detect format: Syncthing device_id vs member_tag + if DEVICE_ID_RE.match(identifier): + memberships = repos["members"].get_by_device(conn, identifier) + else: + memberships = repos["members"].get_all_by_member_tag(conn, identifier) + + # Fallback for self: config device_id → member_tag + if not memberships and config: + my_did = ( + config.syncthing.device_id + if getattr(config, "syncthing", None) + else None + ) + if config.member_tag: + if identifier == my_did or identifier == config.member_tag: + teams = repos["teams"].list_all(conn) + for t in teams: + m = repos["members"].get(conn, t.name, config.member_tag) + if m: + memberships.append(m) + + if not memberships: + raise HTTPException(404, f"Member '{identifier}' not found") +``` + +- [ ] **Step 4: Add new fields to the profile response** + +After the stats computation (around line 280), add the new fields before building the final response dict: + +```python + # New fields: member_tag, machine_tag, unsynced_count, last_packaged_at, + # sync_direction, project_sync + from routers.sync_teams import _get_active_counts, _count_packaged + + unsynced_count = None + last_packaged_at = None + project_sync = None + sync_direction_val = None + + if is_you: + # Compute per-project sync data (eliminates N+1 API calls from frontend) + active_counts = _get_active_counts() + project_sync_list = [] + total_gap = 0 + for m in memberships: + team_projects = repos["projects"].list_for_team(conn, m.team_name) + for p in team_projects: + if p.status.value != "shared": + continue + enc, display = _resolve_project(conn, p.git_identity) + local_count = 0 + if enc: + row = conn.execute( + "SELECT COUNT(*) FROM sessions WHERE project_encoded_name = ? AND (source IS NULL OR source != 'remote')", + (enc,), + ).fetchone() + local_count = row[0] if row else 0 + packaged_count = _count_packaged(member_tag, p.folder_suffix) + active_count = active_counts.get(enc, 0) if enc else 0 + gap = max(0, local_count - packaged_count - active_count) + total_gap += gap + project_sync_list.append({ + "team_name": m.team_name, + "git_identity": p.git_identity, + "encoded_name": enc, + "name": display or p.git_identity, + "local_count": local_count, + "packaged_count": packaged_count, + "active_count": active_count, + "gap": gap, + }) + unsynced_count = total_gap + project_sync = project_sync_list + + # last_packaged_at — all session_packaged events are from self + lp_row = conn.execute( + "SELECT MAX(created_at) FROM sync_events WHERE event_type = 'session_packaged'" + ).fetchone() + last_packaged_at = lp_row[0] if lp_row and lp_row[0] else None + + # sync_direction: aggregate from accepted subscriptions + subs = repos["subs"].list_for_member(conn, member_tag) + accepted_dirs = {s.direction.value for s in subs if s.status.value == "accepted"} + if len(accepted_dirs) == 0: + sync_direction_val = None + elif len(accepted_dirs) == 1: + sync_direction_val = next(iter(accepted_dirs)) + else: + sync_direction_val = "mixed" +``` + +Then add these to the return dict (after existing fields): + +```python + return { + "member_tag": member_tag, + "user_id": user_id, + "machine_tag": memberships[0].machine_tag, + "device_id": device_id or "", + # ... existing fields ... + "unsynced_count": unsynced_count, + "last_packaged_at": last_packaged_at, + "sync_direction": sync_direction_val, + "project_sync": project_sync, + } +``` + +- [ ] **Step 5: Update `list_members` to include `member_tag` and `machine_tag`** + +In the listing endpoint response builder (lines 104-112), add `member_tag` and `machine_tag`: + +```python + result.append({ + "name": entry["name"], + "member_tag": tag, + "machine_tag": entry.get("_machine_tag", ""), + "device_id": did or "", + # ... rest unchanged + }) +``` + +Also store `_machine_tag` when building `members_by_tag` (line 87-93): + +```python + else: + members_by_tag[tag] = { + "name": m.user_id, + "device_id": m.device_id or (my_device_id if tag == my_member_tag else m.device_id), + "teams": [t.name], + "_added_at": m.added_at, + "_member_tag": tag, + "_machine_tag": m.machine_tag, + } +``` + +- [ ] **Step 6: Add member creation collision guard** + +In the add-member / join endpoint (find the function that creates new members — likely in `team_service.py` or `sync_members.py`), add a check before saving: + +```python +# Collision guard: reject if member_tag already registered to a different device +existing = repos["members"].get_all_by_member_tag(conn, new_member_tag) +for e in existing: + if e.device_id and e.device_id != new_device_id: + raise HTTPException(409, f"member_tag '{new_member_tag}' already registered to a different device") +``` + +- [ ] **Step 7: Update activity and settings endpoint signatures** + +In `sync_members.py`, find the activity endpoint (`GET /sync/members/{device_id}/activity`) and settings endpoints. Apply the same identifier resolution pattern: + +```python +@router.get("/members/{identifier}/activity") +async def get_member_activity( + identifier: str, + # ... existing params ... +): + # Resolve identifier to member_tag + if DEVICE_ID_RE.match(identifier): + memberships = repos["members"].get_by_device(conn, identifier) + else: + memberships = repos["members"].get_all_by_member_tag(conn, identifier) + if not memberships: + raise HTTPException(404, f"Member '{identifier}' not found") + member_tag = memberships[0].member_tag + # ... rest of function uses member_tag ... +``` + +Apply the same change to `GET /sync/teams/{team}/members/{identifier}/settings` and `PATCH /sync/teams/{team}/members/{identifier}/settings`. + +- [ ] **Step 7: Run tests** + +Run: `cd api && python -m pytest tests/test_member_identifier.py tests/test_packaging_service.py tests/test_project_status_gap.py -v` +Expected: All PASS + +- [ ] **Step 8: Commit** + +```bash +git add api/routers/sync_members.py api/tests/test_member_identifier.py +git commit -m "feat(sync): switch member API from device_id to member_tag identifier + +Auto-detects Syncthing device_id via strict base32 regex, falls back to +member_tag lookup. Adds member_tag, machine_tag, unsynced_count, +last_packaged_at, sync_direction, project_sync to profile response. +List endpoint now includes member_tag and machine_tag. + +Co-Authored-By: Claude Opus 4.6 (1M context) " +``` + +--- + +### Task 4: Update frontend TypeScript types + +**Files:** +- Modify: `frontend/src/lib/api-types.ts` + +- [ ] **Step 1: Update MemberProfile interface** + +Find the `MemberProfile` interface in `api-types.ts` and add the new fields: + +```typescript +export interface MemberProfile { + // ... existing fields ... + member_tag: string; + machine_tag: string; + unsynced_count: number | null; + last_packaged_at: string | null; + sync_direction: 'both' | 'send' | 'receive' | 'mixed' | null; + project_sync: MemberProjectSync[] | null; +} + +export interface MemberProjectSync { + team_name: string; + git_identity: string; + encoded_name: string | null; + name: string; + local_count: number; + packaged_count: number; + active_count: number; + gap: number; +} +``` + +Also update the member listing item type to include `member_tag` and `machine_tag`. + +- [ ] **Step 2: Run type check** + +Run: `cd frontend && npm run check` +Expected: May have errors in components that reference old fields — note them for next tasks. + +- [ ] **Step 3: Commit** + +```bash +cd /Users/jayantdevkar/Documents/GitHub/claude-karma/.claude/worktrees/syncthing-sync-design +git add frontend/src/lib/api-types.ts +git commit -m "feat(sync): add member_tag, project_sync, sync health fields to MemberProfile type + +Co-Authored-By: Claude Opus 4.6 (1M context) " +``` + +--- + +### Task 5: Rename frontend route from `[device_id]` to `[member_tag]` + +**Files:** +- Rename: `frontend/src/routes/members/[device_id]/` → `frontend/src/routes/members/[member_tag]/` +- Modify: `frontend/src/routes/members/[member_tag]/+page.server.ts` +- Modify: `frontend/src/routes/members/[member_tag]/+page.svelte` +- Modify: `frontend/src/routes/members/+page.svelte` + +- [ ] **Step 1: Rename the route directory** + +```bash +cd /Users/jayantdevkar/Documents/GitHub/claude-karma/.claude/worktrees/syncthing-sync-design +git mv frontend/src/routes/members/\[device_id\] frontend/src/routes/members/\[member_tag\] +``` + +- [ ] **Step 2: Update `+page.server.ts`** + +Change `params.device_id` to `params.member_tag` and update the API call: + +```typescript +export const load: PageServerLoad = async ({ fetch, params }) => { + const memberTag = params.member_tag; + + const profileResult = await safeFetch( + fetch, + `${API_BASE}/sync/members/${encodeURIComponent(memberTag)}` + ); + + return { + memberTag, + profile: profileResult.ok ? profileResult.data : null, + error: profileResult.ok ? null : profileResult.message + }; +}; +``` + +- [ ] **Step 3: Update `+page.svelte`** + +Update all references from `data.deviceId` to `data.memberTag`. Update breadcrumbs to show member_tag. + +- [ ] **Step 4: Update MemberListItem interface in `+page.server.ts`** + +In `frontend/src/routes/members/+page.server.ts`, the `MemberListItem` interface needs `member_tag` and `machine_tag` fields added to match the updated API response: + +```typescript +interface MemberListItem { + name: string; + member_tag: string; + machine_tag: string; + device_id: string; + connected: boolean; + is_you: boolean; + team_count: number; + teams: string[]; + added_at: string; +} +``` + +- [ ] **Step 5: Update members listing page** + +In `frontend/src/routes/members/+page.svelte`, change card links from `/members/{member.device_id}` to `/members/{member.member_tag}`. Change `{#each}` key from `member.device_id` to `member.member_tag`. + +- [ ] **Step 5: Run type check** + +Run: `cd frontend && npm run check` +Expected: 0 errors + +- [ ] **Step 6: Commit** + +```bash +git add -A frontend/src/routes/members/ +git commit -m "feat(sync): rename member route from [device_id] to [member_tag] + +Co-Authored-By: Claude Opus 4.6 (1M context) " +``` + +--- + +### Task 6: Fix MemberSessionsTab — use member_tag for remote query + +**Files:** +- Modify: `frontend/src/lib/components/team/MemberSessionsTab.svelte:117` + +- [ ] **Step 1: Fix the session query** + +In `MemberSessionsTab.svelte`, line 117, change: + +```typescript +// Before: +params.set('user', profile.user_id); + +// After: +params.set('user', profile.member_tag); +``` + +This is the one-line fix that makes remote sessions visible. It works because Task 2 normalized `remote_user_id` to always store `member_tag`. + +- [ ] **Step 2: Run type check** + +Run: `cd frontend && npm run check` +Expected: 0 errors + +- [ ] **Step 3: Commit** + +```bash +cd /Users/jayantdevkar/Documents/GitHub/claude-karma/.claude/worktrees/syncthing-sync-design +git add frontend/src/lib/components/team/MemberSessionsTab.svelte +git commit -m "fix(sync): use member_tag instead of user_id for remote session query + +Fixes sessions not showing up for remote members. The remote_user_id +column stores member_tag (e.g., 'jay.mac'), not bare user_id ('jay'). + +Co-Authored-By: Claude Opus 4.6 (1M context) " +``` + +--- + +### Task 7: Add clickable navigation from TeamMembersTab to member pages + +**Files:** +- Modify: `frontend/src/lib/components/team/TeamMembersTab.svelte` + +- [ ] **Step 1: Read the current component** + +Read `TeamMembersTab.svelte` to understand the current card template structure and variable names. + +- [ ] **Step 2: Make member name a link** + +Find the member name display element and wrap it in an `` tag: + +```svelte + + {member.user_id} + +``` + +- [ ] **Step 3: Make avatar clickable** + +Wrap the avatar div in an `` tag with the same href. Add hover ring effect: + +```svelte + + + +``` + +- [ ] **Step 4: Import getTeamMemberHexColor if not already imported** + +```typescript +import { getTeamMemberHexColor } from '$lib/utils'; +``` + +- [ ] **Step 5: Run type check** + +Run: `cd frontend && npm run check` +Expected: 0 errors + +- [ ] **Step 6: Commit** + +```bash +cd /Users/jayantdevkar/Documents/GitHub/claude-karma/.claude/worktrees/syncthing-sync-design +git add frontend/src/lib/components/team/TeamMembersTab.svelte +git commit -m "feat(sync): add clickable navigation from team members tab to member pages + +Name and avatar link to /members/{member_tag} with member-colored hover. + +Co-Authored-By: Claude Opus 4.6 (1M context) " +``` + +--- + +### Task 8: Update member detail page header with sync health metadata + +**Files:** +- Modify: `frontend/src/routes/members/[member_tag]/+page.svelte` + +- [ ] **Step 1: Read the current header section** + +Understand the current PageHeader usage and metadata items. + +- [ ] **Step 2: Update header metadata** + +Replace the current metadata items (device ID, throughput, last active) with: + +```svelte +{@const metadataItems = [ + { icon: Tag, text: profile.member_tag }, + { icon: Monitor, text: `Machine: ${profile.machine_tag}` }, + { icon: Users, text: `${profile.teams.length} team${profile.teams.length !== 1 ? 's' : ''}` }, +]} +``` + +For self (`is_you`), add sync health items: + +```svelte +{#if profile.is_you && profile.unsynced_count != null} + + + {profile.unsynced_count > 0 ? `${profile.unsynced_count} unsynced` : 'All synced'} + +{/if} +{#if profile.sync_direction} + Direction: {profile.sync_direction} +{/if} +{#if profile.last_packaged_at} + Last synced: {formatRelativeTime(profile.last_packaged_at)} +{/if} +``` + +- [ ] **Step 3: Run type check** + +Run: `cd frontend && npm run check` +Expected: 0 errors + +- [ ] **Step 4: Commit** + +```bash +cd /Users/jayantdevkar/Documents/GitHub/claude-karma/.claude/worktrees/syncthing-sync-design +git add frontend/src/routes/members/\[member_tag\]/+page.svelte +git commit -m "feat(sync): update member page header with sync health metadata + +Shows member_tag, machine, team count, unsynced count, sync direction, +and last synced time. Unsynced highlighted in warning color when > 0. + +Co-Authored-By: Claude Opus 4.6 (1M context) " +``` + +--- + +### Task 9: Add Sync Health card and Unsynced stat to MemberOverviewTab + +**Files:** +- Modify: `frontend/src/lib/components/team/MemberOverviewTab.svelte` + +- [ ] **Step 1: Read the current overview tab** + +Understand the stats row and existing cards. + +- [ ] **Step 2: Add Unsynced stat card** + +In the stats row (4th card), add: + +```svelte +{#if profile.is_you} +
+ + {profile.unsynced_count ?? 0} + +

Unsynced

+
+{:else} +
+ {profile.stats.total_projects} +

Projects

+
+{/if} +``` + +- [ ] **Step 3: Add Sync Health card (self only)** + +After the stats row, before the activity chart: + +```svelte +{#if profile.is_you && profile.project_sync} +
+
+

Sync Health

+ +
+
+ {#each profile.project_sync as ps (ps.git_identity)} +
+ {ps.name} + {ps.packaged_count}/{ps.local_count} packaged + {#if ps.gap === 0} + In Sync + {:else} + {ps.gap} ready + {/if} +
+ {/each} +
+
+{/if} +``` + +Add the sync function and state: + +```typescript +import { RefreshCw, Loader2 } from 'lucide-svelte'; +import { API_BASE } from '$lib/config'; +import { invalidateAll } from '$app/navigation'; + +let syncing = $state(false); + +async function syncNow() { + syncing = true; + try { + await fetch(`${API_BASE}/sync/package`, { method: 'POST' }).catch(() => null); + // Re-fetch page data (profile) via SvelteKit's invalidation + await invalidateAll(); + } finally { + syncing = false; + } +} +``` + +- [ ] **Step 4: Add "Sessions from {name}" card for remote members** + +```svelte +{#if !profile.is_you} +
+
+

Sessions from {profile.user_id}

+
+
+ {#each profile.teams as team (team.name)} + {#each team.projects as proj (proj.encoded_name)} +
+ {proj.name} + {proj.session_count} sessions +
+ {/each} + {/each} +
+
+{/if} +``` + +- [ ] **Step 5: Run type check** + +Run: `cd frontend && npm run check` +Expected: 0 errors + +- [ ] **Step 6: Commit** + +```bash +cd /Users/jayantdevkar/Documents/GitHub/claude-karma/.claude/worktrees/syncthing-sync-design +git add frontend/src/lib/components/team/MemberOverviewTab.svelte +git commit -m "feat(sync): add Sync Health card and unsynced stat to member overview + +Self view: Unsynced stat card + per-project Sync Health with Sync Now button. +Remote view: Sessions from {name} summary with per-project counts. + +Co-Authored-By: Claude Opus 4.6 (1M context) " +``` + +--- + +### Task 10: Final verification + +- [ ] **Step 1: Run all backend tests** + +Run: `cd api && python -m pytest tests/ -v --timeout=30` +Expected: All tests PASS + +- [ ] **Step 2: Run frontend type check** + +Run: `cd frontend && npm run check` +Expected: 0 errors + +- [ ] **Step 3: Manual E2E test** + +1. Start API + frontend +2. Navigate to `/members` → verify cards link to `/members/{member_tag}` +3. Click a member → verify breadcrumbs, header metadata, sessions tab works +4. Check self view: Unsynced stat, Sync Health card, Sync Now button +5. Check remote member: Sessions from {name} card +6. Navigate to `/team/{name}` → Members tab → click name → verify navigation +7. Verify member colors are consistent across all views + +- [ ] **Step 4: Commit any fixups** + +```bash +git add -A +git commit -m "chore(sync): member page improvements — final cleanup + +Co-Authored-By: Claude Opus 4.6 (1M context) " +``` diff --git a/docs/superpowers/plans/2026-03-19-unsynced-sessions.md b/docs/superpowers/plans/2026-03-19-unsynced-sessions.md new file mode 100644 index 00000000..f5117f70 --- /dev/null +++ b/docs/superpowers/plans/2026-03-19-unsynced-sessions.md @@ -0,0 +1,957 @@ +# Unsynced Sessions Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Let users see which sessions are ready to sync and trigger on-demand packaging at global, team, and per-project granularity. + +**Architecture:** Extract packaging pipeline from watcher_manager into a shared PackagingService. Add a `POST /sync/package` endpoint with scope params. Fix the gap calculation to exclude active sessions. Surface sync badges and "Sync Now" buttons in TeamProjectsTab and fix OverviewTab's sync action. + +**Tech Stack:** Python/FastAPI (backend), Svelte 5 (frontend), SQLite, SessionPackager (cli/karma/packager.py) + +**Spec:** `docs/superpowers/specs/2026-03-19-unsynced-sessions-design.md` + +--- + +### Task 1: Extract PackagingService from watcher_manager + +**Files:** +- Create: `api/services/sync/packaging_service.py` +- Modify: `api/services/watcher_manager.py:339-414` +- Test: `api/tests/test_packaging_service.py` + +- [ ] **Step 1: Write the failing test** + +Create `api/tests/test_packaging_service.py`: + +```python +import sys +from pathlib import Path +sys.path.insert(0, str(Path(__file__).parent.parent)) + +import sqlite3 +import threading +from unittest.mock import MagicMock, patch + +import pytest +from db.schema import ensure_schema +from domain.team import Team +from domain.project import SharedProject +from domain.subscription import Subscription, SubscriptionStatus, SyncDirection +from domain.member import Member, MemberStatus +from repositories.team_repo import TeamRepository +from repositories.project_repo import ProjectRepository +from repositories.subscription_repo import SubscriptionRepository +from repositories.member_repo import MemberRepository + + +@pytest.fixture +def conn(): + c = sqlite3.connect(":memory:") + c.row_factory = sqlite3.Row + c.execute("PRAGMA foreign_keys=ON") + ensure_schema(c) + return c + + +@pytest.fixture +def seeded_conn(conn): + """Seed a team with one project and an accepted send subscription.""" + TeamRepository().save(conn, Team(name="t1", leader_device_id="D1", leader_member_tag="jay.mac")) + ProjectRepository().save(conn, SharedProject( + team_name="t1", git_identity="owner/repo", + encoded_name="-Users-me-repo", folder_suffix="owner-repo", + )) + MemberRepository().save(conn, Member( + team_name="t1", member_tag="jay.mac", device_id="D1", + user_id="jay", machine_tag="mac", status=MemberStatus.ACTIVE, + )) + sub = Subscription( + member_tag="jay.mac", team_name="t1", + project_git_identity="owner/repo", + ).accept(SyncDirection.BOTH) + SubscriptionRepository().save(conn, sub) + return conn + + +class TestPackagingServiceResolve: + def test_resolve_projects_returns_accepted_send_projects(self, seeded_conn): + from services.sync.packaging_service import PackagingService + svc = PackagingService(member_tag="jay.mac") + projects = svc.resolve_packagable_projects(seeded_conn) + assert len(projects) == 1 + assert projects[0]["git_identity"] == "owner/repo" + assert projects[0]["team_name"] == "t1" + + def test_resolve_skips_receive_only_subscription(self, seeded_conn): + # Change subscription to receive-only + sub = SubscriptionRepository().get(seeded_conn, "jay.mac", "t1", "owner/repo") + updated = sub.change_direction(SyncDirection.RECEIVE) + SubscriptionRepository().save(seeded_conn, updated) + + from services.sync.packaging_service import PackagingService + svc = PackagingService(member_tag="jay.mac") + projects = svc.resolve_packagable_projects(seeded_conn) + assert len(projects) == 0 + + def test_resolve_no_scope_returns_all_teams(self, seeded_conn): + from services.sync.packaging_service import PackagingService + svc = PackagingService(member_tag="jay.mac") + projects = svc.resolve_packagable_projects(seeded_conn) + assert len(projects) == 1 + + def test_resolve_with_team_filter(self, seeded_conn): + from services.sync.packaging_service import PackagingService + svc = PackagingService(member_tag="jay.mac") + projects = svc.resolve_packagable_projects(seeded_conn, team_name="t1") + assert len(projects) == 1 + projects = svc.resolve_packagable_projects(seeded_conn, team_name="nonexistent") + assert len(projects) == 0 + + def test_resolve_with_project_filter(self, seeded_conn): + from services.sync.packaging_service import PackagingService + svc = PackagingService(member_tag="jay.mac") + projects = svc.resolve_packagable_projects( + seeded_conn, team_name="t1", git_identity="owner/repo", + ) + assert len(projects) == 1 + projects = svc.resolve_packagable_projects( + seeded_conn, team_name="t1", git_identity="nope", + ) + assert len(projects) == 0 +``` + +- [ ] **Step 2: Run test to verify it fails** + +Run: `cd api && python -m pytest tests/test_packaging_service.py -v` +Expected: FAIL — `ModuleNotFoundError: No module named 'services.sync.packaging_service'` + +- [ ] **Step 3: Implement PackagingService** + +Create `api/services/sync/packaging_service.py`: + +```python +"""Shared packaging service — used by both watcher and on-demand endpoint.""" +from __future__ import annotations + +import logging +import sqlite3 +import threading +from dataclasses import dataclass, field +from pathlib import Path +from typing import Any, Optional + +logger = logging.getLogger(__name__) + +# Per-project locks to prevent concurrent packaging of the same project +_project_locks: dict[str, threading.Lock] = {} +_locks_lock = threading.Lock() + + +def _get_project_lock(encoded_name: str) -> threading.Lock: + with _locks_lock: + if encoded_name not in _project_locks: + _project_locks[encoded_name] = threading.Lock() + return _project_locks[encoded_name] + + +@dataclass +class PackageResult: + team_name: str + git_identity: str + sessions_packaged: int = 0 + error: Optional[str] = None + + +class PackagingService: + """Centralised session packaging — resolves subscriptions, builds outbox + paths, calls SessionPackager, logs events.""" + + def __init__( + self, + member_tag: str, + user_id: str = "unknown", + machine_id: str = "unknown", + device_id: str = "", + ): + self.member_tag = member_tag + self.user_id = user_id + self.machine_id = machine_id + self.device_id = device_id + + def resolve_packagable_projects( + self, + conn: sqlite3.Connection, + *, + team_name: Optional[str] = None, + git_identity: Optional[str] = None, + ) -> list[dict[str, Any]]: + """Return projects the current member can package (accepted + send/both). + + Each entry: {"team_name", "git_identity", "encoded_name", "folder_suffix"} + """ + from repositories.subscription_repo import SubscriptionRepository + from repositories.project_repo import ProjectRepository + + subs = SubscriptionRepository().list_for_member(conn, self.member_tag) + results: list[dict[str, Any]] = [] + seen: set[tuple[str, str]] = set() # dedup by (encoded_name, team_name) + + for s in subs: + if s.status.value != "accepted": + continue + if s.direction.value not in ("send", "both"): + continue + if team_name and s.team_name != team_name: + continue + + project = ProjectRepository().get(conn, s.team_name, s.project_git_identity) + if not project or project.status.value != "shared": + continue + if git_identity and project.git_identity != git_identity: + continue + + enc = project.encoded_name or "" + key = (enc, s.team_name) + if key in seen: + continue + seen.add(key) + + results.append({ + "team_name": s.team_name, + "git_identity": project.git_identity, + "encoded_name": enc, + "folder_suffix": project.folder_suffix, + }) + return results + + def package_project( + self, + conn: sqlite3.Connection, + *, + team_name: str, + git_identity: str, + encoded_name: str, + folder_suffix: str, + ) -> PackageResult: + """Package sessions for a single project. Thread-safe via per-project lock.""" + from karma.packager import SessionPackager + from karma.worktree_discovery import find_worktree_dirs + from karma.config import KARMA_BASE + from services.syncthing.folder_manager import build_outbox_folder_id + + lock = _get_project_lock(encoded_name) + if not lock.acquire(blocking=False): + return PackageResult( + team_name=team_name, + git_identity=git_identity, + error="Packaging already in progress", + ) + + try: + projects_dir = Path.home() / ".claude" / "projects" + claude_dir = projects_dir / encoded_name + if not claude_dir.is_dir(): + return PackageResult( + team_name=team_name, + git_identity=git_identity, + error=f"Project dir not found: {encoded_name}", + ) + + # Resolve outbox path + folder_id = build_outbox_folder_id(self.member_tag, folder_suffix) + outbox = KARMA_BASE / folder_id + outbox.mkdir(parents=True, exist_ok=True) + + # Discover worktree dirs + wt_dirs = find_worktree_dirs(encoded_name, projects_dir) + + packager = SessionPackager( + project_dir=claude_dir, + user_id=self.user_id, + machine_id=self.machine_id, + device_id=self.device_id, + project_path="", + extra_dirs=wt_dirs, + member_tag=self.member_tag, + ) + manifest = packager.package(staging_dir=outbox) + count = len(manifest.sessions) if manifest else 0 + + # Log sync events + self._log_events(conn, team_name, git_identity, manifest) + + return PackageResult( + team_name=team_name, + git_identity=git_identity, + sessions_packaged=count, + ) + except Exception as e: + logger.warning("Packaging failed for %s: %s", encoded_name, e) + return PackageResult( + team_name=team_name, + git_identity=git_identity, + error=str(e), + ) + finally: + lock.release() + + def _log_events(self, conn, team_name, git_identity, manifest): + if not manifest or not manifest.sessions: + return + try: + from repositories.event_repo import EventRepository + from domain.events import SyncEvent, SyncEventType + repo = EventRepository() + for session_uuid in manifest.sessions: + repo.log(conn, SyncEvent( + event_type=SyncEventType.session_packaged, + team_name=team_name, + project_git_identity=git_identity, + session_uuid=session_uuid, + )) + except Exception: + logger.debug("Failed to log session_packaged events", exc_info=True) +``` + +- [ ] **Step 4: Run tests to verify they pass** + +Run: `cd api && python -m pytest tests/test_packaging_service.py -v` +Expected: All 5 tests PASS + +- [ ] **Step 5: Refactor watcher_manager to use PackagingService** + +In `api/services/watcher_manager.py`, replace the `make_package_fn` closure (lines 339-414) to delegate to `PackagingService.package_project()`: + +```python +# Replace make_package_fn with: +def make_package_fn( + en=encoded, pt=proj_teams, ps=proj.get("folder_suffix", en), + gi=proj.get("git_identity", en), +): + def package(): + from db.connection import get_writer_db + from services.sync.packaging_service import PackagingService + db = get_writer_db() + svc = PackagingService( + member_tag=member_tag or user_id, + user_id=user_id, + machine_id=machine_id, + device_id=device_id, + ) + # Try each team this project belongs to + for tn in pt: + svc.package_project( + db, + team_name=tn, + git_identity=gi, + encoded_name=en, + folder_suffix=ps, + ) + # Preserve _last_packaged_at for status reporting + self._last_packaged_at = ( + datetime.now(timezone.utc).isoformat() + ) + return package +``` + +- [ ] **Step 6: Run existing tests to verify no regressions** + +Run: `cd api && python -m pytest tests/ -v --timeout=30 -x` +Expected: All existing tests PASS + +- [ ] **Step 7: Commit** + +```bash +git add api/services/sync/packaging_service.py api/tests/test_packaging_service.py api/services/watcher_manager.py +git commit -m "refactor(sync): extract PackagingService from watcher_manager" +``` + +--- + +### Task 2: Add `POST /sync/package` endpoint + +**Files:** +- Modify: `api/routers/sync_system.py` +- Test: `api/tests/test_sync_package_endpoint.py` + +- [ ] **Step 1: Write the failing test** + +Create `api/tests/test_sync_package_endpoint.py`: + +```python +import sys +from pathlib import Path +sys.path.insert(0, str(Path(__file__).parent.parent)) + +from unittest.mock import AsyncMock, MagicMock, patch +import pytest +from httpx import AsyncClient, ASGITransport +from main import app + + +@pytest.fixture +def mock_config(): + config = MagicMock() + config.member_tag = "jay.mac" + config.user_id = "jay" + config.machine_id = "mac" + config.device_id = "D1" + config.syncthing = MagicMock() + config.syncthing.device_id = "D1" + return config + + +@pytest.mark.asyncio +async def test_package_endpoint_exists(mock_config): + """POST /sync/package returns 200, not 404/405.""" + with patch("routers.sync_system.require_config", return_value=mock_config): + with patch("services.sync.packaging_service.PackagingService") as MockSvc: + instance = MockSvc.return_value + instance.resolve_packagable_projects.return_value = [] + transport = ASGITransport(app=app) + async with AsyncClient(transport=transport, base_url="http://test") as client: + res = await client.post("/sync/package") + assert res.status_code != 404 + assert res.status_code != 405 +``` + +- [ ] **Step 2: Run test to verify it fails** + +Run: `cd api && python -m pytest tests/test_sync_package_endpoint.py -v` +Expected: FAIL — 404 or 405 (route doesn't exist yet) + +- [ ] **Step 3: Implement the endpoint** + +Add to `api/routers/sync_system.py`: + +```python +@router.post("/package") +async def trigger_package( + team_name: Optional[str] = None, + git_identity: Optional[str] = None, + conn: sqlite3.Connection = Depends(get_conn), + config=Depends(require_config), +): + """Trigger on-demand session packaging. + + Scope: + - No params: all projects across all teams + - team_name: all projects in that team + - team_name + git_identity: single project + """ + from services.sync.packaging_service import PackagingService + + svc = PackagingService( + member_tag=config.member_tag, + user_id=config.user_id, + machine_id=config.machine_id, + device_id=config.syncthing.device_id if config.syncthing else "", + ) + + projects = svc.resolve_packagable_projects( + conn, team_name=team_name, git_identity=git_identity, + ) + + results = [] + for proj in projects: + result = svc.package_project( + conn, + team_name=proj["team_name"], + git_identity=proj["git_identity"], + encoded_name=proj["encoded_name"], + folder_suffix=proj["folder_suffix"], + ) + entry = { + "team_name": result.team_name, + "git_identity": result.git_identity, + "sessions_packaged": result.sessions_packaged, + } + if result.error: + entry["error"] = result.error + results.append(entry) + + return {"ok": True, "packaged": results} +``` + +Also add `Optional` import if not already present at top of file. + +- [ ] **Step 4: Run test to verify it passes** + +Run: `cd api && python -m pytest tests/test_sync_package_endpoint.py -v` +Expected: PASS + +- [ ] **Step 5: Commit** + +```bash +git add api/routers/sync_system.py api/tests/test_sync_package_endpoint.py +git commit -m "feat(sync): add POST /sync/package endpoint for on-demand packaging" +``` + +--- + +### Task 3: Fix gap calculation — exclude active sessions + +**Files:** +- Modify: `api/routers/sync_teams.py:291-366` +- Test: `api/tests/test_project_status_gap.py` + +- [ ] **Step 1: Write the failing test** + +Create `api/tests/test_project_status_gap.py`: + +```python +import sys +from pathlib import Path +sys.path.insert(0, str(Path(__file__).parent.parent)) + +import json +import tempfile +from datetime import datetime, timezone, timedelta +from unittest.mock import patch + +import pytest +from routers.sync_teams import _get_active_counts + + +@pytest.fixture +def live_sessions_dir(tmp_path): + """Create a temp live-sessions dir with test data.""" + live_dir = tmp_path / "live-sessions" + live_dir.mkdir() + return live_dir + + +def _write_live_session(live_dir, slug, session_id, encoded_name, state="RUNNING", idle_minutes=0): + now = datetime.now(timezone.utc) + updated = now - timedelta(minutes=idle_minutes) + data = { + "session_id": session_id, + "state": state, + "transcript_path": f"/Users/me/.claude/projects/{encoded_name}/{session_id}.jsonl", + "updated_at": updated.isoformat(), + } + (live_dir / f"{slug}.json").write_text(json.dumps(data)) + + +class TestGetActiveCounts: + def test_empty_dir_returns_empty(self, live_sessions_dir): + result = _get_active_counts(live_sessions_dir) + assert result == {} + + def test_running_session_counted(self, live_sessions_dir): + _write_live_session(live_sessions_dir, "s1", "uuid-1", "-Users-me-repo", state="RUNNING") + result = _get_active_counts(live_sessions_dir) + assert result.get("-Users-me-repo", 0) == 1 + + def test_ended_session_not_counted(self, live_sessions_dir): + _write_live_session(live_sessions_dir, "s1", "uuid-1", "-Users-me-repo", state="ENDED") + result = _get_active_counts(live_sessions_dir) + assert result.get("-Users-me-repo", 0) == 0 + + def test_stale_session_not_counted(self, live_sessions_dir): + _write_live_session(live_sessions_dir, "s1", "uuid-1", "-Users-me-repo", state="RUNNING", idle_minutes=35) + result = _get_active_counts(live_sessions_dir) + assert result.get("-Users-me-repo", 0) == 0 + + def test_multiple_projects(self, live_sessions_dir): + _write_live_session(live_sessions_dir, "s1", "uuid-1", "-Users-me-repo-a", state="RUNNING") + _write_live_session(live_sessions_dir, "s2", "uuid-2", "-Users-me-repo-a", state="RUNNING") + _write_live_session(live_sessions_dir, "s3", "uuid-3", "-Users-me-repo-b", state="RUNNING") + result = _get_active_counts(live_sessions_dir) + assert result["-Users-me-repo-a"] == 2 + assert result["-Users-me-repo-b"] == 1 +``` + +- [ ] **Step 2: Run test to verify it fails** + +Run: `cd api && python -m pytest tests/test_project_status_gap.py -v` +Expected: FAIL — `ImportError: cannot import name '_get_active_counts'` + +- [ ] **Step 3: Implement `_get_active_counts` helper** + +Add to `api/routers/sync_teams.py`, near the other helpers: + +```python +def _get_active_counts(live_sessions_dir: Path | None = None) -> dict[str, int]: + """Count active (non-ended, non-stale) sessions per project encoded_name. + + Reads ~/.claude_karma/live-sessions/*.json. Returns {encoded_name: count}. + Uses worktree-to-parent resolution so worktree sessions roll up to + the real project (same logic as LiveSession.resolved_project_encoded_name). + """ + from karma.packager import STALE_LIVE_SESSION_SECONDS + + if live_sessions_dir is None: + from config import settings as app_settings + live_sessions_dir = app_settings.karma_base / "live-sessions" + + if not live_sessions_dir.is_dir(): + return {} + + import json as _json + now = datetime.now(timezone.utc) + counts: dict[str, int] = {} + + for json_file in live_sessions_dir.glob("*.json"): + try: + data = _json.loads(json_file.read_text(encoding="utf-8")) + if data.get("state") == "ENDED": + continue + + # Check staleness + updated_str = data.get("updated_at") + if updated_str: + updated = datetime.fromisoformat(updated_str.replace("Z", "+00:00")) + if updated.tzinfo is None: + updated = updated.replace(tzinfo=timezone.utc) + if (now - updated).total_seconds() > STALE_LIVE_SESSION_SECONDS: + continue + + # Extract encoded_name from transcript_path + tp = data.get("transcript_path", "") + if "/projects/" not in tp: + continue + parts = tp.split("/projects/", 1)[1].split("/") + if not parts: + continue + enc = parts[0] + + # Worktree resolution: if the encoded name looks like a worktree + # path (contains ".claude-worktrees" or "claude/worktrees"), + # resolve to the real project via git_root if available. + git_root = data.get("git_root") + if git_root and (".claude-worktrees" in enc or "-worktrees-" in enc): + enc = "-" + git_root.lstrip("/").replace("/", "-") + + counts[enc] = counts.get(enc, 0) + 1 + except (ValueError, OSError): + continue + return counts +``` + +Also add required imports at top of file if not present: `from datetime import datetime, timezone` and `from pathlib import Path`. + +- [ ] **Step 4: Run test to verify it passes** + +Run: `cd api && python -m pytest tests/test_project_status_gap.py -v` +Expected: All 5 tests PASS + +- [ ] **Step 5: Wire into `get_project_status` endpoint** + +In `api/routers/sync_teams.py`, modify `get_project_status` (around line 338-365): + +```python + # After computing local_counts and received_by_encoded... + # Get active session counts to exclude from gap + active_counts = _get_active_counts() + + result = [] + for p in projects: + # ... existing sub_counts, encoded, display logic ... + local_count = local_counts.get(encoded, 0) if encoded else 0 + received = received_by_encoded.get(encoded, {}) if encoded else {} + packaged_count = ( + _count_packaged(member_tag, p.folder_suffix) if member_tag else 0 + ) + active_count = active_counts.get(encoded, 0) if encoded else 0 + + result.append({ + # ... existing fields ... + "active_count": active_count, + "gap": max(0, local_count - packaged_count - active_count) if member_tag else None, + }) +``` + +- [ ] **Step 6: Run all sync tests to verify no regressions** + +Run: `cd api && python -m pytest tests/test_project_status_gap.py tests/test_packaging_service.py -v` +Expected: All PASS + +- [ ] **Step 7: Commit** + +```bash +git add api/routers/sync_teams.py api/tests/test_project_status_gap.py +git commit -m "fix(sync): exclude active sessions from gap calculation, add active_count field" +``` + +--- + +### Task 4: Update frontend TypeScript types + +**Files:** +- Modify: `frontend/src/lib/api-types.ts` + +- [ ] **Step 1: Update SyncProjectStatus type** + +In `frontend/src/lib/api-types.ts`, replace the type alias (line 1824-1825): + +```typescript +/** Per-project sync status with active session tracking */ +export interface SyncProjectStatus extends SyncTeamProject { + active_count?: number; + subscription_counts?: { + offered: number; + accepted: number; + paused: number; + declined: number; + }; +} +``` + +- [ ] **Step 2: Run type check** + +Run: `cd frontend && npm run check` +Expected: No new type errors + +- [ ] **Step 3: Commit** + +```bash +git add frontend/src/lib/api-types.ts +git commit -m "feat(sync): break SyncProjectStatus into own interface with active_count" +``` + +--- + +### Task 5: Add sync badges and actions to TeamProjectsTab + +**Files:** +- Modify: `frontend/src/lib/components/team/TeamProjectsTab.svelte` + +- [ ] **Step 1: Add project-status data fetching** + +Add to the ` @@ -192,7 +180,7 @@ {/if} + {/each} + + +{/if} +
Date range
diff --git a/frontend/src/lib/components/FiltersBottomSheet.svelte b/frontend/src/lib/components/FiltersBottomSheet.svelte index 4bfe72d0..0a99b43e 100644 --- a/frontend/src/lib/components/FiltersBottomSheet.svelte +++ b/frontend/src/lib/components/FiltersBottomSheet.svelte @@ -6,6 +6,7 @@ import type { SearchScopeSelection, SessionStatusFilter, + SessionSourceFilter, SearchDateRange, LiveSubStatus, LiveStatusCounts @@ -31,6 +32,10 @@ liveStatusCounts?: LiveStatusCounts; /** Count of completed sessions */ completedCount?: number; + /** Current source filter */ + source?: SessionSourceFilter; + /** Callback when source filter changes */ + onSourceChange?: (source: SessionSourceFilter) => void; } let { @@ -46,7 +51,9 @@ liveSubStatuses = ALL_LIVE_SUB_STATUSES, onLiveSubStatusChange, liveStatusCounts, - completedCount + completedCount, + source = 'all', + onSourceChange }: Props = $props(); // Prevent body scroll when sheet is open @@ -135,6 +142,8 @@ {onLiveSubStatusChange} {liveStatusCounts} {completedCount} + {source} + {onSourceChange} variant="mobile" />
diff --git a/frontend/src/lib/components/FiltersDropdown.svelte b/frontend/src/lib/components/FiltersDropdown.svelte index 04d0f812..3f848684 100644 --- a/frontend/src/lib/components/FiltersDropdown.svelte +++ b/frontend/src/lib/components/FiltersDropdown.svelte @@ -4,6 +4,7 @@ import { browser } from '$app/environment'; import type { SessionStatusFilter, + SessionSourceFilter, SearchDateRange, LiveSubStatus, LiveStatusCounts, @@ -31,6 +32,10 @@ completedCount?: number; /** Whether data is currently loading/updating */ isLoading?: boolean; + /** Current source filter */ + source?: SessionSourceFilter; + /** Callback when source filter changes */ + onSourceChange?: (source: SessionSourceFilter) => void; class?: string; } @@ -48,6 +53,8 @@ liveStatusCounts, completedCount, isLoading = false, + source = 'all', + onSourceChange, class: className = '' }: Props = $props(); @@ -115,6 +122,8 @@ {onLiveSubStatusChange} {liveStatusCounts} {completedCount} + {source} + {onSourceChange} variant="desktop" /> diff --git a/frontend/src/lib/components/GlobalSessionCard.svelte b/frontend/src/lib/components/GlobalSessionCard.svelte index 62bad90f..d62d665b 100644 --- a/frontend/src/lib/components/GlobalSessionCard.svelte +++ b/frontend/src/lib/components/GlobalSessionCard.svelte @@ -8,7 +8,8 @@ GitBranch, Folder, Monitor, - Bot + Bot, + Globe } from 'lucide-svelte'; import type { SessionWithContext, LiveSessionSummary } from '$lib/api-types'; import { statusConfig } from '$lib/live-session-config'; @@ -22,7 +23,9 @@ getProjectNameFromEncoded, getSessionDisplayName, sessionHasTitle, - getSessionDisplayPrompt + getSessionDisplayPrompt, + isRemoteSession, + getTeamMemberColor } from '$lib/utils'; interface Props { @@ -47,6 +50,13 @@ const modelColor = $derived(getModelColor(session.models_used)); const hasBranch = $derived(session.git_branches && session.git_branches.length > 0); + // Remote session handling + const isRemote = $derived(isRemoteSession(session)); + const teamMemberColor = $derived( + session.remote_user_id ? getTeamMemberColor(session.remote_user_id) : null + ); + const remoteUserName = $derived(session.remote_user_id ?? null); + // Parse project name from encoded name to preserve hyphens (e.g., "claude-karma" not "karma") const displayProjectName = $derived( session.project_display_name || session.project_name || getProjectNameFromEncoded(session.project_encoded_name ?? '') @@ -107,16 +117,21 @@ // - Recently ended (≤45 min) → model color // - Old sessions → faint gray const leftBorderColor = $derived( - hasLiveStatus - ? isRecentlyEnded - ? modelColorConfig[modelColor].border // Recently ended → model - : (liveStatusConfig?.color ?? modelColorConfig[modelColor].border) // Active → status - : 'var(--text-faint)' // Old → faint + isRemote && teamMemberColor + ? teamMemberColor.border // Remote → team member color + : hasLiveStatus + ? isRecentlyEnded + ? modelColorConfig[modelColor].border // Recently ended → model + : (liveStatusConfig?.color ?? modelColorConfig[modelColor].border) // Active → status + : 'var(--text-faint)' // Old → faint ); // Ring color for live sessions (used for subtle ring highlight) const ringColor = $derived(liveStatusConfig?.color ?? 'var(--success)'); + // Remote session hint for faster API lookup + const remoteQueryParam = $derived(isRemote ? '?remote=1' : ''); + // Build live status text for accessibility const liveStatusText = $derived( hasLiveStatus && liveSession?.status ? `, status: ${liveSession.status}` : '' @@ -124,7 +139,7 @@ + {#if isRemote && remoteUserName} + + {/if} {#if session.session_source === 'desktop'}
@@ -304,10 +334,10 @@
-
+
{displayMessageCount} @@ -329,7 +359,22 @@
-
+
+ {#if isRemote && remoteUserName} + + {/if} {#if showSubagentBadge} {#if subagentHref} + + {#if open} + + {/if} +
diff --git a/frontend/src/lib/components/NavigationCard.svelte b/frontend/src/lib/components/NavigationCard.svelte index 6320718b..8e7da818 100644 --- a/frontend/src/lib/components/NavigationCard.svelte +++ b/frontend/src/lib/components/NavigationCard.svelte @@ -17,7 +17,8 @@ | 'teal' | 'violet' | 'indigo' - | 'amber'; + | 'amber' + | 'rose'; disabled?: boolean; } @@ -119,6 +120,14 @@ gradient: 'linear-gradient(135deg, var(--nav-amber-subtle) 0%, rgba(217, 119, 6, 0.15) 100%)', glow: '0 4px 20px -2px rgba(217, 119, 6, 0.25)' + }, + rose: { + text: 'var(--nav-rose)', + bg: 'var(--nav-rose-subtle)', + border: 'var(--nav-rose)', + gradient: + 'linear-gradient(135deg, var(--nav-rose-subtle) 0%, rgba(244, 63, 132, 0.15) 100%)', + glow: '0 4px 20px -2px rgba(244, 63, 132, 0.25)' } }; diff --git a/frontend/src/lib/components/SessionCard.svelte b/frontend/src/lib/components/SessionCard.svelte index cdcab8b4..1cf971e5 100644 --- a/frontend/src/lib/components/SessionCard.svelte +++ b/frontend/src/lib/components/SessionCard.svelte @@ -1,5 +1,5 @@ - - Desktop + {#if isRemote || session.session_source === 'desktop'} +
+ {#if isRemote && remoteUserName} + e.stopPropagation()} + > + + {remoteUserName} + + {/if} + {#if session.session_source === 'desktop'} +
+ + Desktop +
+ {/if}
{/if}
@@ -322,6 +348,17 @@
+ {#if isRemote && remoteUserName} + e.stopPropagation()} + > + + {remoteUserName} + + {/if} {#if session.session_source === 'desktop'}
..., ..., ... - return text - .replace(/[^<]*<\/command-message>/g, '') - .replace(/[^<]*<\/command-name>/g, '') - .replace(//g, '') - .replace(/<\/command-args>/g, '') - .replace(/<[^>]+>/g, '') // Remove any other tags - .trim(); - } - - // Truncate text - function truncate(text: string | undefined, maxLen: number): string { + // Clean and truncate prompt text for chain node display + function cleanAndTruncate(text: string | undefined, maxLen: number): string { if (!text) return ''; const cleaned = cleanPromptText(text); - if (cleaned.length <= maxLen) return cleaned; - return cleaned.slice(0, maxLen).trim() + '...'; + return truncate(cleaned, maxLen); } @@ -192,7 +179,7 @@ {#if node.initial_prompt && !node.is_continuation_marker}

- {truncate(node.initial_prompt, 80)} + {cleanAndTruncate(node.initial_prompt, 80)}

{:else if node.is_continuation_marker}

diff --git a/frontend/src/lib/components/StatsCard.svelte b/frontend/src/lib/components/StatsCard.svelte index 5f6aaade..3f8d4ef5 100644 --- a/frontend/src/lib/components/StatsCard.svelte +++ b/frontend/src/lib/components/StatsCard.svelte @@ -55,6 +55,10 @@ accent: { bg: 'bg-[var(--accent-subtle)] border-[var(--accent)]/20', text: 'text-[var(--accent)]' + }, + rose: { + bg: 'bg-[var(--nav-rose-subtle)] border-[var(--nav-rose)]/20', + text: 'text-[var(--nav-rose)]' } }; @@ -83,11 +87,16 @@ {className} " > - -

- {title}{#if description} - ({description}){/if} + +
+
+ {title} +
+ {#if description} +
+ {description} +
+ {/if}
diff --git a/frontend/src/lib/components/agents/AgentTrendChart.svelte b/frontend/src/lib/components/agents/AgentTrendChart.svelte index 9b74964b..31f0f7af 100644 --- a/frontend/src/lib/components/agents/AgentTrendChart.svelte +++ b/frontend/src/lib/components/agents/AgentTrendChart.svelte @@ -14,7 +14,8 @@ registerChartDefaults, createResponsiveConfig, createCommonScaleConfig, - getThemeColors + getThemeColors, + onThemeChange } from '$lib/components/charts/chartConfig'; Chart.register( @@ -121,11 +122,15 @@ }); } + let cleanupTheme: (() => void) | null = null; + onMount(() => { if (sortedTrend.length > 0) createChart(); + cleanupTheme = onThemeChange(() => createChart()); }); onDestroy(() => { + cleanupTheme?.(); chart?.destroy(); }); diff --git a/frontend/src/lib/components/charts/SessionsChart.svelte b/frontend/src/lib/components/charts/SessionsChart.svelte index 5f15fb48..c42a6b9c 100644 --- a/frontend/src/lib/components/charts/SessionsChart.svelte +++ b/frontend/src/lib/components/charts/SessionsChart.svelte @@ -16,8 +16,10 @@ createResponsiveConfig, createCommonScaleConfig, chartColorPalette, - getThemeColors + getThemeColors, + onThemeChange } from './chartConfig'; + import { getUserChartColor, getUserChartLabel } from '$lib/utils'; // Register Chart.js components Chart.register( @@ -31,12 +33,63 @@ Tooltip ); + // Shared date utilities (used by buildChartData and multi-user paths) + function getLocalDateKey(d: Date): string { + const year = d.getFullYear(); + const month = String(d.getMonth() + 1).padStart(2, '0'); + const day = String(d.getDate()).padStart(2, '0'); + return `${year}-${month}-${day}`; + } + + function formatLocalDate(dateKey: string): string { + const [year, month, day] = dateKey.split('-').map(Number); + const date = new Date(year, month - 1, day); + return date.toLocaleDateString('en-US', { month: 'short', day: 'numeric' }); + } + + /** Fill all dates between min and max (with single-day padding) */ + function fillDateRange(dateKeys: string[]): string[] { + if (dateKeys.length === 0) return []; + + const minDateKey = dateKeys[0]; + const maxDateKey = dateKeys[dateKeys.length - 1]; + const isSingleDay = minDateKey === maxDateKey; + const result: string[] = []; + + if (isSingleDay) { + const [y, m, d] = minDateKey.split('-').map(Number); + result.push(getLocalDateKey(new Date(y, m - 1, d - 1))); + } + + const [minY, minM, minD] = minDateKey.split('-').map(Number); + const [maxY, maxM, maxD] = maxDateKey.split('-').map(Number); + let cur = new Date(minY, minM - 1, minD); + const end = new Date(maxY, maxM - 1, maxD); + while (cur <= end) { + result.push(getLocalDateKey(cur)); + cur = new Date(cur.getTime() + 86400000); + } + + if (isSingleDay) { + const [y, m, d] = maxDateKey.split('-').map(Number); + result.push(getLocalDateKey(new Date(y, m - 1, d + 1))); + } + + return result; + } + interface Props { sessionsByDate: Record; + sessionsByDateByUser?: Record>; + userNames?: Record; class?: string; } - let { sessionsByDate, class: className = '' }: Props = $props(); + let { sessionsByDate, sessionsByDateByUser, userNames, class: className = '' }: Props = $props(); + + let hasMultiUser = $derived( + !!sessionsByDateByUser && Object.keys(sessionsByDateByUser).length > 1 + ); let canvas: HTMLCanvasElement; let chart: Chart | null = null; @@ -53,12 +106,6 @@ return { labels: [], data: [], dateRange: '' }; } - const formatLocalDate = (dateKey: string): string => { - const [year, month, day] = dateKey.split('-').map(Number); - const date = new Date(year, month - 1, day); - return date.toLocaleDateString('en-US', { month: 'short', day: 'numeric' }); - }; - const formatLocalDateFull = (dateKey: string): string => { const [year, month, day] = dateKey.split('-').map(Number); const date = new Date(year, month - 1, day); @@ -69,50 +116,14 @@ }); }; - const getLocalDateKey = (d: Date): string => { - const year = d.getFullYear(); - const month = String(d.getMonth() + 1).padStart(2, '0'); - const day = String(d.getDate()).padStart(2, '0'); - return `${year}-${month}-${day}`; - }; + const allDates = fillDateRange(dateKeys); + const labels = allDates.map(formatLocalDate); + const data = allDates.map((d) => byDate[d] || 0); const minDateKey = dateKeys[0]; const maxDateKey = dateKeys[dateKeys.length - 1]; const isSingleDay = minDateKey === maxDateKey; - const labels: string[] = []; - const data: number[] = []; - - // For single day, add padding day before to center the point - if (isSingleDay) { - const [year, month, day] = minDateKey.split('-').map(Number); - const prevDate = new Date(year, month - 1, day - 1); - labels.push(formatLocalDate(getLocalDateKey(prevDate))); - data.push(0); - } - - // Fill all dates between min and max (including gaps) - const [minYear, minMonth, minDay] = minDateKey.split('-').map(Number); - const [maxYear, maxMonth, maxDay] = maxDateKey.split('-').map(Number); - - let currentDate = new Date(minYear, minMonth - 1, minDay); - const endDate = new Date(maxYear, maxMonth - 1, maxDay); - - while (currentDate <= endDate) { - const dateKey = getLocalDateKey(currentDate); - labels.push(formatLocalDate(dateKey)); - data.push(byDate[dateKey] || 0); - currentDate = new Date(currentDate.getTime() + 24 * 60 * 60 * 1000); - } - - // For single day, add padding day after to center the point - if (isSingleDay) { - const [year, month, day] = maxDateKey.split('-').map(Number); - const nextDate = new Date(year, month - 1, day + 1); - labels.push(formatLocalDate(getLocalDateKey(nextDate))); - data.push(0); - } - const dateRange = isSingleDay ? formatLocalDateFull(minDateKey) : `${formatLocalDateFull(minDateKey)} - ${formatLocalDateFull(maxDateKey)}`; @@ -123,54 +134,128 @@ // Compute derived values for template let chartData = $derived(buildChartData(sessionsByDate)); - onMount(() => { + function createSessionChart() { + chart?.destroy(); + chart = null; + if (!canvas) return; + registerChartDefaults(); const { labels, data } = chartData; - - // Get resolved theme colors const colors = getThemeColors(); - chart = new Chart(canvas, { - type: 'line', - data: { - labels, - datasets: [ - { - label: 'Sessions', - data, - borderColor: chartColorPalette[0], - backgroundColor: 'rgba(124, 58, 237, 0.1)', - fill: true, - tension: 0.4, - pointRadius: 4, - pointBackgroundColor: chartColorPalette[0], - pointBorderColor: colors.bgBase, - pointBorderWidth: 2 - } - ] - }, - options: { - ...createResponsiveConfig(), - plugins: { - ...createResponsiveConfig().plugins, - legend: { - display: false + if (hasMultiUser) { + const userIds = Object.keys(sessionsByDateByUser!); + const sorted = userIds.filter((id) => id !== '_local').sort(); + if (userIds.includes('_local')) sorted.unshift('_local'); + + const dateKeys = Object.keys(sessionsByDate) + .filter((k) => sessionsByDate[k] != null) + .sort(); + const allDates = fillDateRange(dateKeys); + const multiLabels = allDates.map(formatLocalDate); + + const datasets = sorted.map((userId) => { + const isLocal = userId === '_local'; + const hex = getUserChartColor(userId); + const userData = sessionsByDateByUser![userId] ?? {}; + return { + label: getUserChartLabel(userId, userNames), + data: allDates.map((d) => userData[d] ?? 0), + borderColor: hex, + backgroundColor: isLocal ? 'rgba(124, 58, 237, 0.1)' : 'transparent', + fill: isLocal, + tension: 0.4, + pointRadius: 3, + pointBackgroundColor: hex, + pointBorderColor: colors.bgBase, + pointBorderWidth: 2, + borderWidth: isLocal ? 2 : 1.5 + }; + }); + + chart = new Chart(canvas, { + type: 'line', + data: { labels: multiLabels, datasets }, + options: { + ...createResponsiveConfig(), + plugins: { + ...createResponsiveConfig().plugins, + legend: { + display: true, + position: 'top', + align: 'end', + labels: { + boxWidth: 8, + boxHeight: 8, + usePointStyle: true, + pointStyle: 'circle', + font: { size: 10 }, + padding: 12 + } + }, + tooltip: { + ...createResponsiveConfig().plugins.tooltip, + backgroundColor: colors.bgBase, + titleColor: colors.text, + bodyColor: colors.textSecondary, + borderColor: colors.border, + borderWidth: 1, + mode: 'index', + intersect: false + } }, - tooltip: { - ...createResponsiveConfig().plugins.tooltip, - backgroundColor: colors.bgBase, - titleColor: colors.text, - bodyColor: colors.textSecondary, - borderColor: colors.border, - borderWidth: 1 - } + scales: createCommonScaleConfig() + } + }); + } else { + chart = new Chart(canvas, { + type: 'line', + data: { + labels, + datasets: [ + { + label: 'Sessions', + data, + borderColor: chartColorPalette[0], + backgroundColor: 'rgba(124, 58, 237, 0.1)', + fill: true, + tension: 0.4, + pointRadius: 4, + pointBackgroundColor: chartColorPalette[0], + pointBorderColor: colors.bgBase, + pointBorderWidth: 2 + } + ] }, - scales: createCommonScaleConfig() - } - }); + options: { + ...createResponsiveConfig(), + plugins: { + ...createResponsiveConfig().plugins, + legend: { display: false }, + tooltip: { + ...createResponsiveConfig().plugins.tooltip, + backgroundColor: colors.bgBase, + titleColor: colors.text, + bodyColor: colors.textSecondary, + borderColor: colors.border, + borderWidth: 1 + } + }, + scales: createCommonScaleConfig() + } + }); + } + } + + let cleanupTheme: (() => void) | null = null; + + onMount(() => { + createSessionChart(); + cleanupTheme = onThemeChange(() => createSessionChart()); }); onDestroy(() => { + cleanupTheme?.(); chart?.destroy(); }); @@ -179,7 +264,27 @@ if (chart && sessionsByDate) { const { labels, data } = chartData; chart.data.labels = labels; - chart.data.datasets[0].data = data; + + if (hasMultiUser && sessionsByDateByUser) { + const dateKeys = Object.keys(sessionsByDate) + .filter((k) => sessionsByDate[k] != null) + .sort(); + const allDates = fillDateRange(dateKeys); + chart.data.labels = allDates.map(formatLocalDate); + + const userIds = Object.keys(sessionsByDateByUser); + const sorted = userIds.filter((id) => id !== '_local').sort(); + if (userIds.includes('_local')) sorted.unshift('_local'); + + sorted.forEach((userId, i) => { + if (chart!.data.datasets[i]) { + const userData = sessionsByDateByUser[userId] ?? {}; + chart!.data.datasets[i].data = allDates.map((d) => userData[d] ?? 0); + } + }); + } else { + chart.data.datasets[0].data = data; + } chart.update(); } }); diff --git a/frontend/src/lib/components/charts/ToolsChart.svelte b/frontend/src/lib/components/charts/ToolsChart.svelte index 3cf0a3d8..0f3ab9e7 100644 --- a/frontend/src/lib/components/charts/ToolsChart.svelte +++ b/frontend/src/lib/components/charts/ToolsChart.svelte @@ -8,7 +8,8 @@ createResponsiveConfig, chartColorPalette, getChartColor, - getThemeColors + getThemeColors, + onThemeChange } from './chartConfig'; // Register Chart.js components @@ -55,7 +56,11 @@ // Total for percentage calculation let total = $derived(allEntries.reduce((sum, [, count]) => sum + count, 0)); - onMount(() => { + function createDoughnutChart() { + chart?.destroy(); + chart = null; + if (!canvas) return; + registerChartDefaults(); const colors = getThemeColors(); @@ -77,7 +82,7 @@ plugins: { ...createResponsiveConfig().plugins, legend: { - display: false // We'll use custom legend + display: false }, tooltip: { ...createResponsiveConfig().plugins.tooltip, @@ -98,9 +103,17 @@ cutout: '65%' } }); + } + + let cleanupTheme: (() => void) | null = null; + + onMount(() => { + createDoughnutChart(); + cleanupTheme = onThemeChange(() => createDoughnutChart()); }); onDestroy(() => { + cleanupTheme?.(); chart?.destroy(); }); diff --git a/frontend/src/lib/components/charts/UsageAnalytics.svelte b/frontend/src/lib/components/charts/UsageAnalytics.svelte index 00dbd32a..467f6e03 100644 --- a/frontend/src/lib/components/charts/UsageAnalytics.svelte +++ b/frontend/src/lib/components/charts/UsageAnalytics.svelte @@ -19,10 +19,12 @@ registerChartDefaults, createResponsiveConfig, createCommonScaleConfig, - getThemeColors + getThemeColors, + onThemeChange } from './chartConfig'; import SegmentedControl from '$lib/components/ui/SegmentedControl.svelte'; import { API_BASE } from '$lib/config'; + import { getUserChartColor, getUserChartLabel } from '$lib/utils'; Chart.register( LineController, @@ -75,6 +77,9 @@ type RangeKey = '7d' | '30d' | '90d'; let selectedRange = $state('30d'); + type ViewMode = 'by-item' | 'by-user'; + let viewMode = $state('by-item'); + const rangeOptions = [ { label: '7d', value: '7d' }, { label: '30d', value: '30d' }, @@ -125,6 +130,12 @@ let hasData = $derived(data !== null && filteredTotal > 0); + let hasUserData = $derived( + data !== null && + data.trend_by_user !== undefined && + Object.keys(data.trend_by_user).length > 1 + ); + const DEFAULT_VISIBLE = 5; const EXPANDED_VISIBLE = 10; @@ -290,6 +301,79 @@ return datasets; }); + // Per-user chart datasets + let userChartDatasets = $derived.by(() => { + if (!data?.trend_by_user || !filteredTrend.length) return []; + + const trendByUser = data.trend_by_user; + const dateLabels = filteredTrend.map(d => d.date); + const showPoints = filteredTrend.length <= 14; + + // Sort users: _local first, then remotes alphabetically + const userIds = Object.keys(trendByUser); + const sorted = userIds.filter(id => id !== '_local').sort(); + if (userIds.includes('_local')) sorted.unshift('_local'); + + const datasets: ChartDataset<'line'>[] = []; + + for (const userId of sorted) { + const points = trendByUser[userId] ?? []; + const dateMap = new Map(points.map(p => [p.date, p.count])); + const userData = dateLabels.map(d => dateMap.get(d) ?? 0); + const hex = getUserChartColor(userId); + const isLocal = userId === '_local'; + + datasets.push({ + label: getUserChartLabel(userId, data.user_names), + data: userData, + borderColor: hex, + backgroundColor: hexToRgba(hex, isLocal ? 0.08 : 0.03), + fill: isLocal, + tension: 0.4, + pointRadius: showPoints ? 2.5 : 0, + pointHoverRadius: 4, + pointBackgroundColor: hex, + borderWidth: isLocal ? 2 : 1.5 + }); + } + + return datasets; + }); + + // Per-user top items (sorted by total usage) + let userTopItems = $derived.by(() => { + if (!data?.trend_by_user) return []; + const trendByUser = data.trend_by_user; + const userIds = Object.keys(trendByUser); + const sorted = userIds.filter(id => id !== '_local').sort(); + if (userIds.includes('_local')) sorted.unshift('_local'); + + const items = sorted.map(userId => { + const total = (trendByUser[userId] ?? []).reduce((sum, p) => sum + p.count, 0); + return { name: userId, count: total }; + }); + + const max = items.length > 0 ? Math.max(...items.map(i => i.count), 1) : 1; + return items.map(item => ({ + name: getUserChartLabel(item.name, data?.user_names), + count: item.count, + pct: (item.count / max) * 100, + color: getUserChartColor(item.name) + })); + }); + + // Per-user legend items + let userLegendItems = $derived.by(() => { + if (!data?.trend_by_user) return []; + const userIds = Object.keys(data.trend_by_user); + const sorted = userIds.filter(id => id !== '_local').sort(); + if (userIds.includes('_local')) sorted.unshift('_local'); + return sorted.map(userId => ({ + name: getUserChartLabel(userId, data?.user_names), + color: getUserChartColor(userId) + })); + }); + // Legend items for the mini legend — derived from shared topItemNames let legendItems = $derived.by(() => { if (!data) return []; @@ -308,7 +392,8 @@ let chart: Chart | null = null; function createChart() { - if (!canvas || filteredTrend.length === 0 || chartDatasets.length === 0) return; + const activeDatasets = viewMode === 'by-user' ? userChartDatasets : chartDatasets; + if (!canvas || filteredTrend.length === 0 || activeDatasets.length === 0) return; chart?.destroy(); registerChartDefaults(); @@ -318,7 +403,7 @@ type: 'line', data: { labels: trendLabels, - datasets: chartDatasets + datasets: activeDatasets }, options: { ...createResponsiveConfig(), @@ -345,22 +430,27 @@ }); } + let cleanupTheme: (() => void) | null = null; + onMount(() => { if (hasData) createChart(); + cleanupTheme = onThemeChange(() => createChart()); }); onDestroy(() => { + cleanupTheme?.(); chart?.destroy(); }); - // Rebuild chart when datasets or filter changes + // Rebuild chart when datasets, filter, or view mode changes $effect(() => { - const hasDatasets = chartDatasets.length > 0; + const activeDatasets = viewMode === 'by-user' ? userChartDatasets : chartDatasets; + const hasDatasets = activeDatasets.length > 0; if (canvas && hasDatasets) { if (chart) { chart.data.labels = trendLabels; - chart.data.datasets = chartDatasets; + chart.data.datasets = activeDatasets; chart.update(); } else { createChart(); @@ -388,7 +478,7 @@ {#if !loading || data} -
+
{/if} @@ -411,7 +501,7 @@
{:else if data} -
+
@@ -450,15 +540,34 @@ {#if data.trend.length > 0}
-
+

Activity Trend

+ {#if hasUserData} + + {/if}
{#if legendItems.length > 0}
- {#each legendItems as item} + {#each viewMode === 'by-user' ? userLegendItems : legendItems as item}
- {#each topItems as { name, count, pct, color }, i} - {@const displayName = itemDisplayFn ? itemDisplayFn(name) : name} - {@const href = itemLinkFn ? itemLinkFn(name) : itemLinkPrefix ? `${itemLinkPrefix}${encodeURIComponent(name)}` : null} + {#each viewMode === 'by-user' ? userTopItems : topItems as { name, count, pct, color }, i} + {@const displayName = viewMode === 'by-user' ? name : itemDisplayFn ? itemDisplayFn(name) : name} + {@const href = viewMode === 'by-user' ? null : itemLinkFn ? itemLinkFn(name) : itemLinkPrefix ? `${itemLinkPrefix}${encodeURIComponent(name)}` : null}
{#snippet dotLabel()} diff --git a/frontend/src/lib/components/charts/chartConfig.ts b/frontend/src/lib/components/charts/chartConfig.ts index 8ee9eee7..2dfe71e2 100644 --- a/frontend/src/lib/components/charts/chartConfig.ts +++ b/frontend/src/lib/components/charts/chartConfig.ts @@ -1,27 +1,52 @@ import { Chart } from 'chart.js'; /** - * Register global Chart.js defaults for consistent styling across all charts - * Should be called once during app initialization or in each chart component's onMount + * Get theme colors from CSS custom properties. + * Chart.js renders on via the Canvas 2D API, which does NOT support + * CSS variable strings. Always resolve variables to actual color values before + * passing them to Chart.js. + * @returns Object containing commonly used theme colors as resolved hex/rgb values + */ +export function getThemeColors() { + const style = getComputedStyle(document.documentElement); + return { + primary: style.getPropertyValue('--accent').trim(), + text: style.getPropertyValue('--text-primary').trim(), + textSecondary: style.getPropertyValue('--text-secondary').trim(), + textMuted: style.getPropertyValue('--text-muted').trim(), + textFaint: style.getPropertyValue('--text-faint').trim(), + border: style.getPropertyValue('--border').trim(), + bgBase: style.getPropertyValue('--bg-base').trim(), + bgMuted: style.getPropertyValue('--bg-muted').trim(), + bgSubtle: style.getPropertyValue('--bg-subtle').trim() + }; +} + +/** + * Register global Chart.js defaults for consistent styling across all charts. + * Must be called from onMount (needs DOM access to resolve CSS variables). */ export function registerChartDefaults() { + const colors = getThemeColors(); Chart.defaults.font.family = 'JetBrains Mono, monospace'; - Chart.defaults.color = 'var(--text-secondary)'; + Chart.defaults.color = colors.textSecondary; } /** - * Create a responsive chart configuration with common options + * Create a responsive chart configuration with common options. + * All colors are resolved from CSS custom properties at call time. * @param maintainAspectRatio - Whether to maintain aspect ratio (default: false for better container fitting) * @returns Base configuration object that can be spread into chart options */ export function createResponsiveConfig(maintainAspectRatio = false) { + const colors = getThemeColors(); return { responsive: true, maintainAspectRatio, plugins: { legend: { labels: { - color: 'var(--text-secondary)', + color: colors.textSecondary, font: { family: 'JetBrains Mono, monospace', size: 11 @@ -29,10 +54,10 @@ export function createResponsiveConfig(maintainAspectRatio = false) { } }, tooltip: { - backgroundColor: 'var(--bg-base)', // High contrast background - titleColor: 'var(--text-primary)', - bodyColor: 'var(--text-secondary)', - borderColor: 'var(--border)', + backgroundColor: colors.bgBase, + titleColor: colors.text, + bodyColor: colors.textSecondary, + borderColor: colors.border, borderWidth: 1, padding: 10, cornerRadius: 8, @@ -50,37 +75,20 @@ export function createResponsiveConfig(maintainAspectRatio = false) { } /** - * Get theme colors from CSS custom properties - * Useful for dynamic color assignment based on current theme - * @returns Object containing commonly used theme colors - */ -export function getThemeColors() { - const style = getComputedStyle(document.documentElement); - return { - primary: style.getPropertyValue('--accent').trim(), - text: style.getPropertyValue('--text-primary').trim(), - textSecondary: style.getPropertyValue('--text-secondary').trim(), - textMuted: style.getPropertyValue('--text-muted').trim(), - border: style.getPropertyValue('--border').trim(), - bgBase: style.getPropertyValue('--bg-base').trim(), - bgMuted: style.getPropertyValue('--bg-muted').trim(), - bgSubtle: style.getPropertyValue('--bg-subtle').trim() - }; -} - -/** - * Create common scale configuration for line charts + * Create common scale configuration for line charts. + * All colors are resolved from CSS custom properties at call time. * @returns Scale configuration object for x and y axes */ export function createCommonScaleConfig() { + const colors = getThemeColors(); return { x: { grid: { - color: 'rgba(128, 128, 128, 0.1)', // Subtle grid lines works in light and dark + color: 'rgba(128, 128, 128, 0.1)', // Neutral gray works in both themes drawOnChartArea: false }, ticks: { - color: 'var(--text-muted)', + color: colors.textMuted, font: { family: 'JetBrains Mono, monospace', size: 10 @@ -92,10 +100,10 @@ export function createCommonScaleConfig() { beginAtZero: true, grace: '20%', grid: { - color: 'rgba(128, 128, 128, 0.1)' // Subtle grid lines + color: 'rgba(128, 128, 128, 0.1)' }, ticks: { - color: 'var(--text-muted)', + color: colors.textMuted, font: { family: 'JetBrains Mono, monospace', size: 10 @@ -106,6 +114,26 @@ export function createCommonScaleConfig() { }; } +/** + * Watch for theme changes (data-theme attribute on ) and invoke callback. + * Returns a cleanup function to disconnect the observer. + * Use in onMount/onDestroy to recreate charts with updated colors. + */ +export function onThemeChange(callback: () => void): () => void { + const observer = new MutationObserver((mutations) => { + for (const mutation of mutations) { + if (mutation.type === 'attributes' && mutation.attributeName === 'data-theme') { + callback(); + } + } + }); + observer.observe(document.documentElement, { + attributes: true, + attributeFilter: ['data-theme'] + }); + return () => observer.disconnect(); +} + /** * Get chart colors from CSS variables (for dynamic theme support) * Call this in onMount or use getComputedStyle for live values diff --git a/frontend/src/lib/components/command-palette/CommandPalette.svelte b/frontend/src/lib/components/command-palette/CommandPalette.svelte index 7dadcbdb..16ca9f46 100644 --- a/frontend/src/lib/components/command-palette/CommandPalette.svelte +++ b/frontend/src/lib/components/command-palette/CommandPalette.svelte @@ -24,6 +24,7 @@ import KeyIndicator from '$lib/components/ui/KeyIndicator.svelte'; import type { Project } from '$lib/api-types'; import { API_BASE } from '$lib/config'; + import { cleanPromptText } from '$lib/utils'; interface Props { onToggleTheme?: () => void; @@ -190,7 +191,7 @@ function getSessionLabel(s: SessionItem): string { return ( s.title || - (s.initial_prompt ? s.initial_prompt.slice(0, 60) : (s.slug || '').slice(0, 8)) + (s.initial_prompt ? cleanPromptText(s.initial_prompt).slice(0, 60) : (s.slug || '').slice(0, 8)) ); } // Handle keydown to ensure Escape always closes @@ -520,7 +521,7 @@ {#each sessions as session} handleSelect( () => diff --git a/frontend/src/lib/components/commands/CommandUsageCard.svelte b/frontend/src/lib/components/commands/CommandUsageCard.svelte index ba045ca3..4519dda3 100644 --- a/frontend/src/lib/components/commands/CommandUsageCard.svelte +++ b/frontend/src/lib/components/commands/CommandUsageCard.svelte @@ -13,6 +13,10 @@ description?: string | null; last_used?: string | null; session_count?: number; + remote_count?: number; + local_count?: number; + remote_user_ids?: string[]; + is_remote_only?: boolean; } interface Props { @@ -66,6 +70,8 @@ description={command.description} lastUsed={command.last_used} sessionCount={command.session_count ?? null} + isRemoteOnly={command.is_remote_only ?? false} + remoteUserIds={command.remote_user_ids ?? []} class={className} > {#snippet icon()} diff --git a/frontend/src/lib/components/commands/CommandsPanel.svelte b/frontend/src/lib/components/commands/CommandsPanel.svelte index d7489f9f..32a8c0a5 100644 --- a/frontend/src/lib/components/commands/CommandsPanel.svelte +++ b/frontend/src/lib/components/commands/CommandsPanel.svelte @@ -1,19 +1,15 @@ + +{#if loading} +
+ +
+{:else if error} +
+ + {error} + +
+{:else if members.length === 0} + +
+ +

No team members yet

+

+ Set up Syncthing sync to share sessions with teammates and see how they use {domainLabel.toLowerCase()}. +

+ + Set up Sync + + +
+{:else} +
+ +
+
+
+ +
+
+

+ {members.length} member{members.length !== 1 ? 's' : ''} + + · {totalUsage.toLocaleString()} total {domainLabel.toLowerCase()} uses this month + +

+ {#if topMember} +

+ Most active: {topMember.name} + with {topMember.total.toLocaleString()} uses +

+ {/if} +
+
+
+ + +
+ {#each members as member (member.userId)} + {@const profileHref = member.isLocal ? null : `/members/${encodeURIComponent(member.userId)}`} +
+
+ +
+
+ +
+ {member.name.charAt(0).toUpperCase()} +
+
+

+ {member.name} +

+

+ {member.total.toLocaleString()} {domainLabel.toLowerCase()} use{member.total !== 1 ? 's' : ''} + {#if member.lastActive} + · last {formatRelativeTime(member.lastActive)} + {/if} +

+
+
+ + + {#if member.trend.length >= 2} +
+ + + + +
+ {/if} +
+ + + {#if member.topItems.length > 0} +
+

+ Top {domainLabel} +

+ {#each member.topItems as item, i} + {@const maxCount = member.topItems[0].count} + {@const pct = maxCount > 0 ? (item.count / maxCount) * 100 : 0} +
+
+
+ {#if item.href} + + {item.displayName} + + {:else} + + {item.displayName} + + {/if} + + {item.count} + +
+
+
+
+
+
+ {/each} +
+ {/if} + + + {#if profileHref} + + View profile + + + {/if} +
+
+ {/each} +
+ +
+{/if} diff --git a/frontend/src/lib/components/plan/PlanCard.svelte b/frontend/src/lib/components/plan/PlanCard.svelte index 21698f6e..58c781e3 100644 --- a/frontend/src/lib/components/plan/PlanCard.svelte +++ b/frontend/src/lib/components/plan/PlanCard.svelte @@ -1,8 +1,9 @@ - +
-
- +
+

{plan.title || plan.slug}

- {#if plan.session_context && sessionUrl} + {#if isRemote && plan.remote_user_id} + e.stopPropagation()} + > + + {plan.remote_user_id} + + {:else if plan.session_context && sessionUrl} + + +
+ {#if selectedScope === 'project'} +

+ Will be saved to .claude/{itemDir}/{itemName}/ in the current project directory. +

+ {/if} +
+ + + {#if errorMsg} +
+ {errorMsg} +
+ {/if} + + {#if successMsg} +
+ + {successMsg} +
+ {/if} +
+ {/snippet} + + {#snippet footer()} + + + {/snippet} + diff --git a/frontend/src/lib/components/shared/PairingCodeCard.svelte b/frontend/src/lib/components/shared/PairingCodeCard.svelte new file mode 100644 index 00000000..a2adc827 --- /dev/null +++ b/frontend/src/lib/components/shared/PairingCodeCard.svelte @@ -0,0 +1,136 @@ + + +{#if variant === 'card'} + +
+
+
+ +

Your Pairing Code

+
+

Share this with a team leader so they can add you to their team

+ + {#if pairingLoading} +
+ + Loading pairing code... +
+ {:else if pairingCode} +
+ + {pairingCode} + + +
+ {#if pairingMemberTag} +

+ Your identity: {pairingMemberTag} +

+ {/if} + {:else} +
+

Pairing code unavailable. Make sure sync is configured.

+
+ {/if} +
+
+{:else} + + {#if pairingLoading} +
+
+
+
+ {:else if pairingCode} +
+
+ {pairingCode} +
+ +
+ {#if pairingMemberTag} +

+ Your identity: {pairingMemberTag} +

+ {/if} + {:else} +
+ Pairing code unavailable. Check /sync setup. +
+ {/if} +{/if} diff --git a/frontend/src/lib/components/shared/UsageCard.svelte b/frontend/src/lib/components/shared/UsageCard.svelte index 455a2901..5cdc485e 100644 --- a/frontend/src/lib/components/shared/UsageCard.svelte +++ b/frontend/src/lib/components/shared/UsageCard.svelte @@ -1,5 +1,5 @@ -
+
diff --git a/frontend/src/lib/components/skeleton/HistorySkeleton.svelte b/frontend/src/lib/components/skeleton/HistorySkeleton.svelte index 1576de5a..7057bfb9 100644 --- a/frontend/src/lib/components/skeleton/HistorySkeleton.svelte +++ b/frontend/src/lib/components/skeleton/HistorySkeleton.svelte @@ -3,7 +3,7 @@ import SkeletonText from './SkeletonText.svelte'; -
+
diff --git a/frontend/src/lib/components/skeleton/MemberDetailSkeleton.svelte b/frontend/src/lib/components/skeleton/MemberDetailSkeleton.svelte new file mode 100644 index 00000000..e3476d56 --- /dev/null +++ b/frontend/src/lib/components/skeleton/MemberDetailSkeleton.svelte @@ -0,0 +1,49 @@ + + +
+ +
+ + / + + / + +
+ + +
+
+ +
+
+ + + +
+
+ + +
+
+ {#each Array(4) as _} + + {/each} +
+
+
+
+ + +
+ +
+ + +
+ + +
+
diff --git a/frontend/src/lib/components/skeleton/MembersPageSkeleton.svelte b/frontend/src/lib/components/skeleton/MembersPageSkeleton.svelte new file mode 100644 index 00000000..876e9131 --- /dev/null +++ b/frontend/src/lib/components/skeleton/MembersPageSkeleton.svelte @@ -0,0 +1,41 @@ + + +
+ +
+
+ + / + +
+
+ +
+ + +
+
+
+ + +
+ + +
+ + +
+ {#each Array(4) as _} +
+ +
+ + +
+
+ {/each} +
+
diff --git a/frontend/src/lib/components/skeleton/index.ts b/frontend/src/lib/components/skeleton/index.ts index d8eeb958..78a5a248 100644 --- a/frontend/src/lib/components/skeleton/index.ts +++ b/frontend/src/lib/components/skeleton/index.ts @@ -29,3 +29,5 @@ export { default as SessionsPageSkeleton } from './SessionsPageSkeleton.svelte'; export { default as SkeletonLiveSessionsSection } from './SkeletonLiveSessionsSection.svelte'; export { default as HooksPageSkeleton } from './HooksPageSkeleton.svelte'; export { default as ArchivedPageSkeleton } from './ArchivedPageSkeleton.svelte'; +export { default as MembersPageSkeleton } from './MembersPageSkeleton.svelte'; +export { default as MemberDetailSkeleton } from './MemberDetailSkeleton.svelte'; diff --git a/frontend/src/lib/components/skills/SkillUsageCard.svelte b/frontend/src/lib/components/skills/SkillUsageCard.svelte index a38fbbf0..9ce800d8 100644 --- a/frontend/src/lib/components/skills/SkillUsageCard.svelte +++ b/frontend/src/lib/components/skills/SkillUsageCard.svelte @@ -14,6 +14,10 @@ session_count?: number; category?: SkillCategory; description?: string | null; + remote_count?: number; + local_count?: number; + remote_user_ids?: string[]; + is_remote_only?: boolean; } interface Props { @@ -60,6 +64,8 @@ lastUsed={skill.last_used} sessionCount={skill.session_count ?? null} {neverUsed} + isRemoteOnly={skill.is_remote_only ?? false} + remoteUserIds={skill.remote_user_ids ?? []} class={className} > {#snippet icon()} diff --git a/frontend/src/lib/components/skills/SkillUsageTable.svelte b/frontend/src/lib/components/skills/SkillUsageTable.svelte index 193fff56..ee3260ed 100644 --- a/frontend/src/lib/components/skills/SkillUsageTable.svelte +++ b/frontend/src/lib/components/skills/SkillUsageTable.svelte @@ -1,6 +1,6 @@ + +
+ + +
+ +
+ + Syncthing: {syncthingUp ? 'Connected' : 'Not Running'} + + {#if totalUnsynced > 0} +

+ {totalUnsynced} session{totalUnsynced !== 1 ? 's' : ''} not yet synced +

+ {:else if projectStatuses.length > 0} +

All sessions in sync

+ {/if} +
+ +
+ + + + + + {#if membersLoading && projectStatusLoading} +
+ {#each [1, 2, 3, 4] as i (i)} + + {/each} +
+ {:else} + {@const teamHref = teamName ? '/team/' + encodeURIComponent(teamName) : '/team'} +
+ + +

{connectedMembers}/{totalMembers}

+

Teammates Online

+ + + +

{projectCount}

+

Projects

+ +
+ +

{sessionsSharedCount}

+

Sessions Shared

+
+
+ +

{sessionsReceivedCount}

+

Sessions Received

+
+
+ {/if} + + + {#if projectStatusLoading} +
+
+ {#each [1, 2, 3] as i (i)} + + {/each} +
+
+ {:else if projectStatuses.length > 0} +
+ +
+
+ +

Project Sync Status

+ + {projectStatuses.length} + +
+
+ + +
+ {#each projectStatuses as proj (proj.git_identity)} +
+ +
+ + {proj.name} + +
+ + {proj.packaged_count}/{proj.local_count} sessions packaged + + {#if proj.teams && proj.teams.length > 0} + {#each proj.teams as t (t)} + + {t} + + {/each} + {/if} +
+
+ {#if proj.gap === 0} + + + In Sync + + {:else} + + {proj.gap} behind + + {/if} +
+ {/each} +
+
+ {/if} + + + {#if activityLoading} +
+
+ {#each [1, 2, 3] as i (i)} + + {/each} +
+
+ {:else if recentEvents.length > 0} +
+ +
+ +

Recent Activity

+
+ + +
+ {#each recentEvents as ev, i (ev.created_at ?? i)} +
+

{formatSyncEvent(ev)}

+ {formatRelativeTime(ev.created_at)} +
+ {/each} +
+
+ {/if} + + +
+ + + {#if machineDetailsOpen} +
+
+ {#if status?.user_id} +
+ Your Name + {status.user_id} +
+ {/if} + + {#if status?.machine_id} +
+ Machine + {status.machine_id} +
+ {/if} + + {#if detect?.version} +
+ Syncthing Version + v{detect.version} +
+ {/if} + + {#if ownDeviceId} +
+ Device ID +
+ {ownDeviceId} + +
+
+ {/if} + + {#if !status?.user_id && !status?.machine_id && !detect?.version} +

No machine details available.

+ {/if} +
+ + +
+ {#if resetResult} +
+ Sync reset complete. Reloading... +
+ {:else if resetConfirm} +
+

This will:

+
    +
  • Remove all karma shared folders from Syncthing
    • +
  • Remove all paired team devices
    • +
  • Stop the Syncthing daemon
    • +
  • Delete all remote sessions, handshakes & metadata
    • +
  • Clear sync config, teams, members, events & rejections
    • +
  • Remove stale database files
    • +
+ +
+ + +
+
+ {:else} + + {/if} +
+
+ {/if} +
+ +
diff --git a/frontend/src/lib/components/sync/PendingInvitationCard.svelte b/frontend/src/lib/components/sync/PendingInvitationCard.svelte new file mode 100644 index 00000000..b07a07e8 --- /dev/null +++ b/frontend/src/lib/components/sync/PendingInvitationCard.svelte @@ -0,0 +1,380 @@ + + +{#if loading && !firstLoadDone} + +
+
+
+
+
+
+
+
+
+
+
+
+
+{:else if invitations.length > 0} + {#each invitations as inv (inv.device_id)} + {@const isAccepting = acceptingId === inv.device_id} + {@const isDismissing = dismissingId === inv.device_id} + {@const isBusy = isAccepting || isDismissing} + {@const visibleProjects = inv.projects.slice(0, 2)} + {@const extraCount = inv.projects.length - 2} + +
+ +
+ +
+ {inv.leader_user_id.charAt(0) || '?'} +
+ +
+
+

+ {inv.team_name ? `Team invitation — ${inv.team_name}` : 'Device pairing request'} +

+ + pending + +
+

+ {inv.leader_member_tag || inv.leader_user_id} + {inv.team_name ? 'wants to sync' : 'wants to connect'} +

+
+
+ + +
+
+
+ Device + {truncateDeviceId(inv.device_id)} +
+
+ Requested + {inv.time ? formatRelativeTime(inv.time) : 'Just now'} +
+ + {#if inv.projects.length > 0} +
+
+ Projects + {#each visibleProjects as proj (proj)} + + {proj} + + {/each} + {#if extraCount > 0} + + +{extraCount} + + {/if} +
+
+ {/if} +
+ + +
+ +

+ Accepting pairs this device and syncs team metadata. You'll then choose which projects to accept on the team page. +

+
+ + +
+ + +
+
+
+ {/each} +{/if} diff --git a/frontend/src/lib/components/sync/ProjectTeamTab.svelte b/frontend/src/lib/components/sync/ProjectTeamTab.svelte new file mode 100644 index 00000000..0be477a3 --- /dev/null +++ b/frontend/src/lib/components/sync/ProjectTeamTab.svelte @@ -0,0 +1,307 @@ + + +
+
+

Team Activity

+

+ What teammates are working on in this project. +

+
+ + {#if loading} +
+ +
+ {:else if error} +
+ + {error} + +
+ {:else if users.length === 0} +
+ +

No team sessions yet

+

+ When teammates sync sessions for this project, they'll appear here. +

+
+ {:else} + + + + +
+ {#each memberAggs as member (member.user.user_id)} + {@const color = getTeamMemberColor(member.user.user_id)} + {@const isExpanded = expandedUsers.has(member.user.user_id)} +
+ + + + + {#if isExpanded} +
+ {#each member.user.sessions.slice(0, 15) as session (session.uuid)} + + {/each} + {#if member.user.sessions.length > 15} +

+ +{member.user.sessions.length - 15} older sessions +

+ {/if} +
+ {/if} +
+ {/each} +
+ {/if} +
diff --git a/frontend/src/lib/components/sync/SetupWizard.svelte b/frontend/src/lib/components/sync/SetupWizard.svelte new file mode 100644 index 00000000..31d35620 --- /dev/null +++ b/frontend/src/lib/components/sync/SetupWizard.svelte @@ -0,0 +1,839 @@ + + + +
+ +
+
+ {#each STEPS as label, i} + {@const idx = i} + {@const done = step > idx} + {@const active = step === idx} +
+ +
+ +
+ {#if done} + + {:else} + {idx + 1} + {/if} +
+ + + {label} + +
+ + {#if i < STEPS.length - 1} +
+ {/if} +
+ {/each} +
+
+ + + + + {#if step === 0} +
+
+

Peer-to-Peer Session Sync

+

+ Share Claude Code sessions across your machines or with teammates — without any cloud service. +

+
+ +
+

+ Claude Karma uses Syncthing to sync sessions + directly between your devices. There's no cloud server in the middle — your data travels + encrypted from one machine to another, and stays entirely under your control. +

+ + +
+
+
+ +
+
+

Your data, your machines

+

Sessions never leave your devices. No accounts, no third-party storage.

+
+
+ +
+
+ +
+
+

Encrypted in transit

+

All transfers use TLS encryption. Only paired devices can connect.

+
+
+ +
+
+ +
+
+

No central server

+

Direct device-to-device sync over your local network or internet.

+
+
+ +
+
+ +
+
+

Open source & auditable

+

Syncthing is fully open source. You can inspect every line of code.

+
+
+
+ + +
+

How the sync flow works

+
+
+ 1 +

+ Watcher detects changes — Claude Karma monitors your ~/.claude/projects/ directory for new or updated session files. +

+
+
+ 2 +

+ Sessions are packaged — Changed sessions are bundled into lightweight sync packages (just metadata and conversation data). +

+
+
+ 3 +

+ Syncthing transfers the packages — Files are synced directly to paired devices over an encrypted connection. If devices are on the same LAN, sync is near-instant. Otherwise, Syncthing routes through encrypted relay servers. +

+
+
+ 4 +

+ Teammates see shared sessions — Received packages appear in each team member's Karma dashboard automatically. +

+
+
+
+ + +
+

What gets synced

+
+
+
+ +
+
+

Session conversations & messages

+
+
+
+
+ +
+
+

Tool usage & token statistics

+
+
+
+
+ +
+
+

Session metadata & timelines

+
+
+
+
+ +
+
+

Never your source code, secrets, or credentials

+
+
+
+
+ + +
+

How devices connect

+
+
+ +
+

+ Each device gets a unique Device ID (a cryptographic fingerprint). To pair devices, you exchange Device IDs — no accounts, no passwords. Only devices you've explicitly paired can connect and sync data. +

+
+
+ + +
+

Three things to know

+

+ Everything in Karma sync is built on three simple ideas. +

+ +
+ +
+
+
+ +
+ You (Member) +
+

+ Each person + machine is a unique member. +

+
+ + jayant.macbook + +
+ you + + + your machine +
+
+
+ + +
+
+
+ +
+ Team +
+

+ A group of members who can see each other's sessions. +

+
+ backend-crew +
+ jayant + ayush + priya +
+
+
+ + +
+
+
+ +
+ Project +
+

+ You pick which projects to share with each team. +

+
+ org/claude-karma +
+ shared with backend-crew +
+
+
+
+
+ + +
+

How sessions move

+ +
+ +
+ +
+
+ + Your Machine +
+
+
+ + Use Claude Code +
+
+ + Session saved +
+
+ + Auto-packaged +
+
+ YOUR OUTBOX +
+
+
+ + +
+
+
+ +
+
+ Encrypted +
+
+ +
+
+
+ + +
+
+ + Teammate's Machine +
+
+
+ THEIR INBOX +
+
+ + Session appears +
+
+ + Visible in Karma +
+
+ + Works both ways +
+
+
+
+ + +

+ Your outbox and their inbox are the same folder. + You send; they receive. No copying, no uploading — sessions just appear. +

+
+
+ + +
+ + Read the full sync guide → + +
+ +
+ +
+
+
+ + + + + {:else if step === 1} +
+
+

Install Syncthing

+

+ Syncthing is a lightweight, open-source file synchronization program that runs as a background service on your machine. +

+
+ + {#if detect?.running} + +
+
+ +
+

+ Syncthing detected +

+

+ Syncthing{#if detect.version} v{detect.version}{/if} is installed and running. Advancing... +

+
+
+
+ {:else} + +
+
+ +
+

+ Syncthing not detected +

+

+ Install and start Syncthing, then click "Check Again". +

+
+
+ +
+ {#each installInstructions as instr} +
+
+ + {instr.label} + + {#if instr.os === detectedOS} + (detected) + {/if} +
+
+ + {instr.command} + + +
+
+ {/each} +
+ + {#if checkError} +

{checkError}

+ {/if} + + +
+ {/if} + + +
+

What this installs

+
+
+
+ +
+

+ A background service — Syncthing runs quietly in the background. It starts automatically on boot and uses minimal resources when idle. +

+
+
+
+ +
+

+ A local web UI — Syncthing provides an admin interface at localhost:8384 for advanced configuration. Claude Karma manages everything for you, but you can inspect settings there anytime. +

+
+
+
+ +
+

+ Lightweight — Uses ~30-50 MB of RAM when idle. CPU usage is negligible between syncs. +

+
+
+
+ + + + + + {#if detectedOS === 'macos'} +
+
+ +
+

macOS will ask about local network access

+

+ When Syncthing first starts, macOS may show a popup asking if Syncthing can "find and connect to devices on your local network". This controls local discovery (finding devices on the same Wi-Fi/LAN). +

+
+

+ Allow (recommended) — Enables fast, direct LAN sync between nearby devices. No data leaves your network. +

+

+ Deny (still works) — Sync will still work through Syncthing's encrypted relay servers over the internet. Slightly slower, but fully functional. +

+
+

+ You can change this later in System Settings → Privacy & Security → Local Network. +

+
+
+
+ {/if} +
+ + + + + {:else if step === 2} +
+
+

Name This Machine

+

+ Give this device an identifier so others can recognize it in the sync network. +

+
+ + +
+ +
+ + Syncthing{#if detect?.version} v{detect.version}{/if} running + +

+ One more step — name this machine to start syncing. +

+
+
+ +
+ +
+ + +

+ Used to identify this machine in the sync network. +

+
+ + + {#if detect?.device_id} +
+

Device ID

+
+ + {detect.device_id} + + +
+
+ {/if} + + + {#if initError} +
+ +
+

{initError}

+ +
+
+ {/if} + +
+ + +
+
+
+ {/if} +
diff --git a/frontend/src/lib/components/sync/SyncStatusBanner.svelte b/frontend/src/lib/components/sync/SyncStatusBanner.svelte new file mode 100644 index 00000000..f1a161d5 --- /dev/null +++ b/frontend/src/lib/components/sync/SyncStatusBanner.svelte @@ -0,0 +1,49 @@ + + +{#if running} +
+ + Sync active + + Manage + + +
+{:else} +
+ + + {syncthingUp ? 'Session watcher paused' : 'Syncthing not running'} + + + Start sync + + +
+{/if} diff --git a/frontend/src/lib/components/team/AddProjectDialog.svelte b/frontend/src/lib/components/team/AddProjectDialog.svelte new file mode 100644 index 00000000..221bed92 --- /dev/null +++ b/frontend/src/lib/components/team/AddProjectDialog.svelte @@ -0,0 +1,161 @@ + + + + {#snippet children()} +
+ {#if availableProjects.length === 0} +

+ All projects are already shared with this team. +

+ {:else} +

Select projects to sync:

+
+ {#each availableProjects as project (project.encoded_name)} + + {/each} +
+ {/if} + + {#if sharedProjectNames.length > 0} +

+ Already shared: {sharedProjectNames.join(', ')} +

+ {/if} + + {#if error} +

{error}

+ {/if} +
+ {/snippet} + + {#snippet footer()} + + + {/snippet} + diff --git a/frontend/src/lib/components/team/CreateTeamDialog.svelte b/frontend/src/lib/components/team/CreateTeamDialog.svelte new file mode 100644 index 00000000..b73c5350 --- /dev/null +++ b/frontend/src/lib/components/team/CreateTeamDialog.svelte @@ -0,0 +1,103 @@ + + + + {#snippet children()} +
+
+ + e.key === 'Enter' && handleCreate()} + /> +

+ 2-64 characters. Letters, numbers, dashes, underscores. +

+
+ + {#if error} +

{error}

+ {/if} +
+ {/snippet} + + {#snippet footer()} + + + {/snippet} + diff --git a/frontend/src/lib/components/team/GettingStartedBanner.svelte b/frontend/src/lib/components/team/GettingStartedBanner.svelte new file mode 100644 index 00000000..61597f2c --- /dev/null +++ b/frontend/src/lib/components/team/GettingStartedBanner.svelte @@ -0,0 +1,378 @@ + + +{#if visible} + +{/if} + + diff --git a/frontend/src/lib/components/team/MemberActivityTab.svelte b/frontend/src/lib/components/team/MemberActivityTab.svelte new file mode 100644 index 00000000..56812ec5 --- /dev/null +++ b/frontend/src/lib/components/team/MemberActivityTab.svelte @@ -0,0 +1,222 @@ + + +
+ +
+

Activity Log

+ {#if loading} + + {/if} +
+ + +
+ {#each typePills as pill} + + {/each} +
+ + +
+ {#if events.length === 0} +

No activity yet

+ {:else} +
+ {#each groupedEvents as group (group.label)} + +
+ + {group.label} + ({group.events.length}) + +
+ + {#each group.events as event, i (event.created_at + '-' + i)} +
+ + + {#if isSyncEventWarning(event.event_type)} + + + + {:else} + + {/if} + + + +
+

+ {formatSyncEvent(event)} +

+
+ + {formatRelativeTime(event.created_at)} + + {#if event.event_type && SYNC_EVENT_META[event.event_type]} + + {event.event_type.replace(/_/g, ' ')} + + {/if} + {#if event.team_name} + + {event.team_name} + + {/if} +
+
+
+ {/each} + {/each} +
+ + {#if hasMore} +
+ +
+ {/if} + {/if} +
+
diff --git a/frontend/src/lib/components/team/MemberOverviewTab.svelte b/frontend/src/lib/components/team/MemberOverviewTab.svelte new file mode 100644 index 00000000..79c90946 --- /dev/null +++ b/frontend/src/lib/components/team/MemberOverviewTab.svelte @@ -0,0 +1,405 @@ + + +
+ + +
+
+

{profile.stats.total_sessions}

+

Total Sessions

+
+
+

{profile.stats.sessions_sent}

+

Sent

+
+
+

{profile.stats.sessions_received}

+

Received

+
+ {#if profile.is_you} +
+

+ {profile.unsynced_count ?? 0} +

+

Unsynced

+
+ {:else} +
+

{profile.stats.total_projects}

+

Projects

+
+ {/if} +
+ + + {#if profile.is_you && profile.project_sync && profile.project_sync.length > 0} +
+
+

Sync Health

+ +
+
+ {#each profile.project_sync as ps (ps.team_name + ':' + ps.git_identity)} +
+ {ps.name} + {ps.packaged_count}/{ps.local_count} packaged + {#if ps.gap === 0} + + + In Sync + + {:else} + + {ps.gap} ready + + {/if} +
+ {/each} +
+
+ {/if} + + + {#if !profile.is_you} + {#if projectList.length > 0} +
+
+

Sessions from {profile.user_id}

+
+
+ {#each projectList as proj (proj.encoded_name)} +
+ {proj.name} + {proj.session_count} sessions +
+ {/each} +
+
+ {/if} + {/if} + + + {#if hasChartData} +
+
+

Session Activity

+
+ + + {profile.stats.sessions_sent} sent + + + + {profile.stats.sessions_received} received + +
+
+
+ +
+
+ {:else} +
+

No session activity data yet

+
+ {/if} + + + {#if projectList.length > 0} +
+

+ Projects +

+
+ {#each projectList as project, i (project.encoded_name)} + {@const pct = maxProjectSessions > 0 ? (project.session_count / maxProjectSessions) * 100 : 0} + + +
+ + + + {i + 1} + + + + + + {project.name} + + + +
+ + + {project.session_count} + +
+ + {/each} +
+
+ {/if} + + + {#if recentActivity.length > 0} +
+
+

+ Recent Activity +

+ {#if profile.activity.length > 5} + + View all + + + {/if} +
+
+ {#each recentActivity as event, i (event.created_at + '-' + i)} +
+

+ {formatSyncEvent(event)} +

+ + + {formatRelativeTime(event.created_at)} + +
+ {/each} +
+
+ {/if} + +
diff --git a/frontend/src/lib/components/team/MemberSessionsTab.svelte b/frontend/src/lib/components/team/MemberSessionsTab.svelte new file mode 100644 index 00000000..65c0235c --- /dev/null +++ b/frontend/src/lib/components/team/MemberSessionsTab.svelte @@ -0,0 +1,566 @@ + + +
+ {#if loading} +
+ +
+ {:else if error} +

{error}

+ {:else if sessions.length === 0} + + {:else} + +
+
+ + {totalCount} + {#if apiTotal !== null && apiTotal > totalCount} + of {apiTotal} {apiTotal === 1 ? 'session' : 'sessions'} + {:else} + {totalCount === 1 ? 'session' : 'sessions'} + {/if} +
+
+ + {#if hasActiveFilters || selectedProjectFilters.size > 0 || searchTokens.length > 0} + {filteredSessionsCount} filtered sessions + {:else if apiTotal !== null && apiTotal > totalCount} + {totalCount} of {apiTotal} loaded + {:else} + {totalCount} sessions + {/if} + + +
+ + +
+
+
+ + +
+
+ + + + + {#if showFiltersDropdown && !isMobile} + (showFiltersDropdown = false)} + /> + {/if} +
+
+ + + {#if isMobile} + (showFiltersDropdown = false)} + {scopeSelection} + onScopeSelectionChange={handleScopeSelectionChange} + status={filters.status} + onStatusChange={handleStatusChange} + dateRange={filters.dateRange} + onDateRangeChange={handleDateRangeChange} + onReset={handleClearAllFilters} + /> + {/if} + + + + + + {#if availableProjects.length > 1} +
+ Projects: + {#each availableProjects as project (project.encoded)} + + {/each} + {#if selectedProjectFilters.size > 1} + + {/if} +
+ {/if} + + + {#if filteredSessions.length > 0} + {#if viewMode === 'list'} +
+ {#each groupedByDate as group (group.label)} +
+

+ {group.label} + ({group.sessions.length}) +

+
+ {#each group.sessions as session (session.uuid)} + + {/each} +
+
+ {/each} +
+ {:else} +
+ {#each groupedByDate as group (group.label)} +
+

+ {group.label} + ({group.sessions.length}) +

+
+ {#each group.sessions as session (session.uuid)} + + {/each} +
+
+ {/each} +
+ {/if} + + + {#if hasMore} +
+ +
+ {/if} + {:else if hasActiveFilters || searchTokens.length > 0 || selectedProjectFilters.size > 0} + +
+ {#if searchTokens.length > 0} +

+ No sessions found matching: {searchTokens.join(', ')} +

+ {/if} + {#if selectedProjectFilters.size > 0} +

+ Project filter: {[...selectedProjectFilters].map((enc) => getProjectLabel(enc)).join(', ')} +

+ {/if} +
+ + + {/if} + {/if} +
diff --git a/frontend/src/lib/components/team/MemberSettingsTab.svelte b/frontend/src/lib/components/team/MemberSettingsTab.svelte new file mode 100644 index 00000000..21290d1a --- /dev/null +++ b/frontend/src/lib/components/team/MemberSettingsTab.svelte @@ -0,0 +1,324 @@ + + +{#if profile.teams.length === 0} +
+

Not a member of any teams.

+
+{:else} +
+ +
+ +

+ Override sync direction for this member per team. When no override is set, + the team default applies. Overrides only affect this member's data flow. +

+
+ + {#each teamStates as state, idx (state.teamName)} +
+ +
+
+ + {state.teamName} + + {#if profile.teams[idx]} + + {profile.teams[idx].member_count} member{profile.teams[idx].member_count !== 1 ? 's' : ''} + + {/if} +
+ + {#if state.syncDirection.source === 'member' && !state.loading} + + {/if} +
+ + +
+ {#if state.loading} +
+ +
+ {:else if state.error} +
+

{state.error}

+ +
+ {:else} + +
+ {#each CASCADE_STEPS as step, i} + {@const isActive = state.syncDirection.source === step} + {@const isPast = CASCADE_STEPS.indexOf(state.syncDirection.source) > i} + {#if i > 0} + + {/if} + + {step} + {#if isActive} + + {/if} + + {/each} +
+ + +
+ {#each DIRECTION_OPTIONS as opt (opt.value)} + {@const active = state.syncDirection.value === opt.value} + {@const DirIcon = opt.icon} + + {/each} +
+ + + {#each DIRECTION_OPTIONS.filter((o) => o.value === state.syncDirection.value) as activeDir} +

+ + {activeDir.desc} + {#if state.syncDirection.source !== 'member'} + + (inherited from {sourceLabel(state.syncDirection.source).toLowerCase()}) + + {/if} +

+ {/each} + + {#if state.syncDirection.source !== 'member'} +

+ Select a direction to create a member-level override +

+ {/if} + {/if} +
+
+ {/each} +
+{/if} diff --git a/frontend/src/lib/components/team/MemberSparkline.svelte b/frontend/src/lib/components/team/MemberSparkline.svelte new file mode 100644 index 00000000..4cd28574 --- /dev/null +++ b/frontend/src/lib/components/team/MemberSparkline.svelte @@ -0,0 +1,69 @@ + + +
+ +
diff --git a/frontend/src/lib/components/team/MemberTeamsTab.svelte b/frontend/src/lib/components/team/MemberTeamsTab.svelte new file mode 100644 index 00000000..389cb122 --- /dev/null +++ b/frontend/src/lib/components/team/MemberTeamsTab.svelte @@ -0,0 +1,76 @@ + + +{#if profile.teams.length === 0} +

+ Not a member of any teams. +

+{:else} +
+

+ Member of {profile.teams.length} team{profile.teams.length === 1 ? '' : 's'} +

+ +
+ {#each profile.teams as team (team.name)} + + +
+

+ {team.name} +

+ +
+ + +
+ + + {team.member_count} member{team.member_count === 1 ? '' : 's'} + + + + {team.project_count} project{team.project_count === 1 ? '' : 's'} + + {#if team.online_count > 0} + + + {team.online_count} online + + {/if} +
+ + + {#if team.projects.length > 0} +
+ {#each [...team.projects].sort((a, b) => b.session_count - a.session_count) as project (project.encoded_name)} + + {project.name} + {project.session_count} + + {/each} +
+ {/if} + + {/each} +
+
+{/if} diff --git a/frontend/src/lib/components/team/ProjectMemberBar.svelte b/frontend/src/lib/components/team/ProjectMemberBar.svelte new file mode 100644 index 00000000..b479101b --- /dev/null +++ b/frontend/src/lib/components/team/ProjectMemberBar.svelte @@ -0,0 +1,81 @@ + + +{#if segments.length > 0} +
+ +
+ {#each segments as segment (segment.name)} +
+ {/each} +
+ + +
+ {#each segments as segment (segment.name)} + + + {segment.name} ({segment.count}) + + {/each} +
+
+{/if} diff --git a/frontend/src/lib/components/team/TeamActivityFeed.svelte b/frontend/src/lib/components/team/TeamActivityFeed.svelte new file mode 100644 index 00000000..84bd74cd --- /dev/null +++ b/frontend/src/lib/components/team/TeamActivityFeed.svelte @@ -0,0 +1,213 @@ + + +
+ +
+

Activity Log

+ {#if loading} + + {/if} +
+ + +
+ {#each typePills as pill} + + {/each} +
+ + + {#if members.length > 0} +
+ {#each members as member} + {@const displayName = memberDisplayName(member)} + {@const hex = getTeamMemberHexColor(displayName)} + {@const active = filterMember === member.member_tag} + + {/each} +
+ {/if} + + +
+ {#if events.length === 0} +

No activity yet

+ {:else} +
+ {#each events as event, i (event.created_at + '-' + i)} +
+ + + {#if isSyncEventWarning(event.event_type)} + + + + {:else} + + {/if} + + + +
+

+ {formatSyncEvent(event)} +

+
+ + {formatRelativeTime(event.created_at)} + + {#if event.member_tag} + + {event.member_tag} + + {/if} + {#if event.event_type && SYNC_EVENT_META[event.event_type]} + + {event.event_type.replace(/_/g, ' ')} + + {/if} +
+
+
+ {/each} +
+ + {#if hasMore} +
+ +
+ {/if} + {/if} +
+
diff --git a/frontend/src/lib/components/team/TeamActivityTab.svelte b/frontend/src/lib/components/team/TeamActivityTab.svelte new file mode 100644 index 00000000..a9a6261f --- /dev/null +++ b/frontend/src/lib/components/team/TeamActivityTab.svelte @@ -0,0 +1,17 @@ + + +
+ + +
diff --git a/frontend/src/lib/components/team/TeamCard.svelte b/frontend/src/lib/components/team/TeamCard.svelte new file mode 100644 index 00000000..edf3f57a --- /dev/null +++ b/frontend/src/lib/components/team/TeamCard.svelte @@ -0,0 +1,109 @@ + + + + +
+
+

+ {team.name} +

+ + {team.status} + + {#if activeCount > 0} + + + {activeCount} active + + {/if} + {#if pendingCount > 0} + + + {pendingCount} pending + + {/if} +
+
+ + + {memberCount} {memberCount === 1 ? 'member' : 'members'} + + · + + + {projectCount} {projectCount === 1 ? 'project' : 'projects'} + +
+
+ + +
+ {#each members.slice(0, 5) as member (member.member_tag)} + {@const displayName = memberDisplayName(member)} +
+ {initials(displayName)} + {#if member.status === 'active'} + + {/if} +
+ {/each} + {#if memberCount > 5} +
+ +{memberCount - 5} +
+ {/if} +
+ + + + diff --git a/frontend/src/lib/components/team/TeamMemberCard.svelte b/frontend/src/lib/components/team/TeamMemberCard.svelte new file mode 100644 index 00000000..9cef8d55 --- /dev/null +++ b/frontend/src/lib/components/team/TeamMemberCard.svelte @@ -0,0 +1,132 @@ + + +
+
+
+ {displayName.charAt(0).toUpperCase()} +
+
+
+ + {displayName} + {#if isSelf} + (you) + {/if} + + + {#if isConnected || isSelf} + + Online + {:else} + + Offline + {/if} + +
+ {#if member.device_id} +

+ {member.device_id.length > 20 ? member.device_id.slice(0, 20) + '...' : member.device_id} +

+ {/if} +
+
+ + {#if !isSelf} +
+ {#if confirmRemove} +
+ + +
+ {:else} + + {/if} +
+ {/if} +
diff --git a/frontend/src/lib/components/team/TeamMembersTab.svelte b/frontend/src/lib/components/team/TeamMembersTab.svelte new file mode 100644 index 00000000..62c2dfbc --- /dev/null +++ b/frontend/src/lib/components/team/TeamMembersTab.svelte @@ -0,0 +1,297 @@ + + +
+ + {#if isLeader && showAddForm} +
+
+ + +

+ Your teammate can find their pairing code on the /sync page. +

+
+ {#if addError} +

{addError}

+ {/if} +
+ + +
+
+ {:else if isLeader} + + {/if} + + {#if members.length === 0 && !showAddForm} +

+ No members yet. Click "Add Member" and paste a teammate's pairing code. +

+ {:else if members.length > 0} +
+ {#each members as member (member.member_tag)} + {@const displayName = memberDisplayName(member)} + {@const colors = getTeamMemberColor(displayName)} + {@const hexColor = getTeamMemberHexColor(displayName)} + {@const self = isSelf(member)} +
+ +
+ + +
+ {displayName.charAt(0).toUpperCase()} +
+ + +
+
+ + {member.user_id} + + {#if self} + + You + + {/if} + + {member.status} + + {#if member.status === 'removed' && member.delivery_pending} + + delivery pending + + {/if} +
+
+ + {member.machine_tag} + +
+
+ + + {#if isLeader && !self} + {#if confirmRemove === member.member_tag} +
+ + +
+ {:else} + + {/if} + {/if} +
+ + +
+ {member.member_tag} + · + {member.device_id.slice(0, 7)}… +
+
+ {/each} +
+ {/if} + + + {#if members.length <= 1} +
+

+ Waiting for members? +

+
    +
  • + + Ask your teammate to copy their pairing code from /sync +
    • +
  • + + Both machines need + Syncthing running + — check with + brew services info syncthing +
    • +
  • + + Discovery via relay can take 15-60 seconds after joining +
    • +
+
+ {/if} +
diff --git a/frontend/src/lib/components/team/TeamOverviewTab.svelte b/frontend/src/lib/components/team/TeamOverviewTab.svelte new file mode 100644 index 00000000..c35c96db --- /dev/null +++ b/frontend/src/lib/components/team/TeamOverviewTab.svelte @@ -0,0 +1,138 @@ + + +
+ + {#if offeredSubscriptionCount && offeredSubscriptionCount > 0} + + {/if} + + + onswitchtab?.('projects')} + onAddMember={() => onswitchtab?.('members')} + /> + + +
+
+
+
+

{team.name}

+ + {team.status} + +
+
+ + + Leader: {team.leader_member_tag} + + {#if createdDate} + + + Created {createdDate} + + {/if} +
+
+
+
+ + +
+ +
+ +
diff --git a/frontend/src/lib/components/team/TeamProjectsTab.svelte b/frontend/src/lib/components/team/TeamProjectsTab.svelte new file mode 100644 index 00000000..e7fff559 --- /dev/null +++ b/frontend/src/lib/components/team/TeamProjectsTab.svelte @@ -0,0 +1,598 @@ + + +
+ + {#if offeredProjects.length > 0} +
+
+
+ +
+

+ Pending Invitation{offeredProjects.length !== 1 ? 's' : ''} +

+ + {offeredProjects.length} + +
+ + {#each offeredProjects as project (project.git_identity)} + {@const info = getProjectInfo(project)} + {@const isActing = subscriptionActing === project.git_identity} + {@const dir = getSelectedDir(project.git_identity)} + +
+ +
+
+
+ +
+
+
+

+ {info.displayName} +

+ + invitation + +
+

{info.path}

+
+
+ +

+ Choose how you want to sync sessions for this project: +

+
+ + +
+
+ {#each DIRECTION_OPTIONS as opt} + {@const isSelected = dir === opt.value} + {@const Icon = opt.icon} + + {/each} +
+
+ + +
+ + +
+
+ {/each} +
+ {/if} + + + + + {#if isLeader} +
+ +
+ {/if} + + {#if removeProjectError} +

{removeProjectError}

+ {/if} + + +
+
+

Active Projects

+
+ {#if totalTeamGap > 0} + + {/if} +
+ +
+ {#each activeProjects as project (project.git_identity)} + {@const info = getProjectInfo(project)} + {@const mySub = getMySubscription(project.git_identity)} + {@const isActing = subscriptionActing === project.git_identity} + {@const isDirActing = directionActing === project.git_identity} + {@const ps = statusByGit.get(project.git_identity)} + {@const hasSendSub = mySub?.status === 'accepted' && (mySub?.direction === 'send' || mySub?.direction === 'both')} + +
+ +
+
+
+ +
+
+ {#if info.localEncodedName} + + {info.displayName} + + {:else} + + {info.displayName} + + {/if} +

{info.path}

+
+
+ +
+ + + {project.status} + + + + {#if ps && hasSendSub} + {#if (ps.gap ?? 0) === 0} + + + In Sync + + {:else} + + {ps.gap} ready to sync + + + {/if} + {/if} + + + {#if isLeader && removeProjectConfirm === project.git_identity} +
+ + +
+ {:else if isLeader} + + {/if} +
+
+ + + {#if mySub} +
+
+ Sync: + + {mySub.status} + + {#if mySub.status === 'accepted'} + {@const DirIcon = directionIcon(mySub.direction)} + + {/if} +
+ +
+ {#if mySub.status === 'accepted'} + + {:else if mySub.status === 'paused'} + + {:else if mySub.status === 'declined'} + + {/if} +
+
+ {/if} +
+ {/each} + + {#if projects.length === 0} +
+
+ +
+

No projects shared yet

+

+ {#if isLeader} + Add projects to start syncing sessions with your team. + {:else} + The team leader hasn't shared any projects yet. + {/if} +

+
+ {/if} +
+
+ + diff --git a/frontend/src/lib/components/timeline/TimelineEventCard.svelte b/frontend/src/lib/components/timeline/TimelineEventCard.svelte index ecc564bb..deaa9062 100644 --- a/frontend/src/lib/components/timeline/TimelineEventCard.svelte +++ b/frontend/src/lib/components/timeline/TimelineEventCard.svelte @@ -98,10 +98,11 @@ event.event_type === 'tool_call' ? getToolIcon(toolName) : config.icon ); - // Display title — for subagent spawns, show "Spawn [type] subagent" + // Display title — for subagent spawns, show "Spawn [type] subagent" with optional display_name const displayTitle = $derived.by(() => { if (event.metadata?.spawned_agent_id && event.metadata?.subagent_type) { - return `Spawn ${event.metadata.subagent_type} subagent`; + const name = event.metadata.display_name ? ` "${event.metadata.display_name}"` : ''; + return `Spawn ${event.metadata.subagent_type}${name} subagent`; } return event.title; }); diff --git a/frontend/src/lib/components/timeline/ToolCallDetail.svelte b/frontend/src/lib/components/timeline/ToolCallDetail.svelte index eaa4664d..7695cc99 100644 --- a/frontend/src/lib/components/timeline/ToolCallDetail.svelte +++ b/frontend/src/lib/components/timeline/ToolCallDetail.svelte @@ -24,6 +24,30 @@ import DOMPurify from 'isomorphic-dompurify'; import type { TimelineEvent } from '$lib/api-types'; import { formatDisplayPath } from '$lib/utils'; + import { Image } from 'lucide-svelte'; + + /** + * Detect if a string looks like base64-encoded binary data. + * Returns the detected media type if it looks like an image, null otherwise. + */ + function detectBase64Image(text: string): string | null { + if (!text || text.length < 100) return null; + // Check for data URI prefix + const dataUriMatch = text.match(/^data:(image\/[a-z+]+);base64,/i); + if (dataUriMatch) return dataUriMatch[1]; + // Check if content is predominantly base64 chars (A-Z, a-z, 0-9, +, /, =) + // with minimal whitespace — a strong signal of binary data + const sample = text.slice(0, 500).replace(/\s/g, ''); + const base64Ratio = sample.replace(/[^A-Za-z0-9+/=]/g, '').length / sample.length; + if (base64Ratio > 0.95 && text.length > 500) { + // Heuristic: PNG starts with iVBOR, JPEG with /9j/, GIF with R0lG + if (text.startsWith('iVBOR')) return 'image/png'; + if (text.startsWith('/9j/')) return 'image/jpeg'; + if (text.startsWith('R0lG')) return 'image/gif'; + return 'application/octet-stream'; + } + return null; + } interface Props { event: TimelineEvent; @@ -1257,8 +1281,9 @@ ? resultContent : JSON.stringify(resultContent, null, 2)} {@const isError = resultStatus === 'error'} + {@const detectedImageType = detectBase64Image(content)} {@const maxLength = 1000} - {@const truncated = content.length > maxLength} + {@const truncated = !detectedImageType && content.length > maxLength}

+ {#if detectedImageType && detectedImageType.startsWith('image/')} + +
+
+ + + Image result ({detectedImageType}, {Math.round(content.length * 0.75 / 1024)}KB) + +
+ Tool result image +
+ {:else if detectedImageType} + +
+
+ + Binary content ({Math.round(content.length * 0.75 / 1024)}KB) + +
+
+ {:else}
+
{@render children()}
diff --git a/frontend/src/lib/components/ui/TabsTrigger.svelte b/frontend/src/lib/components/ui/TabsTrigger.svelte index 4982f478..7fcb0c21 100644 --- a/frontend/src/lib/components/ui/TabsTrigger.svelte +++ b/frontend/src/lib/components/ui/TabsTrigger.svelte @@ -19,7 +19,7 @@ class=" px-4 py-2 text-sm font-medium rounded-md transition-all duration-200 ease-out - flex items-center gap-2 + flex items-center gap-2 whitespace-nowrap focus:outline-none focus-visible:ring-2 focus-visible:ring-[var(--accent)] focus-visible:ring-offset-2 focus-visible:ring-offset-[var(--bg-base)] data-[state=active]:bg-[var(--bg-base)] data-[state=active]:text-[var(--text-primary)] diff --git a/frontend/src/lib/config.ts b/frontend/src/lib/config.ts index 382fb55c..608cf716 100644 --- a/frontend/src/lib/config.ts +++ b/frontend/src/lib/config.ts @@ -32,5 +32,7 @@ export const POLLING_INTERVALS = { /** Live sessions polling interval (ms) */ LIVE_SESSIONS: 2_000, /** Historical data polling interval (ms) */ - HISTORICAL_DATA: 30_000 + HISTORICAL_DATA: 30_000, + /** Sync status polling interval (ms) */ + SYNC_STATUS: 10_000 } as const; diff --git a/frontend/src/lib/search.ts b/frontend/src/lib/search.ts index 1b7f8227..af8e370f 100644 --- a/frontend/src/lib/search.ts +++ b/frontend/src/lib/search.ts @@ -11,6 +11,7 @@ import type { SearchScope, SearchScopeSelection, SessionStatusFilter, + SessionSourceFilter, SearchDateRange, LiveSubStatus, LiveSessionSummary, @@ -31,7 +32,8 @@ export const DEFAULT_FILTERS: SearchFilters = { scope: 'both', status: 'all', dateRange: 'all', - liveSubStatuses: [...ALL_LIVE_SUB_STATUSES] + liveSubStatuses: [...ALL_LIVE_SUB_STATUSES], + source: 'all' }; /** Maximum number of search tokens allowed */ @@ -63,6 +65,7 @@ export function filtersToParams(filters: SearchFilters): URLSearchParams { if (filters.liveSubStatuses && filters.liveSubStatuses.length < ALL_LIVE_SUB_STATUSES.length) { params.set('substatus', filters.liveSubStatuses.join(',')); } + if (filters.source && filters.source !== 'all') params.set('source', filters.source); return params; } @@ -96,6 +99,7 @@ export function paramsToFilters(params: URLSearchParams): SearchFilters { const statusParam = params.get('status'); const rangeParam = params.get('range'); const substatusParam = params.get('substatus'); + const sourceParam = params.get('source'); const queryParam = params.get('q') || ''; // Parse tokens from query param @@ -115,7 +119,8 @@ export function paramsToFilters(params: URLSearchParams): SearchFilters { .filter((s) => ALL_LIVE_SUB_STATUSES.includes(s as LiveSubStatus) ) as LiveSubStatus[]) - : [...ALL_LIVE_SUB_STATUSES] + : [...ALL_LIVE_SUB_STATUSES], + source: isValidSource(sourceParam) ? sourceParam : 'all' }; } @@ -127,6 +132,10 @@ function isValidStatus(value: string | null): value is SessionStatusFilter { return value === 'all' || value === 'live' || value === 'completed'; } +function isValidSource(value: string | null): value is SessionSourceFilter { + return value === 'all' || value === 'local' || value === 'remote'; +} + function isValidDateRange(value: string | null): value is SearchDateRange { return ( value === 'all' || @@ -153,6 +162,7 @@ const ALL_FILTER_PARAM_KEYS = [ 'from', 'to', 'substatus', + 'source', 'branches', 'project', 'page' @@ -328,6 +338,14 @@ export function getFilterChips(filters: SearchFilters): FilterChip[] { }); } + if (filters.source && filters.source !== 'all') { + chips.push({ + key: 'source', + label: 'Source', + value: filters.source === 'local' ? 'Local' : 'Remote' + }); + } + return chips; } @@ -400,13 +418,15 @@ export function hasActiveFilters(filters: SearchFilters): boolean { filters.liveSubStatuses !== undefined && filters.liveSubStatuses.length < ALL_LIVE_SUB_STATUSES.length; const hasTokens = filters.tokens && filters.tokens.length > 0; + const hasSourceFilter = filters.source !== undefined && filters.source !== 'all'; return ( hasTokens || filters.query !== '' || filters.scope !== 'both' || filters.status !== 'all' || filters.dateRange !== 'all' || - hasSubStatusFilter + hasSubStatusFilter || + hasSourceFilter ); } @@ -514,6 +534,12 @@ export const STATUS_OPTIONS: { value: SessionStatusFilter; label: string; color? { value: 'completed', label: 'Completed', color: 'var(--text-muted)' } ]; +export const SOURCE_OPTIONS: { value: SessionSourceFilter; label: string }[] = [ + { value: 'all', label: 'All' }, + { value: 'local', label: 'Local' }, + { value: 'remote', label: 'Remote' } +]; + export const DATE_RANGE_OPTIONS: { value: SearchDateRange; label: string }[] = [ { value: 'all', label: 'All time' }, { value: 'today', label: 'Today' }, @@ -809,6 +835,25 @@ export function filterSessionsByBranch( ); } +/** + * Filter sessions by source (local vs remote). + * + * @param sessions - Array of sessions to filter + * @param source - Source filter: 'all', 'local', or 'remote' + * @returns Filtered sessions matching the source + */ +export function filterSessionsBySource( + sessions: T[], + source: SessionSourceFilter +): T[] { + if (source === 'all') return sessions; + + return sessions.filter((session) => { + const isRemote = !!(session as SessionSummary).remote_user_id; + return source === 'remote' ? isRemote : !isRemote; + }); +} + /** * Filter sessions by project (OR logic - matches ANY selected project). * diff --git a/frontend/src/lib/utils.ts b/frontend/src/lib/utils.ts index aa6b55e8..e2ad2979 100644 --- a/frontend/src/lib/utils.ts +++ b/frontend/src/lib/utils.ts @@ -213,6 +213,19 @@ export function truncate(text: string, maxLength: number): string { return text.slice(0, maxLength - 3) + '...'; } +/** + * Clean prompt text by removing command tags (skill invocation metadata) + * and any stray HTML tags. Shared by ExpandablePrompt, SessionChainView, SubagentCard, etc. + */ +export function cleanPromptText(text: string): string { + return text + .replace(/[^<]*<\/command-message>\s*/g, '') + .replace(/[^<]*<\/command-name>\s*/g, '') + .replace(/[\s\S]*?<\/command-args>\s*/g, '') + .replace(/<[^>]+>/g, '') // Strip any remaining HTML tags + .trim(); +} + /** * Format file size in human-readable format (e.g., "1.2 KB", "3.4 MB") */ @@ -419,7 +432,7 @@ export function getSessionDisplayPrompt( initialPrompt?: string, sessionTitles?: string[] ): string | null { - if (initialPrompt && initialPrompt !== 'No prompt') return initialPrompt; + if (initialPrompt && initialPrompt !== 'No prompt') return cleanPromptText(initialPrompt); return sessionTitles?.[0] || null; } @@ -716,6 +729,121 @@ export const modelColorConfig: Record< } }; +// ============================================ +// Team Member Color Utilities (Remote Sessions) +// ============================================ + +/** Color palette for team members, avoiding model colors (purple/blue/green) */ +const TEAM_MEMBER_PALETTE = [ + 'coral', + 'rose', + 'amber', + 'cyan', + 'pink', + 'lime', + 'indigo', + 'teal', + 'sky', + 'violet', + 'emerald', + 'orange', + 'fuchsia', + 'slate', + 'gold', + 'ruby' +] as const; + +type TeamColor = (typeof TEAM_MEMBER_PALETTE)[number]; + +export interface TeamMemberColorConfig { + border: string; + badge: string; + text: string; + bg: string; +} + +/** Deterministic hash to palette index for a userId */ +function teamMemberPaletteIndex(userId: string): number { + let hash = 0; + for (let i = 0; i < userId.length; i++) { + hash = (hash << 5) - hash + userId.charCodeAt(i); + hash |= 0; + } + return Math.abs(hash) % TEAM_MEMBER_PALETTE.length; +} + +/** + * Deterministic hash-based color assignment for team members. + * Same userId always gets the same color. + */ +export function getTeamMemberColor(userId: string): TeamMemberColorConfig { + const color: TeamColor = TEAM_MEMBER_PALETTE[teamMemberPaletteIndex(userId)]; + return { + border: `var(--team-${color})`, + badge: `bg-[var(--team-${color}-subtle)] border-[var(--team-${color})]/20`, + text: `text-[var(--team-${color})]`, + bg: `var(--team-${color}-subtle)` + }; +} + +// ============================================ +// Chart Hex Color Utilities (for Chart.js canvas) +// ============================================ + +/** Hex colors matching TEAM_MEMBER_PALETTE CSS var names — for Chart.js canvas rendering */ +const TEAM_HEX_COLORS: Record = { + coral: '#f97066', + rose: '#f43f5e', + amber: '#f59e0b', + cyan: '#06b6d4', + pink: '#ec4899', + lime: '#84cc16', + indigo: '#6366f1', + teal: '#14b8a6', + sky: '#0ea5e9', + violet: '#7c3aed', + emerald: '#10b981', + orange: '#f97316', + fuchsia: '#c026d3', + slate: '#64748b', + gold: '#eab308', + ruby: '#be123c' +}; + +/** Accent purple used for local user in charts */ +export const LOCAL_USER_HEX = '#7c3aed'; + +/** + * Get hex color for a team member (for Chart.js). + * Uses same hash as getTeamMemberColor() for consistency. + */ +export function getTeamMemberHexColor(userId: string): string { + return TEAM_HEX_COLORS[TEAM_MEMBER_PALETTE[teamMemberPaletteIndex(userId)]]; +} + +/** Get hex color for a user_id. '_local' → accent purple, others → team color */ +export function getUserChartColor(userId: string): string { + return userId === '_local' ? LOCAL_USER_HEX : getTeamMemberHexColor(userId); +} + +/** Get display label for a user in charts */ +export function getUserChartLabel( + userId: string, + userNames?: Record +): string { + if (userId === '_local') return 'You'; + const name = userNames?.[userId]; + if (name) return name; + return userId.length > 16 ? userId.slice(0, 14) + '\u2026' : userId; +} + +/** + * Check if a session is from a remote machine + */ +export function isRemoteSession(session: { remote_user_id?: string }): boolean { + return !!session.remote_user_id; +} + // ============================================ // Subagent Color Utilities // ============================================ @@ -1032,6 +1160,8 @@ export function getSkillCategoryLabel(category: string): string { return 'Plugin'; case 'custom_skill': return 'Custom'; + case 'inherited_skill': + return 'Inherited'; default: return category; } @@ -1047,6 +1177,8 @@ export function getSkillCategoryColorVars(category: string): { color: string; su case 'plugin_skill': case 'custom_skill': return _getSharedCategoryColorVars(category); + case 'inherited_skill': + return { color: 'var(--nav-amber)', subtle: 'oklch(0.75 0.1 80 / 0.1)' }; default: return { color: 'var(--text-muted)', subtle: 'var(--bg-muted)' }; } @@ -1529,6 +1661,37 @@ export function toSessionWithContext(s: McpSessionSummary | SessionSummary): Ses session_titles: s.session_titles, project_encoded_name: encoded, project_path: encoded ?? '', - project_name: displayName || getProjectNameFromEncoded(encoded ?? '') + project_name: displayName || getProjectNameFromEncoded(encoded ?? ''), + session_source: ('session_source' in s ? s.session_source : undefined) ?? undefined, + source: ('source' in s ? s.source : undefined) ?? undefined, + remote_user_id: ('remote_user_id' in s ? s.remote_user_id : undefined) ?? undefined, + remote_machine_id: ('remote_machine_id' in s ? s.remote_machine_id : undefined) ?? undefined }; } + +// ============================================ +// Byte Formatting +// ============================================ + +/** + * Format bytes into human-readable size (e.g., "1.2 MB", "3.5 GB") + * Uses binary units (1024-based). + */ +export function formatBytes(bytes: number): string { + if (bytes < 1024) return `${bytes} B`; + if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`; + if (bytes < 1024 * 1024 * 1024) return `${(bytes / (1024 * 1024)).toFixed(1)} MB`; + return `${(bytes / (1024 * 1024 * 1024)).toFixed(1)} GB`; +} + +/** + * Format bytes per second into human-readable rate (e.g., "1.2 KB/s") + * Uses binary units (1024-based). + */ +export function formatBytesRate(bytesPerSec: number): string { + if (bytesPerSec < 1024) return `${bytesPerSec.toFixed(0)} B/s`; + if (bytesPerSec < 1024 * 1024) return `${(bytesPerSec / 1024).toFixed(1)} KB/s`; + if (bytesPerSec < 1024 * 1024 * 1024) + return `${(bytesPerSec / (1024 * 1024)).toFixed(1)} MB/s`; + return `${(bytesPerSec / (1024 * 1024 * 1024)).toFixed(1)} GB/s`; +} diff --git a/frontend/src/lib/utils/sync-events.ts b/frontend/src/lib/utils/sync-events.ts new file mode 100644 index 00000000..b4d12a19 --- /dev/null +++ b/frontend/src/lib/utils/sync-events.ts @@ -0,0 +1,119 @@ +/** + * Shared formatting utilities for SyncEvent objects. + * + * Consolidates event description logic previously duplicated between + * OverviewTab.svelte (humanizeEvent) and TeamActivityFeed.svelte (describeEvent). + */ + +import type { SyncEvent } from '$lib/api-types'; + +/** + * Event metadata used for rendering (color, label). + */ +export const SYNC_EVENT_META: Record = { + team_created: { color: 'text-[var(--success)]', label: 'created the team' }, + team_deleted: { color: 'text-[var(--error)]', label: 'deleted the team' }, + team_left: { color: 'text-[var(--warning)]', label: 'left the team' }, + member_joined: { color: 'text-[var(--success)]', label: 'joined the team' }, + member_added: { color: 'text-[var(--success)]', label: 'was added' }, + member_auto_accepted: { color: 'text-[var(--success)]', label: 'was auto-accepted' }, + member_removed: { color: 'text-[var(--error)]', label: 'was removed' }, + project_shared: { color: 'text-[var(--accent)]', label: 'shared a project' }, + project_added: { color: 'text-[var(--accent)]', label: 'added a project' }, + project_removed: { color: 'text-[var(--warning)]', label: 'removed a project' }, + folders_shared: { color: 'text-[var(--accent)]', label: 'synced folders' }, + pending_accepted: { color: 'text-[var(--success)]', label: 'accepted pending folders' }, + session_packaged: { color: 'text-[var(--accent)]', label: 'packaged a session' }, + session_received: { color: 'text-[var(--accent)]', label: 'received a session' }, + file_rejected: { color: 'text-[var(--error)]', label: 'file rejected' }, + sync_paused: { color: 'text-[var(--warning)]', label: 'sync paused' }, + settings_changed: { color: 'text-[var(--accent)]', label: 'changed settings' }, + sync_now: { color: 'text-[var(--accent)]', label: 'triggered sync' }, + watcher_started: { color: 'text-[var(--success)]', label: 'watcher started' }, + watcher_stopped: { color: 'text-[var(--warning)]', label: 'watcher stopped' }, + watch_started: { color: 'text-[var(--success)]', label: 'watcher started' }, + watch_stopped: { color: 'text-[var(--warning)]', label: 'watcher stopped' }, + subscription_accepted: { color: 'text-[var(--success)]', label: 'accepted subscription' }, + subscription_paused: { color: 'text-[var(--warning)]', label: 'paused subscription' }, + subscription_resumed: { color: 'text-[var(--success)]', label: 'resumed subscription' }, + subscription_declined: { color: 'text-[var(--error)]', label: 'declined subscription' }, +}; + +/** + * Returns a human-readable description for a SyncEvent. + * + * Handles both v3 (member_name, string detail) and v4 (member_tag, Record detail) shapes. + */ +export function formatSyncEvent(ev: SyncEvent): string { + const meta = SYNC_EVENT_META[ev.event_type]; + // v4 uses member_tag, v3 uses member_name + const actor = ev.member_tag || ev.member_name || 'System'; + const team = ev.team_name ?? 'team'; + + const base = meta ? `${actor} ${meta.label}` : `${actor}: ${ev.event_type.replace(/_/g, ' ')}`; + + // Simple overrides for team-level events + switch (ev.event_type) { + case 'watch_started': + return `Session watcher started for ${team}`; + case 'watch_stopped': + return 'Session watcher stopped'; + case 'team_created': + return `Team ${team} created`; + case 'team_deleted': + return `Team ${team} deleted`; + case 'pending_accepted': + break; + } + + // Parse structured detail field (v4: already a Record, v3: JSON string) + let detail = ''; + if (ev.detail) { + try { + const d = typeof ev.detail === 'string' ? JSON.parse(ev.detail) : ev.detail; + if (ev.event_type === 'project_shared' && d.session_count !== undefined) { + detail = ` (${d.session_count} sessions)`; + } else if (ev.event_type === 'pending_accepted' && d.count) { + detail = ` (${d.count} folders)`; + } else if (ev.event_type === 'folders_shared') { + detail = ` (${d.outboxes || 0} out, ${d.inboxes || 0} in)`; + } else if (ev.event_type === 'file_rejected' && d.reason) { + detail = `: ${d.reason}`; + } else if (ev.event_type === 'settings_changed' && d.sync_session_limit) { + const labels: Record = { + all: 'All', + recent_100: 'Recent 100', + recent_10: 'Recent 10' + }; + detail = ` -> ${labels[d.sync_session_limit] || d.sync_session_limit}`; + } else if (ev.event_type === 'subscription_accepted' && d.direction) { + detail = ` (${d.direction})`; + } else if (d.git_identity) { + detail = ` for ${d.git_identity}`; + } + } catch { + /* ignore parse errors */ + } + } + + // Append project name suffix where relevant (v3 compat) + if ( + ev.project_encoded_name && + !['settings_changed', 'pending_accepted'].includes(ev.event_type) + ) { + const projName = ev.project_encoded_name.split('-').pop() || ev.project_encoded_name; + return `${base} in ${projName}${detail}`; + } + + return `${base}${detail}`; +} + +/** Get the CSS color class for a sync event type */ +export function syncEventColor(eventType: string): string { + return SYNC_EVENT_META[eventType]?.color ?? 'text-[var(--text-muted)]'; +} + +/** Whether an event type should be shown with a warning indicator */ +export function isSyncEventWarning(eventType: string): boolean { + return ['file_rejected', 'sync_paused'].includes(eventType); +} diff --git a/frontend/src/lib/utils/url-view-state.ts b/frontend/src/lib/utils/url-view-state.ts new file mode 100644 index 00000000..e12c6be7 --- /dev/null +++ b/frontend/src/lib/utils/url-view-state.ts @@ -0,0 +1,40 @@ +import { browser } from '$app/environment'; + +/** + * Create a pair of $effect callbacks for syncing a view mode to/from URL `?view=` param. + * Call both returned functions inside your component's ` -
+
+ +
+ +
+
@@ -29,9 +35,12 @@ - - + + + + +
@@ -40,9 +49,23 @@
- - -
- -
+ + diff --git a/frontend/src/routes/about/+page.svelte b/frontend/src/routes/about/+page.svelte index 896e29ae..47362b04 100644 --- a/frontend/src/routes/about/+page.svelte +++ b/frontend/src/routes/about/+page.svelte @@ -81,7 +81,7 @@ @@ -94,10 +94,10 @@

Make sure the API is running on port 8000.

{:else} -
+
-
{/if} + +
+ +
+ {#if hasActiveFilters} +
+ {/if} +
@@ -1083,3 +1132,15 @@ {/if} {/if}
+ +{#if detail?.is_remote_only && detail?.remote_definition?.content} + (inheritModalOpen = false)} + onInherited={() => { inheritModalOpen = false; }} + /> +{/if} diff --git a/frontend/src/routes/sync/+page.server.ts b/frontend/src/routes/sync/+page.server.ts new file mode 100644 index 00000000..6b2d4871 --- /dev/null +++ b/frontend/src/routes/sync/+page.server.ts @@ -0,0 +1,16 @@ +import type { PageServerLoad } from './$types'; +import type { SyncDetect, SyncStatusResponse } from '$lib/api-types'; +import { API_BASE } from '$lib/config'; +import { safeFetch } from '$lib/utils/api-fetch'; + +export const load: PageServerLoad = async ({ fetch }) => { + const [detectResult, statusResult] = await Promise.all([ + safeFetch(fetch, `${API_BASE}/sync/detect`), + safeFetch(fetch, `${API_BASE}/sync/status`) + ]); + + return { + detect: detectResult.ok ? detectResult.data : null, + status: statusResult.ok ? statusResult.data : null + }; +}; diff --git a/frontend/src/routes/sync/+page.svelte b/frontend/src/routes/sync/+page.svelte new file mode 100644 index 00000000..bfbf0b90 --- /dev/null +++ b/frontend/src/routes/sync/+page.svelte @@ -0,0 +1,118 @@ + + +
+ + {#snippet headerRight()} + {#if syncStatus?.configured} +
+ {#if lastUpdated} + + Last updated: {secondsSinceUpdate}s ago + + {/if} + +
+ {/if} + {/snippet} + + + { + if (teams?.length) goto(`/team/${encodeURIComponent(teams[0])}`); + else refreshData(); + }} /> + + {#if !syncStatus?.configured} + + {:else} + + {/if} +
diff --git a/frontend/src/routes/team/+page.server.ts b/frontend/src/routes/team/+page.server.ts new file mode 100644 index 00000000..c95733a2 --- /dev/null +++ b/frontend/src/routes/team/+page.server.ts @@ -0,0 +1,36 @@ +import type { PageServerLoad } from './$types'; +import { API_BASE } from '$lib/config'; +import { fetchAllWithFallbacks } from '$lib/utils/api-fetch'; +import type { SyncStatusResponse, SyncTeam, SyncSubscription } from '$lib/api-types'; + +export const load: PageServerLoad = async ({ fetch }) => { + const [syncStatus, teamsData, subsData] = await fetchAllWithFallbacks(fetch, [ + { + url: `${API_BASE}/sync/status`, + fallback: { configured: false } as SyncStatusResponse + }, + { + url: `${API_BASE}/sync/teams`, + fallback: { teams: [] as SyncTeam[] } + }, + { + url: `${API_BASE}/sync/subscriptions`, + fallback: { subscriptions: [] as SyncSubscription[] } + } + ] as const); + + // Count offered subscriptions per team + const subs: SyncSubscription[] = subsData.subscriptions ?? []; + const pendingByTeam: Record = {}; + for (const s of subs) { + if (s.status === 'offered') { + pendingByTeam[s.team_name] = (pendingByTeam[s.team_name] ?? 0) + 1; + } + } + + return { + syncStatus, + teams: teamsData.teams ?? [], + pendingByTeam + }; +}; diff --git a/frontend/src/routes/team/+page.svelte b/frontend/src/routes/team/+page.svelte new file mode 100644 index 00000000..f1079020 --- /dev/null +++ b/frontend/src/routes/team/+page.svelte @@ -0,0 +1,181 @@ + + + + {#snippet headerRight()} + {#if configured && teams.length > 0} + + {/if} + {/snippet} + + +
+ { + if (teams?.length) goto(`/team/${encodeURIComponent(teams[0])}`); + else invalidateAll(); + }} /> + + {#if !configured} + +
+
+ +
+

Set up sync first

+

+ Before creating or joining a team, you need to install Syncthing and initialize sync. +

+ + Go to Sync Setup + + +
+ {:else if teams.length === 0} + +
+
+ +
+

No teams yet

+

+ Get started by creating or joining a team +

+ +
+ +
+
+
+ +
+

Create a Team

+
+

+ You're the leader. Create a team, share projects, and add members using their pairing codes. +

+ +
+ + +
+
+
+ +
+

Join a Team

+
+

+ Share your pairing code with a team leader. They'll add you from their end. +

+ + +
+ +
+
+
+
+ {:else} + + + + +
+ + Sync status → + +
+ + +
+ {#each teams as team (team.name)} + + {/each} +
+ {/if} +
+ + diff --git a/frontend/src/routes/team/[name]/+page.server.ts b/frontend/src/routes/team/[name]/+page.server.ts new file mode 100644 index 00000000..e837efab --- /dev/null +++ b/frontend/src/routes/team/[name]/+page.server.ts @@ -0,0 +1,55 @@ +import type { PageServerLoad } from './$types'; +import { API_BASE } from '$lib/config'; +import { safeFetch, fetchWithFallback } from '$lib/utils/api-fetch'; +import type { + SyncTeam, + SyncStatusResponse, + SyncEvent +} from '$lib/api-types'; + +interface ProjectSummary { + encoded_name: string; + path: string; + slug?: string; + display_name?: string; + session_count: number; + git_remote_url?: string; +} + +export const load: PageServerLoad = async ({ fetch, params }) => { + const teamName = params.name; + const teamNameEnc = encodeURIComponent(teamName); + + // Fetch in parallel: team detail (includes members+projects+subscriptions), sync status, activity, all projects + const [teamResult, syncStatus, activityData, allProjects] = await Promise.all([ + safeFetch(fetch, `${API_BASE}/sync/teams/${teamNameEnc}`), + fetchWithFallback(fetch, `${API_BASE}/sync/status`, { + configured: false + }), + fetchWithFallback<{ events: SyncEvent[] }>( + fetch, + `${API_BASE}/sync/teams/${teamNameEnc}/activity?limit=20`, + { events: [] } + ), + fetchWithFallback( + fetch, + `${API_BASE}/projects`, + [] + ) + ]); + + const team = teamResult.ok ? teamResult.data : null; + + return { + teamName, + team, + syncStatus, + activity: activityData.events ?? [], + allProjects: allProjects.map((p) => ({ + encoded_name: p.encoded_name, + name: p.display_name || p.slug || p.encoded_name, + path: p.path, + git_remote_url: p.git_remote_url ?? null + })) + }; +}; diff --git a/frontend/src/routes/team/[name]/+page.svelte b/frontend/src/routes/team/[name]/+page.svelte new file mode 100644 index 00000000..3b3b04fe --- /dev/null +++ b/frontend/src/routes/team/[name]/+page.svelte @@ -0,0 +1,330 @@ + + + + {#snippet headerRight()} +
+ {#if team} + + {team.status} + + {/if} + +
+ {/snippet} + + +{#if team} + + + Overview + Members ({members.filter(m => m.member_tag !== memberTag).length}) + + Projects ({projects.length}) + {#if offeredCount > 0} + {offeredCount} + {/if} + + Activity + Settings + + + + activeTab = tab} + offeredSubscriptionCount={offeredCount} + /> + + + + + + + + + + + + + + + +
+ +
+

Team Actions

+ + {#if deleteConfirm} + +
+ +

+ {#if isLeader} + Dissolve team "{data.teamName}"? This will remove all members, stop syncing, and clean up Syncthing folders for everyone. + {:else} + Leave team "{data.teamName}"? This will stop syncing with all members and clean up Syncthing folders on this machine. + {/if} +

+
+ + +
+
+ {#if deleteError} +

{deleteError}

+ {/if} + {:else} + + {/if} +
+
+ + +{:else if !teamEverLoaded} +
+ +

Setting up "{data.teamName}"...

+

Waiting for team metadata to sync

+
+{:else} +
+ +

Team "{data.teamName}" not found

+ + Back to Teams + +
+{/if} diff --git a/frontend/src/routes/tools/+page.svelte b/frontend/src/routes/tools/+page.svelte index d85d1074..cfee1bb7 100644 --- a/frontend/src/routes/tools/+page.svelte +++ b/frontend/src/routes/tools/+page.svelte @@ -11,6 +11,7 @@ Puzzle } from 'lucide-svelte'; import { navigating } from '$app/stores'; + import { createUrlViewState } from '$lib/utils/url-view-state'; import { listNavigation } from '$lib/actions/listNavigation'; import PageHeader from '$lib/components/layout/PageHeader.svelte'; import SkeletonBox from '$lib/components/skeleton/SkeletonBox.svelte'; @@ -26,19 +27,33 @@ import McpContextBar from '$lib/components/tools/McpContextBar.svelte'; import { getServerColorVars, getToolItemChartHex, parseBuiltinTool, parseMcpTool } from '$lib/utils/mcp'; import UsageAnalytics from '$lib/components/charts/UsageAnalytics.svelte'; + import MemberUsageGrid from '$lib/components/members/MemberUsageGrid.svelte'; import type { McpServer, StatItem } from '$lib/api-types'; let { data } = $props(); // Client-side filter state let searchQuery = $state(''); - let viewMode = $state<'servers' | 'tools' | 'analytics'>('servers'); + let viewMode = $state<'servers' | 'tools' | 'analytics' | 'members'>('servers'); let sourceFilter = $state<'all' | 'plugin' | 'standalone' | 'builtin'>('all'); + const validViews = ['servers', 'tools', 'analytics', 'members'] as const; + + // URL state persistence for view mode + const { initFromUrl, syncToUrl } = createUrlViewState( + 'servers', validViews, + () => viewMode, (v) => viewMode = v + ); + $effect(initFromUrl); + $effect(syncToUrl); + + // Reset sub-filter when entering members view + $effect(() => { if (viewMode === 'members') sourceFilter = 'all'; }); const viewOptions = [ { label: 'By Server', value: 'servers' }, { label: 'All Tools', value: 'tools' }, - { label: 'Usage Analytics', value: 'analytics' } + { label: 'Usage Analytics', value: 'analytics' }, + { label: 'By Member', value: 'members' } ]; const sourceOptions = [ @@ -301,10 +316,12 @@ >
- + {#if viewMode !== 'members'} + + {/if}
- {#if viewMode !== 'analytics'} + {#if viewMode !== 'analytics' && viewMode !== 'members'}
- {#if !hasServers} -
- -

No tools found

-

- Tool usage will appear here once you start using Claude Code -

-
- {:else if !hasFiltered} -
- -

No matching servers

-

- Try adjusting your search or source filter -

-
+ {#if viewMode === 'members'} + + {:else if viewMode === 'analytics'} + {:else if !hasServers} +
+ +

No tools found

+

+ Tool usage will appear here once you start using Claude Code +

+
+ {:else if !hasFiltered} +
+ +

No matching servers

+

+ Try adjusting your search or source filter +

+
{:else if viewMode === 'tools'} diff --git a/frontend/src/routes/tools/[server_name]/[tool_name]/+page.svelte b/frontend/src/routes/tools/[server_name]/[tool_name]/+page.svelte index 45475615..73924f41 100644 --- a/frontend/src/routes/tools/[server_name]/[tool_name]/+page.svelte +++ b/frontend/src/routes/tools/[server_name]/[tool_name]/+page.svelte @@ -33,7 +33,7 @@ import FiltersBottomSheet from '$lib/components/FiltersBottomSheet.svelte'; import ActiveFilterChips from '$lib/components/ActiveFilterChips.svelte'; import { getServerColorVars, getServerChartHex } from '$lib/utils/mcp'; - import { getProjectNameFromEncoded } from '$lib/utils'; + import { getProjectNameFromEncoded, toSessionWithContext } from '$lib/utils'; import { DEFAULT_FILTERS, DEFAULT_SCOPE_SELECTION, @@ -50,7 +50,6 @@ } from '$lib/search'; import type { StatItem, - McpSessionSummary, SessionWithContext, SearchFilters, SearchScopeSelection @@ -210,27 +209,6 @@ : [] ); - // Convert McpSessionSummary to SessionWithContext - function toSessionWithContext(s: McpSessionSummary): SessionWithContext { - return { - uuid: s.uuid, - slug: s.slug ?? '', - message_count: s.message_count, - start_time: s.start_time ?? '', - end_time: s.end_time ?? undefined, - duration_seconds: s.duration_seconds ?? undefined, - models_used: s.models_used, - subagent_count: s.subagent_count, - has_todos: false, - initial_prompt: s.initial_prompt ?? undefined, - git_branches: s.git_branches, - session_titles: s.session_titles, - project_encoded_name: s.project_encoded_name ?? undefined, - project_path: s.project_encoded_name ?? '', - project_name: s.project_display_name || getProjectNameFromEncoded(s.project_encoded_name ?? '') - }; - } - // Sessions as SessionWithContext for filtering let sessionsAsContext = $derived( detail ? detail.sessions.map(toSessionWithContext) : [] diff --git a/git-radio b/git-radio new file mode 160000 index 00000000..ba3005ff --- /dev/null +++ b/git-radio @@ -0,0 +1 @@ +Subproject commit ba3005ff5e60e954a92b6ef6a7512e539b44fcee diff --git a/package-lock.json b/package-lock.json new file mode 100644 index 00000000..0a00c3d2 --- /dev/null +++ b/package-lock.json @@ -0,0 +1,6 @@ +{ + "name": "syncthing-sync-design", + "lockfileVersion": 3, + "requires": true, + "packages": {} +}