arctx-cli 0.3.1b2__tar.gz → 0.3.1b4__tar.gz

{arctx_cli-0.3.1b2 → arctx_cli-0.3.1b4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: arctx-cli
-Version: 0.3.1b2
+Version: 0.3.1b4
 Summary: CLI for ARCTX — append-only DAG editing and refactoring
 Project-URL: Homepage, https://github.com/takumiecd/arctx
 Project-URL: Repository, https://github.com/takumiecd/arctx
@@ -17,7 +17,7 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Topic :: Utilities
 Requires-Python: >=3.10
-Requires-Dist: arctx>=0.3.1b2
+Requires-Dist: arctx==0.3.1b4
 Provides-Extra: dev
 Requires-Dist: black>=23.0; extra == 'dev'
 Requires-Dist: mypy>=1.0; extra == 'dev'
@@ -26,9 +26,11 @@ Requires-Dist: pytest>=7.0; extra == 'dev'
 Requires-Dist: ruff>=0.1.0; extra == 'dev'
 Description-Content-Type: text/markdown
 
-# arctx-cli
+# ARCTX CLI
 
-Command-line interface and TUI for ARCTX (Arc + Context).
+Command-line interface for ARCTX experiment graphs. Use it to initialize runs,
+record steps, attach results, cut abandoned branches, export reports, and serve
+the Web GUI.
 
 ## Installation
 
@@ -41,11 +43,12 @@ This also installs `arctx` as a dependency.
 ## Usage
 
 ```bash
-arctx init
-arctx transition create --from <node_id> --payload-type <type>
+arctx init optimize --extension git --run-id demo
+arctx add --from <node_id> --type experiment --field variant=A
 arctx dump
 ```
 
 ## Package layout
 
-This package provides the `arctx` CLI command and TUI. The core API is in the separate `arctx` package.
+This package provides the `arctx` CLI command. The core API is in the separate
+`arctx` package; the experimental TUI is shipped separately as `arctx-tui`.

arctx_cli-0.3.1b4/README.md

@@ -0,0 +1,26 @@
+# ARCTX CLI
+
+Command-line interface for ARCTX experiment graphs. Use it to initialize runs,
+record steps, attach results, cut abandoned branches, export reports, and serve
+the Web GUI.
+
+## Installation
+
+```bash
+pip install arctx-cli
+```
+
+This also installs `arctx` as a dependency.
+
+## Usage
+
+```bash
+arctx init optimize --extension git --run-id demo
+arctx add --from <node_id> --type experiment --field variant=A
+arctx dump
+```
+
+## Package layout
+
+This package provides the `arctx` CLI command. The core API is in the separate
+`arctx` package; the experimental TUI is shipped separately as `arctx-tui`.

{arctx_cli-0.3.1b2 → arctx_cli-0.3.1b4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "arctx-cli"
-version = "0.3.1b2"
+version = "0.3.1b4"
 description = "CLI for ARCTX — append-only DAG editing and refactoring"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -25,7 +25,7 @@ classifiers = [
     "Topic :: Utilities",
 ]
 dependencies = [
-    "arctx>=0.3.1b2",
+    "arctx==0.3.1b4",
 ]
 
 [project.optional-dependencies]

{arctx_cli-0.3.1b2 → arctx_cli-0.3.1b4}/src/arctx_cli/append_batch.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 from arctx.core.append import AppendBatch, GraphRecordEnvelope
+from arctx.core.lanes import format_lane_validation_errors, lane_validation_errors
 
 
 def graph_counts(handle) -> dict[str, set[str]]:
@@ -12,6 +13,7 @@ def graph_counts(handle) -> dict[str, set[str]]:
         "steps": set(handle.run_graph.steps),
         "payloads": set(handle.run_graph.payloads),
         "work_events": {event.event_id for event in handle.run_graph.work_events},
+        "lane_error_count": {str(_lane_error_count(handle))},
     }
 
 
@@ -24,6 +26,8 @@ def maybe_append_or_save(
     before: dict[str, set[str]],
 ) -> None:
     """Use append_batch for capable stores, otherwise fall back to save_run."""
+    if _has_new_work_events(handle, before):
+        _ensure_no_new_lane_errors(handle, baseline=_baseline_lane_error_count(before))
     if user_id is None or lane_id is None or not hasattr(store, "append_batch"):
         store.save_run(handle)
         return
@@ -80,3 +84,36 @@ def build_append_batch(
 
 def _new_ids(current: dict[str, object], before: dict[str, set[str]], key: str) -> list[str]:
     return [record_id for record_id in current if record_id not in before.get(key, set())]
+
+
+def _has_new_work_events(handle, before: dict[str, set[str]]) -> bool:
+    return any(
+        event.event_id not in before.get("work_events", set())
+        for event in handle.run_graph.work_events
+    )
+
+
+def _lane_error_count(handle) -> int:
+    return len(
+        lane_validation_errors(
+            handle.run_graph,
+            root_node_id=handle.root_node_id,
+        )
+    )
+
+
+def _baseline_lane_error_count(before: dict[str, set[str]]) -> int:
+    values = before.get("lane_error_count", {"0"})
+    try:
+        return int(next(iter(values)))
+    except (StopIteration, ValueError):
+        return 0
+
+
+def _ensure_no_new_lane_errors(handle, *, baseline: int) -> None:
+    current = lane_validation_errors(
+        handle.run_graph,
+        root_node_id=handle.root_node_id,
+    )
+    if len(current) > baseline:
+        raise ValueError(format_lane_validation_errors(current[baseline:]))

arctx_cli-0.3.1b4/src/arctx_cli/commands/_lane_context.py

@@ -0,0 +1,91 @@
+"""Shared helpers for resolving the current lane and its active frontiers.
+
+Both ``arctx add`` (defaulting ``--from`` to the current lane's frontier) and
+``arctx guide`` (reporting "Active Frontiers in Lane") need the same three
+steps: resolve the active lane id (env / --lane / repo pointer), look up the
+``Lane`` object by id or name, and compute its active frontier nodes. Keeping
+this in one place means both commands agree on lane resolution order and on
+what counts as a frontier.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+def find_lane(handle, name_or_id: str):
+    """Resolve a Lane object by lane_id or by name. Returns None if absent."""
+    lane = handle.run_graph.lanes.get(name_or_id)
+    if lane is not None:
+        return lane
+    for candidate in handle.run_graph.lanes.values():
+        if candidate.name == name_or_id:
+            return candidate
+    return None
+
+
+@dataclass(frozen=True)
+class LaneFrontierContext:
+    """Resolution result: the lane id/name that was requested, the Lane object
+    found for it (if any), and its active frontier node ids."""
+
+    lane_id: str
+    lane_name: str | None
+    frontier_node_ids: tuple[str, ...]
+
+
+def resolve_lane_frontiers(handle, lane_id: str) -> LaneFrontierContext:
+    """Resolve ``lane_id`` (id or name) to its active frontier nodes.
+
+    ``lane_id`` should already be resolved via the canonical chain (explicit
+    flag / ``ARCTX_LANE_ID`` / repo pointer) — see
+    ``arctx_cli.context.resolve_lane_id_from_args``. This helper only does the
+    graph-level lookup: Lane object + frontier computation.
+    """
+    from arctx.core.lanes import lane_active_frontiers
+
+    lane = find_lane(handle, lane_id)
+    if lane is None:
+        return LaneFrontierContext(lane_id=lane_id, lane_name=None, frontier_node_ids=())
+    frontiers = lane_active_frontiers(handle.run_graph, lane.lane_id)
+    return LaneFrontierContext(
+        lane_id=lane.lane_id, lane_name=lane.name, frontier_node_ids=frontiers
+    )
+
+
+def root_frontier_fallback(handle) -> str | None:
+    """Return the run root node id if it is usable as a default ``--from``.
+
+    The run root is deliberately excluded from lane membership (it is run
+    metadata, not a lane-owned record — see ``lane_membership``), so
+    ``lane_active_frontiers`` never includes it and a brand-new run always
+    reports zero frontiers for every lane. That makes the very first
+    ``arctx add`` on a fresh run fail without ``--from`` even though the root
+    is the only possible input.
+
+    Returns the root node id when it is both active (not cut) and itself a
+    frontier (no outgoing steps yet, from *any* lane) — i.e. nothing has been
+    recorded against it yet. Returns ``None`` otherwise, so callers fall back
+    to the existing "no active frontiers" error.
+    """
+    from arctx.core.cuts import is_active_node
+
+    root_node_id = handle.root_node_id
+    if not root_node_id or root_node_id not in handle.run_graph.nodes:
+        return None
+    if not is_active_node(handle.run_graph, root_node_id):
+        return None
+    if handle.run_graph.steps_from_node(root_node_id):
+        return None
+    return root_node_id
+
+
+def describe_frontier_candidates(handle, node_ids) -> list[str]:
+    """Format frontier node ids as ``n_xxx (type_a, type_b)`` lines, like guide."""
+    lines = []
+    for node_id in node_ids:
+        payloads = handle.run_graph.payloads_for_node(node_id)
+        types = [p.payload_type for p in payloads]
+        type_str = f" ({', '.join(types)})" if types else ""
+        lines.append(f"{node_id}{type_str}")
+    return lines

{arctx_cli-0.3.1b2 → arctx_cli-0.3.1b4}/src/arctx_cli/commands/add.py

@@ -7,6 +7,11 @@ import json
 import sys
 
 from arctx_cli.append_batch import graph_counts, maybe_append_or_save
+from arctx_cli.commands._lane_context import (
+    describe_frontier_candidates,
+    resolve_lane_frontiers,
+    root_frontier_fallback,
+)
 from arctx_cli.commands._targets import step_view
 from arctx_cli.context import (
     resolve_run_id_from_args,
@@ -14,7 +19,9 @@ from arctx_cli.context import (
     resolve_user_id_from_args,
     resolve_lane_id_from_args,
 )
+from arctx_cli.lane_gate import ensure_lane_open
 from arctx_cli.payload_builder import build_payload, parse_field_args, parse_json_object
+from arctx_cli.post_write_check import warn_if_invalid
 
 
 def add_parser(subparsers) -> argparse.ArgumentParser:
@@ -22,10 +29,14 @@ def add_parser(subparsers) -> argparse.ArgumentParser:
     parser.add_argument(
         "--from",
         action="append",
-        required=True,
+        required=False,
+        default=None,
         dest="input_nodes",
         metavar="NODE_ID",
-        help="Input node (repeatable for multi-input steps)",
+        help=(
+            "Input node (repeatable for multi-input steps). If omitted, "
+            "defaults to the current lane's single active frontier node."
+        ),
     )
     parser.add_argument("--title", default=None)
     parser.add_argument("--type", dest="payload_kind", default=None)
@@ -36,14 +47,50 @@ def add_parser(subparsers) -> argparse.ArgumentParser:
     parser.add_argument("--store-dir", default=None)
     parser.add_argument("--user", default=None)
     parser.add_argument("--lane", default=None)
+    parser.add_argument("--force", action="store_true",
+                        help="Write even if the target lane is closed")
 
     return parser
 
 
+def _default_input_node_ids(handle, lane_id: str) -> list[str]:
+    """Default ``--from`` to the current lane's single active frontier node.
+
+    Raises ``ValueError`` (with a corrective, ready-to-copy command) when the
+    lane has zero or more than one active frontier, since there is no single
+    unambiguous node to continue from.
+    """
+    context = resolve_lane_frontiers(handle, lane_id)
+    frontiers = context.frontier_node_ids
+    lane_label = context.lane_name or context.lane_id
+
+    if len(frontiers) == 1:
+        return [frontiers[0]]
+
+    if not frontiers:
+        root_node_id = root_frontier_fallback(handle)
+        if root_node_id is not None:
+            return [root_node_id]
+        raise ValueError(
+            f"--from is required here: lane {lane_label!r} has no active frontiers. "
+            f"Pass --from NODE_ID explicitly. Use `arctx guide --context` or "
+            f"`arctx dump` to find a node, e.g.: arctx add --from n_xxx ..."
+        )
+
+    candidates = describe_frontier_candidates(handle, frontiers)
+    listing = "\n".join(f"  - {line}" for line in candidates)
+    example = frontiers[0]
+    raise ValueError(
+        f"--from is required here: lane {lane_label!r} has {len(frontiers)} active "
+        f"frontiers. Pick one:\n{listing}\n"
+        f"arctx add --from {example} ..."
+    )
+
+
 def run_add_step_command(
     *,
     run_id: str,
-    input_node_ids: list[str],
+    input_node_ids: list[str] | None,
     title: str | None,
     payload_kind: str | None,
     payload_type: str,
@@ -52,11 +99,15 @@ def run_add_step_command(
     store_dir: str,
     user_id: str | None = None,
     lane_id: str | None = None,
+    force: bool = False,
 ) -> 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)
+    ensure_lane_open(handle, lane_id, force=force)
+    if not input_node_ids:
+        input_node_ids = _default_input_node_ids(handle, lane_id or "default")
     data = dict(json_data or {})
     data.update(field_data or {})
     if title is not None:
@@ -94,8 +145,9 @@ def run_add_step_command(
 
 def cli_add(args) -> int:
     try:
+        run_id = resolve_run_id_from_args(args)
         result = run_add_step_command(
-            run_id=resolve_run_id_from_args(args),
+            run_id=run_id,
             input_node_ids=args.input_nodes,
             title=args.title,
             payload_kind=args.payload_kind,
@@ -105,9 +157,11 @@ def cli_add(args) -> int:
             store_dir=args.store_dir,
             user_id=resolve_user_id_from_args(args),
             lane_id=resolve_lane_id_from_args(args),
+            force=args.force,
         )
         print(json.dumps(result["step"], ensure_ascii=False, indent=2))
-        return 0
+        strict_rc = warn_if_invalid(run_id, args.store_dir, command_name="add")
+        return strict_rc or 0
     except (KeyError, ValueError, json.JSONDecodeError) as exc:
         print(f"error: {exc}", file=sys.stderr)
         return 1

{arctx_cli-0.3.1b2 → arctx_cli-0.3.1b4}/src/arctx_cli/commands/asset.py

@@ -13,6 +13,7 @@ from arctx_cli.context import (
     resolve_user_id_from_args,
     resolve_lane_id_from_args,
 )
+from arctx_cli.lane_gate import ensure_lane_open
 
 
 def add_parser(subparsers) -> argparse.ArgumentParser:
@@ -27,6 +28,8 @@ def add_parser(subparsers) -> argparse.ArgumentParser:
     sp_attach.add_argument("--store-dir", default=None)
     sp_attach.add_argument("--user", default=None)
     sp_attach.add_argument("--lane", default=None)
+    sp_attach.add_argument("--force", action="store_true",
+                           help="Write even if the target lane is closed")
 
     sp_list = asset_sub.add_parser("list", help="List assets for a Node or Step")
     sp_list.add_argument("--target", required=True, dest="target_id", help="Node or Step ID")
@@ -72,6 +75,7 @@ def _cli_asset_attach(args) -> int:
         return 1
 
     try:
+        ensure_lane_open(handle, lane_id, force=args.force)
         before = graph_counts(handle)
         payload = handle.attach_asset(
             args.target_id,

{arctx_cli-0.3.1b2 → arctx_cli-0.3.1b4}/src/arctx_cli/commands/attach.py

@@ -15,6 +15,8 @@ from arctx_cli.context import (
     resolve_lane_id_from_args,
 )
 from arctx_cli.payload_builder import build_payload, parse_field_args, parse_json_object
+from arctx_cli.lane_gate import ensure_lane_open
+from arctx_cli.post_write_check import warn_if_invalid
 
 
 def add_parser(subparsers) -> argparse.ArgumentParser:
@@ -28,6 +30,8 @@ def add_parser(subparsers) -> argparse.ArgumentParser:
     parser.add_argument("--store-dir", default=None)
     parser.add_argument("--user", default=None)
     parser.add_argument("--lane", default=None)
+    parser.add_argument("--force", action="store_true",
+                        help="Write even if the target lane is closed")
     return parser
 
 
@@ -42,11 +46,13 @@ def run_attach_command(
     store_dir: str,
     user_id: str | None = None,
     lane_id: str | None = None,
+    force: bool = False,
 ) -> 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)
+    ensure_lane_open(handle, lane_id, force=force)
     target_kind = resolve_target_kind(handle, target_id)
     if target_kind == "payload":
         raise ValueError("cannot attach a payload to another payload")
@@ -97,8 +103,9 @@ def run_attach_command(
 
 def cli_attach(args) -> int:
     try:
+        run_id = resolve_run_id_from_args(args)
         result = run_attach_command(
-            run_id=resolve_run_id_from_args(args),
+            run_id=run_id,
             target_id=args.target_id,
             payload_kind=args.payload_kind,
             payload_type=args.payload_type,
@@ -107,9 +114,11 @@ def cli_attach(args) -> int:
             store_dir=args.store_dir,
             user_id=resolve_user_id_from_args(args),
             lane_id=resolve_lane_id_from_args(args),
+            force=args.force,
         )
         print(json.dumps(result["payload"], ensure_ascii=False, indent=2))
-        return 0
+        strict_rc = warn_if_invalid(run_id, args.store_dir, command_name="attach")
+        return strict_rc or 0
     except (KeyError, ValueError, json.JSONDecodeError) as exc:
         print(f"error: {exc}", file=sys.stderr)
         return 1

{arctx_cli-0.3.1b2 → arctx_cli-0.3.1b4}/src/arctx_cli/commands/cut.py

@@ -13,6 +13,7 @@ from arctx_cli.context import (
     resolve_lane_id_from_args,
 )
 from arctx_cli.append_batch import graph_counts, maybe_append_or_save
+from arctx_cli.post_write_check import warn_if_invalid
 
 
 def add_parser(subparsers) -> argparse.ArgumentParser:
@@ -99,4 +100,5 @@ def cli_cut(args) -> int:
         lane_id=resolve_lane_id_from_args(args),
     )
     print(json.dumps(result["cut"], ensure_ascii=False, indent=2))
-    return 0
+    strict_rc = warn_if_invalid(run_id, args.store_dir, command_name="cut")
+    return strict_rc or 0

{arctx_cli-0.3.1b2 → arctx_cli-0.3.1b4}/src/arctx_cli/commands/dump.py

@@ -30,6 +30,8 @@ def add_parser(subparsers) -> argparse.ArgumentParser:
                         help="Hide observed (result) output steps")
     parser.add_argument("--full-payloads", action="store_true",
                         help="Include full payload metrics / rationale")
+    parser.add_argument("--expand-closed-lanes", action="store_true",
+                        help="Show closed lane internals instead of summary-only collapsed lanes")
     parser.add_argument("--run", default=None)
     parser.add_argument("--store-dir", default=None)
     return parser
@@ -43,12 +45,18 @@ def run_dump_command(
     node_id: str | None = None,
     depth: int | None = None,
     full_payloads: bool = False,
+    expand_closed_lanes: 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)
+    opts = DumpOptions(
+        node_id=node_id,
+        depth=depth,
+        full_payloads=full_payloads,
+        expand_closed_lanes=expand_closed_lanes,
+    )
     return dump(handle, fmt, opts)
 
 
@@ -67,6 +75,7 @@ def cli_dump(args) -> int:
         observed_only=args.observed_only,
         predicted_only=args.predicted_only,
         full_payloads=args.full_payloads,
+        expand_closed_lanes=args.expand_closed_lanes,
     )
     print(dump(handle, args.fmt, opts))
     return 0