arctx-cli 0.2.0b2__py3-none-any.whl

arctx_cli/ext/git/worktree.py

@@ -0,0 +1,173 @@
+"""arctx git worktree — thin wrappers around ``git worktree``.
+
+This is a lifecycle helper. The actual graph state lives on the
+WorkSession that is later attached to the worktree via
+``arctx work-session env --worktree`` (or via spawn/start). These
+commands only manage the git side: ``add`` creates a new
+``git worktree`` on a fresh branch, ``list`` shows the registered
+worktrees, and ``remove`` invokes ``git worktree remove``.
+
+Recording per-worktree session metadata is intentionally left to
+``arctx work-session start --worktree``; that keeps a single canonical
+path for writing WorkSession state and lets users attach a worktree
+that was created outside arctx (``git worktree add`` directly).
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+from arctx.ext.git.helpers.repo import resolve_worktree_path
+
+
+def add_parser(subparsers) -> argparse.ArgumentParser:
+    """Register the ``worktree`` subcommand under ``arctx git``."""
+    parser = subparsers.add_parser(
+        "worktree",
+        help="Manage git worktrees attached to this ARCTX run",
+        description=(
+            "Thin wrapper around `git worktree`. Use these to create / list "
+            "/ remove worktrees; attach them to a ARCTX work session with "
+            "`arctx work-session start --worktree PATH`."
+        ),
+    )
+    sub = parser.add_subparsers(dest="worktree_command", required=True)
+
+    add = sub.add_parser(
+        "add",
+        help="git worktree add PATH [BRANCH] — create a new worktree",
+    )
+    add.add_argument("path", help="Filesystem path for the new worktree")
+    add.add_argument(
+        "branch",
+        nargs="?",
+        default=None,
+        help="Branch to check out. Defaults to a new branch named after the path leaf.",
+    )
+    add.add_argument(
+        "--base",
+        default=None,
+        help="Base ref for the new branch (defaults to HEAD).",
+    )
+    add.add_argument(
+        "--existing-branch",
+        action="store_true",
+        help="Check out an existing branch instead of creating one.",
+    )
+    add.add_argument("--store-dir", default=None)
+
+    list_cmd = sub.add_parser("list", help="git worktree list --porcelain (parsed as JSON)")
+    list_cmd.add_argument("--store-dir", default=None)
+
+    remove = sub.add_parser("remove", help="git worktree remove PATH")
+    remove.add_argument("path")
+    remove.add_argument(
+        "--force",
+        action="store_true",
+        help="Pass --force to git worktree remove (drop dirty / locked).",
+    )
+    remove.add_argument("--store-dir", default=None)
+
+    return parser
+
+
+def cli_worktree(args) -> int:
+    """Dispatch ``arctx git worktree`` subcommands."""
+    if args.worktree_command == "add":
+        return _cli_worktree_add(args)
+    if args.worktree_command == "list":
+        return _cli_worktree_list(args)
+    if args.worktree_command == "remove":
+        return _cli_worktree_remove(args)
+    print(f"unknown worktree subcommand: {args.worktree_command}", file=sys.stderr)
+    return 1
+
+
+def _cli_worktree_add(args) -> int:
+    target = Path(args.path).expanduser().resolve()
+    cwd = resolve_worktree_path(None)
+    cmd = ["git", "worktree", "add"]
+    if args.branch is None and not args.existing_branch:
+        leaf = target.name or "arctx-worktree"
+        cmd += ["-b", leaf, str(target)]
+        if args.base:
+            cmd.append(args.base)
+    elif args.existing_branch:
+        if args.branch is None:
+            print("error: --existing-branch requires BRANCH", file=sys.stderr)
+            return 2
+        cmd += [str(target), args.branch]
+    else:
+        # explicit new branch name
+        cmd += ["-b", args.branch, str(target)]
+        if args.base:
+            cmd.append(args.base)
+
+    result = subprocess.run(cmd, cwd=str(cwd), capture_output=True, text=True)
+    if result.returncode != 0:
+        sys.stderr.write(result.stderr)
+        return result.returncode
+
+    print(
+        json.dumps(
+            {
+                "path": str(target),
+                "branch": args.branch
+                or (target.name or "arctx-worktree" if not args.existing_branch else None),
+                "command": cmd,
+            },
+            ensure_ascii=False,
+            indent=2,
+        )
+    )
+    return 0
+
+
+def _cli_worktree_list(args) -> int:  # noqa: ARG001
+    cwd = resolve_worktree_path(None)
+    result = subprocess.run(
+        ["git", "worktree", "list", "--porcelain"],
+        cwd=str(cwd),
+        capture_output=True,
+        text=True,
+    )
+    if result.returncode != 0:
+        sys.stderr.write(result.stderr)
+        return result.returncode
+
+    entries: list[dict] = []
+    current: dict = {}
+    for line in result.stdout.splitlines():
+        if not line.strip():
+            if current:
+                entries.append(current)
+                current = {}
+            continue
+        if " " in line:
+            key, value = line.split(" ", 1)
+        else:
+            key, value = line, ""
+        current[key] = value
+    if current:
+        entries.append(current)
+
+    print(json.dumps({"worktrees": entries}, ensure_ascii=False, indent=2))
+    return 0
+
+
+def _cli_worktree_remove(args) -> int:
+    cwd = resolve_worktree_path(None)
+    cmd = ["git", "worktree", "remove"]
+    if args.force:
+        cmd.append("--force")
+    cmd.append(str(Path(args.path).expanduser()))
+    result = subprocess.run(cmd, cwd=str(cwd), capture_output=True, text=True)
+    if result.returncode != 0:
+        sys.stderr.write(result.stderr)
+        return result.returncode
+    print(json.dumps({"removed": str(Path(args.path).expanduser().resolve())}, indent=2))
+    return 0

arctx_cli/ext_registry.py

@@ -0,0 +1,34 @@
+"""CLI-side extension registration.
+
+Keeps the arctx layer free of CLI dependencies.  ``arctx_cli.main``
+calls :func:`register_enabled_cli` to attach argparse subparsers for each
+extension that is enabled in the current run directory.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Iterable
+
+
+def register_extension_cli(subparsers, names: Iterable[str]) -> None:
+    """Register CLI namespaces provided by the named extensions."""
+    from arctx.ext import load_extension
+    from arctx_cli.commands import register_cli_commands
+
+    seen: set[str] = set()
+    for name in names:
+        if name in seen:
+            continue
+        ext = load_extension(name)
+        register_cli_commands(subparsers, ext.cli_commands())
+        seen.add(ext.name)
+
+
+def register_enabled_cli(subparsers, run_dir: str | Path | None) -> None:
+    """Register CLI namespaces for extensions enabled in a run directory."""
+    if run_dir is None:
+        return
+    from arctx.ext.enabled import load_enabled
+
+    register_extension_cli(subparsers, (item.name for item in load_enabled(run_dir)))

arctx_cli/main.py

@@ -0,0 +1,133 @@
+"""arctx CLI entry point."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from arctx_cli.commands import core_cli_commands, register_cli_commands
+
+
+def _build_parser(*, run_dir: str | None = None) -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="arctx",
+        description="Record optimization and problem-solving processes",
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    register_cli_commands(subparsers, core_cli_commands())
+
+    from arctx_cli.ext_registry import register_enabled_cli  # noqa: PLC0415
+
+    register_enabled_cli(subparsers, run_dir)
+
+    return parser
+
+
+def _resolve_run_dir_for_alias(tokens: list[str]) -> str | None:
+    """Best-effort resolution of run_dir for alias loading.
+
+    Reads ``--run`` / ``ARCTX_RUN_ID`` / ``<gitdir>/arctx-id``. Returns None if no
+    run can be resolved without side-effects.
+    """
+    import os
+    from pathlib import Path
+
+    # Look for --run <id> in tokens
+    run_id: str | None = None
+    store_dir: str | None = None
+    for i, tok in enumerate(tokens):
+        if tok == "--run" and i + 1 < len(tokens):
+            run_id = tokens[i + 1]
+        if tok == "--store-dir" and i + 1 < len(tokens):
+            store_dir = tokens[i + 1]
+        if tok.startswith("--run="):
+            run_id = tok[6:]
+        if tok.startswith("--store-dir="):
+            store_dir = tok[12:]
+
+    if run_id is None:
+        run_id = os.environ.get("ARCTX_RUN_ID")
+
+    if run_id is None:
+        # Try <gitdir>/arctx-id
+        try:
+            from arctx_cli.paths import find_repo_root, read_arctx_id  # noqa: PLC0415
+
+            repo_root = find_repo_root()
+            run_id = read_arctx_id(repo_root)
+        except Exception:  # noqa: BLE001
+            pass
+
+    if run_id is None:
+        return None
+
+    if store_dir is None:
+        try:
+            from arctx_cli.paths import resolve_store_dir  # noqa: PLC0415
+
+            store_dir = resolve_store_dir()
+        except Exception:  # noqa: BLE001
+            return None
+
+    candidate = Path(store_dir) / run_id
+    return str(candidate) if candidate.is_dir() else None
+
+
+def _collect_ext_default_aliases(run_dir: str | None) -> list[dict[str, str]]:
+    """Load default_aliases from extensions enabled in the current run."""
+    from arctx.ext import load_extension  # noqa: PLC0415
+    from arctx.ext.enabled import load_enabled  # noqa: PLC0415
+
+    ext_aliases: list[dict[str, str]] = []
+    seen: set[str] = set()
+    if run_dir is None:
+        return ext_aliases
+
+    for ee in load_enabled(run_dir):
+        if ee.name in seen:
+            continue
+        try:
+            ext = load_extension(ee.name)
+            ext_aliases.append(ext.default_aliases())
+            seen.add(ext.name)
+        except (KeyError, ImportError):
+            continue
+    return ext_aliases
+
+
+def parse_args(argv: list[str] | None = None):
+    """Parse CLI arguments."""
+    tokens: list[str] | None = None if argv is None else list(argv)
+    run_dir = _resolve_run_dir_for_alias(tokens or sys.argv[1:])
+    parser = _build_parser(run_dir=run_dir)
+    return parser.parse_args(argv)
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Run the CLI entry point."""
+    tokens: list[str] = list(argv if argv is not None else sys.argv[1:])
+
+    # --- Alias resolution (one level only) ---
+    run_dir = _resolve_run_dir_for_alias(tokens)
+    ext_aliases = _collect_ext_default_aliases(run_dir)
+    from arctx_cli.alias import load_alias_table, resolve_alias  # noqa: PLC0415
+
+    alias_table = load_alias_table(
+        run_dir=run_dir,
+        extensions_default_aliases=ext_aliases,
+    )
+    tokens = resolve_alias(alias_table, tokens)
+    # ---
+
+    parser = _build_parser(run_dir=run_dir)
+    args = parser.parse_args(tokens)
+    handler = getattr(args, "_arctx_handler", None)
+    if handler is not None:
+        return handler(args)
+
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

arctx_cli/paths.py

@@ -0,0 +1,27 @@
+"""ARCTX path resolution — re-exports from arctx.paths.
+
+All path logic lives in arctx.paths. This module re-exports the public
+symbols so that CLI code can use ``from arctx_cli.paths import ...``.
+"""
+
+from arctx.paths import (  # noqa: F401
+    find_repo_root,
+    read_arctx_id,
+    resolve_git_dir,
+    resolve_arctx_home,
+    resolve_store_dir,
+    runs_dir,
+    arctx_id_path,
+    write_arctx_id,
+)
+
+__all__ = [
+    "find_repo_root",
+    "read_arctx_id",
+    "resolve_git_dir",
+    "resolve_arctx_home",
+    "resolve_store_dir",
+    "runs_dir",
+    "arctx_id_path",
+    "write_arctx_id",
+]

arctx_cli/payload_builder.py

@@ -0,0 +1,23 @@
+"""Re-export payload builder helpers from arctx.payload_builder.
+
+The implementation lives in arctx so that arctx-tui and other non-CLI
+consumers can use it without depending on arctx-cli.
+"""
+
+from arctx.payload_builder import (  # noqa: F401
+    _dict_field,
+    build_payload,
+    parse_field_args,
+    parse_json_object,
+    payload_schema,
+    payload_type_names,
+)
+
+__all__ = [
+    "_dict_field",
+    "build_payload",
+    "parse_field_args",
+    "parse_json_object",
+    "payload_schema",
+    "payload_type_names",
+]

arctx_cli/workspace.py

@@ -0,0 +1,64 @@
+"""Workspace-local cursor persistence.
+
+Cursors are view state for UI and wrapper commands. Core RunHandle
+writers must not read this module.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from arctx.core.types import JSONValue, to_jsonable
+
+
+@dataclass(frozen=True)
+class CursorRecord:
+    cursor_id: str
+    user_id: str
+    run_id: str
+    target_kind: str
+    target_id: str
+    label: str = ""
+    metadata: dict[str, JSONValue] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, JSONValue]:
+        return to_jsonable(self)  # type: ignore[return-value]
+
+
+def workspace_dir(store_dir: str) -> Path:
+    return Path(store_dir).parent / "workspace"
+
+
+def cursors_path(store_dir: str) -> Path:
+    return workspace_dir(store_dir) / "cursors.json"
+
+
+def load_cursors(store_dir: str) -> dict[str, CursorRecord]:
+    path = cursors_path(store_dir)
+    if not path.exists():
+        return {}
+    data = json.loads(path.read_text(encoding="utf-8"))
+    return {
+        cursor_id: CursorRecord(**record)
+        for cursor_id, record in data.get("cursors", {}).items()
+    }
+
+
+def save_cursor(record: CursorRecord, store_dir: str) -> Path:
+    cursors = load_cursors(store_dir)
+    cursors[record.cursor_id] = record
+    path = cursors_path(store_dir)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(
+        json.dumps(
+            {"cursors": {key: value.to_dict() for key, value in cursors.items()}},
+            ensure_ascii=False,
+            indent=2,
+            sort_keys=True,
+        )
+        + "\n",
+        encoding="utf-8",
+    )
+    return path

arctx_cli-0.2.0b2.dist-info/METADATA

@@ -0,0 +1,48 @@
+Metadata-Version: 2.4
+Name: arctx-cli
+Version: 0.2.0b2
+Summary: ARCTX CLI: command-line interface for arctx
+Project-URL: Homepage, https://github.com/takumiecd/stag
+Project-URL: Repository, https://github.com/takumiecd/stag
+Author: Takumi Ishida
+License: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Requires-Dist: arctx>=0.2.0b2
+Provides-Extra: dev
+Requires-Dist: black>=23.0; extra == 'dev'
+Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# arctx-cli
+
+Command-line interface and TUI for ARCTX (Arc + Context).
+
+## Installation
+
+```bash
+pip install arctx-cli
+```
+
+This also installs `arctx` as a dependency.
+
+## Usage
+
+```bash
+arctx init
+arctx transition create --from <node_id> --payload-type <type>
+arctx dump
+```
+
+## Package layout
+
+This package provides the `arctx` CLI command and TUI. The core API is in the separate `arctx` package.

arctx_cli-0.2.0b2.dist-info/RECORD

@@ -0,0 +1,49 @@
+arctx_cli/__init__.py,sha256=tDpQZYOaVdRiUQlhxcxtS0ujm9uxGXH16GO_DkmgtP8,25
+arctx_cli/alias.py,sha256=JQsuVnTp7mxIXKPSyQZIjWdpurE_4lJSKUHGNImCiyo,7488
+arctx_cli/append_batch.py,sha256=HoM7x1_MtFlhd_C4HRU2rUrVB_3LhOXApvK6TzSi8K8,3085
+arctx_cli/context.py,sha256=R9Le8Izkb30jQDql3MT2JdmhZHmCc0uxvkx64Ok10yo,1210
+arctx_cli/ext_registry.py,sha256=q6k_f21QWpJuhKdEHIXxQ9yLBy-xSYICwedc4S6O3gk,1114
+arctx_cli/main.py,sha256=dvMBhxm_f3SDIaeX7XBrzwiwCITsGE_jSIWp1le3dO8,3996
+arctx_cli/paths.py,sha256=bBf-nNrFEP5753ELHSTtFxyvIoc8mbI_acCOEzVzCkI,598
+arctx_cli/payload_builder.py,sha256=VS4xw-DUOrdLW1wFtp5vzNPRe5DmfBvSQkEhwVRMY1w,523
+arctx_cli/workspace.py,sha256=BBC55RAVdSVdbS9y10x-FSqEEMevgxq_-AgDeTwlH9U,1670
+arctx_cli/commands/__init__.py,sha256=VirPNWS9gN7XTIoaXAL_mIRMULzfwyeD0sz4TOv4d8M,4600
+arctx_cli/commands/alias_cmd.py,sha256=67CHgfZMQ7Ooj7AEQo3q-MaoWWCPoyPZqQIJMJUXI64,5972
+arctx_cli/commands/anchor.py,sha256=RoLIIyGQS4lRYHocfNv3i_sKxMjUJ87xB7RaFEQdSWk,2359
+arctx_cli/commands/current.py,sha256=BPxOR0fynkLtt4DOMaGflX018oPS9F0_NGngwOaZUIA,1929
+arctx_cli/commands/cut.py,sha256=lSXE_JJsM-dqsdODrdCy-6a-9Njoqsr8pQ8dqB6p0hY,2811
+arctx_cli/commands/dump.py,sha256=Ky8dIDf_9fACI_1Ee5fglWlaBCnT--weJsrz-zc96v4,2554
+arctx_cli/commands/ext.py,sha256=88VwLJtRldDhVsAolUdN_HLKG7fKByG5Oo6q8LwrkIQ,7463
+arctx_cli/commands/git.py,sha256=LsNuroSTcq0pACIQu8A3n6I-FZ9f65gD0S0R4BavcMA,7590
+arctx_cli/commands/graph.py,sha256=vPu2mpehPCiNu9ltlqAszi-iA8G9ROPWLzQkv4IBU-c,2740
+arctx_cli/commands/guide.py,sha256=CNURTljNgV9kbDt8Ht7FmPh-Qbxa0gW29UY2uIsAbU4,11815
+arctx_cli/commands/init.py,sha256=58J4LbV7kKFXIk7WJ5FCZ95Y7fVrWhg3e7xxNnFrei0,7531
+arctx_cli/commands/list.py,sha256=hZ22SnPOlKO6g2FM9GPSa_U4yjicgPfpa9BanVqbhGU,1111
+arctx_cli/commands/migrate.py,sha256=egWT_lAaFWbtX8XhM_VhtlFoazOnkiaOZOUmUiLnuEQ,3973
+arctx_cli/commands/node.py,sha256=amoC7gnUvLMMIA1sHJ70K-MkaHQzz61NH06MpJiBupQ,1793
+arctx_cli/commands/outcomes.py,sha256=rhJ6zZMZlskYtTaFSourlRvQCGEl3lzco8OjdoptRgE,1695
+arctx_cli/commands/payload.py,sha256=0yrEfP9JoeJVVLUTydaKeGUcIBD2o-1e8ztTB2EZviw,7074
+arctx_cli/commands/reachable.py,sha256=oIYtOXcxDu3N4UGc-_E3N-pK3WSzW8QIrnATyhdxdds,2422
+arctx_cli/commands/show.py,sha256=W3DECjql6STWbrjcntT2RhhnnFIqa-zPKBGj_lquVnE,3987
+arctx_cli/commands/sync.py,sha256=OkYethlMklqYR4S7tOhoa5jzrdQ_6dNEKGF1xxGldaQ,7536
+arctx_cli/commands/trace.py,sha256=gecrPriUo15OUvSZF8PwK9sV9HpVnzI1ZkpzaAn2VbY,1252
+arctx_cli/commands/transition.py,sha256=7-6kChKCVCfSHIaDNHUASpVr-_jz7BwiyjzqHlpDVJA,7410
+arctx_cli/commands/use.py,sha256=OpRvIxKEMTFisqEbGglv0zrMzBypT01W6ZNUoXyK8S0,1801
+arctx_cli/commands/view.py,sha256=U7o7Co4VTfXfcEmNgUFf6zjcN-GOVkk7WVSnBEchYzo,2761
+arctx_cli/commands/work_session.py,sha256=yvFJTZisZMDanm7s-FiOpOfpUES4kVwWbubgrW0lPVE,11813
+arctx_cli/ext/__init__.py,sha256=Ju-TMDVdaYLxi5y60gzj7YWk9mp-3Jq10atMqhxl4a0,38
+arctx_cli/ext/command/__init__.py,sha256=NZhLiTrwNUpwnOgtXAJ4QmpCKek2UUKGHlwq4MmdT9g,3543
+arctx_cli/ext/git/__init__.py,sha256=vLdXnqplyPPu-3F4oFPN46RwaDdxvrEC5UyjSOqk7pw,24
+arctx_cli/ext/git/branch.py,sha256=0_wnyRh9x8_C2stRiuFdIGHihbhUlcxvdVJV8e_S5Gw,4724
+arctx_cli/ext/git/cherry_pick.py,sha256=vzb_zcgm7t8n9JGi7xTgHE3tj4h-hc6vEpBFf5Ay0h0,4422
+arctx_cli/ext/git/commit.py,sha256=Mo3G7ecId9rY90cC_y2YNFGw4V7pbrwXhMMRL8PKNSY,6368
+arctx_cli/ext/git/hook.py,sha256=uwNMagpJJb3fINgY9FjaLCBS06njcG1SiRFcEO68SeM,26489
+arctx_cli/ext/git/merge.py,sha256=wXQZWhlhYgZWW8sVvpj44xHF1D9aKbXE3tC9Lhs3abU,6064
+arctx_cli/ext/git/reset.py,sha256=vHjD5YYvxPmkDyQ7ekT6PYjqI1Bg2o75phoUZJosfkQ,3845
+arctx_cli/ext/git/revert.py,sha256=JOK6JzBG1Su1awU1kqw9dDWDIxPYLGP-0AG_srTxKtE,5010
+arctx_cli/ext/git/verify.py,sha256=jhfDYqe3EhMgpZv17PLhwUyuT-FEjVgwKzwZB1_av4k,3861
+arctx_cli/ext/git/worktree.py,sha256=T-jeswPQkNyuui3ROgOguaNkaqx7P-twmT6cbLOncgA,5698
+arctx_cli-0.2.0b2.dist-info/METADATA,sha256=biiMYiIGb8EwWOZs-6Q9iTXe6QlBunMqsRRgQtCkp1o,1335
+arctx_cli-0.2.0b2.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+arctx_cli-0.2.0b2.dist-info/entry_points.txt,sha256=GF0iaqs7ahYtV7IBIvm1Y_DuII2cDJicSD5UZNLr-RU,46
+arctx_cli-0.2.0b2.dist-info/RECORD,,

arctx_cli-0.2.0b2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

arctx_cli-0.2.0b2.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+arctx = arctx_cli.main:main