arctx-cli 0.2.0b2__py3-none-any.whl

arctx_cli/commands/work_session.py

@@ -0,0 +1,330 @@
+"""arctx CLI work-session command."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import shlex
+import subprocess
+import sys
+from os import environ
+
+from arctx_cli.context import (
+    resolve_run_id_from_args,
+    resolve_store,
+    resolve_user_id_from_args,
+)
+from arctx.core.append import AppendBatch
+from arctx.core.ids import opaque_id
+
+
+def add_parser(subparsers) -> argparse.ArgumentParser:
+    parser = subparsers.add_parser(
+        "work-session",
+        help="Create, inspect, and pin work sessions for parallel work",
+        description=(
+            "Create and use work sessions. Use explicit mode with --work-session on "
+            "mutating commands, or fixed mode via `eval \"$(arctx work-session env "
+            "--run RUN --new)\"`. Fixed mode writes only shell environment variables, "
+            "so parallel terminals and child processes do not share the <gitdir>/arctx-id pointer."
+        ),
+    )
+    work_sub = parser.add_subparsers(dest="work_session_command", required=True)
+
+    start = work_sub.add_parser(
+        "start",
+        help="Create a work session and print its id",
+        description=(
+            "Create a work session in a run. This does not switch global state; pass "
+            "the id with --work-session or use `work-session env` for shell-local "
+            "fixed mode."
+        ),
+    )
+    start.add_argument("--run", default=None)
+    start.add_argument("--work-session", default=None)
+    start.add_argument("--user", default=None)
+    start.add_argument("--store-dir", default=None)
+    start.add_argument(
+        "--worktree",
+        default=None,
+        metavar="PATH",
+        help=(
+            "Attach this work session to a git worktree at PATH. The path "
+            "is recorded in WorkSession.metadata and exported as "
+            "ARCTX_GIT_WORKTREE for child processes."
+        ),
+    )
+    start.add_argument("--json", action="store_true", dest="as_json")
+
+    env = work_sub.add_parser(
+        "env",
+        help="Print shell exports for shell-local fixed mode",
+        description=(
+            "Print exports for ARCTX_RUN_ID, ARCTX_WORK_SESSION_ID, and ARCTX_USER_ID. "
+            "Use eval with this output to pin only the current shell or subprocess "
+            "environment, which is safe for parallel terminals."
+        ),
+    )
+    env.add_argument("work_session_id", nargs="?")
+    env.add_argument("--run", default=None)
+    env.add_argument("--new", action="store_true", dest="create_new")
+    env.add_argument("--user", default=None)
+    env.add_argument("--store-dir", default=None)
+    env.add_argument(
+        "--worktree",
+        default=None,
+        metavar="PATH",
+        help=(
+            "Attach the session to a git worktree at PATH. With --new the "
+            "path is stored on the new WorkSession; the exports include "
+            "ARCTX_GIT_WORKTREE=PATH so subsequent git verbs run there."
+        ),
+    )
+    env.add_argument("--json", action="store_true", dest="as_json")
+
+    spawn = work_sub.add_parser(
+        "spawn",
+        help="Run a command with a child-only fixed work session",
+        description=(
+            "Run a child command with ARCTX_RUN_ID, ARCTX_WORK_SESSION_ID, and "
+            "ARCTX_USER_ID set only in that child process. Use this for Codex, "
+            "Claude Code, scripts, or other parallel workers."
+        ),
+    )
+    spawn.add_argument("--run", default=None)
+    spawn.add_argument("--work-session", default=None)
+    spawn.add_argument("--user", default=None)
+    spawn.add_argument("--store-dir", default=None)
+    spawn.add_argument(
+        "--worktree",
+        default=None,
+        metavar="PATH",
+        help=(
+            "Attach the child session to a git worktree at PATH and export "
+            "ARCTX_GIT_WORKTREE=PATH for the child command."
+        ),
+    )
+    spawn.add_argument("command", nargs=argparse.REMAINDER)
+
+    list_cmd = work_sub.add_parser("list", help="List work sessions in a run")
+    list_cmd.add_argument("--run", default=None)
+    list_cmd.add_argument("--store-dir", default=None)
+
+    show = work_sub.add_parser("show", help="Show one work session")
+    show.add_argument("work_session_id")
+    show.add_argument("--run", default=None)
+    show.add_argument("--store-dir", default=None)
+
+    return parser
+
+
+def run_work_session_start_command(
+    *,
+    run_id: str,
+    work_session_id: str | None,
+    user_id: str,
+    store_dir: str,
+    worktree: str | None = None,
+) -> dict:
+    store = resolve_store(store_dir)
+    if not store.run_path(run_id).exists():
+        raise KeyError(f"unknown run_id: {run_id}")
+    handle = store.load_run(run_id)
+    ws_id = work_session_id or opaque_id("ws")
+    metadata = _build_worktree_metadata(worktree)
+    session = handle.ensure_work_session(
+        user_id=user_id,
+        work_session_id=ws_id,
+        metadata=metadata or None,
+    )
+    if session is None:
+        raise RuntimeError("failed to create work session")
+    if hasattr(store, "append_batch"):
+        store.append_batch(
+            AppendBatch(
+                run_id=run_id,
+                user_id=user_id,
+                work_session_id=ws_id,
+                work_session=session,
+                records=(),
+                events=(),
+            )
+        )
+    else:
+        store.save_run(handle)
+    result = {"run_id": run_id, "work_session_id": ws_id, "user_id": user_id}
+    if worktree:
+        result["worktree"] = str(metadata["worktree"]["path"])
+    return result
+
+
+def _build_worktree_metadata(worktree: str | None) -> dict:
+    """Resolve worktree path to absolute path and capture branch / repo info.
+
+    Returns the metadata dict to store on the WorkSession, or an empty
+    dict when no worktree was requested. The path is normalised so that
+    it does not depend on the caller's cwd; the branch lookup is best
+    effort and silently degrades when git is unavailable or the path is
+    not a real worktree.
+    """
+    if not worktree:
+        return {}
+    from pathlib import Path  # noqa: PLC0415
+
+    path = Path(worktree).expanduser().resolve()
+    info: dict = {"path": str(path)}
+    try:
+        from arctx.ext.git.helpers import repo as git_repo  # noqa: PLC0415
+
+        branch = git_repo.current_branch(path)
+        if branch is not None:
+            info["branch"] = branch
+        info["repo_common_dir"] = str(git_repo.common_dir(path))
+    except Exception:  # noqa: BLE001
+        # Recording the path is still useful; git lookups are best-effort.
+        pass
+    return {"worktree": info}
+
+
+def run_work_session_env_command(
+    *,
+    run_id: str,
+    work_session_id: str | None,
+    create_new: bool,
+    user_id: str,
+    store_dir: str,
+    worktree: str | None = None,
+) -> dict:
+    if create_new:
+        return run_work_session_start_command(
+            run_id=run_id,
+            work_session_id=work_session_id,
+            user_id=user_id,
+            store_dir=store_dir,
+            worktree=worktree,
+        )
+    if not work_session_id:
+        raise ValueError("work_session_id is required unless --new is used")
+    result = {"run_id": run_id, "work_session_id": work_session_id, "user_id": user_id}
+    if worktree:
+        from pathlib import Path  # noqa: PLC0415
+
+        result["worktree"] = str(Path(worktree).expanduser().resolve())
+    return result
+
+
+def run_work_session_list_command(*, run_id: str, store_dir: str) -> dict:
+    store = resolve_store(store_dir)
+    if not store.run_path(run_id).exists():
+        raise KeyError(f"unknown run_id: {run_id}")
+    handle = store.load_run(run_id)
+    return {
+        "run_id": run_id,
+        "work_sessions": [
+            session.to_dict()
+            for session in sorted(
+                handle.run_graph.work_sessions.values(),
+                key=lambda s: (s.started_at or "", s.work_session_id),
+            )
+        ],
+    }
+
+
+def run_work_session_show_command(
+    *,
+    run_id: str,
+    work_session_id: str,
+    store_dir: str,
+) -> dict:
+    listed = run_work_session_list_command(run_id=run_id, store_dir=store_dir)
+    for session in listed["work_sessions"]:
+        if session["work_session_id"] == work_session_id:
+            return {"run_id": run_id, "work_session": session}
+    raise KeyError(f"unknown work_session_id: {work_session_id}")
+
+
+def cli_work_session(args) -> int:
+    try:
+        if args.work_session_command == "start":
+            result = run_work_session_start_command(
+                run_id=resolve_run_id_from_args(args),
+                work_session_id=args.work_session,
+                user_id=resolve_user_id_from_args(args),
+                store_dir=args.store_dir,
+                worktree=getattr(args, "worktree", None),
+            )
+            _print_result(result, as_json=args.as_json)
+            return 0
+
+        if args.work_session_command == "env":
+            result = run_work_session_env_command(
+                run_id=resolve_run_id_from_args(args),
+                work_session_id=args.work_session_id,
+                create_new=args.create_new,
+                user_id=resolve_user_id_from_args(args),
+                store_dir=args.store_dir,
+                worktree=getattr(args, "worktree", None),
+            )
+            if args.as_json:
+                print(json.dumps(result, ensure_ascii=False, indent=2))
+            else:
+                print(_env_exports(result))
+            return 0
+
+        if args.work_session_command == "spawn":
+            if not args.command:
+                raise ValueError("spawn requires a command after --")
+            result = run_work_session_start_command(
+                run_id=resolve_run_id_from_args(args),
+                work_session_id=args.work_session,
+                user_id=resolve_user_id_from_args(args),
+                store_dir=args.store_dir,
+                worktree=getattr(args, "worktree", None),
+            )
+            child_env = dict(environ)
+            child_env["ARCTX_RUN_ID"] = result["run_id"]
+            child_env["ARCTX_WORK_SESSION_ID"] = result["work_session_id"]
+            child_env["ARCTX_USER_ID"] = result["user_id"]
+            if result.get("worktree"):
+                child_env["ARCTX_GIT_WORKTREE"] = result["worktree"]
+            command = args.command[1:] if args.command[:1] == ["--"] else args.command
+            return subprocess.call(command, env=child_env)
+
+        if args.work_session_command == "list":
+            result = run_work_session_list_command(
+                run_id=resolve_run_id_from_args(args),
+                store_dir=args.store_dir,
+            )
+            print(json.dumps(result, ensure_ascii=False, indent=2))
+            return 0
+
+        if args.work_session_command == "show":
+            result = run_work_session_show_command(
+                run_id=resolve_run_id_from_args(args),
+                work_session_id=args.work_session_id,
+                store_dir=args.store_dir,
+            )
+            print(json.dumps(result, ensure_ascii=False, indent=2))
+            return 0
+    except (KeyError, RuntimeError, ValueError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+    return 1
+
+
+def _print_result(result: dict, *, as_json: bool) -> None:
+    if as_json:
+        print(json.dumps(result, ensure_ascii=False, indent=2))
+    else:
+        print(result["work_session_id"])
+
+
+def _env_exports(result: dict) -> str:
+    lines = [
+        f"export ARCTX_RUN_ID={shlex.quote(result['run_id'])}",
+        f"export ARCTX_WORK_SESSION_ID={shlex.quote(result['work_session_id'])}",
+        f"export ARCTX_USER_ID={shlex.quote(result['user_id'])}",
+    ]
+    if result.get("worktree"):
+        lines.append(f"export ARCTX_GIT_WORKTREE={shlex.quote(result['worktree'])}")
+    return "\n".join(lines)

arctx_cli/context.py

@@ -0,0 +1,38 @@
+"""CLI current-run context persistence.
+
+Session-level resolution logic (resolve_store, resolve_run_id, resolve_user_id,
+resolve_work_session_id, _config_path, RunHandleProxy, ExtensionAwareStore) now
+lives in arctx.session.  This module re-exports those names so existing CLI
+code keeps working, and adds the argparse-Namespace helpers that belong here.
+"""
+
+from __future__ import annotations
+
+from arctx.session import (  # noqa: F401
+    ExtensionAwareStore,
+    RunHandleProxy,
+    _config_path,
+    resolve_run_id,
+    resolve_store,
+    resolve_user_id,
+    resolve_work_session_id,
+)
+
+
+def resolve_run_id_from_args(args) -> str:
+    """Resolve a run_id from a parsed argparse namespace.
+
+    Reads the ``--run`` flag and falls back to the env var and the
+    ``<gitdir>/arctx-id`` pointer.
+    """
+    return resolve_run_id(getattr(args, "run", None))
+
+
+def resolve_user_id_from_args(args) -> str:
+    """Resolve user attribution from parsed CLI args."""
+    return resolve_user_id(getattr(args, "user", None))
+
+
+def resolve_work_session_id_from_args(args) -> str:
+    """Resolve work-session attribution from parsed CLI args."""
+    return resolve_work_session_id(getattr(args, "work_session", None))

arctx_cli/ext/__init__.py

@@ -0,0 +1 @@
+"""CLI-side extension subpackages."""

arctx_cli/ext/command/__init__.py

@@ -0,0 +1,110 @@
+"""CLI commands for the command extension."""
+
+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,
+)
+from arctx.ext.command import CommandNamespace
+
+
+def add_parser(subparsers) -> argparse.ArgumentParser:
+    parser = subparsers.add_parser("command", help="Run external commands")
+    command_sub = parser.add_subparsers(dest="command_command", required=True)
+
+    sp_run = command_sub.add_parser(
+        "run",
+        help="Run an external command and record its result",
+    )
+    sp_run.add_argument("--run", default=None)
+    sp_run.add_argument("--store-dir", default=None)
+    sp_run.add_argument("--user", default=None)
+    sp_run.add_argument("--work-session", default=None)
+    sp_run.add_argument("--cwd", default=None)
+    sp_run.add_argument("--max-output-chars", type=int, default=20000)
+    sp_run.add_argument(
+        "argv",
+        nargs=argparse.REMAINDER,
+        help="Command to execute. Prefix with -- when needed.",
+    )
+    return parser
+
+
+def run_command_run_command(
+    *,
+    run_id: str,
+    store_dir: str,
+    argv: list[str],
+    cwd: str | None = None,
+    user_id: str | None = None,
+    work_session_id: str | None = None,
+    max_output_chars: int = 20000,
+) -> dict[str, object]:
+    store = resolve_store(store_dir)
+    if not store.run_path(run_id).exists():
+        raise KeyError(f"unknown run_id: {run_id}")
+    handle = store.load_run(run_id)
+    command_ns = getattr(handle, "command", None)
+    if not isinstance(command_ns, CommandNamespace):
+        raise RuntimeError("command extension is not enabled for this run")
+
+    before = graph_counts(handle)
+    result = command_ns.run(
+        command=argv,
+        cwd=cwd,
+        user_id=user_id,
+        work_session_id=work_session_id,
+        max_output_chars=max_output_chars,
+    )
+    maybe_append_or_save(
+        store=store,
+        handle=handle,
+        user_id=user_id,
+        work_session_id=work_session_id,
+        before=before,
+    )
+    return {
+        "transition": result["transition"].to_dict(),
+        "output_node": result["output_node"].to_dict(),
+        "payload": result["payload"].to_dict(),
+        "exit_code": result["exit_code"],
+    }
+
+
+def cli_command(args) -> int:
+    try:
+        if args.command_command == "run":
+            argv = _strip_separator(list(args.argv))
+            if not argv:
+                print("error: command run requires a command after --", file=sys.stderr)
+                return 2
+            result = run_command_run_command(
+                run_id=resolve_run_id_from_args(args),
+                store_dir=args.store_dir,
+                argv=argv,
+                cwd=args.cwd,
+                user_id=resolve_user_id_from_args(args),
+                work_session_id=resolve_work_session_id_from_args(args),
+                max_output_chars=args.max_output_chars,
+            )
+            print(json.dumps(result, ensure_ascii=False, indent=2))
+            return int(result["exit_code"])
+        print(f"unknown command subcommand: {args.command_command}", file=sys.stderr)
+        return 2
+    except Exception as exc:  # noqa: BLE001
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+
+
+def _strip_separator(argv: list[str]) -> list[str]:
+    if argv and argv[0] == "--":
+        return argv[1:]
+    return argv

arctx_cli/ext/git/__init__.py

@@ -0,0 +1 @@
+"""Git CLI commands."""

arctx_cli/ext/git/branch.py

@@ -0,0 +1,140 @@
+"""arctx CLI branch command.
+
+Provides:
+  arctx branch list       — list all known branches and their tip node IDs
+  arctx branch show NAME  — show tip, members count, and BranchPayload transitions
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from arctx_cli.context import resolve_run_id_from_args, resolve_store
+from arctx.core.schema.work_helpers import BRANCH_TIP_EVENT
+from arctx.ext.git.queries import branch_members
+
+
+def add_parser(subparsers) -> argparse.ArgumentParser:
+    """Register the ``branch`` subcommand parser."""
+    p = subparsers.add_parser("branch", help="Inspect git branches recorded in arctx")
+    branch_sub = p.add_subparsers(dest="branch_command", required=True)
+
+    sp_list = branch_sub.add_parser("list", help="List all known branches")
+    sp_list.add_argument("--run", default=None)
+    sp_list.add_argument("--store-dir", default=None)
+
+    sp_show = branch_sub.add_parser("show", help="Show branch tip and members")
+    sp_show.add_argument("name", help="Branch name")
+    sp_show.add_argument("--run", default=None)
+    sp_show.add_argument("--store-dir", default=None)
+
+    return p
+
+
+def _all_branches(graph) -> dict[str, str]:
+    """Return a mapping of branch_name → tip_node_id from BranchTipEvents.
+
+    The latest event per branch wins (events are in append order).
+    """
+    tips: dict[str, str] = {}
+    for event in graph.work_events:
+        if event.event_type == BRANCH_TIP_EVENT:
+            branch = str(event.data.get("branch", ""))
+            tip = str(event.data.get("tip_node_id", ""))
+            if branch:
+                tips[branch] = tip
+    return tips
+
+
+def run_branch_list_command(*, run_id: str | None, store_dir: str | None) -> list[dict]:
+    """Return a list of all branches with their current tip node IDs.
+
+    Returns
+    -------
+    List of dicts with keys ``branch`` and ``tip_node_id``.
+    """
+    store = resolve_store(store_dir)
+    handle = store.load_run(run_id)
+    branches = _all_branches(handle.run_graph)
+    return [{"branch": b, "tip_node_id": t} for b, t in sorted(branches.items())]
+
+
+def run_branch_show_command(
+    *, name: str, run_id: str | None, store_dir: str | None
+) -> dict:
+    """Return detailed info for a single branch.
+
+    Returns
+    -------
+    dict with keys:
+      - branch: str
+      - tip_node_id: str | None
+      - members_count: int
+      - members_sample: list[str] (up to 10 node IDs)
+      - transitions: list[dict] for transitions that carry a BranchPayload
+        targeting this branch
+    """
+    store = resolve_store(store_dir)
+    handle = store.load_run(run_id)
+    graph = handle.run_graph
+
+    branches = _all_branches(graph)
+    tip_node_id: str | None = branches.get(name)
+
+    members: set[str] = set()
+    if tip_node_id:
+        members = branch_members(graph, name)
+
+    # Find transitions with BranchPayload(branch=name).
+    branch_transitions = []
+    for t_id, transition in graph.transitions.items():
+        for p in graph.payloads_for_transition(t_id, payload_type="branch"):
+            if getattr(p, "branch", None) == name:
+                # Collect associated GitChangePayload info.
+                git_payloads = graph.payloads_for_transition(t_id, payload_type="git_change")
+                head_commit = git_payloads[-1].head_commit if git_payloads else None
+                branch_transitions.append(
+                    {
+                        "transition_id": t_id,
+                        "output_node_id": transition.output_node_id,
+                        "head_commit": head_commit,
+                        "branch_payload_id": p.payload_id,
+                    }
+                )
+
+    return {
+        "branch": name,
+        "tip_node_id": tip_node_id,
+        "members_count": len(members),
+        "members_sample": sorted(members)[:10],
+        "transitions": branch_transitions,
+    }
+
+
+def cli_branch(args) -> int:
+    """Entry point for ``arctx branch`` subcommand."""
+    run_id = resolve_run_id_from_args(args)
+
+    if args.branch_command == "list":
+        try:
+            result = run_branch_list_command(run_id=run_id, store_dir=args.store_dir)
+        except Exception as exc:  # noqa: BLE001
+            print(f"error: {exc}", file=sys.stderr)
+            return 1
+        print(json.dumps(result, indent=2))
+        return 0
+
+    if args.branch_command == "show":
+        try:
+            result = run_branch_show_command(
+                name=args.name, run_id=run_id, store_dir=args.store_dir
+            )
+        except Exception as exc:  # noqa: BLE001
+            print(f"error: {exc}", file=sys.stderr)
+            return 1
+        print(json.dumps(result, indent=2))
+        return 0
+
+    return 1