arctx-cli 0.2.0b2__py3-none-any.whl

arctx_cli/ext/git/merge.py

@@ -0,0 +1,204 @@
+"""arctx CLI merge command.
+
+Drives a git merge (or arctx-only join) and records a multi-input Transition
+with MergePayload or JoinPayload.
+
+Usage:
+  arctx merge --other <ref> [-m <message>] [--join]
+  arctx merge --other branch:<name> [--join]
+  arctx merge --other node:<id> [--join]
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from arctx_cli.append_batch import graph_counts, maybe_append_or_save
+from arctx_cli.context import (
+    resolve_run_id_from_args,
+    resolve_store,
+    resolve_user_id_from_args,
+    resolve_work_session_id_from_args,
+)
+
+
+def _parse_merge_ref(ref: str) -> tuple[str | None, str | None]:
+    """Parse a merge ref into (other_branch, other_node_id).
+
+    Formats accepted:
+    - "branch:<name>"  → other_branch
+    - "node:<id>"      → other_node_id
+    - "<anything>"     → treated as branch name
+    """
+    if ref.startswith("branch:"):
+        return ref[len("branch:"):], None
+    if ref.startswith("node:"):
+        return None, ref[len("node:"):]
+    return ref, None
+
+
+def add_parser(subparsers) -> argparse.ArgumentParser:
+    """Register the ``merge`` subcommand parser."""
+    p = subparsers.add_parser(
+        "merge",
+        help="Drive a git merge and record a multi-input arctx transition",
+    )
+    p.add_argument(
+        "--other",
+        required=True,
+        metavar="REF",
+        help=(
+            "The branch or node to merge in. Format: 'branch:<name>', "
+            "'node:<id>', or just '<name>' (auto-detected as branch name)."
+        ),
+    )
+    p.add_argument(
+        "-m",
+        "--message",
+        default=None,
+        help="Override the merge commit message",
+    )
+    p.add_argument(
+        "--branch",
+        default=None,
+        help="Override the current branch name (default: inferred from git)",
+    )
+    p.add_argument(
+        "--join",
+        action="store_true",
+        help=(
+            "Treat as a arctx-only join (no common ancestor). "
+            "Records JoinPayload instead of MergePayload. "
+            "Does NOT run git merge."
+        ),
+    )
+    p.add_argument("--run", default=None, help="Explicit run id")
+    p.add_argument("--store-dir", default=None, help="Store directory")
+    p.add_argument("--user", default=None, help="User id for attribution")
+    p.add_argument("--work-session", default=None, help="Work session id")
+    return p
+
+
+def run_merge_command(
+    *,
+    other: str,
+    message: str | None,
+    branch: str | None,
+    run_id: str | None,
+    store_dir: str | None,
+    user_id: str | None,
+    work_session_id: str | None,
+    join: bool = False,
+    # Test-only parameters; not exposed in the CLI parser.
+    dry_run: bool = False,
+    head_commit: str | None = None,
+) -> dict:
+    """Execute a merge (or join) and persist the resulting graph records.
+
+    Parameters
+    ----------
+    other:
+        Merge target reference. Format: 'branch:<name>', 'node:<id>', or '<name>'.
+    message:
+        Override the merge commit message. If None, git uses its default.
+    branch:
+        Current branch name override (None → infer from git).
+    run_id:
+        Explicit run id. If None, resolved from env / <gitdir>/arctx-id.
+    store_dir:
+        Store directory. If None, resolved from ARCTX_HOME.
+    user_id:
+        User id for work event attribution.
+    work_session_id:
+        Work session id.
+    join:
+        If True, use JoinPayload instead of MergePayload.
+
+    Returns
+    -------
+    dict with transition_id, output_node_id, branch, head_commit,
+    input_node_ids, merge_payload_type.
+    """
+    other_branch, other_node_id = _parse_merge_ref(other)
+
+    store = resolve_store(store_dir)
+    handle = store.load_run(run_id)
+
+    before = graph_counts(handle)
+
+    transition = handle.git.merge(
+        other_branch=other_branch,
+        other_node_id=other_node_id,
+        message=message,
+        branch=branch,
+        user_id=user_id,
+        work_session_id=work_session_id,
+        join=join,
+        dry_run=dry_run,
+        head_commit=head_commit,
+    )
+
+    maybe_append_or_save(
+        store=store,
+        handle=handle,
+        user_id=user_id,
+        work_session_id=work_session_id,
+        before=before,
+    )
+
+    git_payloads = handle.run_graph.payloads_for_transition(
+        transition.transition_id, payload_type="git_change"
+    )
+    head_commit = git_payloads[-1].head_commit if git_payloads else ""
+    branch_payloads = handle.run_graph.payloads_for_transition(
+        transition.transition_id, payload_type="branch"
+    )
+    resolved_branch = branch_payloads[-1].branch if branch_payloads else ""
+
+    payload_type = "join" if join else "merge"
+
+    return {
+        "transition_id": transition.transition_id,
+        "output_node_id": transition.output_node_id,
+        "input_node_ids": list(transition.input_node_ids),
+        "branch": resolved_branch,
+        "head_commit": head_commit,
+        "merge_payload_type": payload_type,
+    }
+
+
+def cli_merge(args) -> int:
+    """Entry point for ``arctx merge`` subcommand."""
+    from arctx.ext.git.verbs._forward_transition import ParallelSessionConflict  # noqa: PLC0415
+
+    run_id = resolve_run_id_from_args(args)
+    user_id = resolve_user_id_from_args(args)
+    work_session_id = resolve_work_session_id_from_args(args)
+
+    try:
+        result = run_merge_command(
+            other=args.other,
+            message=args.message,
+            branch=args.branch,
+            run_id=run_id,
+            store_dir=args.store_dir,
+            user_id=user_id,
+            work_session_id=work_session_id,
+            join=args.join,
+        )
+    except ParallelSessionConflict as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        print(
+            "hint: another session has advanced this branch. "
+            "Rebase / pull before committing.",
+            file=sys.stderr,
+        )
+        return 2
+    except Exception as exc:  # noqa: BLE001
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+
+    print(json.dumps(result, indent=2))
+    return 0

arctx_cli/ext/git/reset.py

@@ -0,0 +1,138 @@
+"""arctx CLI reset command.
+
+Resets the session pointer to a past node WITHOUT creating a new Transition.
+Analogous to ``git reset``: moves HEAD back but does not produce a new commit.
+
+For mode="hard", discarded transitions receive a CutPayload. For "mixed" and
+"soft" the transitions are left active (working tree / index changes remain).
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from arctx_cli.append_batch import graph_counts, maybe_append_or_save
+from arctx_cli.context import (
+    resolve_run_id_from_args,
+    resolve_store,
+    resolve_user_id_from_args,
+    resolve_work_session_id_from_args,
+)
+
+
+def add_parser(subparsers) -> argparse.ArgumentParser:
+    """Register the ``reset`` subcommand parser."""
+    p = subparsers.add_parser(
+        "reset",
+        help="Reset to a past node (no new transition)",
+    )
+    g = p.add_mutually_exclusive_group(required=True)
+    g.add_argument("--node", default=None, help="Target node id")
+    g.add_argument(
+        "--sha", default=None, help="Target commit sha (lookup via transition_by_sha)"
+    )
+    p.add_argument(
+        "--mode",
+        choices=["hard", "mixed", "soft"],
+        default="hard",
+        help="Reset mode (default: hard)",
+    )
+    p.add_argument("--branch", default=None, help="Override branch name")
+    p.add_argument("--run", default=None, help="Explicit run id")
+    p.add_argument("--store-dir", default=None, help="Store directory")
+    p.add_argument("--user", default=None, help="User id for attribution")
+    p.add_argument("--work-session", default=None, help="Work session id")
+    return p
+
+
+def run_reset_command(
+    *,
+    to_node_id: str | None,
+    to_sha: str | None,
+    mode: str,
+    branch: str | None,
+    run_id: str | None,
+    store_dir: str | None,
+    user_id: str | None,
+    work_session_id: str | None,
+    dry_run: bool = False,
+) -> dict:
+    """Execute a reset and persist the resulting graph records.
+
+    Parameters
+    ----------
+    to_node_id:
+        Target node id. Mutually exclusive with to_sha.
+    to_sha:
+        Target commit sha (looked up via transition_by_sha).
+    mode:
+        "hard" | "mixed" | "soft".
+    branch:
+        Branch name override for the SessionPointerEvent.
+    run_id:
+        Explicit run id.
+    store_dir:
+        Store directory.
+    user_id:
+        User id for work event attribution.
+    work_session_id:
+        Work session id.
+    dry_run:
+        If True, skip actual git operations.
+
+    Returns
+    -------
+    dict with to_node_id, from_node_id, discarded_transition_ids, mode,
+    event_id.
+    """
+    store = resolve_store(store_dir)
+    handle = store.load_run(run_id)
+
+    before = graph_counts(handle)
+
+    result = handle.git.reset(
+        to_node_id=to_node_id,
+        to_sha=to_sha,
+        mode=mode,
+        branch=branch,
+        user_id=user_id,
+        work_session_id=work_session_id,
+        dry_run=dry_run,
+    )
+
+    maybe_append_or_save(
+        store=store,
+        handle=handle,
+        user_id=user_id,
+        work_session_id=work_session_id,
+        before=before,
+    )
+
+    return result
+
+
+def cli_reset(args) -> int:
+    """Entry point for ``arctx reset`` subcommand."""
+    run_id = resolve_run_id_from_args(args)
+    user_id = resolve_user_id_from_args(args)
+    work_session_id = resolve_work_session_id_from_args(args)
+
+    try:
+        result = run_reset_command(
+            to_node_id=args.node,
+            to_sha=args.sha,
+            mode=args.mode,
+            branch=args.branch,
+            run_id=run_id,
+            store_dir=args.store_dir,
+            user_id=user_id,
+            work_session_id=work_session_id,
+        )
+    except Exception as exc:  # noqa: BLE001
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+
+    print(json.dumps(result, indent=2))
+    return 0

arctx_cli/ext/git/revert.py

@@ -0,0 +1,157 @@
+"""arctx CLI revert command.
+
+Drives a ``git revert`` and records the corresponding arctx Transition with
+BranchPayload, GitChangePayload, RevertPayload, BranchTipEvent, and
+SessionPointerEvent.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from arctx_cli.append_batch import graph_counts, maybe_append_or_save
+from arctx_cli.context import (
+    resolve_run_id_from_args,
+    resolve_store,
+    resolve_user_id_from_args,
+    resolve_work_session_id_from_args,
+)
+
+
+def add_parser(subparsers) -> argparse.ArgumentParser:
+    """Register the ``revert`` subcommand parser."""
+    p = subparsers.add_parser(
+        "revert",
+        help="Revert a commit (or transition) and record a arctx transition",
+    )
+    g = p.add_mutually_exclusive_group(required=True)
+    g.add_argument("--sha", default=None, help="Commit sha to revert")
+    g.add_argument("--transition", default=None, help="Transition id (lookup latest sha)")
+    p.add_argument("-m", "--message", default=None, help="Override commit message")
+    p.add_argument("--branch", default=None, help="Override branch name")
+    p.add_argument("--run", default=None, help="Explicit run id")
+    p.add_argument("--store-dir", default=None, help="Store directory")
+    p.add_argument("--user", default=None, help="User id for attribution")
+    p.add_argument("--work-session", default=None, help="Work session id")
+    return p
+
+
+def run_revert_command(
+    *,
+    target_sha: str | None,
+    target_transition: str | None,
+    message: str | None,
+    branch: str | None,
+    run_id: str | None,
+    store_dir: str | None,
+    user_id: str | None,
+    work_session_id: str | None,
+) -> dict:
+    """Execute a revert and persist the resulting graph records.
+
+    Parameters
+    ----------
+    target_sha:
+        Commit SHA to revert. Mutually exclusive with target_transition.
+    target_transition:
+        Transition ID whose latest sha to revert.
+    message:
+        Override commit message.
+    branch:
+        Branch name override.
+    run_id:
+        Explicit run id.
+    store_dir:
+        Store directory.
+    user_id:
+        User id for work event attribution.
+    work_session_id:
+        Work session id.
+
+    Returns
+    -------
+    dict with transition_id, output_node_id, branch, head_commit,
+    reverted_transition, reverted_commit.
+    """
+    store = resolve_store(store_dir)
+    handle = store.load_run(run_id)
+
+    before = graph_counts(handle)
+
+    transition = handle.git.revert(
+        target_sha=target_sha,
+        target_transition=target_transition,
+        message=message,
+        branch=branch,
+        user_id=user_id,
+        work_session_id=work_session_id,
+    )
+
+    maybe_append_or_save(
+        store=store,
+        handle=handle,
+        user_id=user_id,
+        work_session_id=work_session_id,
+        before=before,
+    )
+
+    # Extract payload info for the result.
+    git_payloads = handle.run_graph.payloads_for_transition(
+        transition.transition_id, payload_type="git_change"
+    )
+    head_commit = git_payloads[-1].head_commit if git_payloads else ""
+    branch_payloads = handle.run_graph.payloads_for_transition(
+        transition.transition_id, payload_type="branch"
+    )
+    resolved_branch = branch_payloads[-1].branch if branch_payloads else ""
+    revert_payloads = handle.run_graph.payloads_for_transition(
+        transition.transition_id, payload_type="revert"
+    )
+    reverted_transition = revert_payloads[-1].reverted_transition if revert_payloads else ""
+    reverted_commit = revert_payloads[-1].reverted_commit if revert_payloads else ""
+
+    return {
+        "transition_id": transition.transition_id,
+        "output_node_id": transition.output_node_id,
+        "branch": resolved_branch,
+        "head_commit": head_commit,
+        "reverted_transition": reverted_transition,
+        "reverted_commit": reverted_commit,
+    }
+
+
+def cli_revert(args) -> int:
+    """Entry point for ``arctx revert`` subcommand."""
+    from arctx.ext.git.verbs._forward_transition import ParallelSessionConflict  # noqa: PLC0415
+
+    run_id = resolve_run_id_from_args(args)
+    user_id = resolve_user_id_from_args(args)
+    work_session_id = resolve_work_session_id_from_args(args)
+
+    try:
+        result = run_revert_command(
+            target_sha=args.sha,
+            target_transition=args.transition,
+            message=args.message,
+            branch=args.branch,
+            run_id=run_id,
+            store_dir=args.store_dir,
+            user_id=user_id,
+            work_session_id=work_session_id,
+        )
+    except ParallelSessionConflict as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        print(
+            "hint: another session has advanced this branch. "
+            "Rebase / pull before committing.",
+            file=sys.stderr,
+        )
+        return 2
+    except Exception as exc:  # noqa: BLE001
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+
+    print(json.dumps(result, indent=2))
+    return 0

arctx_cli/ext/git/verify.py

@@ -0,0 +1,140 @@
+"""arctx CLI verify command.
+
+Validates the Descendant constraint (REDESIGN §10.9 invariant 7) over all
+non-cut transitions in the current run.
+
+Exit codes:
+  0 — no violations
+  1 — one or more violations (or command error)
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from arctx_cli.context import resolve_run_id_from_args, resolve_store
+
+
+def add_parser(subparsers) -> argparse.ArgumentParser:
+    """Register the ``verify`` subcommand parser."""
+    p = subparsers.add_parser(
+        "verify",
+        help="Verify the descendant constraint over all transitions",
+    )
+    p.add_argument(
+        "--repo",
+        default=None,
+        help="Repo path (default: cwd)",
+    )
+    p.add_argument("--run", default=None, help="Explicit run id")
+    p.add_argument("--store-dir", default=None, help="Store directory")
+    p.add_argument(
+        "--json",
+        action="store_true",
+        dest="json_output",
+        help="Output results as JSON",
+    )
+    return p
+
+
+def run_verify_command(
+    *,
+    run_id: str | None,
+    store_dir: str | None,
+    repo_path: Path | None = None,
+    skip_dead_sha_check: bool = False,
+) -> dict:
+    """Execute verify and return a result dict.
+
+    Parameters
+    ----------
+    run_id:
+        Explicit run id (or None to auto-resolve).
+    store_dir:
+        Store directory (or None to use ARCTX_HOME default).
+    repo_path:
+        Path to git repo root. Defaults to cwd.
+    skip_dead_sha_check:
+        If True, skip ``git cat-file -e`` pre-checks. For testing.
+
+    Returns
+    -------
+    dict with keys:
+      violations: list of violation dicts
+      summary: {"checked": int, "violations": int, "by_kind": {kind: int}}
+    """
+    store = resolve_store(store_dir)
+    handle = store.load_run(run_id)
+
+    violations = handle.git.verify(
+        repo_path=repo_path,
+        skip_dead_sha_check=skip_dead_sha_check,
+    )
+
+    # Count non-cut transitions that were checked.
+    from arctx.core.cuts import inactive_transition_ids  # noqa: PLC0415
+    graph = handle.run_graph
+    inactive = inactive_transition_ids(graph)
+    checked = sum(1 for t_id in graph.transitions if t_id not in inactive)
+
+    by_kind: dict[str, int] = {}
+    for v in violations:
+        by_kind[v.kind] = by_kind.get(v.kind, 0) + 1
+
+    violation_dicts = [
+        {
+            "transition_id": v.transition_id,
+            "kind": v.kind,
+            "message": v.message,
+            "details": v.details,
+        }
+        for v in violations
+    ]
+
+    return {
+        "violations": violation_dicts,
+        "summary": {
+            "checked": checked,
+            "violations": len(violations),
+            "by_kind": by_kind,
+        },
+    }
+
+
+def cli_verify(args) -> int:
+    """Entry point for ``arctx verify`` subcommand."""
+    run_id = resolve_run_id_from_args(args)
+    repo_path = Path(args.repo) if args.repo else None
+
+    try:
+        result = run_verify_command(
+            run_id=run_id,
+            store_dir=args.store_dir,
+            repo_path=repo_path,
+        )
+    except Exception as exc:  # noqa: BLE001
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+
+    if args.json_output:
+        print(json.dumps(result, indent=2))
+    else:
+        summary = result["summary"]
+        violations = result["violations"]
+        if not violations:
+            print(
+                f"ok: {summary['checked']} transition(s) checked, "
+                "no violations found"
+            )
+        else:
+            print(
+                f"FAIL: {summary['violations']} violation(s) in "
+                f"{summary['checked']} transition(s) checked"
+            )
+            for v in violations:
+                print(f"  [{v['kind']}] {v['transition_id']}: {v['message']}")
+
+    return 0 if not result["violations"] else 1