Contract home directory paths in JSON/NDJSON output

[tony]

Contract home directory paths in JSON/NDJSON output

Summary

This PR makes JSON/NDJSON output consistent by contracting home directory paths to use tilde notation (~/) across all commands (list, status, sync).

⚠️ Breaking Change: Automation consuming JSON/NDJSON output may need updates.

Problem

JSON/NDJSON output had an inconsistency where workspace_root used tilde notation but path used absolute paths:

{
  "name": "flask",
  "path": "/home/username/code/flask",     // ❌ Absolute path
  "workspace_root": "~/code/"               // ✅ Tilde notation
}

This created three issues:

1. Inconsistency: Same type of data (filesystem paths) represented differently
2. Privacy: Exposes usernames in JSON output
3. Portability: Absolute paths don't work when configs are shared between machines

Solution

Apply contract_user_home() to all path fields in JSON/NDJSON output:

{
  "name": "flask",
  "path": "~/code/flask",                   // ✅ Tilde notation
  "workspace_root": "~/code/"               // ✅ Tilde notation
}

Changes

Modified path fields in:

• vcspull list: Both flat and tree output modes
• vcspull status: Repository status output
• vcspull sync: Both plan and sync event output

Important: Human-readable output unchanged. Only JSON/NDJSON affected.

Benefits

1. Consistency: All path fields now use the same notation
2. Privacy: No username exposure in JSON output
3. Portability: Configs and output work across different machines/users
4. Alignment: Code behavior now matches documentation (which already showed ~/ in examples)

Breaking Change Details

Impact

Automation that:

• Parses path fields from JSON/NDJSON output
• Expects absolute paths
• Doesn't handle tilde expansion

Will need to expand tildes to absolute paths before use.

Migration Guide

Most tools handle tilde expansion automatically. If needed:

Python:

import pathlib
expanded = pathlib.Path(path).expanduser()

Bash:

expanded_path="${path/#\~/$HOME}"

JavaScript:

const expanded = path.replace(/^~/, process.env.HOME);

Test Coverage

Added 6 comprehensive parametrized tests using project's NamedTuple pattern:

tests/cli/test_list.py

• test_list_repos_path_contraction with 3 fixtures:
  • JSON output path contraction
  • NDJSON output path contraction
  • Tree mode JSON path contraction

tests/cli/test_status.py

• test_status_repos_path_contraction with 3 fixtures:
  • JSON output path contraction
  • NDJSON output path contraction
  • Detailed mode JSON path contraction

All tests verify:

• Paths start with ~/
• Paths don't contain absolute home directory
• workspace_root consistency maintained

Examples

vcspull list --json

Before:

[
  {
    "name": "tiktoken",
    "url": "git+https://github.com/openai/tiktoken.git",
    "path": "/home/d/study/ai/tiktoken",
    "workspace_root": "~/study/ai/"
  }
]

After:

[
  {
    "name": "tiktoken",
    "url": "git+https://github.com/openai/tiktoken.git",
    "path": "~/study/ai/tiktoken",
    "workspace_root": "~/study/ai/"
  }
]

vcspull status --json

Before:

[
  {
    "reason": "status",
    "name": "flask",
    "path": "/home/username/code/flask",
    "workspace_root": "~/code/",
    "exists": true
  }
]

After:

[
  {
    "reason": "status",
    "name": "flask",
    "path": "~/code/flask",
    "workspace_root": "~/code/",
    "exists": true
  }
]

vcspull sync --dry-run --json

Before:

[
  {
    "reason": "plan",
    "name": "flask",
    "path": "/home/username/code/flask",
    "workspace_root": "~/code/",
    "action": "clone"
  }
]

After:

[
  {
    "reason": "plan",
    "name": "flask",
    "path": "~/code/flask",
    "workspace_root": "~/code/",
    "action": "clone"
  }
]

Implementation Details

Modified Functions

1. src/vcspull/cli/list.py (2 locations)

   • Line 169: Flat output mode
   • Line 220: Tree output mode

2. src/vcspull/cli/status.py (1 location)

   • Line 266: Status output

3. src/vcspull/cli/sync.py (2 locations)

   • Line 267: Plan entry creation
   • Line 727: Sync event output

Test Structure

Using project's NamedTuple parametrization pattern:

class PathContractionFixture(t.NamedTuple):
    test_id: str
    output_json: bool
    output_ndjson: bool
    tree: bool

PATH_CONTRACTION_FIXTURES: list[PathContractionFixture] = [
    PathContractionFixture(
        test_id="json-output-contracts-paths",
        output_json=True,
        output_ndjson=False,
        tree=False,
    ),
    # ... more fixtures
]

@pytest.mark.parametrize(
    list(PathContractionFixture._fields),
    PATH_CONTRACTION_FIXTURES,
    ids=[fixture.test_id for fixture in PATH_CONTRACTION_FIXTURES],
)
def test_list_repos_path_contraction(...):
    # Test implementation

Documentation

Documentation already correct - examples in docs/cli/*.md were updated in PR #473 to show tilde notation proactively. This PR makes the actual code behavior match what the docs promised.

Testing

All 208 tests pass:

$ uv run pytest
============================= 208 passed in 4.79s ==============================

Verified output:

$ uv run vcspull list --json | jq '.[0].path'
"~/study/ai/tiktoken"

Commits

1. 4de9970 - cli(feat[privacy]): Contract home paths in JSON/NDJSON output
2. 2c4e749 - cli(test[privacy]): Add comprehensive tests for contracted JSON paths
3. 52da2d7 - docs(CHANGES): Document path contraction as breaking change for v1.41.x

Checklist

• Source code changes implemented
• Comprehensive test coverage added (6 parametrized tests)
• All tests passing (208/208)
• CHANGES file updated with breaking change notice
• Documentation verified (already correct from PR cli(feat[introspection]): Contract $HOME to ~/ in human-readable output #473)
• Examples tested manually
• Migration guide provided

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 79.10%. Comparing base (639c049) to head (52da2d7).
⚠️ Report is 4 commits behind head on master.

Additional details and impacted files

@@           Coverage Diff           @@
##           master     #475   +/-   ##
=======================================
  Coverage   79.10%   79.10%           
=======================================
  Files          14       14           
  Lines        1527     1527           
  Branches      321      321           
=======================================
  Hits         1208     1208           
  Misses        201      201           
  Partials      118      118           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.