syncade 0.6.2__py3-none-any.whl

syncade/cli/preflight_paths.py

@@ -0,0 +1,90 @@
+"""Refuse unusable write targets BEFORE auto-init mutates the operator's directory.
+
+Both directories checked here are created later — ``worktree_base`` by the loop's worktree
+provisioning, ``.syncade/runs/`` by the run-dir mkdir. Left alone, an unusable one surfaces
+as a ``WorktreeError``/exit-60 or an uncaught ``PermissionError`` *after* the baseline commit,
+so a refused run would have created a repository on its way to failing. Checking here keeps
+that refusal free.
+
+Split out of ``cli/__init__.py``: it is one self-contained concern (*can syncade write where
+it is about to write?*) with one output, and the dogfood panel called out `_run` for holding
+validation, mutation, dispatch and cleanup at once.
+
+``exists()`` follows symlinks and reports a DANGLING link as absent, which would read as
+"absent but creatable" and let a broken link silently become a creation target. Every check
+below tests ``is_symlink()`` first for that reason.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+from syncade.exit_codes import CONFIG_ERROR, WORKTREE_ERROR
+
+
+def _unusable(path: Path, *, need_read: bool = False) -> str | None:
+    """Why ``path`` cannot be written to, as a message SUFFIX, or ``None`` if it can.
+
+    The suffix carries its own separator so callers concatenate rather than choosing one.
+    """
+    if path.is_symlink() and not path.exists():
+        return " is a dangling symlink"
+    if path.exists() and not path.is_dir():
+        return " exists but is not a directory"
+    if path.is_dir():
+        if need_read and not os.access(path, os.R_OK | os.W_OK | os.X_OK):
+            return ": directory is not readable and writable"
+        if not need_read and not os.access(path, os.W_OK | os.X_OK):
+            return ": directory is not writable"
+    return None
+
+
+def check_write_targets(worktree_base: Path, repo_root: Path) -> int | None:
+    """Return an exit code if a write target is unusable, else ``None``.
+
+    ``worktree_base`` problems are CONFIG errors (the operator configured the path);
+    ``.syncade`` problems are environment errors, matching where each value comes from.
+    """
+    reason = _unusable(worktree_base)
+    if reason is not None:
+        print(
+            f"[syncade] config error: worktree-base {str(worktree_base)!r}{reason}",
+            file=sys.stderr,
+        )
+        return CONFIG_ERROR
+
+    # worktree_base is created on demand, so an absent one shifts the question to its parent.
+    if not worktree_base.exists():
+        parent = worktree_base.parent
+        if not parent.exists():
+            print(
+                f"[syncade] config error: worktree-base {str(worktree_base)!r}: "
+                f"parent directory {str(parent)!r} does not exist",
+                file=sys.stderr,
+            )
+            return CONFIG_ERROR
+        if not parent.is_dir():
+            print(
+                f"[syncade] config error: worktree-base {str(worktree_base)!r}: "
+                f"parent {str(parent)!r} exists but is not a directory",
+                file=sys.stderr,
+            )
+            return CONFIG_ERROR
+        if not os.access(parent, os.W_OK | os.X_OK):
+            print(
+                f"[syncade] config error: worktree-base {str(worktree_base)!r}: "
+                f"parent directory {str(parent)!r} is not writable",
+                file=sys.stderr,
+            )
+            return CONFIG_ERROR
+
+    syncade_dir = repo_root / ".syncade"
+    # runs/ needs READ too: resume and the run-id collision loop enumerate it.
+    for path, need_read in ((syncade_dir, False), (syncade_dir / "runs", True)):
+        reason = _unusable(path, need_read=need_read)
+        if reason is not None:
+            print(f"[syncade] error: {str(path)!r}{reason}", file=sys.stderr)
+            return WORKTREE_ERROR
+    return None

syncade/cli/resolve.py

@@ -0,0 +1,116 @@
+"""Diff-base / spec-source resolution helpers for the CLI.
+
+These turn a ``--scope`` token or an ``--openspec`` request into the concrete
+inputs the loop consumes, printing an operator-facing message and returning
+``None`` when the request can't be resolved.
+"""
+
+from __future__ import annotations
+
+import sys
+from collections.abc import Iterable
+from pathlib import Path
+
+from syncade.logging import Logger
+
+
+def _current_branch(repo_root: Path) -> str | None:
+    """The current branch name via ``git rev-parse --abbrev-ref HEAD``, or
+    ``None`` for detached HEAD / failure (used to key the last-reviewed lookup)."""
+    from syncade.process import run_subprocess
+
+    try:
+        result = run_subprocess(
+            ["git", "rev-parse", "--abbrev-ref", "HEAD"], cwd=repo_root, timeout=10.0
+        )
+    except Exception:
+        return None
+    name = result.stdout.strip()
+    return name if result.returncode == 0 and name and name != "HEAD" else None
+
+
+def _resolve_scope_base(repo_root: Path, scope: str, logger: Logger) -> str | None:
+    """Resolve a ``--scope`` token to a concrete base SHA, or ``None`` on
+    an unresolvable scope (a message is printed; the caller stops before the
+    loop). ``since-last-review`` reads the per-branch recorded SHA."""
+    from syncade.base_resolution import BaseResolutionError, resolve_scope
+    from syncade.persistence import read_last_reviewed
+
+    branch = _current_branch(repo_root)
+    last = read_last_reviewed(repo_root, branch) if branch else None
+    try:
+        resolved = resolve_scope(repo_root, scope, last_reviewed_sha=last)
+    except BaseResolutionError as exc:
+        print(f"[syncade] scope error: {exc}", file=sys.stderr)
+        return None
+    if resolved.note:
+        # Scope fallback notes are operator-facing invariants that must surface
+        # even in --quiet mode; bypass logger.warning (suppressed when quiet).
+        print(f"[syncade] scope: {resolved.note}", file=sys.stderr)
+    return resolved.base_sha
+
+
+def _cli_proves_commit(
+    repo_root: Path,
+    base_ref: str | None,
+    strip_files: Iterable[str],
+    *,
+    two_dot: bool = False,
+) -> bool:
+    """True ONLY when the CLI can prove this run will produce reviewable changes.
+
+    The pre-auth commit guard exists so a doomed committing run does not first pay for a
+    provider auth probe. Whether a run commits depends on the FILTERED diff, which the CLI
+    cannot compute — it has not snapshotted. Four earlier attempts asked the opposite
+    question ("can I prove there is NO change?") and each was wrong for a different input,
+    because being wrong there REFUSES A VALID RUN (PR-h-02d.5).
+
+    So the question is inverted and the answer is conservative: return True only when
+    certain, and let ``run_review`` decide otherwise. A wrong answer here costs one auth
+    probe; it can never refuse a run the library would accept.
+
+    Certain case: no base — reviewers see full HEAD, non-empty in any repo with a commit.
+
+    Everything else (any diff-shaping base) defers. ``git diff --name-only`` cannot
+    replicate the authoritative classifier: it C-quotes non-ASCII paths (so strip-list
+    basenames do not match the quoted form), and paths containing `` b/`` produce ambiguous
+    ``diff --git`` headers that ``run_review`` classifies as ``diff_malformed`` with zero
+    dispatches. Both shapes produce false proofs of commit under the basename approach,
+    causing the CLI to refuse runs the library accepts.
+    """
+    return base_ref is None
+
+
+def _resolve_openspec_pr_doc(repo_root: Path, change_id: str | None, logger: Logger) -> Path | None:
+    """Resolve a ``--openspec`` request to a concrete ``pr_doc_path``, or
+    ``None`` on an unresolvable proposal (a message is printed; the caller stops
+    before the loop). Reads the OpenSpec proposal folder's markdown directly
+    (consume-don't-depend — no ``openspec`` binary), assembles it into a spec, and
+    writes it to a staging ``.md`` tempfile. The CLI asks ``run_review`` to copy
+    that staged file into the run directory before ``run-init.json`` is written,
+    then removes the staging tempfile after the run."""
+    import tempfile
+
+    from syncade.spec_source import (
+        SpecSourceError,
+        assemble_openspec_spec,
+        resolve_openspec_change,
+    )
+
+    try:
+        resolved_id = resolve_openspec_change(repo_root, change_id)
+        spec = assemble_openspec_spec(repo_root, resolved_id)
+    except SpecSourceError as exc:
+        print(f"[syncade] openspec error: {exc}", file=sys.stderr)
+        return None
+    tmp = tempfile.NamedTemporaryFile(
+        mode="w",
+        suffix=".md",
+        prefix=f"syncade-openspec-{resolved_id}-",
+        delete=False,
+        encoding="utf-8",
+    )
+    tmp.write(spec)
+    tmp.close()
+    logger.warning(f"openspec: reviewing proposal {resolved_id!r} (assembled spec)")
+    return Path(tmp.name)

syncade/cli/resume_mode.py

@@ -0,0 +1,324 @@
+"""The ``syncade --resume <run-id>`` handler.
+
+Lives in its own module to keep :mod:`syncade.cli.modes` under the file-length
+cap: ``--resume`` is the largest one-shot handler (it rebuilds a ResumePlan from
+on-disk artifacts and re-enters the full review loop), and piling it alongside
+the other mode dispatchers is exactly what makes an entry-point policy easy to
+miss. ``modes`` re-exports :func:`_run_resume` so ``main()``'s dispatch is
+unchanged.
+"""
+
+from __future__ import annotations
+
+import json
+import math
+import sys
+from pathlib import Path
+
+from syncade.cli.auth_gate import auth_gate
+from syncade.cli.config_overrides import apply_worktree_base_override
+from syncade.config_auth import REVIEW_BLOCKS
+from syncade.config_loader import ConfigError, load_config
+from syncade.exit_codes import CONFIG_ERROR, WORKTREE_ERROR
+from syncade.logging import Logger
+from syncade.snapshot import SnapshotError
+from syncade.worktree import WorktreeError
+
+
+def _original_budget(config_snapshot_path) -> dict:
+    """The ORIGINAL run's configured budget, read from its run-init.json config snapshot.
+
+    Returns ``{'budget_tokens': ..., 'budget_usd': ...}`` with ONLY the dimensions the original
+    run actually set (a CLI ``--budget-*`` was folded into that snapshot at launch). ``{}`` on a
+    missing path, any read/parse failure, or a malformed value — budget inheritance is best-effort
+    and must never block a resume or bypass LoopConfig validators."""
+    if config_snapshot_path is None:
+        return {}
+    try:
+        data = json.loads(Path(config_snapshot_path).read_text(encoding="utf-8"))
+        loop = data.get("config_snapshot", {}).get("loop", {}) or {}
+        result = {}
+        for k in ("budget_tokens", "budget_usd"):
+            v = loop.get(k)
+            if v is None:
+                continue
+            if isinstance(v, bool):
+                continue
+            # budget_tokens requires a plain int (LoopConfig._strict_budget_tokens rejects
+            # floats — including 0.0, NaN, and Infinity — so inheriting them via model_copy
+            # would bypass the schema validator). budget_usd allows int/float but must be
+            # finite and non-negative (LoopConfig._budget_usd_isfinite rejects NaN/Inf).
+            if k == "budget_tokens":
+                if not isinstance(v, int) or v < 0:
+                    continue
+            else:
+                if not isinstance(v, (int, float)) or not math.isfinite(v) or v < 0:
+                    continue
+            result[k] = v
+        return result
+    except (OSError, ValueError, TypeError, AttributeError):
+        # AttributeError covers a malformed config_snapshot/loop that isn't a dict.
+        return {}
+
+
+def _resolve_resume_budget(config, args, plan):
+    """Resolve the resumed run's budget and announce it (PR-v2-11).
+
+    Precedence PER DIMENSION: CLI ``--budget-*`` > current ``config.toml`` > the ORIGINAL run's
+    ceiling > none. Inheriting the original ceiling is Finding 2's fix: a run launched with a
+    CLI-only ``--budget-tokens`` must NOT silently resume with no guardrail just because resume
+    reloads config from disk. Only the CEILING is inherited — the TALLY is still fresh (bounds
+    only the resumed spend). The notice fires even under ``--quiet`` (a spend-authorization fact,
+    like the resolved auth mode) so the operator is never surprised by the resumed budget."""
+    cli = {
+        field: value
+        for field, value in (
+            ("budget_tokens", args.budget_tokens),
+            ("budget_usd", args.budget_usd),
+        )
+        if value is not None
+    }
+    if cli:
+        config = config.model_copy(update={"loop": config.loop.model_copy(update=cli)})
+
+    # Inherit when the reloaded config did not EXPLICITLY set this dimension. Testing for
+    # None was equivalent until budget_tokens gained a default (PR-h-field-06) — after which
+    # it is never None, so inheritance silently stopped firing and a run launched at 3,500
+    # tokens resumed at the 50,000,000 default. Not unguarded, but guarded 14,000x looser,
+    # which is the same surprise Finding 2 exists to prevent. `model_fields_set` is the
+    # distinction the layered loader preserves: an omitted key is absent from it, an
+    # explicitly-configured one is present, whatever its value.
+    original = _original_budget(plan.config_snapshot_path)
+    inherited = {
+        dim: original[dim]
+        for dim in ("budget_tokens", "budget_usd")
+        if dim not in config.loop.model_fields_set and original.get(dim) is not None
+    }
+    if inherited:
+        config = config.model_copy(update={"loop": config.loop.model_copy(update=inherited)})
+
+    if config.loop.budget_tokens or config.loop.budget_usd:  # 0 sentinels = no active ceiling
+        msg = (
+            "[syncade] note: --resume applies a FRESH budget to this run's spend; the original "
+            "run's tokens/cost are NOT carried over, so original + resume can exceed a single "
+            "budget ceiling (resuming re-authorizes the spend)."
+        )
+        if inherited:
+            names = ", ".join(f"{k}={v}" for k, v in inherited.items())
+            msg += (
+                f" No budget was set for this resume, so the original run's ceiling was "
+                f"inherited ({names}); pass --budget-tokens/--budget-usd to override."
+            )
+        print(msg, file=sys.stderr)
+    return config
+
+
+def _report_hard_kill(run_dir: Path, run_status) -> None:
+    """Say so when the run being resumed was HARD-KILLED (PR-h-field-02).
+
+    ``run_status.is_stale_running`` has existed since the breadcrumb landed and, until now,
+    nothing in the product called it — a ``running`` state against a dead pid was detectable and
+    never reported. Three field runs died exactly that way, and the operator's only clue was a
+    status file still claiming the run was in progress.
+
+    Nothing in-process can finalize that file after SIGKILL, by definition. What CAN be fixed is
+    the silence: resume is where someone goes after a run vanishes, so resume is where it should
+    be told what it is looking at.
+    """
+    try:
+        status = json.loads((run_dir / "status.json").read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return
+    if not run_status.is_stale_running(status):
+        return
+    phase = status.get("phase") or "an unrecorded phase"
+    print(
+        f"[syncade] the run you are resuming was HARD-KILLED during '{phase}' — its status file "
+        f"still reads 'running' because nothing in the process survived to finalize it "
+        f"(SIGKILL, OOM, or the machine going down). Completed rounds are intact and will be "
+        f"reused; the interrupted round is dropped and retried.",
+        file=sys.stderr,
+    )
+
+
+def _run_resume(args) -> int:
+    """Dispatch ``syncade --resume <run-id>``.
+
+    Resolves the target run-id (specific or 'latest'), builds a
+    :class:`ResumePlan` from on-disk artifacts, and invokes
+    :func:`run_review` with the resume_plan threaded in. Maps the
+    resume-specific exceptions to exit codes:
+
+    - Config load failure → 50 (CONFIG_ERROR).
+    - repo_root discovery failure → 60 (WORKTREE_ERROR).
+    - :class:`ResumeError` (run-id not found / not eligible /
+      malformed) → 60.
+    - :class:`TreeDriftError` (drift without --force-drift) → 60.
+    - Any other orchestrator exception bubbles up to ``main()``
+      where it gets the same mapping as the fresh-run path.
+
+    The actual loop runs through the existing
+    :func:`syncade.orchestrator.run_review` with
+    ``resume_plan=plan, force_drift=args.force_drift``; its
+    exit code is the resumed run's verdict.
+    """
+    # Import the resume helpers lazily — operators not running
+    # --resume don't need to pay the import cost.
+    from syncade import run_status
+    from syncade.orchestrator import run_review
+    from syncade.orchestrator.resume import (
+        ResumeError,
+        plan_resume,
+        read_resume_decision,
+        resolve_resume_target,
+    )
+    from syncade.snapshot import discover_repo_root
+
+    # Discover the repo root for runs_root resolution and for any
+    # downstream code that wants to know "what tree are we in".
+    repo_root_hint = Path(args.repo_root).expanduser() if args.repo_root else Path.cwd()
+    try:
+        repo_root = discover_repo_root(repo_root_hint)
+    except SnapshotError as exc:
+        print(f"[syncade] snapshot error: {exc}", file=sys.stderr)
+        return WORKTREE_ERROR
+
+    def _emit_deprecation(message: str) -> None:
+        print(f"[syncade] {message}", file=sys.stderr)
+
+    try:
+        config = load_config(repo_root, preset=args.preset, deprecation_callback=_emit_deprecation)
+    except ConfigError as exc:
+        print(f"[syncade] config error: {exc}", file=sys.stderr)
+        return CONFIG_ERROR
+
+    # --max-rounds overrides the original run's cap (same model_copy as the fresh handler).
+    if args.max_rounds is not None:
+        new_loop = config.loop.model_copy(update={"max_rounds": args.max_rounds})
+        config = config.model_copy(update={"loop": new_loop})
+
+    runs_root = repo_root / ".syncade" / "runs"
+
+    # Read the current branch to filter "latest" by branch (detached HEAD → None).
+    current_branch: str | None = None
+    try:
+        from syncade.orchestrator.resume import _current_head_branch
+
+        current_branch = _current_head_branch(repo_root)
+    except Exception:
+        # Best-effort; a git failure falls back to no branch filter (drift check catches it).
+        current_branch = None
+
+    # Resolve the resume target + plan BEFORE the guard and auth_gate: the guard needs the
+    # EFFECTIVE cap the resumed run will use (max(config, plan.max_rounds)), and a resume
+    # error should surface without spawning a provider auth probe.
+    try:
+        run_id = resolve_resume_target(runs_root, args.resume, current_branch)
+        plan = plan_resume(
+            repo_root,
+            runs_root / run_id,
+            max_rounds_override=config.loop.max_rounds if args.max_rounds is not None else None,
+        )
+        # If the resumed round escalated, read the operator's decision (refuses with
+        # ResumeError when none was recorded). Read BEFORE run_review drops the round dir.
+        operator_decision = read_resume_decision(runs_root / run_id, plan.resumed_round)
+        _report_hard_kill(runs_root / run_id, run_status)
+    except ResumeError as exc:
+        print(f"[syncade] resume error: {exc}", file=sys.stderr)
+        return WORKTREE_ERROR
+
+    config = _resolve_resume_budget(config, args, plan)
+    # Honor the configured/overridden worktree base on resume too (dogfood B2): without this a
+    # resumed run silently falls back to /tmp/syncade even when the run relocated its worktrees.
+    config = apply_worktree_base_override(config, args)
+
+    # Default-branch refusal (PR-v2-26, D1(c)). will_commit uses the EFFECTIVE cap
+    # run_review will use — a single-pass resume (effective == 1) commits nothing and is
+    # exempt; a multi-round resume with a base defers to run_review (auth probe first);
+    # only a baseless multi-round resume is refused here before auth. Deriving it from
+    # the current config/CLI max_rounds alone would be wrong: a run launched at max_rounds=3
+    # but resumed with the config drifted to 1 still commits (effective == 3).
+    from syncade.orchestrator.branch_guard import current_branch_name, guard_default_branch
+
+    effective_max_rounds = max(config.loop.max_rounds, plan.max_rounds)
+    # Refuse ONLY when we can PROVE the resumed run commits (D1(c), PR-h-02d.5) — the same
+    # inversion as the fresh path. Literal `base_oid == HEAD` equality was too narrow: a
+    # resumed run whose pinned base is NOT HEAD but whose diff filters empty takes the
+    # no_changes_to_review path, and refusing it before auth diverged from run_review.
+    #
+    # `two_dot=True` is correct and NOT the merge-base hazard the previous comment warned
+    # about: plan.base_oid is the ALREADY-RESOLVED effective diff base, and a resumed run
+    # re-snapshots with three_dot=False against it (loop.py). So the literal `base..HEAD`
+    # range is exactly what run_review will diff — re-deriving a merge base here is what
+    # would be wrong.
+    from .resolve import _cli_proves_commit
+
+    _resume_will_commit = effective_max_rounds > 1 and _cli_proves_commit(
+        repo_root, plan.base_oid, config.review.strip_repo_context_files, two_dot=True
+    )
+    try:
+        guard_default_branch(
+            repo_root,
+            current_branch_name(repo_root),
+            allow=args.allow_default_branch,
+            will_commit=_resume_will_commit,
+        )
+    except WorktreeError as exc:
+        print(f"[syncade] worktree error: {exc}", file=sys.stderr)
+        return WORKTREE_ERROR
+
+    gate = auth_gate(config, REVIEW_BLOCKS)
+    if gate is not None:
+        return gate
+
+    logger = Logger("quiet" if args.quiet else "normal")
+    if not args.quiet:
+        print(
+            f"[syncade] resuming run {plan.run_id} at round "
+            f"{plan.resumed_round} (completed: {plan.completed_rounds}; "
+            f"expected snapshot SHA: {plan.expected_sha[:12]})"
+        )
+
+    with run_status.install_signal_handlers():
+        try:
+            result = run_review(
+                repo_root=repo_root,
+                pr_doc_path=plan.pr_doc_path,
+                config=config,
+                base_ref=plan.base_oid if plan.base_oid is not None else plan.base_ref,
+                timeout_seconds=args.timeout,
+                logger=logger,
+                force_dirty=args.force_dirty,
+                allow_default_branch=args.allow_default_branch,
+                resume_plan=plan,
+                force_drift=args.force_drift,
+                operator_decision=operator_decision,
+                worktree_base=config.worktree_base,
+            )
+        except FileNotFoundError as exc:
+            print(f"[syncade] error: {exc}", file=sys.stderr)
+            return 2
+        except NotADirectoryError as exc:
+            print(f"[syncade] error: {exc}", file=sys.stderr)
+            return 2
+        except SnapshotError as exc:
+            print(f"[syncade] snapshot error: {exc}", file=sys.stderr)
+            # These typed handlers intercept before the catch-all, so each finalizes
+            # the breadcrumb itself — else a clean exit-60 leaves status.json `running`
+            # and reads as a hard kill.
+            run_status.finalize_active(f"exception:{type(exc).__name__}", WORKTREE_ERROR)
+            return WORKTREE_ERROR
+        except ResumeError as exc:
+            print(f"[syncade] resume error: {exc}", file=sys.stderr)
+            run_status.finalize_active(f"exception:{type(exc).__name__}", WORKTREE_ERROR)
+            return WORKTREE_ERROR
+        except WorktreeError as exc:
+            print(f"[syncade] worktree error: {exc}", file=sys.stderr)
+            run_status.finalize_active(f"exception:{type(exc).__name__}", WORKTREE_ERROR)
+            return WORKTREE_ERROR
+        except KeyboardInterrupt:
+            return run_status.finalize_signal()
+        except Exception as exc:
+            run_status.finalize_active(f"exception:{type(exc).__name__}", None)
+            raise
+    return result.exit_code