cli(feat): Modernize CLI with new commands and streamlined flags

why: Align vcspull CLI with modern DevOps tool conventions (Terraform,
Cargo, Ruff, Biome) for improved developer experience and automation
support. Previous CLI lacked introspection commands, dry-run support,
and machine-readable output.

what:
Breaking Changes:
- Remove `vcspull import` command (split into `add` and `discover`)
- Rename `-c/--config` to `-f/--file` across all commands
- Add `-w/--workspace/--workspace-root` (all aliases supported)

New Commands:
- `vcspull list` - List configured repos with --tree, --json, --ndjson
- `vcspull status` - Check repo health (exists, clean/dirty, ahead/behind)
- `vcspull add` - Add single repository with --dry-run support
- `vcspull discover` - Scan filesystem for repos with --dry-run support

New Infrastructure:
- Create _output.py for OutputFormatter (JSON/NDJSON/human modes)
- Create _colors.py with semantic colors and NO_COLOR support
- Add --dry-run/-n flag to sync, add, discover commands
- Add --json/--ndjson structured output to sync, list, status
- Add --color {auto,always,never} flag with NO_COLOR env support

Improvements:
- Split _import.py into add.py (single) and discover.py (bulk)
- Update sync.py with new flags and dry-run preview mode
- Update fmt.py to use -f flag instead of -c
- Wire all new commands in __init__.py with updated examples
- Update README.md with new command examples
- Update CHANGES with breaking changes and migration guide
- Update test_log.py for new module structure

Migration Guide in CHANGES:
- vcspull import NAME URL → vcspull add NAME URL
- vcspull import --scan DIR → vcspull discover DIR
- vcspull sync -c FILE → vcspull sync -f FILE
- vcspull sync --workspace-root PATH → vcspull sync -w PATH

refs: All tests pass (109 tests), mypy clean, ruff clean

Author: tony

CHANGES

@@ -31,7 +31,57 @@ $ pipx install --suffix=@next 'vcspull' --pip-args '\--pre' --force
 
 <!-- Maintainers, insert changes / features for the next release here -->
 
-_Notes on upcoming releases will be added here_
+### BREAKING CHANGES
+
+This release modernizes the vcspull CLI to align with DevOps tool conventions (Terraform, Cargo, Ruff, Biome). **This is a breaking change release**.
+
+#### Command Changes
+
+- **REMOVED**: `vcspull import` command
+  - Use `vcspull add <name> <url>` to add a single repository
+  - Use `vcspull discover <path>` to scan and add multiple repositories
+- **NEW**: `vcspull list` - List configured repositories with optional `--tree`, `--json`, `--ndjson` output
+- **NEW**: `vcspull status` - Check repository health (ahead/behind, clean/dirty)
+- **NEW**: `vcspull add` - Add a single repository (replaces `vcspull import <name> <url>`)
+- **NEW**: `vcspull discover` - Scan filesystem for repositories (replaces `vcspull import --scan`)
+
+#### Flag Changes
+
+- **RENAMED**: `-c/--config` → `-f/--file` (all commands)
+- **NEW**: `-w/--workspace/--workspace-root` - All three aliases supported for workspace root
+- **NEW**: `--dry-run/-n` - Preview changes without making modifications (sync, add, discover)
+- **NEW**: `--json/--ndjson` - Machine-readable output for automation (sync, list, status)
+- **NEW**: `--color {auto,always,never}` - Control color output
+
+#### Migration Guide
+
+```bash
+# Old → New
+vcspull import NAME URL              → vcspull add NAME URL
+vcspull import --scan DIR            → vcspull discover DIR
+vcspull sync -c FILE                 → vcspull sync -f FILE
+vcspull sync --workspace-root PATH   → vcspull sync -w PATH  # (or keep long form)
+vcspull fmt -c FILE                  → vcspull fmt -f FILE
+```
+
+### Features
+
+#### Developer Experience Improvements
+
+- All commands now support `--dry-run` for safe previewing of changes
+- Structured output (`--json`, `--ndjson`) enables CI/CD integration
+- Semantic colors with `NO_COLOR` environment variable support
+- Short `-w` flag for workspace root reduces typing
+- Consistent flag naming across all commands
+
+#### New Introspection Commands
+
+- `vcspull list` - View all configured repositories
+  - `--tree` mode groups by workspace root
+  - `--json/--ndjson` for programmatic access
+- `vcspull status` - Check repository health
+  - Shows which repos exist, are dirty, or missing
+  - `--detailed` mode for additional information
 
 ## vcspull v1.38.0 (2025-10-18)
 

README.md

@@ -68,7 +68,7 @@ You can test the unpublished version of vcspull before its released.
 ## Configuration
 
 Add your repos to `~/.vcspull.yaml`. You can edit the file by hand or let
-`vcspull import` create entries for you.
+`vcspull add` or `vcspull discover` create entries for you.
 
 ```yaml
 ~/code/:
@@ -91,31 +91,32 @@ more [configuration](https://vcspull.git-pull.com/configuration.html))
 be used as a declarative manifest to clone your repos consistently across
 machines. Subsequent syncs of initialized repos will fetch the latest commits.
 
-### Import repositories from the CLI
+### Add repositories from the CLI
 
-Register an existing remote without touching YAML manually:
+Register a single repository without touching YAML manually:
 
 ```console
-$ vcspull import my-lib https://github.com/example/my-lib.git --path ~/code/my-lib
+$ vcspull add my-lib https://github.com/example/my-lib.git --path ~/code/my-lib
 ```
 
 - Omit `--path` to default the entry under `./`.
-- Use `--workspace-root` when you want to force a specific workspace root, e.g.
-  `--workspace-root ~/projects/libs`.
-- Pass `-c/--config` to import into an alternate YAML file.
+- Use `-w/--workspace` when you want to force a specific workspace root, e.g.
+  `-w ~/projects/libs`.
+- Pass `-f/--file` to add to an alternate YAML file.
+- Use `--dry-run` to preview changes before writing.
 - Follow with `vcspull sync my-lib` to clone or update the working tree after registration.
 
-### Scan local checkouts and import en masse
+### Discover local checkouts and add en masse
 
 Have a directory tree full of cloned Git repositories? Scan and append them to
 your configuration:
 
 ```console
-$ vcspull import --scan ~/code --recursive
+$ vcspull discover ~/code --recursive
 ```
 
 The scan shows each repository before import unless you opt into `--yes`. Add
-`--workspace-root ~/code/` to pin the resulting workspace root or `--config` to
+`-w ~/code/` to pin the resulting workspace root or `-f` to
 write somewhere other than the default `~/.vcspull.yaml`.
 
 ### Normalize configuration files
@@ -124,7 +125,7 @@ After importing or editing by hand, run the formatter to tidy up keys and keep
 entries sorted:
 
 ```console
-$ vcspull fmt --config ~/.vcspull.yaml --write
+$ vcspull fmt -f ~/.vcspull.yaml --write
 ```
 
 Use `vcspull fmt --all --write` to format every YAML file that vcspull can
@@ -149,7 +150,7 @@ or svn project with a git dependency:
 Clone / update repos via config file:
 
 ```console
-$ vcspull sync -c external_deps.yaml '*'
+$ vcspull sync -f external_deps.yaml '*'
 ```
 
 See the [Quickstart](https://vcspull.git-pull.com/quickstart.html) for