Fix status reporting, unify dry-run JSON, support non-git VCS (#514)

Breaking: sync --dry-run --json now emits a flat array of plan
entries instead of a nested workspace-grouped object, matching
the schema of sync --json and status --json.

Fixes:
- Status: repos without upstream showed as "up to date"
  (ahead/behind was 0 instead of None)
- Status: non-git directories were counted as dirty
- Sync: duplicate repos when multiple patterns match the
  same path
- Sync: non-git repos were BLOCKED in dry-run instead of
  UPDATE
- Sync: update_repo return type was GitSync, now includes
  HgSync and SvnSync
- Formatter: missing option flags (-d, -x, -V, --fetch,
  --offline, --verbose, --max-concurrent, --name, --url)

New:
- _HelpTheme protocol for CPython 3.14+ argparse colorization
- SVN and Mercurial tests for update_repo
- Non-git repos excluded from clean/dirty status counts

Docs:
- README and quickstart sync examples updated to use --all

Author: tony

CHANGES

@@ -33,6 +33,78 @@ $ uvx --from 'vcspull' --prerelease allow vcspull
 _Notes on upcoming releases will be added here_
 <!-- END PLACEHOLDER - ADD NEW CHANGELOG ENTRIES BELOW THIS LINE -->
 
+### Breaking changes
+
+#### cli(sync): Route dry-run JSON through OutputFormatter (#514)
+
+JSON dry-run output bypassed `OutputFormatter`, producing a nested
+workspace schema instead of the flat array used by other commands.
+Dry-run JSON and NDJSON now use the same `formatter.emit()` path.
+
+- Dry-run `--json` output is now a flat array of plan entries, matching
+  the schema of `sync --json` and `status --json`
+
+### What's new
+
+#### cli(_formatter): Add `_HelpTheme` protocol for argparse colorization (#514)
+
+Add a typed protocol documenting the CPython 3.14+ argparse theme
+attributes consumed by `VcspullHelpFormatter`. The formatter hooks into
+`_theme` to colorize example command blocks in help text, applying
+distinct colors to program names, subcommands, and options.
+
+### Bug fixes
+
+#### cli(status): Fix false "up to date" and phantom dirty counts (#514)
+
+`check_repo_status` initialized `ahead`/`behind` to `0` instead of
+`None` when no upstream is tracked, causing `_determine_plan_action`
+to report repos as "up to date" when the remote state was actually
+unknown. Additionally, non-git directories (where `clean` is `None`)
+were counted as dirty in the status summary.
+
+- Initialize `ahead`/`behind` as `None` so missing upstream propagates
+  correctly
+- Use identity checks (`is True` / `is False`) instead of truthiness
+  for `clean`, excluding non-git repos from clean/dirty counts
+
+#### cli(sync): Deduplicate repos matched by multiple patterns (#514)
+
+When multiple patterns matched the same repository (e.g. `"myrepo"`
+and `"*"`), the repo was synced multiple times. Repos are now
+deduplicated by path after pattern matching.
+
+#### cli(sync): Report non-git repos as UPDATE in dry-run plan (#514)
+
+`_determine_plan_action` blocked non-git repos in dry-run output even
+though `update_repo` supports SVN and Mercurial via `create_project()`.
+Non-git repos now show `UPDATE` with a "non-git VCS" detail instead of
+`BLOCKED`.
+
+#### cli(sync): Widen `update_repo` return type (#514)
+
+Return type was annotated as `GitSync` but `create_project()` returns
+`GitSync | HgSync | SvnSync`. The annotation now matches the actual
+return type.
+
+#### cli(_formatter): Complete option classification for help colorization (#514)
+
+The help formatter's option sets were missing several flags (`-d`,
+`-x`, `-V`, `--fetch`, `--offline`, `--verbose`, etc.) and
+value-expecting options (`--max-concurrent`, `--name`, `--url`),
+causing tokens following those options to be misclassified in colorized
+help output.
+
+### Documentation
+
+- Update sync examples in README and quickstart to use `--all`, matching
+  the v1.53.0 CLI change (#514)
+
+### Tests
+
+- Add SVN and Mercurial tests for `update_repo` to verify non-git VCS
+  paths (#514)
+
 ## vcspull v1.53.0 (2026-02-08)
 
 ### What's new

README.md

@@ -174,7 +174,7 @@ duplicate roots reported, not rewritten.
 ## Sync your repos
 
 ```console
-$ vcspull sync
+$ vcspull sync --all
 ```
 
 Preview planned work with Terraform-style plan output or emit structured data

docs/quickstart.md

@@ -139,7 +139,7 @@ Now run the command, to pull all the repositories in your
 `.vcspull.yaml` / `.vcspull.json`.
 
 ```console
-$ vcspull sync
+$ vcspull sync --all
 ```
 
 Also, you can sync arbitrary projects, lets assume you have a mercurial
@@ -154,7 +154,7 @@ be any name):
 Use `-f/--file` to specify a config.
 
 ```console
-$ vcspull sync -f .deps.yaml
+$ vcspull sync -f .deps.yaml --all
 ```
 
 You can also use [fnmatch] to pull repositories from your config in

src/vcspull/cli/_formatter.py

@@ -16,6 +16,9 @@
     "--path",
     "--color",
     "--field",
+    "--max-concurrent",
+    "--name",
+    "--url",
 }
 
 OPTIONS_FLAG_ONLY = {
@@ -34,6 +37,7 @@
     "--ndjson",
     "--tree",
     "--detailed",
+    "-d",
     "-i",
     "--ignore-case",
     "-S",
@@ -44,14 +48,57 @@
     "-v",
     "--invert-match",
     "--any",
+    "--exit-on-error",
+    "-x",
+    "--fetch",
+    "--long",
+    "--offline",
+    "--relative-paths",
+    "--show-unchanged",
+    "--summary-only",
+    "--version",
+    "-V",
+    "--no-concurrent",
+    "--sequential",
+    "--no-merge",
+    "--verbose",
 }
 
 
+class _HelpTheme(t.Protocol):
+    """Protocol describing the argparse color theme.
+
+    Python 3.14+ sets ``self._theme`` on ``HelpFormatter`` instances via
+    ``_colorize.get_theme().argparse``.  This protocol documents the
+    attributes consumed by :meth:`VcspullHelpFormatter._fill_text` and
+    :meth:`VcspullHelpFormatter._colorize_example_line`.
+    """
+
+    heading: str
+    reset: str
+    label: str
+    long_option: str
+    short_option: str
+    prog: str
+    action: str
+
+
 class VcspullHelpFormatter(argparse.RawDescriptionHelpFormatter):
-    """Render description blocks while colorizing example sections when possible."""
+    """Extend argparse help colorization to example command sections.
+
+    Python 3.14+ natively colorizes usage and option groups via
+    ``_set_color()`` / ``_colorize.get_theme().argparse``.  This
+    formatter hooks into the same ``_theme`` attribute to additionally
+    colorize the "examples:" blocks in description text, applying
+    distinct colors to program names, subcommands, long/short options,
+    and option values.
+
+    When ``_theme`` is ``None`` (older Python or ``NO_COLOR`` set),
+    ``_fill_text`` falls through to the base class unchanged.
+    """
 
     def _fill_text(self, text: str, width: int, indent: str) -> str:
-        theme = getattr(self, "_theme", None)
+        theme = t.cast("_HelpTheme | None", getattr(self, "_theme", None))
         if not text or theme is None:
             return super()._fill_text(text, width, indent)
 
@@ -105,7 +152,7 @@ def _colorize_example_line(
         self,
         content: str,
         *,
-        theme: t.Any,
+        theme: _HelpTheme,
         expect_value: bool,
     ) -> _ColorizedLine:
         parts: list[str] = []

src/vcspull/cli/_output.py

@@ -132,29 +132,6 @@ class PlanResult:
     entries: list[PlanEntry]
     summary: PlanSummary
 
-    def to_workspace_mapping(self) -> dict[str, list[PlanEntry]]:
-        """Group plan entries by workspace root."""
-        grouped: dict[str, list[PlanEntry]] = {}
-        for entry in self.entries:
-            grouped.setdefault(entry.workspace_root, []).append(entry)
-        return grouped
-
-    def to_json_object(self) -> dict[str, t.Any]:
-        """Return the JSON structure for ``--json`` output."""
-        workspaces: list[dict[str, t.Any]] = []
-        for workspace_root, entries in self.to_workspace_mapping().items():
-            workspaces.append(
-                {
-                    "path": workspace_root,
-                    "operations": [entry.to_payload() for entry in entries],
-                },
-            )
-        return {
-            "format_version": "1",
-            "workspaces": workspaces,
-            "summary": self.summary.to_payload(),
-        }
-
 
 class OutputFormatter:
     """Manages output formatting for different modes (human, JSON, NDJSON)."""

src/vcspull/cli/discover.py

@@ -393,6 +393,7 @@ def discover_repos(
             cwd=cwd,
         )
 
+    # TODO(#discover-non-git): Also scan for .hg and .svn repositories
     if recursive:
         for root, dirs, _ in os.walk(scan_dir):
             if ".git" in dirs:

src/vcspull/cli/status.py

@@ -297,8 +297,8 @@ def check_repo_status(repo: ConfigDict, detailed: bool = False) -> dict[str, t.A
                 if branch_result is not None:
                     status["branch"] = branch_result.stdout.strip()
 
-                ahead = 0
-                behind = 0
+                ahead: int | None = None
+                behind: int | None = None
                 upstream_available = _run_git_command(
                     repo_path,
                     "rev-parse",
@@ -443,9 +443,9 @@ def status_repos(
 
         if status["exists"]:
             summary["exists"] += 1
-            if status["clean"]:
+            if status["clean"] is True:
                 summary["clean"] += 1
-            else:
+            elif status["clean"] is False:
                 summary["dirty"] += 1
         else:
             summary["missing"] += 1

src/vcspull/cli/sync.py

@@ -5,7 +5,6 @@
 import argparse
 import asyncio
 import contextlib
-import json
 import logging
 import os
 import pathlib
@@ -23,6 +22,8 @@
 from libvcs._internal.shortcuts import create_project
 from libvcs._internal.types import VCSLiteral
 from libvcs.sync.git import GitSync
+from libvcs.sync.hg import HgSync
+from libvcs.sync.svn import SvnSync
 from libvcs.url import registry as url_tools
 
 from vcspull import exc
@@ -196,7 +197,7 @@ def _determine_plan_action(
         return PlanAction.CLONE, "missing"
 
     if not status.get("is_git"):
-        return PlanAction.BLOCKED, "not a git repository"
+        return PlanAction.UPDATE, "non-git VCS (detailed plan not available)"
 
     clean_state = status.get("clean")
     if clean_state is False:
@@ -491,14 +492,9 @@ def _emit_plan_output(
         show_unchanged=render_options.show_unchanged,
     )
 
-    if formatter.mode == OutputMode.NDJSON:
-        for entry in display_entries:
-            formatter.emit(entry)
-        formatter.emit(plan.summary)
-        return
-    structured = PlanResult(entries=display_entries, summary=plan.summary)
-    sys.stdout.write(json.dumps(structured.to_json_object(), indent=2) + "\n")
-    sys.stdout.flush()
+    for entry in display_entries:
+        formatter.emit(entry)
+    formatter.emit(plan.summary)
 
 
 def create_sync_subparser(parser: argparse.ArgumentParser) -> argparse.ArgumentParser:
@@ -696,6 +692,16 @@ def sync(
                 unmatched_count += 1
             found_repos.extend(found)
 
+        # Deduplicate repos matched by multiple patterns
+        seen_paths: set[str] = set()
+        deduped: list[ConfigDict] = []
+        for repo in found_repos:
+            key = str(repo.get("path", ""))
+            if key not in seen_paths:
+                seen_paths.add(key)
+                deduped.append(repo)
+        found_repos = deduped
+
     if workspace_root:
         found_repos = filter_by_workspace(found_repos, workspace_root)
 
@@ -924,7 +930,7 @@ def update_repo(
     repo_dict: t.Any,
     progress_callback: ProgressCallback | None = None,
     # repo_dict: Dict[str, Union[str, Dict[str, GitRemote], pathlib.Path]]
-) -> GitSync:
+) -> GitSync | HgSync | SvnSync:
     """Synchronize a single repository."""
     repo_dict = deepcopy(repo_dict)
     if "pip_url" not in repo_dict:
@@ -941,7 +947,7 @@ def update_repo(
 
         repo_dict["vcs"] = vcs
 
-    r = create_project(**repo_dict)  # Creates the repo object
+    r: GitSync | HgSync | SvnSync = create_project(**repo_dict)
     if repo_dict.get("vcs") == "git":
         result = r.update_repo(set_remotes=True)
     else:
@@ -952,5 +958,4 @@ def update_repo(
         repo_name = str(repo_dict.get("name", repo_dict.get("url", "unknown")))
         raise SyncFailedError(repo_name=repo_name, errors=error_messages)
 
-    # TODO: Fix this
-    return r  # type:ignore
+    return r