template-press

Press a new identity onto an existing repository. template-press is a standalone command-line utility: you point it at a target repo, it discovers and validates that repo's current identity, rewrites every occurrence to a new identity, and — only after verifying that none of the old identity survives — writes a receipt. A wrong or partial run fails loudly instead of silently corrupting the target.

It is not a project template you fork; it is a tool you run against other repos, one at a time. The rebrand engine is pure standard library, so the installed package has zero runtime dependencies.

Install

uvx --from template-press press --help   # run without installing
# or
pip install template-press

Usage

# preview the plan (writes nothing)
press rebrand --target ../my-repo --config press-answers.toml --dry-run

# apply, verify, and write a receipt
press rebrand --target ../my-repo --config press-answers.toml

press-answers.toml describes the destination identity:

[answers]
package_name = "new_pkg"
repo_name    = "new-repo"
app_name     = "newcli"
author       = "Jane Dev"
email        = "jane@example.com"
owner        = "janedev"

Keep your filled-in press-answers.toml out of the target (it is transient operator input, not committed state). A repo may commit a press/press-answers.example.toml placeholder to advertise the field shape — copy it, fill it, and pass it via --config. It has the same [answers] fields shown above.

The target's current identity is read from a committed <target>/press/press-source.toml. On a first run, --dry-run prints a proposed source-config from discovery; review it and re-run with --accept-discovery to write and use it.

How it stays safe

• Config-first identity, discovery as a guard. The committed source-config is authoritative; discovery cross-checks it against the target and refuses to run on a mismatch, so the press never rewrites the wrong repo.
• Verify-then-mark. After rewriting, a no-leak scan confirms no source identity remains. Any leftover ⇒ exit 1 and no receipt — a partial rebrand is a loud failure, not a false success.
• Boundary-safe replacement. Short tokens (press, an owner like go) match only at word boundaries, so ordinary prose (compress, ongoing) is never touched.

Exit codes

The exit code is the contract:

--dry-run exits 0 after printing the plan without touching the target (no receipt). It warns on a statically unsupported host; target-filesystem capability is probed only during real apply. Forced apply uses a guarded non-atomic fallback and warns about its destination-overwrite race.

Documentation

• Full docs: https://template-press.readthedocs.io/
• Design contract: docs/design/0006-external-target-model.md
• Agent runbooks: press-target (drive a press) and rebrand-matrix (the R1/R2/R3 acceptance matrix)

Contributing

See AGENTS.md for the canonical toolchain and verification flow (just setup → just check → commit) and .github/CONTRIBUTING.md for the human contributor guide.

License

MIT — see LICENSE.