Skip to content

command-sync.md

Latest commit

 

History

History
111 lines (79 loc) · 2.07 KB

command-sync.md

File metadata and controls

111 lines (79 loc) · 2.07 KB

sync

sync applies template-backed repo standards into an existing repository.

It is the write-back counterpart to audit.

Command

oss-bootstrap sync --target <path> [--dry-run] [--json]

v1 scope

In v1, sync only manages template-owned files that are safe to update repeatedly.

Managed files

  • README.md
  • AGENTS.md
  • CHANGELOG.md
  • CONTRIBUTING.md
  • CODE_OF_CONDUCT.md
  • SECURITY.md
  • LICENSE
  • .editorconfig
  • .gitignore
  • .github/workflows/ci.yml
  • .github/workflows/release.yml
  • .github/ISSUE_TEMPLATE/bug_report.md
  • .github/ISSUE_TEMPLATE/feature_request.md
  • .github/PULL_REQUEST_TEMPLATE.md

Not managed in v1

  • src/**
  • test/**
  • package.json
  • tsconfig.json
  • eslint.config.js
  • tsup.config.ts
  • vitest.config.ts

The goal is to fix repo drift without rewriting user product code or build choices.

Metadata inference

sync renders templates using values inferred from the target repo:

  • project name
  • description
  • GitHub username
  • author name
  • author email
  • license
  • package manager

Inference sources:

  1. package.json
  2. repository/homepage/bugs URLs
  3. repo folder name
  4. safe defaults

Write behavior

For each managed file:

  • if missing: create it
  • if present and different: update it
  • if present and identical: skip it

sync must print which files were created, updated, or skipped.

Dry run

With --dry-run, sync performs the same comparison but does not write files.

This is the default review path for existing repos.

Output contract

Human-readable output must include:

  • target path
  • whether this was a dry run
  • created files
  • updated files
  • skipped files

JSON output must include:

  • target
  • dryRun
  • created
  • updated
  • skipped
  • packageManager
  • license

Exit behavior

  • exit 0: command completed
  • exit 1: target could not be analyzed or templates could not be rendered

v1 guardrails

  • never touch src/ or test/
  • never regenerate starter code
  • never overwrite package.json
  • keep sync bounded to template-backed standards first