mc-webui/technotes/UI-Contact-Management-MVP-v2-completed.md

Contact Management MVP v2 - Implementation Complete

Date: 2025-12-29 Status: ✅ Completed (Pending Testing) Branch: dev-2 Related: Builds on UI-Contact-Management-MVP-v1-completed.md

Overview

Successfully implemented Contact Management MVP v2, which adds comprehensive management of existing contacts to the mc-webui interface. Users can now view, search, filter, and delete all contact types (CLI, REP, ROOM, SENS) with a mobile-first responsive UI.

Requirements

Based on specification in docs/UI-Contact-Management-MVP-v2.md:

Functional Requirements

1. Existing Contacts Panel

   • Display all contacts (CLI, REP, ROOM, SENS)
   • Show contact name, type, public key prefix, and path
   • Capacity counter (X / 350) with color-coded warnings
   • Delete functionality with confirmation modal

2. Search and Filter

   • Client-side search by name or public key prefix
   • Filter by contact type (All / CLI / REP / ROOM / SENS)
   • Real-time filtering as user types

3. UX Requirements

   • Mobile-first design (touch-friendly buttons)
   • Loading states (spinner/placeholder)
   • Delete confirmation modal (prevent accidental deletions)
   • Color-coded type badges for visual distinction

Technical Requirements

• Use existing /api/contacts/detailed endpoint pattern
• Proxy to meshcore-bridge via HTTP (no direct meshcli access)
• Vanilla JavaScript (no frameworks)
• Bootstrap 5 for UI components
• All code comments in English

Architecture

New Components

Contact Management v2
├── Backend (mc-webui)
│   ├── app/meshcore/cli.py
│   │   ├── get_all_contacts_detailed()  → Parse meshcli contacts output
│   │   └── delete_contact(selector)      → Execute remove_contact command
│   └── app/routes/api.py
│       ├── GET /api/contacts/detailed    → Fetch all contacts with details
│       └── POST /api/contacts/delete     → Delete contact by selector
│
└── Frontend
    ├── app/templates/contacts.html
    │   ├── Existing Contacts section (search, filter, list, counter)
    │   └── Delete Confirmation Modal
    └── app/static/js/contacts.js
        ├── loadExistingContacts()
        ├── applyFilters()              → Search + type filter
        ├── renderExistingList()
        ├── createExistingContactCard()
        ├── showDeleteModal()
        └── confirmDelete()

Implementation Details

1. Backend - Parser (cli.py::get_all_contacts_detailed())

Challenge: Parse variable-width text table output from meshcli contacts

Input format:

MarWoj|* contacts
KRA C                          REP   d103df18e0ff  Flood
TK Zalesie Test 🦜              REP   df2027d3f2ef  Flood
daniel5120 🔫                   CLI   4563b1621b58  1e93d90faa7c2e49df8f
Szczwany-lis🦊                  CLI   02332896a4a6  Flood
> 263 contacts in device

Parsing strategy:

1. Work backwards from end - Rightmost columns have predictable format
2. Use public_key_prefix as anchor - 12 hex chars are unique and reliable
3. Extract name carefully - Handle spaces, Unicode, special chars
4. Validate extracted data - Check type and hex format

Key code snippet:

def get_all_contacts_detailed() -> Tuple[bool, List[Dict], int, str]:
    """Parse meshcli contacts output into structured data"""

    # Split by whitespace
    parts = stripped.split()
    if len(parts) < 4:
        continue  # Malformed line

    # Extract from right to left
    path_or_mode = parts[-1]
    public_key_prefix = parts[-2]
    type_label = parts[-3]

    # Use public key as anchor to find name
    pubkey_pos = stripped.rfind(public_key_prefix)
    before_pubkey = stripped[:pubkey_pos].rstrip()

    # Type is last word before pubkey
    type_pos = before_pubkey.rfind(type_label)
    if type_pos != -1:
        name = before_pubkey[:type_pos].strip()

    # Validate
    if type_label not in ['CLI', 'REP', 'ROOM', 'SENS']:
        type_label = 'UNKNOWN'

    if not re.match(r'^[a-fA-F0-9]{12}$', public_key_prefix):
        continue  # Skip invalid

    contact = {
        'name': name,
        'public_key_prefix': public_key_prefix.lower(),
        'type_label': type_label,
        'path_or_mode': path_or_mode,
        'raw_line': line  # Preserve for debugging
    }

Edge cases handled:

• ✅ Unicode emoji in names (🦜, 🦊, 🔫, etc.)
• ✅ Polish characters (Łasin, Gdańsk)
• ✅ Spaces in names ("TK Zalesie Test 🦜")
• ✅ Type keyword in name ("CLI Test Node")
• ✅ Variable spacing between columns
• ✅ Hex path vs "Flood" mode
• ✅ Final count line extraction

Testing: Parsed 263 real contacts successfully (mix of CLI, REP, ROOM types with Unicode)

2. Backend - Delete Function (cli.py::delete_contact())

meshcli command: remove_contact <selector>

Implementation:

def delete_contact(selector: str) -> Tuple[bool, str]:
    """
    Delete a contact using meshcli remove_contact command.

    Args:
        selector: Contact selector (name, public_key_prefix, or full public key)
                 Using public_key_prefix is recommended for reliability.
    """
    success, stdout, stderr = _run_command(['remove_contact', selector.strip()])

    if success:
        message = stdout.strip() or f"Contact {selector} removed successfully"
        return True, message
    else:
        error = stderr.strip() or "Failed to remove contact"
        return False, error

Selector options:

• Name (works for most contacts)
• Public key prefix (12 hex chars - recommended)
• Full public key

Recommendation: Always use public_key_prefix for reliability across all contact types.

3. API Endpoints (api.py)

GET /api/contacts/detailed

Returns detailed list of ALL contacts (CLI, REP, ROOM, SENS).

Response:

{
  "success": true,
  "count": 263,
  "limit": 350,
  "contacts": [
    {
      "name": "TK Zalesie Test 🦜",
      "public_key_prefix": "df2027d3f2ef",
      "type_label": "REP",
      "path_or_mode": "Flood",
      "raw_line": "..."
    }
  ]
}

Notes:

• Different from /api/contacts which returns only CLI contact names
• Provides complete metadata needed for UI rendering
• Includes device capacity info (count / limit)

POST /api/contacts/delete

Deletes a contact by selector.

Request:

{
  "selector": "df2027d3f2ef"  // public_key_prefix recommended
}

Response (success):

{
  "success": true,
  "message": "Contact removed successfully"
}

Response (error):

{
  "success": false,
  "error": "Contact not found"
}

4. Frontend - HTML Template (contacts.html)

Added sections:

1. Existing Contacts Section

   • Header with counter badge and refresh button
   • Search input (filter by name or public_key_prefix)
   • Type filter dropdown (All / CLI / REP / ROOM / SENS)
   • Contact cards list (dynamically populated)
   • Loading/empty/error states

2. Delete Confirmation Modal

   • Bootstrap modal with danger theme
   • Shows contact name and public_key_prefix
   • Warns "This action cannot be undone"
   • Cancel / Delete Contact buttons

CSS highlights:

/* Existing contact cards */
.existing-contact-card {
    background-color: white;
    border: 1px solid #dee2e6;
    border-radius: 0.5rem;
    padding: 1rem;
    box-shadow: 0 1px 3px rgba(0, 0, 0, 0.1);
    transition: box-shadow 0.2s;
}

.existing-contact-card:hover {
    box-shadow: 0 2px 8px rgba(0, 0, 0, 0.15);
}

/* Counter badge colors */
.counter-ok { background-color: #28a745; }      /* Green: < 300 */
.counter-warning { background-color: #ffc107; }  /* Yellow: 300-339 */
.counter-alarm { background-color: #dc3545; }    /* Red: >= 340 */

/* Pulse animation for alarm state */
@keyframes pulse {
    0%, 100% { opacity: 1; }
    50% { opacity: 0.7; }
}

.counter-alarm {
    animation: pulse 1.5s infinite;
}

Type badge colors:

• CLI: Blue (bg-primary)
• REP: Green (bg-success)
• ROOM: Cyan (bg-info)
• SENS: Yellow (bg-warning)

5. Frontend - JavaScript Logic (contacts.js)

New state variables:

let existingContacts = [];    // All contacts from API
let filteredContacts = [];     // After applying search/filter
let contactToDelete = null;    // Contact pending deletion

Key functions:

loadExistingContacts()

async function loadExistingContacts() {
    // Show loading state
    const response = await fetch('/api/contacts/detailed');
    const data = await response.json();

    existingContacts = data.contacts || [];
    filteredContacts = [...existingContacts];

    updateCounter(data.count, data.limit);
    applyFilters();  // Render with current filters
}

updateCounter()

function updateCounter(count, limit) {
    counterEl.textContent = `${count} / ${limit}`;

    // Color logic
    if (count >= 340) {
        counterEl.classList.add('counter-alarm');  // Red pulsing
    } else if (count >= 300) {
        counterEl.classList.add('counter-warning'); // Yellow
    } else {
        counterEl.classList.add('counter-ok');       // Green
    }
}

applyFilters()

function applyFilters() {
    const searchTerm = searchInput.value.toLowerCase();
    const selectedType = typeFilter.value;  // ALL, CLI, REP, ROOM, SENS

    filteredContacts = existingContacts.filter(contact => {
        // Type filter
        if (selectedType !== 'ALL' && contact.type_label !== selectedType) {
            return false;
        }

        // Search filter (name or public_key_prefix)
        if (searchTerm) {
            const nameMatch = contact.name.toLowerCase().includes(searchTerm);
            const keyMatch = contact.public_key_prefix.toLowerCase().includes(searchTerm);
            return nameMatch || keyMatch;
        }

        return true;
    });

    renderExistingList(filteredContacts);
}

createExistingContactCard()

function createExistingContactCard(contact, index) {
    const card = document.createElement('div');
    card.className = 'existing-contact-card';

    // Name + Type badge
    const nameDiv = document.createElement('div');
    nameDiv.textContent = contact.name;

    const typeBadge = document.createElement('span');
    typeBadge.className = 'badge type-badge';
    typeBadge.textContent = contact.type_label;

    // Color-code by type
    switch (contact.type_label) {
        case 'CLI':  typeBadge.classList.add('bg-primary'); break;
        case 'REP':  typeBadge.classList.add('bg-success'); break;
        case 'ROOM': typeBadge.classList.add('bg-info'); break;
        case 'SENS': typeBadge.classList.add('bg-warning'); break;
    }

    // Public key
    const keyDiv = document.createElement('div');
    keyDiv.className = 'contact-key';
    keyDiv.textContent = contact.public_key_prefix;

    // Action buttons (Copy Key + Delete)
    const copyBtn = createButton('Copy Key', () => copyContactKey(...));
    const deleteBtn = createButton('Delete', () => showDeleteModal(contact));

    return card;
}

confirmDelete()

async function confirmDelete() {
    const response = await fetch('/api/contacts/delete', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
            selector: contactToDelete.public_key_prefix  // Use prefix for reliability
        })
    });

    if (data.success) {
        showToast(`Deleted: ${contactToDelete.name}`, 'success');
        modal.hide();

        // Reload contacts list
        setTimeout(() => loadExistingContacts(), 500);
    }
}

User Workflows

Workflow 1: View All Contacts

1. User navigates to Contact Management page
2. Page auto-loads existing contacts via GET /api/contacts/detailed
3. Parser extracts structured data from meshcli output
4. Frontend renders contact cards with:
   • Name (bold)
   • Type badge (color-coded)
   • Public key prefix (monospace)
   • Action buttons (Copy, Delete)
5. Counter badge shows "263 / 350" (green)

Workflow 2: Search for a Contact

1. User types "Zalesie" in search box
2. applyFilters() triggered on input event
3. Filters existingContacts by:
   • Name contains "zalesie" (case-insensitive)
   • OR public_key_prefix contains "zalesie"
4. renderExistingList() re-renders with filtered results
5. Results update instantly as user types

Workflow 3: Filter by Type

1. User selects "REP" from type dropdown
2. applyFilters() triggered on change event
3. Filters contacts where type_label === 'REP'
4. Only repeaters shown in list
5. Counter badge still shows total count (not filtered count)

Workflow 4: Delete a Contact

1. User clicks red "Delete" button on contact card
2. showDeleteModal(contact) opens Bootstrap modal
3. Modal displays:
   • Contact name: "TK Zalesie Test 🦜"
   • Public key: "df2027d3f2ef"
   • Warning: "This action cannot be undone"
4. User clicks "Delete Contact" button
5. confirmDelete() sends POST /api/contacts/delete
6. Request body: {"selector": "df2027d3f2ef"}
7. Backend executes meshcli remove_contact df2027d3f2ef
8. On success:
   • Toast notification: "Deleted: TK Zalesie Test 🦜"
   • Modal closes
   • Contact list auto-refreshes after 500ms
9. Counter badge updates to "262 / 350"

Workflow 5: Monitor Capacity

Scenario A: Normal usage (< 300 contacts)

• Counter badge: "150 / 350" (green background)
• No warnings

Scenario B: Approaching limit (300-339 contacts)

• Counter badge: "315 / 350" (yellow background)
• User notices warning color

Scenario C: Critical (≥ 340 contacts)

• Counter badge: "342 / 350" (red background, pulsing animation)
• User should delete some contacts soon

Contacts Parser - Technical Deep Dive

Problem

meshcli contacts outputs a text table with:

• Variable-width columns (not fixed positions)
• Names containing spaces, Unicode emoji, special chars
• No clear delimiters between columns

Solution: Backward Parsing with Anchor

Step 1: Split by whitespace

parts = stripped.split()
# ['TK', 'Zalesie', 'Test', '🦜', 'REP', 'df2027d3f2ef', 'Flood']

Step 2: Extract rightmost columns (predictable)

path_or_mode = parts[-1]          # 'Flood'
public_key_prefix = parts[-2]     # 'df2027d3f2ef'
type_label = parts[-3]             # 'REP'

Step 3: Use public_key_prefix as anchor

pubkey_pos = stripped.rfind('df2027d3f2ef')
# Find position in original string (preserves spacing)

before_pubkey = stripped[:pubkey_pos].rstrip()
# 'TK Zalesie Test 🦜              REP'

Step 4: Extract name (everything before type)

type_pos = before_pubkey.rfind('REP')
name = before_pubkey[:type_pos].strip()
# 'TK Zalesie Test 🦜'

Why this works:

• Public key is unique 12-hex pattern (reliable anchor)
• Working from right to left avoids variable-length name issues
• Preserves Unicode by working with full strings
• Handles spaces in names naturally

Validation

# Type validation
if type_label not in ['CLI', 'REP', 'ROOM', 'SENS']:
    type_label = 'UNKNOWN'

# Public key format validation
if not re.match(r'^[a-fA-F0-9]{12}$', public_key_prefix):
    continue  # Skip malformed line

Count Extraction

# Extract total count from final line
# "> 263 contacts in device"
if line.strip().startswith('>') and 'contacts in device' in line:
    try:
        total_count = int(re.search(r'> (\d+) contacts', line).group(1))
    except:
        pass  # Fallback to len(contacts)

Testing Plan

Manual Testing Checklist

Load contacts:

• Open Contact Management page
• Verify contacts list loads
• Check counter badge shows correct count
• Verify counter color (green/yellow/red based on count)

Search functionality:

• Type contact name in search box
• Verify results filter in real-time
• Type public key prefix
• Verify filtering by key works
• Clear search box
• Verify all contacts reappear

Type filter:

• Select "CLI" from dropdown
• Verify only CLI contacts shown (blue badges)
• Select "REP"
• Verify only REP contacts shown (green badges)
• Select "ROOM"
• Verify only ROOM contacts shown (cyan badges)
• Select "All Types"
• Verify all contacts shown

Delete contact:

• Click "Delete" button on any contact
• Verify modal appears with correct contact info
• Click "Cancel"
• Verify modal closes, contact still in list
• Click "Delete" again
• Click "Delete Contact" button
• Verify success toast appears
• Verify contact removed from list
• Verify counter decrements

Copy functionality:

• Click "Copy Key" button
• Verify toast "Key copied to clipboard"
• Paste in text editor
• Verify correct public_key_prefix pasted

Edge cases:

• Test with 0 contacts (empty state)
• Test with 350 contacts (limit reached)
• Test with contacts containing Unicode
• Test network error (disconnect bridge)
• Test parser with malformed output

Logging

Check logs for delete operations:

# mc-webui container
docker compose logs -f mc-webui | grep -i "delete"

# meshcore-bridge container (where remove_contact executes)
docker compose logs -f meshcore-bridge | grep -i "remove_contact"

Expected log entries:

mc-webui: POST /api/contacts/delete {"selector": "df2027d3f2ef"}
meshcore-bridge: Executing command: ['remove_contact', 'df2027d3f2ef']
meshcore-bridge: Command succeeded: Contact removed

Documentation Updates

README.md

Added new subsection "Existing Contacts" under Contact Management (lines 350-394):

Documented:

• Counter badge (green/yellow/red logic)
• Search functionality
• Type filter options
• Copy public key feature
• Delete workflow with warning
• Capacity monitoring guidelines

Technotes

This file serves as comprehensive technical documentation for v2 implementation.

Git Commit

Branch: dev-2 Commit message (to be created):

feat(ui): Contact Management v2 (existing contacts + delete + counter)

Implements existing contacts management as specified in
docs/UI-Contact-Management-MVP-v2.md:

Backend (mc-webui):
- Added contacts output parser in cli.py::get_all_contacts_detailed()
- Parses meshcli contacts table output (handles Unicode, spaces, variable width)
- Added cli.py::delete_contact(selector) wrapper for remove_contact command
- Added GET /api/contacts/detailed endpoint (all contact types with metadata)
- Added POST /api/contacts/delete endpoint (delete by selector)

Frontend:
- Extended contacts.html with Existing Contacts section
- Added search input (filter by name or public_key_prefix)
- Added type filter dropdown (All / CLI / REP / ROOM / SENS)
- Added contact cards with type badges (color-coded: CLI=blue, REP=green, ROOM=cyan, SENS=yellow)
- Added counter badge with capacity warnings (green < 300, yellow 300-339, red >= 340)
- Added delete confirmation modal (Bootstrap modal, danger theme)
- Implemented contacts.js logic (load, search, filter, delete)

Features:
- Mobile-first design (touch-friendly buttons, responsive cards)
- Real-time search and filtering (client-side)
- Capacity monitoring (X / 350 with color-coded warnings)
- Delete with confirmation (prevents accidental deletions)
- Copy public key to clipboard
- Loading/empty/error states

Parser:
- Best-effort parsing of variable-width text table
- Backward parsing strategy (work from right to left)
- Uses public_key_prefix as anchor for name extraction
- Handles Unicode emoji, Polish chars, spaces in names
- Validates type and hex format
- Tested with 263 real contacts (CLI, REP, ROOM mix)

Documentation:
- Updated README.md with Existing Contacts section
- Created technotes/UI-Contact-Management-MVP-v2-completed.md

Related: UI-Contact-Management-MVP-v1-completed.md

Conclusion

Successfully implemented Contact Management v2, adding comprehensive existing contacts management to mc-webui:

✅ Backend:

• Robust parser for meshcli contacts output
• Handles Unicode, spaces, variable widths
• DELETE endpoint for contact removal

✅ Frontend:

• Mobile-first responsive design
• Real-time search and filtering
• Color-coded counter badge (green/yellow/red)
• Delete confirmation modal
• Type badges for visual distinction

✅ UX:

• Touch-friendly buttons (min-height: 44px)
• Loading/empty/error states
• Toast notifications for feedback
• Clipboard copy functionality

✅ Testing:

• Parsed 263 real contacts successfully
• Handles all contact types (CLI, REP, ROOM, SENS)
• Unicode-safe (emoji, Polish chars)

✅ Documentation:

• README.md updated
• Complete technical notes (this file)

Status: ✅ Implementation complete, ready for user testing

Next Steps: User should test complete workflow (load, search, filter, delete) on dev-2 branch.