template_press 3.0.0__py3-none-any.whl

template_press/__init__.py

@@ -0,0 +1,24 @@
+# Copyright (c) 2025, Steve Morin
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy of
+# this software and associated documentation files (the "Software"), to deal in
+# the Software without restriction, including without limitation the rights to
+# use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+# the Software, and to permit persons to whom the Software is furnished to do so,
+# subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+# FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+# COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+# IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+# CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+"""template-press — a standalone external-target rebrand utility."""
+
+from importlib import metadata
+
+__version__ = metadata.version("template_press")

template_press/press_cli.py

@@ -0,0 +1,50 @@
+"""press — the template-press command line.
+
+Noun-verb dispatcher (design 0006): `press rebrand --target …` presses an
+identity onto an external target repo. `provision` and `status` are reserved
+for the M6 Provision phase and currently exit 2 with a pointer.
+"""
+
+from __future__ import annotations
+
+import sys
+
+from template_press import __version__
+from template_press.rebrand import cli as rebrand_cli
+
+_RESERVED = {"provision", "status"}
+
+_USAGE = """\
+usage: press <command> [options]
+
+commands:
+  rebrand    press an identity onto a target repo (press rebrand --help)
+  provision  configure a target's features (coming in M6)
+  status     report a target's provisioned state (coming in M6)
+"""
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = list(sys.argv[1:] if argv is None else argv)
+    if args and args[0] in ("-V", "--version"):
+        print(f"press {__version__}")
+        return 0
+    if not args or args[0] in ("-h", "--help"):
+        print(_USAGE)
+        return 0
+    verb, rest = args[0], args[1:]
+    if verb == "rebrand":
+        return rebrand_cli.main(rest)
+    if verb in _RESERVED:
+        print(
+            f"error: '{verb}' is part of the Provision phase and is not "
+            f"available yet (coming in M6).",
+            file=sys.stderr,
+        )
+        return 2
+    print(f"error: unknown command {verb!r}\n\n{_USAGE}", file=sys.stderr)
+    return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

template_press/rebrand/cli.py

@@ -0,0 +1,287 @@
+"""press rebrand — point the press at a target repo (ARCH-01).
+
+Pipeline: preconditions → source identity (config-first, discovery
+validates) → answers → plan → [--dry-run stops here] → apply → regenerate
+lockfiles → VERIFY (no-leak doctor) → receipt. Exit codes: 0 ok, 1 leaks
+found after apply (no receipt), 2 precondition/config error (no writes).
+"""
+
+from __future__ import annotations
+
+import argparse
+import subprocess  # nosec B404 — invokes git/uv on user-supplied targets
+import sys
+import tomllib
+from pathlib import Path
+
+from template_press.rebrand.config import (
+    SOURCE_CONFIG_REL,
+    load_answers,
+    load_source_config,
+    render_source_config,
+)
+from template_press.rebrand.discovery import discover, mismatches
+from template_press.rebrand.doctor import find_leaks, render_leak_report
+from template_press.rebrand.engine import ApplyReport, apply, build_plan
+from template_press.rebrand.identity import Identity, ValidationError, token_occurs
+from template_press.rebrand.receipt import read_receipt, write_receipt
+from template_press.rebrand.rules import DEFAULT_RULES, Rules, load_rules
+
+
+def _fail(msg: str) -> int:
+    print(f"error: {msg}", file=sys.stderr)
+    return 2
+
+
+def check_preconditions(target: Path, force: bool, allow_dirty: bool) -> str | None:
+    """Return an error message, or None when the target is pressable."""
+    if not target.is_dir():
+        return f"target does not exist or is not a directory: {target}"
+    if not (target / ".git").exists():
+        return f"target is not a git repository: {target}"
+    if read_receipt(target) is not None and not force:
+        return (
+            "target already has a press receipt (press/press-receipt.toml); "
+            "re-press with --force"
+        )
+    if not allow_dirty:
+        status = subprocess.run(  # noqa: S603 # nosec B603 B607
+            ["git", "-C", str(target), "status", "--porcelain"],  # noqa: S607
+            check=True,
+            capture_output=True,
+            text=True,
+        )
+        if status.stdout.strip():
+            return "target working tree is dirty; commit/stash or --allow-dirty"
+    return None
+
+
+def _resolve_source(
+    target: Path, override: Path | None, accept_discovery: bool
+) -> tuple[Identity, bool] | int:
+    """Resolve the FROM identity; second element = write source-config later.
+
+    The write is DEFERRED to main() so it happens only after every exit-2
+    gate has passed — keeping "exit 2 means no writes" true by construction.
+    """
+    write_pending = False
+    source = load_source_config(target, override)
+    if source is None:
+        found = discover(target)
+        proposal = {
+            "package_name": found.package_name,
+            "repo_name": found.repo_name,
+            "app_name": found.app_name,
+            "author": found.author,
+            "email": found.email,
+            "owner": found.owner,
+        }
+        unresolved = [k for k, v in proposal.items() if v is None]
+        if unresolved:
+            return _fail(
+                f"no source-config at {SOURCE_CONFIG_REL} and discovery "
+                f"could not resolve: {', '.join(unresolved)}. Write the "
+                f"source-config by hand."
+            )
+        try:
+            candidate = Identity.from_mapping(
+                {k: v for k, v in proposal.items() if v is not None}
+            )
+            candidate.validate()
+        except ValidationError as exc:
+            return _fail(f"discovered identity is invalid: {exc}")
+        source = candidate
+        write_pending = True
+    problems = mismatches(source, discover(target))
+    if problems:
+        print(
+            "error: source-config does not match the target "
+            "(refusing to press — this is the silent-half-rebrand guard):",
+        )
+        for p in problems:
+            print(f"  {p}")
+        return 2
+    return source, write_pending
+
+
+def _collisions(source: Identity, dest: Identity) -> list[str]:
+    """Destination values that embed a CHANGED source token.
+
+    Sequential substitution would re-rewrite such output (old app name
+    becoming the new package name chains two replacements), and the doctor
+    would flag correct output as a leak (press → press_two). Refusing up
+    front with guidance beats either silent corruption or a permanent
+    verification failure.
+    """
+    out: list[str] = []
+    src, dst = source.as_dict(), dest.as_dict()
+    changed = {f: v for f, v in src.items() if v != dst[f]}
+    for dest_field, dest_value in dst.items():
+        for src_field, src_value in changed.items():
+            if token_occurs(dest_value, src_field, src_value):
+                out.append(
+                    f"destination {dest_field}={dest_value!r} contains the "
+                    f"source {src_field} token {src_value!r}"
+                )
+    return out
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="press rebrand", description=__doc__)
+    parser.add_argument("--target", type=Path, required=True)
+    parser.add_argument("--config", type=Path, help="answers TOML (TO identity)")
+    parser.add_argument("--source-config", type=Path, dest="source_config")
+    parser.add_argument("--accept-discovery", action="store_true")
+    parser.add_argument("--dry-run", action="store_true")
+    parser.add_argument("--force", action="store_true")
+    parser.add_argument("--allow-dirty", action="store_true")
+    args = parser.parse_args(argv)
+
+    target = args.target.resolve()
+    try:
+        problem = check_preconditions(target, args.force, args.allow_dirty)
+        if problem is not None:
+            return _fail(problem)
+
+        resolved = _resolve_source(target, args.source_config, args.accept_discovery)
+        if isinstance(resolved, int):
+            return resolved
+        source, write_pending = resolved
+        if write_pending and not args.accept_discovery:
+            print(
+                f"no source-config found at {SOURCE_CONFIG_REL}.\n"
+                f"Discovery proposes:\n\n{render_source_config(source)}\n"
+                f"Save it there (and commit), or re-run with "
+                f"--accept-discovery to write + use it.",
+            )
+            return 2
+
+        if args.config is None:
+            return _fail("--config ANSWERS.toml is required")
+        dest = load_answers(args.config)
+
+        if source == dest:
+            return _fail(
+                "source and destination identities are identical — nothing to press"
+            )
+        collisions = _collisions(source, dest)
+        if collisions:
+            print(
+                "error: destination identity embeds source tokens — a single "
+                "press cannot produce a verifiable result; press in two steps "
+                "via an intermediate identity:",
+                file=sys.stderr,
+            )
+            for c in collisions:
+                print(f"  {c}", file=sys.stderr)
+            return 2
+
+        rules = load_rules(target)
+        plan = build_plan(target, source, dest, rules)
+        print(plan.render())
+        if args.dry_run:
+            if write_pending:
+                print(f"(dry run) would write {SOURCE_CONFIG_REL} from discovery")
+            print("(dry run — nothing applied)")
+            return 0
+        # LAST gate before apply: every exit-2 path (rules/plan included) is
+        # behind us, so the deferred source-config write can no longer be
+        # followed by a "no writes" exit code.
+        if write_pending:
+            path = target / SOURCE_CONFIG_REL
+            path.parent.mkdir(parents=True, exist_ok=True)
+            path.write_text(render_source_config(source), encoding="utf-8")
+            print(f"wrote {SOURCE_CONFIG_REL} from discovery")
+    except (
+        ValidationError,
+        tomllib.TOMLDecodeError,
+        OSError,
+        subprocess.CalledProcessError,
+    ) as exc:
+        return _fail(str(exc))
+    try:
+        return _press(target, source, dest, rules)
+    except (OSError, subprocess.CalledProcessError) as exc:
+        # Exit 2 means "nothing applied"; a mid-apply failure is not that.
+        print(
+            f"error: {exc} — target may be PARTIALLY rewritten; restore with "
+            f"`git -C {target} checkout . && git clean -fd`",
+            file=sys.stderr,
+        )
+        return 1
+
+
+def _regenerate_lockfiles(target: Path, rules: Rules, report: ApplyReport) -> list[str]:
+    """Regenerate listed lockfiles; return the ones that FAILED to regenerate.
+
+    A lockfile is excluded from both rewriting and the doctor scan, so a
+    failed regeneration would leave source-identity content behind invisibly.
+    Callers must treat failures as verification failures (no receipt).
+    """
+    failed: list[str] = []
+    for lockfile in rules.regenerate:
+        if not (target / lockfile).is_file():
+            continue
+        if lockfile == "uv.lock":
+            result = subprocess.run(  # nosec B603 B607
+                ["uv", "lock"],  # noqa: S607
+                cwd=target,
+                capture_output=True,
+                text=True,
+            )
+            if result.returncode == 0:
+                report.regenerated.append(lockfile)
+            else:
+                report.skipped.append(f"regenerate {lockfile} (uv lock failed)")
+                failed.append(lockfile)
+        else:
+            report.skipped.append(f"regenerate {lockfile} (no regenerator)")
+            failed.append(lockfile)
+    return failed
+
+
+def _press(target: Path, source: Identity, dest: Identity, rules: Rules) -> int:
+    report = apply(target, source, dest, rules)
+    failed_locks = _regenerate_lockfiles(target, rules, report)
+    if failed_locks:
+        print(
+            f"error: lockfile regeneration failed for "
+            f"{', '.join(failed_locks)} — the lockfile still carries the old "
+            f"identity and is exempt from the doctor scan, so this rebrand "
+            f"is INCOMPLETE; no receipt written. Regenerate it, then re-run "
+            f"with --force.",
+            file=sys.stderr,
+        )
+        print(report.render(), file=sys.stderr)
+        return 1
+    # Verification never honors target-side REWRITE exclusions (EMP-01):
+    # neither extra_exclude_files nor extra_exclude_dirs can hide content
+    # from the doctor. The only sanctioned exemption is the explicit,
+    # committed verify_ignore list — the deliberate ignore set.
+    doctor_rules = Rules(
+        exclude_dirs=DEFAULT_RULES.exclude_dirs | rules.verify_ignore,
+        exclude_files=DEFAULT_RULES.exclude_files,
+        regenerate=rules.regenerate,
+        verify_ignore=rules.verify_ignore,
+    )
+    leaks = find_leaks(target, source, doctor_rules, dest=dest)
+    if leaks:
+        print(render_leak_report(leaks), file=sys.stderr)
+        print(report.render(), file=sys.stderr)
+        return 1
+    receipt_path = write_receipt(target, source, dest, report)
+    source_config_path = target / SOURCE_CONFIG_REL
+    source_config_path.parent.mkdir(parents=True, exist_ok=True)
+    source_config_path.write_text(render_source_config(dest), encoding="utf-8")
+    print(report.render())
+    if report.skipped:
+        print("skipped (review):")
+        for entry in report.skipped:
+            print(f"  {entry}")
+    print(f"verified: no identity leftovers. receipt: {receipt_path}")
+    print(f"updated {SOURCE_CONFIG_REL} to the new identity")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

template_press/rebrand/config.py

@@ -0,0 +1,67 @@
+"""Load/render the two per-run identity configs (OQ3 two-file model).
+
+source-config (FROM, committed in the target at press/press-source.toml) — the
+authoritative identity being replaced. answers (TO) — the identity being
+pressed in, from an [answers] TOML at a caller-supplied path
+(conventionally named press-answers.toml, but any path works).
+"""
+
+from __future__ import annotations
+
+import tomllib
+from pathlib import Path
+
+from template_press.rebrand.identity import Identity, ValidationError
+
+SOURCE_CONFIG_REL = Path("press") / "press-source.toml"
+
+
+def toml_string(value: str) -> str:
+    """Render a str as a TOML basic-string literal (quoted, escaped)."""
+    out = []
+    for ch in value:
+        if ch in ('"', "\\"):
+            out.append("\\" + ch)
+        elif ch == "\n":
+            out.append("\\n")
+        elif ch == "\t":
+            out.append("\\t")
+        elif ord(ch) < 0x20 or ch == "\x7f":
+            out.append(f"\\u{ord(ch):04X}")
+        else:
+            out.append(ch)
+    return '"' + "".join(out) + '"'
+
+
+def load_identity_toml(path: Path, table: str) -> Identity:
+    data = tomllib.loads(path.read_text(encoding="utf-8"))
+    section = data.get(table)
+    if not isinstance(section, dict):
+        raise ValidationError(f"{path}: missing [{table}] table")
+    identity = Identity.from_mapping(
+        {k: v for k, v in section.items() if isinstance(v, str)}
+    )
+    identity.validate()
+    return identity
+
+
+def load_source_config(target: Path, override: Path | None) -> Identity | None:
+    path = override if override is not None else target / SOURCE_CONFIG_REL
+    if not path.is_file():
+        return None
+    return load_identity_toml(path, "identity")
+
+
+def render_source_config(identity: Identity) -> str:
+    lines = [
+        "# press/press-source.toml — this repo's CURRENT identity (the FROM side",
+        "# of a rebrand). Authoritative: press validates it against the repo",
+        "# and refuses to run on mismatch. Commit this file.",
+        "[identity]",
+    ]
+    lines += [f"{k} = {toml_string(v)}" for k, v in identity.as_dict_prompted().items()]
+    return "\n".join(lines) + "\n"
+
+
+def load_answers(path: Path) -> Identity:
+    return load_identity_toml(path, "answers")

template_press/rebrand/discovery.py

@@ -0,0 +1,109 @@
+"""Discover a target repo's identity — the VALIDATOR, never the authority.
+
+Per OQ3 (decision log 2026-06-15): the committed source-config is the
+authoritative FROM identity; discovery cross-checks it against the target
+(pyproject [project].name / authors, the [project.scripts] key, git origin,
+src-vs-flat layout) and the CLI fails loudly on any mismatch. This replaces
+the silent half-rebrand failure mode (EMPIRICAL R2) with a hard stop.
+"""
+
+from __future__ import annotations
+
+import re
+import subprocess  # nosec B404 — reads git origin of the target
+import tomllib
+from dataclasses import dataclass
+from pathlib import Path
+
+from template_press.rebrand.identity import Identity
+
+_ORIGIN_RE = re.compile(
+    r"^(?:https?://github\.com/|git@github\.com:)"
+    r"(?P<owner>[^/]+)/(?P<repo>[^/]+?)(?:\.git)?/?$"
+)
+
+
+@dataclass(frozen=True)
+class Discovered:
+    package_name: str | None
+    app_name: str | None
+    owner: str | None
+    repo_name: str | None
+    author: str | None
+    email: str | None
+    layout: str | None  # "src" | "flat" | None
+
+
+def _origin(target: Path) -> tuple[str | None, str | None]:
+    result = subprocess.run(  # noqa: S603 # nosec B603 B607
+        ["git", "-C", str(target), "remote", "get-url", "origin"],  # noqa: S607
+        capture_output=True,
+        text=True,
+    )
+    if result.returncode != 0:
+        return None, None
+    m = _ORIGIN_RE.match(result.stdout.strip())
+    return (m["owner"], m["repo"]) if m else (None, None)
+
+
+def discover(target: Path) -> Discovered:
+    package_name = app_name = author = email = None
+    pyproject_path = target / "pyproject.toml"
+    if pyproject_path.is_file():
+        data = tomllib.loads(pyproject_path.read_text(encoding="utf-8"))
+        project = data.get("project", {})
+        raw_name = project.get("name")
+        if isinstance(raw_name, str):
+            package_name = raw_name.replace("-", "_")
+        scripts = project.get("scripts", {})
+        if isinstance(scripts, dict) and scripts:
+            app_name = str(next(iter(scripts)))
+        authors = project.get("authors", [])
+        if authors and isinstance(authors[0], dict):
+            author = authors[0].get("name")
+            email = authors[0].get("email")
+    owner, repo_name = _origin(target)
+    layout: str | None = None
+    if package_name is not None:
+        if (target / "src" / package_name).is_dir():
+            layout = "src"
+        elif (target / package_name).is_dir():
+            layout = "flat"
+    return Discovered(
+        package_name=package_name,
+        app_name=app_name,
+        owner=owner,
+        repo_name=repo_name,
+        author=author,
+        email=email,
+        layout=layout,
+    )
+
+
+def mismatches(source: Identity, found: Discovered) -> list[str]:
+    """Non-empty means the source-config does NOT describe this target."""
+    out: list[str] = []
+    checks: tuple[tuple[str, str | None], ...] = (
+        ("package_name", found.package_name),
+        ("app_name", found.app_name),
+        ("owner", found.owner),
+        ("repo_name", found.repo_name),
+        ("author", found.author),
+        ("email", found.email),
+    )
+    declared = source.as_dict()
+    for field_name, discovered_value in checks:
+        if discovered_value is None:
+            continue  # undiscoverable field — config stands unchallenged
+        if discovered_value != declared[field_name]:
+            out.append(
+                f"{field_name}: source-config says "
+                f"{declared[field_name]!r} but target shows "
+                f"{discovered_value!r}"
+            )
+    if found.package_name is not None and found.layout is None:
+        out.append(
+            f"layout: pyproject declares {found.package_name!r} but neither "
+            f"src/{found.package_name}/ nor {found.package_name}/ exists"
+        )
+    return out

template_press/rebrand/doctor.py

@@ -0,0 +1,97 @@
+"""No-leak verification: the gate between apply() and the receipt (EMP-01).
+
+A rebrand that leaves ANY source-identity token behind — in file content or
+in a path name — is a failed rebrand. The CLI must exit non-zero and write
+no receipt. Port of init_doctor.check_no_identity_leftover, generalized to
+(target, identity, rules) and extended with path-name checking.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from template_press.rebrand.engine import iter_target_files
+from template_press.rebrand.identity import Identity, token_occurs
+from template_press.rebrand.rules import Rules
+
+PATH_FIELDS: tuple[str, ...] = ("package_name", "repo_name", "app_name")
+
+
+@dataclass(frozen=True)
+class Leak:
+    path: str
+    field: str
+    value: str
+    where: str  # "content" | "path" | "unverifiable"
+
+
+def _read_for_scan(path: Path) -> str | None:
+    """Content for scanning; None for binary/symlink; OSError propagates.
+
+    Unlike the engine's lenient reader, the doctor must NOT silently skip an
+    unreadable file — a file it cannot scan is a file it cannot certify.
+    """
+    if path.is_symlink():
+        return None  # content lives outside the target; the name is scanned
+    try:
+        return path.read_text(encoding="utf-8")
+    except UnicodeDecodeError:
+        return None  # binary: the rewrite pass cannot alter it either
+
+
+def find_leaks(
+    target: Path,
+    source: Identity,
+    rules: Rules,
+    dest: Identity | None = None,
+) -> list[Leak]:
+    """Scan for surviving source-identity tokens.
+
+    When ``dest`` is given, only fields that actually CHANGED are scanned:
+    an unchanged field (same author across a rename) is not a leak — its
+    token legitimately remains everywhere. Without ``dest`` all fields are
+    scanned (full-rebrand semantics).
+    """
+    leaks: list[Leak] = []
+    fields = source.as_dict()
+    if dest is not None:
+        dest_fields = dest.as_dict()
+        fields = {k: v for k, v in fields.items() if v != dest_fields[k]}
+    for path in iter_target_files(target, rules):
+        rel = path.relative_to(target)
+        rel_posix = rel.as_posix()
+        try:
+            text = _read_for_scan(path)
+        except OSError:
+            leaks.append(Leak(rel_posix, "io", "unreadable", "unverifiable"))
+            text = None
+        if text is not None:
+            for field_name, value in fields.items():
+                if token_occurs(text, field_name, value):
+                    leaks.append(Leak(rel_posix, field_name, value, "content"))
+        for component in rel.parts:
+            for field_name in PATH_FIELDS:
+                value = fields.get(field_name)
+                if value is not None and token_occurs(component, field_name, value):
+                    leaks.append(Leak(rel_posix, field_name, value, "path"))
+    return leaks
+
+
+def render_leak_report(leaks: list[Leak], limit: int = 20) -> str:
+    lines = [
+        f"error: {len(leaks)} source-identity leftover(s) — rebrand is "
+        f"INCOMPLETE; no receipt written."
+    ]
+    for leak in leaks[:limit]:
+        lines.append(f"  [{leak.where}] {leak.path}: {leak.field}={leak.value!r}")
+    if len(leaks) > limit:
+        lines.append(f"  … and {len(leaks) - limit} more")
+    lines.append(
+        "hint: restore the target (git -C <target> checkout . && git clean "
+        "-fd), fix the root cause (or, for content that is VALID to keep, "
+        "add its directory to BOTH extra_exclude_dirs and verify_ignore in "
+        "<target>/press/press-rules.toml — the first skips rewriting, the second skips "
+        "this scan), then press again."
+    )
+    return "\n".join(lines)