Skip to content

Add dry-run and check modes to dev-tools sync #62

@coisa

Description

@coisa

Objective

Add --dry-run and --check modes to dev-tools:sync so maintainers can inspect pending synchronization changes before writing files, and optionally confirm replacements interactively in terminal sessions.

Current Limitation

dev-tools:sync performs file and repository mutations directly. Maintainers of consumer repositories need a safe way to preview changes, identify stale managed files, and use a CI-friendly mode that fails when sync-managed files are drifted.

Proposed Work

Add three execution modes:

  • --dry-run: report the changes sync would make without writing files or running mutating Git operations.
  • --check: report whether the repository is in sync and return a non-zero exit code when changes would be required.
  • --interactive: when running in an interactive terminal, show detected drift and ask whether each managed file should be replaced.

The default dev-tools:sync behavior should remain non-interactive. Prompting should only happen when --interactive is explicitly requested and the input is interactive.

Scope

  • Cover all existing sync phases where practical: Composer metadata, workflow stubs, .editorconfig, Dependabot, wiki setup, .gitignore, .gitattributes, skills, license, and Git hooks.
  • Ensure --dry-run does not write files, create symlinks, initialize hooks, or add submodules.
  • Ensure --check is suitable for CI and exits non-zero on detected drift or missing managed assets.
  • Reuse or prepare drift/status logic from sync phases rather than shelling out blindly.
  • Surface drift details in output, including affected phase, path, and text diffs where available.
  • Keep --interactive optional and TTY-aware so Composer hooks and CI runs do not block on prompts.

Non-goals

  • Implementing selective --only or --skip sync phases.
  • Changing default sync behavior.
  • Forcing prompts during Composer hooks, CI, or non-interactive sessions.
  • Guaranteeing dry-run support for unsupported external tools in the first pass; unsupported phases should report that clearly.

Acceptance Criteria

Delivery Criteria

  • dev-tools:sync --dry-run reports planned changes without modifying the working tree.
  • dev-tools:sync --check exits 0 when no sync changes are needed.
  • dev-tools:sync --check exits non-zero when managed files are missing or drifted.
  • dev-tools:sync --interactive prompts before replacing drifted managed files when input is interactive.
  • Dry-run/check output identifies the affected sync phase and path.
  • Drift output includes text diffs when available and clear fallbacks for non-diffable files.
  • Tests cover dry-run no-write behavior, check-mode exit codes, and interactive replace decisions.

Architectural / Isolation Criteria

  • Sync phases expose inspectable planned actions before mutation.
  • SyncCommand remains orchestration-focused.
  • The implementation keeps output deterministic for CI logs and tests outside explicit interactive mode.

Metadata

Metadata

Assignees

Labels

enhancementNew feature or request

Type

No type

Projects

Status

Released

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions