arctx-cli 0.2.0b2__py3-none-any.whl

arctx_cli/commands/graph.py

@@ -0,0 +1,73 @@
+"""arctx graph commands."""
+
+from __future__ import annotations
+
+import argparse
+import json
+
+from arctx_cli.commands.dump import run_dump_command
+from arctx_cli.commands.reachable import run_reachable_command
+from arctx_cli.commands.trace import run_trace_command
+from arctx_cli.context import resolve_run_id_from_args
+
+
+def add_parser(subparsers) -> argparse.ArgumentParser:
+    parser = subparsers.add_parser("graph", help="Inspect graph structure")
+    graph_sub = parser.add_subparsers(dest="graph_command", required=True)
+
+    sp_dump = graph_sub.add_parser("dump", help="Render the graph")
+    sp_dump.add_argument("--format", dest="fmt", choices=["outline", "mermaid"], default="outline")
+    sp_dump.add_argument("--node", dest="node_id", default=None)
+    sp_dump.add_argument("--depth", type=int, default=None)
+    sp_dump.add_argument("--full-payloads", action="store_true")
+    sp_dump.add_argument("--run", default=None)
+    sp_dump.add_argument("--store-dir", default=None)
+
+    sp_trace = graph_sub.add_parser("trace", help="Trace history from a node")
+    sp_trace.add_argument("node_id")
+    sp_trace.add_argument("--depth", type=int, default=None)
+    sp_trace.add_argument("--run", default=None)
+    sp_trace.add_argument("--store-dir", default=None)
+
+    sp_reachable = graph_sub.add_parser("reachable", help="Show active graph forward from a node")
+    sp_reachable.add_argument("node_id")
+    sp_reachable.add_argument("--include-records", action="store_true")
+    sp_reachable.add_argument("--run", default=None)
+    sp_reachable.add_argument("--store-dir", default=None)
+
+    return parser
+
+
+def cli_graph(args) -> int:
+    if args.graph_command == "dump":
+        print(
+            run_dump_command(
+                run_id=resolve_run_id_from_args(args),
+                fmt=args.fmt,
+                store_dir=args.store_dir,
+                node_id=args.node_id,
+                depth=args.depth,
+                full_payloads=args.full_payloads,
+            )
+        )
+        return 0
+    if args.graph_command == "trace":
+        result = run_trace_command(
+            run_id=resolve_run_id_from_args(args),
+            from_node_id=args.node_id,
+            depth=args.depth,
+            store_dir=args.store_dir,
+        )
+        print(json.dumps(result["history"], ensure_ascii=False, indent=2))
+        return 0
+    if args.graph_command == "reachable":
+        result = run_reachable_command(
+            run_id=resolve_run_id_from_args(args),
+            from_node=args.node_id,
+            view_name=None,
+            include_records=args.include_records,
+            store_dir=args.store_dir,
+        )
+        print(json.dumps(result, ensure_ascii=False, indent=2))
+        return 0
+    return 1

arctx_cli/commands/guide.py

@@ -0,0 +1,360 @@
+"""arctx CLI guide command."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+TOPICS_EN: dict[str, str] = {
+    "overview": """\
+# arctx guide
+
+arctx records optimization and problem-solving work as an append-only RunGraph DAG.
+
+The graph skeleton has two record types:
+
+- Node: a state or point in the work history.
+- Transition: a step from one or more input nodes to exactly one output node.
+
+Meaning is attached as payloads. TransitionPayload, NodePayload,
+GitChangePayload, and CutPayload explain what a node or transition means.
+
+Basic loop:
+
+```text
+init -> transition -> dump
+```
+
+Common commands:
+
+```bash
+arctx init req_demo --run-id demo
+eval "$(arctx work-session env --run demo --new)"
+arctx transition create --run demo --from <node_id> \\
+  --payload-type transition_payload --field type=experiment --field name=baseline
+arctx payload add --run demo --node <node_id> \\
+  --payload-type node_payload --field type=note --field text="context here"
+arctx graph dump --run demo
+```
+""",
+    "agent": """\
+# Agent Rules
+
+- Treat Node and Transition IDs as opaque.
+- Put domain meaning in payloads (TransitionPayload / NodePayload), not in graph fields.
+- Use `arctx transition create` to record attempts.
+- Use `arctx payload add` for node or transition annotations.
+- Use `arctx graph dump` when you need broad context.
+- Use CutPayload through `arctx cut` instead of deleting records.
+- For parallel work, pin each process to a distinct work session with
+  `arctx work-session env --run <run_id> --new` or pass `--work-session` explicitly.
+""",
+    "work-session": """\
+# Work Sessions
+
+Use a work session to separate one process, terminal, or worker's history inside
+the same run.
+
+There are two supported modes.
+
+Explicit mode passes the session on every mutating command:
+
+```bash
+arctx transition create --run demo --work-session ws_a --from <node_id> \\
+  --payload-type transition_payload --field type=experiment
+```
+
+Fixed mode stores the run/session in the current shell environment, not in
+the shared `<gitdir>/arctx-id` pointer:
+
+```bash
+eval "$(arctx work-session env --run demo --new)"
+arctx transition create --from <node_id> --payload-type transition_payload
+```
+
+For sub processes, use `spawn`; each invocation creates or uses one session and
+passes `ARCTX_RUN_ID`, `ARCTX_WORK_SESSION_ID`, and `ARCTX_USER_ID` only to the child.
+
+```bash
+arctx work-session spawn --run demo -- codex
+arctx work-session spawn --run demo -- claude
+```
+""",
+    "dump": """\
+# Dump
+
+`arctx graph dump` renders the active graph in outline or mermaid form. Each
+Transition has exactly one output Node. Cut records render with `✂`; revisited
+nodes with `↻`.
+""",
+    "record": """\
+# Record One Experiment
+
+```bash
+arctx init req_demo --run-id demo
+arctx transition create --run demo --from <root_node_id> \\
+  --payload-type transition_payload --field type=experiment --field name=run1
+arctx transition show --run demo <transition_id> --with-payloads
+```
+""",
+    "payloads": """\
+# Payloads
+
+- TransitionPayload attaches to a Transition. Use `type` to describe the kind of step.
+- NodePayload attaches to a Node. Use `type` to describe the kind of annotation.
+- GitChangePayload attaches to a Transition with git commit / diff info.
+- CutPayload attaches to a Node or Transition to mark it inactive.
+
+Custom subclasses of PayloadBase can be registered with `register_payload_class()`.
+""",
+    "cut": """\
+# Cut
+
+`arctx cut --node <node_id>` or `arctx cut --transition <transition_id>` appends
+an append-only CutPayload. Records are not deleted; inactive branches are computed at read time.
+""",
+    "joins": """\
+# Joins (Multi-input Transitions)
+
+Pass multiple `--from` values to `arctx transition create` to create a
+Transition with multiple input nodes but still exactly one output node.
+""",
+    "git": """\
+# Git
+
+Git commands attach commit information to a Transition.
+
+```bash
+arctx git add --run demo --transition <transition_id> --commit <sha>
+arctx git list --run demo --transition <transition_id>
+arctx git show --run demo --transition <transition_id>
+```
+""",
+}
+
+
+TOPICS_JA: dict[str, str] = {
+    "overview": """\
+# arctx guide
+
+arctx は作業履歴を append-only な DAG として記録します。
+
+グラフ骨格はこの 2 種類だけです。
+
+- Node: 作業履歴上の状態や地点。
+- Transition: 1 つ以上の Node から 1 つの output Node への作業ステップ。
+
+意味は payload に分離します。TransitionPayload / NodePayload /
+GitChangePayload / CutPayload が、Node や Transition に意味を付けます。
+
+基本ループ:
+
+```text
+init -> transition -> dump
+```
+
+よく使うコマンド:
+
+```bash
+arctx init req_demo --run-id demo
+eval "$(arctx work-session env --run demo --new)"
+arctx transition create --run demo --from <node_id> \\
+  --payload-type transition_payload --field type=experiment --field name=baseline
+arctx payload add --run demo --node <node_id> \\
+  --payload-type node_payload --field type=note --field text="context here"
+arctx graph dump --run demo
+```
+""",
+    "agent": """\
+# Agent Rules
+
+- Node / Transition ID は opaque として扱う。
+- ドメイン上の意味は graph record ではなく payload に入れる。
+- 作業の記録は `arctx transition create` を使う。
+- Node / Transition への注釈は `arctx payload add` を使う。
+- 広い文脈確認は `arctx graph dump` を使う。
+- 履歴は削除せず、`arctx cut` で CutPayload を追加する。
+- 並列作業では `arctx work-session env --run <run_id> --new` でプロセスごとに
+  別 work session を固定するか、毎回 `--work-session` を明示する。
+""",
+    "work-session": """\
+# Work Sessions
+
+work session は、同じ run の中で、1 つのプロセス・ターミナル・worker の履歴を
+分けるための単位です。
+
+使い方は 2 種類あります。
+
+毎回明示モードでは、mutating command ごとに session を渡します。
+
+```bash
+arctx transition create --run demo --work-session ws_a --from <node_id> \\
+  --payload-type transition_payload --field type=experiment
+```
+
+固定モードでは、共有の `<gitdir>/arctx-id` ではなく、現在の shell 環境に run/session
+を固定します。並列ターミナルや sub process ではこちらを使います。
+
+```bash
+eval "$(arctx work-session env --run demo --new)"
+arctx transition create --from <node_id> --payload-type transition_payload
+```
+
+sub process を起動する場合は `spawn` を使います。各 invocation は 1 つの session
+を作成または使用し、子プロセスだけに `ARCTX_RUN_ID` / `ARCTX_WORK_SESSION_ID` /
+`ARCTX_USER_ID` を渡します。
+
+```bash
+arctx work-session spawn --run demo -- codex
+arctx work-session spawn --run demo -- claude
+```
+""",
+    "dump": """\
+# Dump
+
+`arctx graph dump` は active graph を outline または mermaid 形式で表示します。
+各 Transition は必ず 1 つの output Node を持ちます。Cut 済みレコードは `✂`、
+再訪した Node は `↻` で表示されます。
+""",
+    "record": """\
+# 1 つの実験を記録する
+
+```bash
+arctx init req_demo --run-id demo
+arctx transition create --run demo --from <root_node_id> \\
+  --payload-type transition_payload --field type=experiment --field name=run1
+arctx transition show --run demo <transition_id> --with-payloads
+```
+""",
+    "payloads": """\
+# Payloads
+
+- TransitionPayload は Transition に付けます。`type` で作業ステップの種類を表します。
+- NodePayload は Node に付けます。`type` で注釈の種類を表します。
+- GitChangePayload は Transition に付け、commit 情報を保持します。
+- CutPayload は Node または Transition に付け、inactive として扱うために使います。
+
+独自の PayloadBase サブクラスは `register_payload_class()` で登録できます。
+""",
+    "cut": """\
+# Cut
+
+`arctx cut node <node_id>` または `arctx cut transition <transition_id>` は
+append-only な CutPayload を追加します。レコードは削除されません。inactive な
+branch は読み取り時に計算されます。
+""",
+    "joins": """\
+# Joins (Multi-input Transitions)
+
+`arctx transition create` に複数の `--from` を渡すと、複数 input node から
+1 つの output node へ向かう Transition を作成できます。
+""",
+    "git": """\
+# Git
+
+Git コマンドは Transition に commit 情報を付けます。
+
+```bash
+arctx git add --run demo --transition <transition_id> --commit <sha>
+arctx git list --run demo --transition <transition_id>
+arctx git show --run demo --transition <transition_id>
+```
+""",
+}
+
+
+GUIDES: dict[str, dict[str, str]] = {
+    "ja": TOPICS_JA,
+    "en": TOPICS_EN,
+}
+
+TOPIC_SUMMARIES: dict[str, dict[str, str]] = {
+    "en": {
+        "overview": "Concept, RunGraph model, basic loop",
+        "agent": "Rules for agents using arctx",
+        "dump": "arctx graph dump output model",
+        "record": "Typical workflow to record one experiment",
+        "work-session": "Separate parallel process history within one run",
+        "payloads": "Payload types and attachment targets",
+        "cut": "Append-only invalidation",
+        "joins": "Multi-input transitions",
+        "git": "Record Git commits on a Transition",
+    },
+    "ja": {
+        "overview": "概念、RunGraph model、基本ループ",
+        "agent": "arctx を使う agent 向けルール",
+        "dump": "arctx graph dump の出力モデル",
+        "record": "1 つの実験を記録する基本フロー",
+        "work-session": "同じ run 内で並列プロセスの履歴を分ける",
+        "payloads": "Payload の種類と attachment target",
+        "cut": "Append-only な無効化",
+        "joins": "複数 input node の Transition",
+        "git": "Transition への Git commit 記録",
+    },
+}
+
+_DEFAULT_TOPIC = "overview"
+
+
+def run_guide_command(*, lang: str = "en", topic: str = _DEFAULT_TOPIC) -> dict:
+    """Return the guide text for *topic* in *lang*."""
+    topics = GUIDES[lang]
+    if topic not in topics:
+        valid = ", ".join(sorted(topics))
+        raise ValueError(f"Unknown topic {topic!r}. Valid topics: {valid}")
+    return {"guide": topics[topic], "lang": lang, "topic": topic}
+
+
+def run_guide_list(lang: str = "en") -> dict:
+    """Return topic id + summary pairs for *lang*."""
+    topics = GUIDES[lang]
+    summaries = TOPIC_SUMMARIES[lang]
+    return {
+        "topics": [{"id": tid, "summary": summaries.get(tid, "")} for tid in topics],
+        "lang": lang,
+    }
+
+
+def add_parser(subparsers) -> argparse.ArgumentParser:
+    parser = subparsers.add_parser(
+        "guide",
+        help="Show the arctx concept and CLI workflow guide",
+    )
+    parser.add_argument(
+        "--lang",
+        choices=sorted(GUIDES),
+        default="en",
+        help="Guide language (default: en)",
+    )
+    parser.add_argument(
+        "--topic",
+        default=None,
+        metavar="NAME",
+        help="Show a specific subtopic (see --list for names)",
+    )
+    parser.add_argument(
+        "--list",
+        action="store_true",
+        dest="list_topics",
+        help="List available topic names and descriptions",
+    )
+    return parser
+
+
+def cli_guide(args) -> int:
+    if args.list_topics:
+        result = run_guide_list(lang=args.lang)
+        for entry in result["topics"]:
+            print(f"  {entry['id']:<12}  {entry['summary']}")
+        return 0
+
+    topic = args.topic if args.topic is not None else _DEFAULT_TOPIC
+    try:
+        result = run_guide_command(lang=args.lang, topic=topic)
+    except ValueError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        print("Run `arctx guide --list` to see available topics.", file=sys.stderr)
+        return 1
+
+    print(result["guide"])
+    return 0

arctx_cli/commands/init.py

@@ -0,0 +1,223 @@
+"""arctx CLI init command."""
+
+from __future__ import annotations
+
+import argparse
+
+import arctx as arctx
+from arctx_cli.context import resolve_store
+from arctx_cli.paths import find_repo_root, resolve_store_dir, arctx_id_path, write_arctx_id
+from arctx.core.schema.requirements import Requirement
+
+
+def add_parser(subparsers) -> argparse.ArgumentParser:
+    """Register the ``init`` subcommand parser."""
+    parser = subparsers.add_parser("init", help="Initialize a new run")
+    parser.add_argument("requirement_id", help="Requirement identifier")
+    parser.add_argument(
+        "--target-type",
+        default="code",
+        help="Target category (default: code)",
+    )
+    parser.add_argument(
+        "--target-id",
+        default=None,
+        help="Specific target identifier (default: requirement_id)",
+    )
+    parser.add_argument(
+        "--run-id",
+        default=None,
+        help="Explicit run id (default: auto-generated)",
+    )
+    parser.add_argument(
+        "--store-dir",
+        default=None,
+        help="Directory to save runs (default: <ARCTX_HOME>/runs)",
+    )
+    parser.add_argument(
+        "--no-hooks",
+        action="store_true",
+        help="Skip installing git hooks (post-rewrite etc.)",
+    )
+    parser.add_argument(
+        "--extension",
+        action="append",
+        default=[],
+        dest="extension",
+        metavar="NAME",
+        help="Enable extension by name (may be repeated)",
+    )
+
+    # Pre-register init options from all built-in extensions so that
+    # extension-specific flags (e.g. --dummy-flag) are accepted at parse time.
+    from arctx.ext import list_available, load_extension  # noqa: PLC0415
+
+    for ext_name in list_available():
+        try:
+            ext = load_extension(ext_name)
+            ext.register_init_options(parser)
+        except Exception:  # noqa: BLE001
+            continue
+
+    return parser
+
+
+def run_init_command(
+    *,
+    requirement_id: str,
+    target_type: str,
+    target_id: str | None,
+    run_id: str | None,
+    store_dir: str | None,
+    no_hooks: bool = False,
+    extensions: list[str] | None = None,
+    extension_options: dict[str, object] | None = None,
+) -> dict[str, str]:
+    """Create a new run and save it to disk.
+
+    Parameters
+    ----------
+    requirement_id:
+        Identifier for the requirement.
+    target_type:
+        Category of the target (e.g. "code", "kernel").
+    target_id:
+        Specific target identifier.
+    run_id:
+        Explicit run id. If None, one is generated automatically.
+    store_dir:
+        Directory under which run directories are created.
+        If None, defaults to ``<ARCTX_HOME>/runs``.
+    no_hooks:
+        If True, skip installing git hooks.
+    extensions:
+        Names of extensions to enable.  Each extension's ``on_init`` is called
+        and the extension is recorded in ``<run_dir>/extensions.json``.
+    extension_options:
+        Flat dict of parsed argparse values for extension-specific options,
+        keyed by their ``dest`` names (e.g. ``ext__dummy_dummy_flag``).
+
+    Returns
+    -------
+    dict with at least ``run_id``, ``root_node_id``, and ``arctx_id_path``
+    (the path where the active-run pointer was written under ``<gitdir>/``,
+    or None if not in a git repo).
+
+    Raises
+    ------
+    FileExistsError
+        If the run directory already exists.
+    KeyError
+        If an extension name is not in the built-in registry.
+    """
+    resolved_store_dir = store_dir if store_dir is not None else resolve_store_dir()
+
+    requirement = Requirement(
+        requirement_id=requirement_id,
+        target_type=target_type,
+        target_id=target_id or requirement_id,
+    )
+
+    handle = arctx.init(requirement, run_id=run_id)
+
+    store = resolve_store(resolved_store_dir)
+    run_path = store.run_path(handle.run_id)
+    if run_path.exists():
+        raise FileExistsError(f"run directory already exists: {run_path}")
+
+    store.save_run(handle)
+
+    # Write the active-run pointer under <gitdir>/arctx-id if we are
+    # inside a git repo. Living under .git/ means git itself never
+    # tracks it, so there is no risk of accidental commits.
+    written_arctx_id_path: str | None = None
+    try:
+        repo_root = find_repo_root()
+        write_arctx_id(repo_root, handle.run_id)
+        written_arctx_id_path = str(arctx_id_path(repo_root))
+    except RuntimeError:
+        # Not inside a git repo — skip pointer creation silently.
+        pass
+
+    installed_hook_path: str | None = None
+    hook_warning: str | None = None
+
+    # Activate requested extensions.
+    enabled_extensions: list[str] = []
+    if extensions:
+        from arctx.ext import load_extension  # noqa: PLC0415
+        from arctx.ext.base import InitContext  # noqa: PLC0415
+        from arctx.ext.enabled import EnabledExtension, add_enabled  # noqa: PLC0415
+
+        for ext_name in extensions:
+            ext = load_extension(ext_name)  # raises KeyError for unknown names
+            opts = dict(extension_options or {})
+            if no_hooks:
+                opts["ext_git_no_hooks"] = True
+            git_hook_existed = False
+            if ext.name == "git" and not opts.get("ext_git_no_hooks"):
+                try:
+                    git_hook_existed = (
+                        find_repo_root() / ".git" / "hooks" / "post-rewrite"
+                    ).exists()
+                except RuntimeError:
+                    git_hook_existed = False
+            ctx = InitContext(
+                run_id=handle.run_id,
+                run_dir=str(run_path),
+                options=opts,
+            )
+            ext.on_init(ctx)
+            if ext.name == "git" and not opts.get("ext_git_no_hooks"):
+                try:
+                    hook_path = find_repo_root() / ".git" / "hooks" / "post-rewrite"
+                    if hook_path.exists() and not git_hook_existed:
+                        installed_hook_path = str(hook_path)
+                    elif hook_path.exists() and git_hook_existed:
+                        hook_warning = f"hook already exists: {hook_path}"
+                except RuntimeError:
+                    pass
+            add_enabled(run_path, EnabledExtension(name=ext.name, version=ext.version, config={}))
+            enabled_extensions.append(ext_name)
+
+    return {
+        "run_id": handle.run_id,
+        "root_node_id": handle.root_node_id,
+        "store_dir": resolved_store_dir,
+        "arctx_id_path": written_arctx_id_path,
+        "hook_path": installed_hook_path,
+        "hook_warning": hook_warning,
+        "enabled_extensions": enabled_extensions,
+    }
+
+
+def cli_init(args) -> int:
+    """Entry point for ``arctx init`` subcommand.
+
+    Prints the generated run_id to stdout on success.
+    """
+    import sys
+
+    try:
+        result = run_init_command(
+            requirement_id=args.requirement_id,
+            target_type=args.target_type,
+            target_id=args.target_id,
+            run_id=args.run_id,
+            store_dir=args.store_dir,
+            no_hooks=args.no_hooks,
+            extensions=list(args.extension or []),
+            extension_options=vars(args),
+        )
+    except KeyError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+    print(result["run_id"])
+    if result.get("hook_path"):
+        print(
+            f"hint: git hook installed at {result['hook_path']}",
+            file=sys.stderr,
+        )
+    if result.get("hook_warning"):
+        print(f"warning: {result['hook_warning']}", file=sys.stderr)
+    return 0

arctx_cli/commands/list.py

@@ -0,0 +1,45 @@
+"""arctx CLI list command."""
+
+from __future__ import annotations
+
+import argparse
+import json
+
+from arctx_cli.context import resolve_store
+
+
+def add_parser(subparsers) -> argparse.ArgumentParser:
+    """Register the ``list`` subcommand parser."""
+    parser = subparsers.add_parser("list", help="List saved runs")
+    parser.add_argument(
+        "--store-dir",
+        default=None,
+        help="Directory where runs are stored (default: .arctx/runs)",
+    )
+    return parser
+
+
+def run_list_command(*, store_dir: str) -> dict:
+    """List all runs in the store directory.
+
+    Parameters
+    ----------
+    store_dir:
+        Directory where runs are stored.
+
+    Returns
+    -------
+    dict with ``runs`` key containing a list of run summary dicts.
+    """
+    store = resolve_store(store_dir)
+    return {"runs": store.list_runs()}
+
+
+def cli_list(args) -> int:
+    """Entry point for ``arctx list`` subcommand.
+
+    Prints the list of runs as JSON to stdout.
+    """
+    result = run_list_command(store_dir=args.store_dir)
+    print(json.dumps(result["runs"], ensure_ascii=False, indent=2))
+    return 0