arctx-cli 0.2.0b2__py3-none-any.whl

arctx_cli/commands/current.py

@@ -0,0 +1,69 @@
+"""arctx CLI current command."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+
+from arctx_cli.paths import find_repo_root, read_arctx_id, resolve_arctx_home
+
+
+def add_parser(subparsers) -> argparse.ArgumentParser:
+    """Register the ``current`` subcommand parser."""
+    parser = subparsers.add_parser("current", help="Show the current run (from <gitdir>/arctx-id)")
+    parser.add_argument(
+        "--store-dir",
+        default=None,
+        help="Directory where runs are stored (default: <ARCTX_HOME>/runs)",
+    )
+    parser.add_argument(
+        "--json",
+        action="store_true",
+        dest="json_output",
+        help="Output as JSON",
+    )
+    return parser
+
+
+def run_current_command(
+    *,
+    store_dir: str | None = None,
+) -> dict:
+    """Show the current run resolved from ``<gitdir>/arctx-id``.
+
+    Parameters
+    ----------
+    store_dir:
+        Ignored (kept for API compatibility). The run path is derived from
+        ARCTX_HOME and the run_id in ``<gitdir>/arctx-id``.
+
+    Returns
+    -------
+    dict with ``run_id`` and ``run_path`` keys.
+
+    Raises
+    ------
+    RuntimeError
+        If not in a git repo or no ``<gitdir>/arctx-id`` is present.
+    """
+    repo_root = find_repo_root()
+    run_id = read_arctx_id(repo_root)
+    if not run_id:
+        raise RuntimeError(
+            "no current run set. "
+            "Run 'arctx init' to create a run or 'arctx use <run_id>' to set one."
+        )
+    arctx_home = resolve_arctx_home()
+    run_path = str(arctx_home/ "runs" / run_id)
+    return {"run_id": run_id, "run_path": run_path}
+
+
+def cli_current(args) -> int:
+    """Entry point for ``arctx current`` subcommand."""
+    result = run_current_command(store_dir=getattr(args, "store_dir", None))
+    if args.json_output:
+        print(json.dumps(result, ensure_ascii=False, indent=2))
+    else:
+        print(result["run_id"])
+    return 0

arctx_cli/commands/cut.py

@@ -0,0 +1,89 @@
+"""arctx CLI cut command."""
+
+from __future__ import annotations
+
+import argparse
+import json
+
+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_cli.append_batch import graph_counts, maybe_append_or_save
+
+
+def add_parser(subparsers) -> argparse.ArgumentParser:
+    parser = subparsers.add_parser("cut", help="Cut a Node or Transition")
+    parser.add_argument("kind", nargs="?", choices=["node", "transition"])
+    parser.add_argument("id", nargs="?")
+    group = parser.add_mutually_exclusive_group(required=False)
+    group.add_argument("--node", dest="node_id", metavar="NODE_ID")
+    group.add_argument("--transition", dest="transition_id", metavar="TRANSITION_ID")
+    parser.add_argument("--run", default=None)
+    parser.add_argument("--reason", default=None)
+    parser.add_argument("--store-dir", default=None)
+    parser.add_argument("--user", default=None)
+    parser.add_argument("--work-session", default=None)
+    return parser
+
+
+def run_cut_command(
+    *,
+    run_id: str,
+    target_id: str,
+    target_kind: str,
+    reason: str | None,
+    store_dir: str,
+    user_id: str | None = None,
+    work_session_id: 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)
+    before = graph_counts(handle)
+    cut = handle.cut(
+        target_id,
+        target_kind=target_kind,  # type: ignore[arg-type]
+        reason=reason,
+        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,
+    )
+    return {"cut": cut.to_dict()}
+
+
+def cli_cut(args) -> int:
+    if args.kind is not None:
+        if args.id is None:
+            raise ValueError("cut requires an id when using positional target")
+        target_id = args.id
+        target_kind = args.kind
+    elif args.node_id is not None:
+        target_id = args.node_id
+        target_kind = "node"
+    elif args.transition_id is not None:
+        target_id = args.transition_id
+        target_kind = "transition"
+    else:
+        raise ValueError("provide 'node <id>', 'transition <id>', --node, or --transition")
+
+    result = run_cut_command(
+        run_id=resolve_run_id_from_args(args),
+        target_id=target_id,
+        target_kind=target_kind,
+        reason=args.reason,
+        store_dir=args.store_dir,
+        user_id=resolve_user_id_from_args(args),
+        work_session_id=resolve_work_session_id_from_args(args),
+    )
+    print(json.dumps(result["cut"], ensure_ascii=False, indent=2))
+    return 0

arctx_cli/commands/dump.py

@@ -0,0 +1,72 @@
+"""arctx CLI dump command: render a run as outline or mermaid."""
+
+from __future__ import annotations
+
+import argparse
+
+from arctx_cli.context import resolve_store, resolve_run_id_from_args
+from arctx.core.run.dump import DumpOptions, dump
+
+
+def add_parser(subparsers) -> argparse.ArgumentParser:
+    parser = subparsers.add_parser(
+        "dump",
+        help="Render the run as an outline (LLM-friendly) or mermaid (visual)",
+    )
+    parser.add_argument(
+        "--format",
+        dest="fmt",
+        choices=["outline", "mermaid"],
+        default="outline",
+        help="Output format (default: outline)",
+    )
+    parser.add_argument("--node", dest="node_id", default=None,
+                        help="Render only the subtree rooted at this node")
+    parser.add_argument("--depth", type=int, default=None,
+                        help="Limit traversal depth")
+    parser.add_argument("--observed-only", action="store_true",
+                        help="Hide predicted output transitions")
+    parser.add_argument("--predicted-only", action="store_true",
+                        help="Hide observed (result) output transitions")
+    parser.add_argument("--full-payloads", action="store_true",
+                        help="Include full payload metrics / rationale")
+    parser.add_argument("--run", default=None)
+    parser.add_argument("--store-dir", default=None)
+    return parser
+
+
+def run_dump_command(
+    *,
+    run_id: str,
+    fmt: str = "outline",
+    store_dir: str = ".arctx/runs",
+    node_id: str | None = None,
+    depth: int | None = None,
+    full_payloads: bool = False,
+) -> str:
+    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)
+    opts = DumpOptions(node_id=node_id, depth=depth, full_payloads=full_payloads)
+    return dump(handle, fmt, opts)
+
+
+def cli_dump(args) -> int:
+    if args.observed_only and args.predicted_only:
+        raise ValueError("--observed-only and --predicted-only are mutually exclusive")
+    store = resolve_store(args.store_dir)
+    run_id = resolve_run_id_from_args(args)
+    if not store.run_path(run_id).exists():
+        raise KeyError(f"unknown run_id: {run_id}")
+    handle = store.load_run(run_id)
+
+    opts = DumpOptions(
+        node_id=args.node_id,
+        depth=args.depth,
+        observed_only=args.observed_only,
+        predicted_only=args.predicted_only,
+        full_payloads=args.full_payloads,
+    )
+    print(dump(handle, args.fmt, opts))
+    return 0

arctx_cli/commands/ext.py

@@ -0,0 +1,236 @@
+"""arctx ext subcommand — manage extensions for a run.
+
+Subcommands
+-----------
+list    List all built-in extensions and whether each is enabled in the current run.
+show    Show details (version, default_aliases) for a named extension as JSON.
+enable  Enable an extension in an existing run (calls on_init, then records it).
+disable Remove an extension from the enabled list (side effects are NOT reversed).
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+
+def add_parser(subparsers) -> argparse.ArgumentParser:
+    """Register the ``ext`` subcommand."""
+    parser = subparsers.add_parser("ext", help="Manage extensions")
+    ext_sub = parser.add_subparsers(dest="ext_command", required=True)
+
+    # ext list
+    _list = ext_sub.add_parser("list", help="List available extensions")
+    _list.add_argument("--run", default=None, help="Run ID")
+    _list.add_argument("--store-dir", default=None, dest="store_dir")
+
+    # ext show <name>
+    show = ext_sub.add_parser("show", help="Show extension details")
+    show.add_argument("name", help="Extension name")
+
+    # ext enable <name>
+    enable = ext_sub.add_parser("enable", help="Enable an extension in the current run")
+    enable.add_argument("name", help="Extension name")
+    enable.add_argument("--run", default=None, help="Run ID")
+    enable.add_argument("--store-dir", default=None, dest="store_dir")
+
+    # ext disable <name>
+    disable = ext_sub.add_parser("disable", help="Disable an extension in the current run")
+    disable.add_argument("name", help="Extension name")
+    disable.add_argument("--run", default=None, help="Run ID")
+    disable.add_argument("--store-dir", default=None, dest="store_dir")
+
+    return parser
+
+
+# ---------------------------------------------------------------------------
+# Command runners
+# ---------------------------------------------------------------------------
+
+
+def run_ext_list_command(
+    *,
+    run_dir: str | None = None,
+) -> dict:
+    """Return info about all built-in extensions.
+
+    Parameters
+    ----------
+    run_dir:
+        When provided, each extension's enabled status is checked against
+        the run's ``extensions.json``.
+    """
+    from arctx.ext import list_available
+    from arctx.ext.enabled import load_enabled
+
+    available = list_available()
+    enabled_names: set[str] = set()
+    if run_dir is not None:
+        enabled_names = {ee.name for ee in load_enabled(run_dir)}
+
+    items = []
+    for name in available:
+        items.append({"name": name, "enabled": name in enabled_names})
+    return {"extensions": items}
+
+
+def run_ext_show_command(name: str) -> dict:
+    """Return details for a named extension.
+
+    Raises
+    ------
+    KeyError
+        If *name* is not registered.
+    """
+    from arctx.ext import load_extension
+
+    ext = load_extension(name)
+    return {
+        "name": ext.name,
+        "version": ext.version,
+        "default_aliases": ext.default_aliases(),
+    }
+
+
+def run_ext_enable_command(
+    *,
+    name: str,
+    run_dir: str,
+) -> dict:
+    """Enable extension *name* in *run_dir*.
+
+    Calls ``on_init`` with an empty options dict (no parser options available
+    after init), then records the extension as enabled.
+
+    Raises
+    ------
+    KeyError
+        If *name* is not in the registry.
+    """
+    from arctx.ext import load_extension
+    from arctx.ext.base import InitContext
+    from arctx.ext.enabled import EnabledExtension, add_enabled, load_enabled
+    from arctx.storage.jsonl import JsonlRunStore
+
+    # Resolve run_id from the run dir (read run.json)
+    import json as _json
+    from pathlib import Path as _Path
+
+    run_json = _Path(run_dir) / "run.json"
+    run_id = _json.loads(run_json.read_text(encoding="utf-8"))["run_id"]
+
+    ext = load_extension(name)
+
+    # Check if already enabled
+    current = load_enabled(run_dir)
+    if any(e.name == name for e in current):
+        return {"status": "already_enabled", "name": name}
+
+    ctx = InitContext(run_id=run_id, run_dir=run_dir, options={})
+    ext.on_init(ctx)
+
+    add_enabled(run_dir, EnabledExtension(name=ext.name, version=ext.version, config={}))
+    return {"status": "enabled", "name": name}
+
+
+def run_ext_disable_command(
+    *,
+    name: str,
+    run_dir: str,
+) -> dict:
+    """Remove extension *name* from the enabled list.
+
+    Does NOT reverse any side effects (files written, hooks installed, etc.).
+    Callers should warn the user about this.
+
+    Raises
+    ------
+    KeyError
+        If *name* is not currently enabled.
+    """
+    from arctx.ext.enabled import load_enabled, save_enabled
+
+    current = load_enabled(run_dir)
+    remaining = [e for e in current if e.name != name]
+    if len(remaining) == len(current):
+        raise KeyError(f"extension {name!r} is not enabled in this run")
+    save_enabled(run_dir, remaining)
+    return {"status": "disabled", "name": name}
+
+
+# ---------------------------------------------------------------------------
+# CLI dispatcher
+# ---------------------------------------------------------------------------
+
+
+def _resolve_run_dir(args) -> str | None:
+    """Best-effort: resolve run_dir from args."""
+    from pathlib import Path
+
+    store_dir = getattr(args, "store_dir", None)
+    run_id_arg = getattr(args, "run", None)
+    if run_id_arg is None:
+        import os
+
+        run_id_arg = os.environ.get("ARCTX_RUN_ID")
+    if run_id_arg and store_dir:
+        return str(Path(store_dir) / run_id_arg)
+    if run_id_arg:
+        from arctx_cli.paths import resolve_store_dir
+
+        return str(Path(resolve_store_dir()) / run_id_arg)
+    return None
+
+
+def cli_ext(args) -> int:
+    """Dispatch arctx ext subcommands."""
+    cmd = args.ext_command
+
+    if cmd == "list":
+        run_dir = _resolve_run_dir(args)
+        result = run_ext_list_command(run_dir=run_dir)
+        print(json.dumps(result, indent=2, ensure_ascii=False))
+        return 0
+
+    if cmd == "show":
+        try:
+            result = run_ext_show_command(args.name)
+        except KeyError as exc:
+            print(f"error: {exc}", file=sys.stderr)
+            return 1
+        print(json.dumps(result, indent=2, ensure_ascii=False))
+        return 0
+
+    if cmd == "enable":
+        run_dir = _resolve_run_dir(args)
+        if run_dir is None:
+            print("error: cannot resolve run directory. Pass --run and --store-dir.", file=sys.stderr)
+            return 1
+        try:
+            result = run_ext_enable_command(name=args.name, run_dir=run_dir)
+        except KeyError as exc:
+            print(f"error: {exc}", file=sys.stderr)
+            return 1
+        status = result["status"]
+        if status == "already_enabled":
+            print(f"warning: {args.name!r} is already enabled", file=sys.stderr)
+        else:
+            print(json.dumps(result, indent=2, ensure_ascii=False))
+        return 0
+
+    if cmd == "disable":
+        run_dir = _resolve_run_dir(args)
+        if run_dir is None:
+            print("error: cannot resolve run directory. Pass --run and --store-dir.", file=sys.stderr)
+            return 1
+        try:
+            result = run_ext_disable_command(name=args.name, run_dir=run_dir)
+        except KeyError as exc:
+            print(f"error: {exc}", file=sys.stderr)
+            return 1
+        print(f"warning: side effects of {args.name!r} are NOT reversed (files remain)", file=sys.stderr)
+        print(json.dumps(result, indent=2, ensure_ascii=False))
+        return 0
+
+    return 1

arctx_cli/commands/git.py

@@ -0,0 +1,216 @@
+"""arctx git subcommand — attach commit hashes to transitions."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+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,
+)
+
+# ---------------------------------------------------------------------------
+# Parser registration
+# ---------------------------------------------------------------------------
+
+
+def add_parser(subparsers) -> argparse.ArgumentParser:
+    """Register the ``git`` command namespace."""
+    git_parser = subparsers.add_parser("git", help="Git integration commands")
+    git_sub = git_parser.add_subparsers(dest="git_command", required=True)
+
+    from arctx_cli.ext.git.branch import add_parser as add_branch_parser
+    from arctx_cli.ext.git.cherry_pick import add_parser as add_cherry_pick_parser
+    from arctx_cli.ext.git.commit import add_parser as add_commit_parser
+    from arctx_cli.ext.git.hook import add_parser as add_hook_parser
+    from arctx_cli.ext.git.merge import add_parser as add_merge_parser
+    from arctx_cli.ext.git.reset import add_parser as add_reset_parser
+    from arctx_cli.ext.git.revert import add_parser as add_revert_parser
+    from arctx_cli.ext.git.verify import add_parser as add_verify_parser
+    from arctx_cli.ext.git.worktree import add_parser as add_worktree_parser
+
+    add_branch_parser(git_sub)
+    add_cherry_pick_parser(git_sub)
+    add_commit_parser(git_sub)
+    add_hook_parser(git_sub)
+    add_merge_parser(git_sub)
+    add_reset_parser(git_sub)
+    add_revert_parser(git_sub)
+    add_verify_parser(git_sub)
+    add_worktree_parser(git_sub)
+
+    sp_list = git_sub.add_parser("list", help="List git_change payloads for a Transition")
+    sp_list.add_argument("--transition", required=True, dest="transition_id")
+    sp_list.add_argument("--run", default=None)
+    sp_list.add_argument("--store-dir", default=None)
+
+    sp_add = git_sub.add_parser("add", help="Attach explicit Git commits to a Transition")
+    sp_add.add_argument("--transition", required=True, dest="transition_id")
+    sp_add.add_argument("--commit", action="append", required=True, dest="commits")
+    sp_add.add_argument("--run", default=None)
+    sp_add.add_argument("--store-dir", default=None)
+    sp_add.add_argument("--user", default=None)
+    sp_add.add_argument("--work-session", default=None)
+
+    sp_show = git_sub.add_parser("show", help="Show git_change payloads for a Transition")
+    sp_show.add_argument("--transition", required=True, dest="transition_id")
+    sp_show.add_argument("--run", default=None)
+    sp_show.add_argument("--store-dir", default=None)
+
+    return git_parser
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _run_dir(store: object, run_id: str) -> Path:
+    return store.run_path(run_id)  # type: ignore[attr-defined]
+
+
+# ---------------------------------------------------------------------------
+# Dispatch
+# ---------------------------------------------------------------------------
+
+
+def cli_git(args) -> int:
+    """Dispatch canonical ``arctx git`` subcommands."""
+    from arctx_cli.ext.git.branch import cli_branch
+    from arctx_cli.ext.git.cherry_pick import cli_cherry_pick
+    from arctx_cli.ext.git.commit import cli_commit
+    from arctx_cli.ext.git.hook import cli_hook
+    from arctx_cli.ext.git.merge import cli_merge
+    from arctx_cli.ext.git.reset import cli_reset
+    from arctx_cli.ext.git.revert import cli_revert
+    from arctx_cli.ext.git.verify import cli_verify
+
+    if args.git_command == "add":
+        return _cli_git_attach(args)
+    if args.git_command == "branch":
+        return cli_branch(args)
+    if args.git_command == "cherry-pick":
+        return cli_cherry_pick(args)
+    if args.git_command == "commit":
+        return cli_commit(args)
+    if args.git_command == "hook":
+        return cli_hook(args)
+    if args.git_command == "list":
+        return _cli_git_list(args)
+    if args.git_command == "merge":
+        return cli_merge(args)
+    if args.git_command == "reset":
+        return cli_reset(args)
+    if args.git_command == "revert":
+        return cli_revert(args)
+    if args.git_command == "show":
+        return _cli_git_show(args)
+    if args.git_command == "verify":
+        return cli_verify(args)
+    if args.git_command == "worktree":
+        from arctx_cli.ext.git.worktree import cli_worktree  # noqa: PLC0415
+
+        return cli_worktree(args)
+    print(f"unknown git subcommand: {args.git_command}", file=sys.stderr)
+    return 1
+
+
+# ---------------------------------------------------------------------------
+# attach
+# ---------------------------------------------------------------------------
+
+
+def _git_payloads_for_transition(args) -> tuple[object, list]:
+    store = resolve_store(args.store_dir)
+    run_id = resolve_run_id_from_args(args)
+    if not store.run_path(run_id).exists():
+        raise KeyError(f"unknown run_id: {run_id}")
+    handle = store.load_run(run_id)
+    if args.transition_id not in handle.run_graph.transitions:
+        raise KeyError(f"unknown transition_id: {args.transition_id}")
+    payloads = handle.run_graph.payloads_for_transition(
+        args.transition_id,
+        payload_type="git_change",
+    )
+    return handle, payloads
+
+
+def _cli_git_list(args) -> int:
+    try:
+        _, payloads = _git_payloads_for_transition(args)
+    except KeyError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+
+    commits: list[str] = []
+    for payload in payloads:
+        for entry in getattr(payload, "commit_log", ()):
+            sha = getattr(entry, "sha", None)
+            if sha is not None:
+                commits.append(str(sha))
+    print(
+        json.dumps(
+            {
+                "transition_id": args.transition_id,
+                "commits": commits,
+            },
+            ensure_ascii=False,
+            indent=2,
+        )
+    )
+    return 0
+
+
+def _cli_git_show(args) -> int:
+    try:
+        _, payloads = _git_payloads_for_transition(args)
+    except KeyError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+    print(json.dumps([p.to_dict() for p in payloads], ensure_ascii=False, indent=2))
+    return 0
+
+
+def _cli_git_attach(args) -> int:
+    store = resolve_store(args.store_dir)
+    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)
+
+    if not store.run_path(run_id).exists():
+        print(f"error: unknown run_id: {run_id}", file=sys.stderr)
+        return 1
+
+    handle = store.load_run(run_id)
+    run_dir = _run_dir(store, run_id)
+
+    from arctx.ext.git.helpers.attach import attach_commits_to_transition
+
+    try:
+        before = graph_counts(handle)
+        result = attach_commits_to_transition(
+            handle,
+            run_dir,
+            args.transition_id,
+            tuple(args.commits),
+            user_id=user_id,
+            work_session_id=work_session_id,
+        )
+    except (KeyError, ValueError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+
+    maybe_append_or_save(
+        store=store,
+        handle=handle,
+        user_id=user_id,
+        work_session_id=work_session_id,
+        before=before,
+    )
+    print(json.dumps(result, ensure_ascii=False, indent=2))
+    return 0