myworkspace/Linkding Browser Extension/LinkdingSync/docs/phase0-plan.md

# Phase 0: Testing & Server Behavior Validation

## Overview

This document outlines the complete Phase 0 plan for testing Linkding server behavior before redesigning the LinkdingSync extension. The goal is to gather critical information about:

1. **API Key Isolation**: Do API keys provide bookmark isolation, or is the user account the only isolation boundary?
2. **Conflict Resolution**: How does Linkding handle same URL in different contexts (paths, notes)?
3. **Delete Behavior**: Does deletion via one API key affect bookmarks created by other keys?
4. **Bundle Tag Filtering**: How do bundles act as filters for bookmark queries?

## Current Status

| Item | Status |
|------|--------|
| Review extension codebase | ✅ Complete |
| Review Linkding source code | ✅ Complete |
| Analyze TODOs.txt findings | ✅ Complete |
| Create test scenarios doc | ✅ Complete |
| Create test runner script | ✅ Complete |
| **Execute tests** | ⏳ Pending |
| **Finalize design** | ⏳ Pending |

---

## Prerequisites

### 1. Create Test User Accounts

You need to create **2 user accounts** on your Linkding instance:

```
user_work      - For work-related bookmarks
user_personal  - For personal bookmarks
```

### 2. Create API Keys

For each user, create **at least 2 API keys** (one per bundle):

| User | Key Purpose | Example Name |
|------|-------------|--------------|
| user_work | Work bundle access | `user_work_key_1` |
| user_work | Work bundle access | `user_work_key_2` |
| user_personal | Personal bundle access | `user_personal_key_1` |
| user_personal | Personal bundle access | `user_personal_key_2` |

**How to create API keys**:
1. Go to Linkding settings → Advanced
2. Click "Create new token"
3. Give it a descriptive name (e.g., "work-bundle-1")
4. Copy the generated key (it won't be shown again)

### 3. Create Bundles

Create bundles for filtering:

| Bundle Name | Purpose |
|-------------|---------|
| `work` | Filter work bookmarks |
| `personal` | Filter personal bookmarks |

### 4. Firefox Configuration

#### Option A: Single Firefox Profile with Multiple API Keys

Create a Firefox profile that can hold multiple API keys for testing. This allows:
- Easy switching between work/personal contexts
- Running automated tests via DevTools console

#### Option B: Separate Firefox Profiles

Create two separate Firefox profiles:
- `work-profile` - Configured with work API key
- `personal-profile` - Configured with personal API key

This is simpler but requires switching profiles between tests.

---

## Test Execution Instructions

### Step 1: Load Test Runner

1. Open Firefox
2. Navigate to your Linkding settings page (any page works)
3. Open DevTools (press `F12`)
4. Go to the **Console** tab
5. Copy the entire contents of `test-runner.js`
6. Paste into the console (Ctrl+Shift+V)
7. Press Enter

You should see:
```
LinkdingSync Test Runner loaded successfully
```

### Step 2: Configure Credentials

In the console, modify the `CONFIG` object:

```javascript
const CONFIG = {
  serverUrl: 'https://links.blabber1565.com',
  workApiKey: 'your_work_api_key_here',      // Paste API key
  personalApiKey: 'your_personal_api_key_here',
  workUser: 'user_work',
  personalUser: 'user_personal',
  workBundle: 'work',
  personalBundle: 'personal',
  cleanupAfterTests: true
};
```

**Security Note**: 
- API keys are stored in the Firefox session (cleared when Firefox closes)
- Consider creating a separate `.creds.txt` file for manual reference if needed

### Step 3: Run Tests

Execute the test suite:

```javascript
runTestSuite()
```

This will run all 6 test scenarios and display results in the console.

### Step 4: Analyze Results

Each test will output:
- Setup information
- API responses
- **Result analysis** with ✓ or ✗ indicators

Example output:
```
=== Scenario 1: Same URL, Different API Keys, Same User ===
  ✓ Created: ID=123, URL=https://example.com
  ✓ Created: ID=456, URL=https://example.com

Results:
  Bookmark 1 ID: 123
  Bookmark 2 ID: 456
  ✅ RESULT: Different bookmark IDs - API keys provide isolation
```

### Step 5: Cleanup (Optional)

After tests complete, clean up test bookmarks:

```javascript
cleanup()
```

Or disable automatic cleanup in CONFIG:

```javascript
cleanupAfterTests: false
```

---

## Expected Test Outcomes

### Test 1: API Key Isolation
**Possible Results:**
- **Same ID**: API keys don't provide isolation - user account is the only boundary
- **Different IDs**: API keys provide isolation within same user

**Decision Impact**:
- If keys don't isolate → Use separate users for work/personal isolation
- If keys do isolate → Can use same user with different API keys

### Test 2: Cross-User Visibility
**Possible Results:**
- **User B sees User A's bookmarks**: Sharing enabled or same underlying user
- **User B cannot see User A's bookmarks**: Proper isolation

**Decision Impact**:
- Need separate users with sharing disabled for true isolation

### Test 3: Path Conflict Resolution
**Possible Results:**
- **Same ID**: Server merges by URL, last-write-wins for path/notes
- **Different IDs**: Server creates separate bookmarks

**Decision Impact**:
- If merges → Need path merge strategy (keep both, prompt user, etc.)
- If separate → Can use duplicate bookmarks for different contexts

### Test 4: Title/Description Merge
**Possible Results:**
- **Last-write-wins**: Most recent update wins
- **Merge**: Both values combined somehow
- **No conflict**: Different titles preserved

**Decision Impact**:
- Determine merge strategy for conflict resolution

### Test 5: Delete Propagation
**Possible Results:**
- **Propagates**: Deleting via one key deletes all
- **Doesn't propagate**: Separate bookmarks per key

**Decision Impact:**
- Aligns with Test 3 results

### Test 6: Bundle Tag Filtering
**Possible Results:**
- **Works**: Tags filter bookmarks by tag
- **Doesn't work**: Tags don't provide isolation

**Decision Impact:**
- Bundle tags can provide logical separation

---

## Test Results Analysis Template

After running tests, document results in `docs/test-results.md`:

```markdown
# Test Results

## Test 1: API Key Isolation
- **Result**: [same/different] IDs
- **Conclusion**: API keys [do/don't] provide isolation
- **Implication**: Need [separate users OR same user strategy]

## Test 2: Cross-User Visibility  
- **Result**: User B [can/cannot] see User A's bookmarks
- **Conclusion**: Sharing is [enabled/disabled]
- **Implication**: [Use different users or different settings]

## Test 3: Path Conflict Resolution
- **Result**: [same/different] IDs
- **Conclusion**: Server [merges/creates separate] bookmarks
- **Implication**: [Merge paths OR keep separate]

## Test 4: Title/Description Conflict
- **Result**: [last-write-wins/merge/no-conflict]
- **Conclusion**: Server [uses last-write/merges/doesn't conflict]
- **Implication**: [Strategy for conflict resolution]

## Test 5: Delete Propagation
- **Result**: Delete [propagated/didn't propagate]
- **Conclusion**: Deletion [affects all OR affects specific]
- **Implication**: [Delete strategy]

## Test 6: Bundle Tag Filtering
- **Result**: Bundle tags [work/don't work]
- **Conclusion**: Tags [provide/isolate] bookmarks
- **Implication**: [Use tags OR use users]

## Final Strategy
Based on results:
- [User isolation approach]
- [Conflict resolution strategy]
- [Sync behavior]
```

---

## Next Steps After Phase 0

Once tests complete:

1. **Analyze Results**: Review test outputs and document in `test-results.md`
2. **Finalize Design**: Create new `design.md` with confirmed behaviors
3. **Redesign Extension**: Implement new architecture based on test findings
4. **Create Tests**: Write unit tests in `tests/` directory
5. **Implement Features**: Add UI improvements and scheduled sync
6. **Document**: Update README.md and API docs

---

## Files Created

| File | Purpose |
|------|---------|
| `docs/phase0-test-scenarios.md` | Detailed test scenarios |
| `test-runner.js` | Automated test execution script |
| `docs/phase0-plan.md` | This document |

---

## Questions for You

Before you create the test accounts and run tests:

1. **Firefox Setup**: Which option do you prefer?
   - Single profile with multiple API keys (more complex, more flexible)
   - Separate profiles (simpler, less flexible)

2. **API Key Count**: Do you want to create:
   - 2 API keys per user (minimal for testing)
   - 4 API keys per user (more scenarios)

3. **Bundles**: Should we create:
   - 2 bundles (`work`, `personal`)
   - 4 bundles (more granular)

4. **Test Execution**: Will you run:
   - All tests at once (`runTestSuite()`)
   - Individual tests as you discover issues

Let me know, and I can adjust the test runner accordingly. Once you're ready to create the test accounts, just let me know and I'll provide final instructions.